Class: Banano::Wallet

Inherits:
Object
  • Object
show all
Defined in:
lib/banano/wallet.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(node:, wallet: nil) ⇒ Wallet

Returns a new instance of Wallet.



35
36
37
38
 
# File 'lib/banano/wallet.rb', line 35

def initialize(node:, wallet: nil)
  @node = node
  @wallet = wallet
end

Instance Attribute Details

#node ⇒ Object (readonly)

Returns the value of attribute node.



33
34
35
 
# File 'lib/banano/wallet.rb', line 33

def node
  @node
end

Instance Method Details

#account(account = nil) ⇒ Banano::WalletAccount

Returns the given account in the wallet as a Banano::WalletAccount instance to let you start working with it.

Call with no account argument if you wish to create a new account in the wallet, like this:

wallet..create     # => Banano::WalletAccount

See Banano::WalletAccount for all the methods you can call on the account object returned.

Examples:

wallet.("nano_...") # => Banano::WalletAccount
wallet..create     # => Banano::WalletAccount

Parameters:

  • account (String) (defaults to: nil) —

    optional String of an account (starting with "ban_...") to start working with. Must be an account within the wallet. When no account is given, the instance returned only allows you to call create on it, to create a new account.

Returns:

Raises:

  • (ArgumentError) —

    if the wallet does no contain the account



78
79
80
 
# File 'lib/banano/wallet.rb', line 78

def ( = nil)
  Banano::WalletAccount.new(node: @node, wallet: @wallet, account: )
end

#accounts ⇒ Array<Banano::WalletAccount>

Array of Banano::WalletAccount instances of accounts in the wallet.

Example:

wallet.accounts # => [Banano::WalletAccount, Banano::WalletAccount...]

Returns:



89
90
91
92
 
# File 'lib/banano/wallet.rb', line 89

def accounts
  wallet_required!
  rpc(action: :account_list)[:accounts]
end

#balance(account_break_down: false, raw: true) ⇒ Hash{Symbol=>Integer|Float|Hash}

Balance of all accounts in the wallet, optionally breaking the balances down by account.

Examples:

wallet.balance

Example response:

{
  "balance"=>5,
  "pending"=>0.001
}

Parameters:

  • account_break_down (Boolean) (defaults to: false) —

    (default is false). When true the response will contain balances per account.

  • raw (Boolean) (defaults to: true) —

    raw or banano units

Returns:

  • (Hash{Symbol=>Integer|Float|Hash}) 


274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/banano/wallet.rb', line 274

def balance(account_break_down: false, raw: true)
  wallet_required!

  if 
    response = rpc(action: :wallet_balances)[:balances].tap do |r|
      unless raw == true
        r.each do |, _|
          r[][:balance] = Banano::Unit.raw_to_ban(r[][:balance]).to_f
          r[][:pending] = Banano::Unit.raw_to_ban(r[][:pending]).to_f
        end
      end
    end
    return response.collect {|k, v| [k.to_s, v] }.to_h
  end

  rpc(action: :wallet_balance_total).tap do |r|
    unless raw == true
      r[:balance] = Banano::Unit.raw_to_ban(r[:balance]).to_f
      r[:pending] = Banano::Unit.raw_to_ban(r[:pending]).to_f
    end
  end
end

#change_default_representative(representative) ⇒ String Also known as: change_representative

Sets the default representative for the wallet. A wallet’s default representative is the representative all new accounts created in the wallet will have. Changing the default representative for a wallet does not change the representatives for existing accounts in the wallet.

Example:

wallet.change_default_representative("ban_...") # => "ban_..."

Parameters:

  • representative (String) —

    the id of the representative account to set as this account’s representative

Returns:

  • (String) —

    the representative account id

Raises:

  • (ArgumentError) —

    if the representative account does not exist

  • (Banano::Error) —

    if setting the representative fails



175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/banano/wallet.rb', line 175

def change_default_representative(representative)
  unless Banano::Account.new(node: @node, address: representative).exists?
    raise ArgumentError, "Representative account does not exist: #{representative}"
  end

  if rpc(action: :wallet_representative_set,
        params: {representative: representative})[:set] == '1'
    representative
  else
    raise Banano::Error, "Setting the representative failed"
  end
end

#change_password(password) ⇒ Boolean

Changes the password for a wallet.

Example:

wallet.change_password("new_pass") #=> true

Returns:

  • (Boolean) —

    indicates if the action was successful



252
253
254
255
 
# File 'lib/banano/wallet.rb', line 252

def change_password(password)
  wallet_required!
  rpc(action: :password_change, params: {password: password})[:changed] == '1'
end

#change_seed(seed) ⇒ Boolean

Changes a wallet’s seed.

It’s recommended to only change the seed of a wallet that contains no accounts.

Example:

wallet.change_seed("000D1BA...") # => true

Parameters:

  • seed (String) —

    the seed to change to.

Returns:

  • (Boolean) —

    indicating whether the change was successful.



51
52
53
54
 
# File 'lib/banano/wallet.rb', line 51

def change_seed(seed)
  wallet_required!
  rpc(action: :wallet_change_seed, params: {seed: seed}).key?(:success)
end

#contains?(account) ⇒ Boolean

Will return true if the account exists in the wallet.

Example:

wallet.contains?("ban_1...") # => true

TODO: account address validation - Maybe Banano::Address .…

Parameters:

  • account (String) —

    id (will start with "ban_...")

Returns:

  • (Boolean) —

    indicating if the wallet contains the given account



102
103
104
105
106
 
# File 'lib/banano/wallet.rb', line 102

def contains?()
  wallet_required!
  response = rpc(action: :wallet_contains, params: {account: })
  !response.empty? && response[:exists] == '1'
end

#create ⇒ Banano::Wallet

Creates a new wallet.

The wallet will be created only on this node. It’s important that if you intend to add funds to accounts in this wallet that you backup the wallet seed in order to restore the wallet in future.

Example:

Banano::Wallet.new.create # => Banano::Wallet

Returns:



118
119
120
121
 
# File 'lib/banano/wallet.rb', line 118

def create
  @wallet = rpc(action: :wallet_create)[:wallet]
  self
end

#default_representative ⇒ String Also known as: representative

The default representative account id for the wallet. This is the representative that all new accounts created in this wallet will have.

Changing the default representative for a wallet does not change the representatives for any accounts that have been created.

Example:

wallet.default_representative # => "ban_3pc..."

Returns:

  • (String) —

    Representative account of the account



155
156
157
 
# File 'lib/banano/wallet.rb', line 155

def default_representative
  rpc(action: :wallet_representative)[:representative]
end

#destroy ⇒ Boolean

Destroys the wallet.

Example:

wallet.destroy # => true

Returns:

  • (Boolean) —

    indicating success of the action



130
131
132
133
134
135
 
# File 'lib/banano/wallet.rb', line 130

def destroy
  wallet_required!
  rpc(action: :wallet_destroy)
  @wallet = nil
  true
end

#export ⇒ Object

Generates a String containing a JSON representation of your wallet.



139
140
141
142
 
# File 'lib/banano/wallet.rb', line 139

def export
  wallet_required!
  rpc(action: :wallet_export)[:json]
end

#id ⇒ String

Returns the wallet id.

Returns:

  • (String) —

    the wallet id



190
191
192
 
# File 'lib/banano/wallet.rb', line 190

def id
  @wallet
end

#info ⇒ Hash{Symbol=>String|Array<Hash{Symbol=>String|Integer|Float}>}

Information about this wallet and all of its accounts.

Examples:

wallet.info

information about the wallet.

Parameters:

  • raw (Boolean) —

    if true return raw, else return ban units

Returns:

  • (Hash{Symbol=>String|Array<Hash{Symbol=>String|Integer|Float}>}) 


203
204
205
206
 
# File 'lib/banano/wallet.rb', line 203

def info
  wallet_required!
  rpc(action: :wallet_info)
end

#lock ⇒ Boolean

Locks the wallet. A locked wallet cannot pocket pending transactions or make payments.

Example:

wallet.lock #=> true

Returns:

  • (Boolean) —

    indicates if the wallet was successfully locked



215
216
217
218
219
 
# File 'lib/banano/wallet.rb', line 215

def lock
  wallet_required!
  response = rpc(action: :wallet_lock)
  !response.empty? && response[:locked] == '1'
end

#locked? ⇒ Boolean

Returns true if the wallet is locked.

Example:

wallet.locked? #=> false

Returns:

  • (Boolean) —

    indicates if the wallet is locked



228
229
230
231
232
 
# File 'lib/banano/wallet.rb', line 228

def locked?
  wallet_required!
  response = rpc(action: :wallet_locked)
  !response.empty? && response[:locked] != '0'
end

#pay(from:, to:, amount:, raw: true, id:) ⇒ String

Makes a payment from an account in your wallet to another account on the nano network.

Note, there may be a delay in receiving a response due to Proof of Work being done. From the Nano RPC:

Proof of Work is precomputed for one transaction in the background. If it has been a while since your last transaction it will send instantly, the next one will need to wait for Proof of Work to be generated.

Parameters:

  • from (String) —

    account id of an account in your wallet

  • raw (Boolean) (defaults to: true) —

    raw or banano units

  • to (String) —

    account id of the recipient of your payment

  • amount (Integer|Float)

Returns:

  • (String) —

    the send block id for the payment

Raises:



316
317
318
319
320
321
 
# File 'lib/banano/wallet.rb', line 316

def pay(from:, to:, amount:, raw: true, id:)
  wallet_required!
  validate_wallet_contains_account!(from)
  # account(from) will return Banano::WalletAccount
  (from).pay(to: to, amount: amount, raw: raw, id: id)
end

#pending(limit: 1000, detailed: false, raw: true) ⇒ Object

Information about pending blocks (payments) that are waiting to be received by accounts in this wallet.

See also the #receive method of this class for how to receive a pending payment.

Examples:

wallet.pending

Parameters:

  • limit (Integer) (defaults to: 1000) —

    number of accounts with pending payments to return (default is 1000)

  • detailed (Boolean) (defaults to: false) —

    return complex Hash of pending block info (default is false)

  • raw (Boolean) (defaults to: true) —

    raw or banano units



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/banano/wallet.rb', line 336

def pending(limit: 1000, detailed: false, raw: true)
  wallet_required!
  params = {count: limit}
  params[:source] = true if detailed

  response = rpc(action: :wallet_pending, params: params)[:blocks]
  return response unless detailed && !response.empty?

  # Map the RPC response, which is:
  # account=>block=>[amount|source] into
  # account=>[block|amount|source]
  response.map do |, data|
    new_data = data.map do |block, amount_and_source|
      d = amount_and_source.merge(block: block.to_s)
      d[:amount] = Banano::Unit.raw_to_ban(d[:amount]) unless raw == true
      d
    end

    [, new_data]
  end
end

#receive(block:, into:) ⇒ String, false

Receives a pending payment into an account in the wallet.

Returns a receive block hash id if a receive was successful, or false if there were no pending payments to receive.

Receive a specific pending block by passing block_id as an argument

Examples:

wallet.receive("718CC21...", into: "ban_..") # => "9AE2311..."

Parameters:

  • into (String) —

    account id of account in your wallet to receive the payment into

  • block (String) —

    block id of pending payment.

Returns:

  • (String) —

    the receive block id

  • (false) —

    if there was no block to receive



373
374
375
376
377
378
 
# File 'lib/banano/wallet.rb', line 373

def receive(block:, into:)
  wallet_required!
  validate_wallet_contains_account!(into)
  # account(into) will return Banano::WalletAccount
  (into).receive(block)
end

#restore(seed:, accounts: 0) ⇒ Banano::Wallet

Restores a previously created wallet by its seed. A new wallet will be created on your node (with a new wallet id) and will have its seed set to the given seed.

Example:

Banano::Protocol.new.wallet.restore(seed: seed, accounts: 1) # => Banano::Wallet

Parameters:

  • seed (String) —

    the wallet seed to restore.

  • accounts (Integer) (defaults to: 0) —

    optionally restore the given number of accounts for the wallet.

Returns:

Raises:



393
394
395
396
397
398
399
400
 
# File 'lib/banano/wallet.rb', line 393

def restore(seed:, accounts: 0)
  create

  raise Banano::Error, "Unable to set seed for wallet" unless change_seed(seed)

  .create(accounts) if accounts > 0
  self
end

#unlock(password) ⇒ Boolean

Unlocks a previously locked wallet.

Example:

wallet.unlock("new_pass") #=> true

Returns:

  • (Boolean) —

    indicates if the unlocking action was successful



241
242
243
244
 
# File 'lib/banano/wallet.rb', line 241

def unlock(password)
  wallet_required!
  rpc(action: :password_enter, params: {password: password})[:valid] == '1'
end