Class: Nanook::WalletAccount

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/nanook/wallet_account.rb

Overview

The Nanook::WalletAccount class lets you manage your nano accounts, including paying and receiving payment.

Initializing

Initialize this class through an instance of Wallet like this:

 = Nanook.new.wallet(wallet_id).()

Or compose the longhand way like this:

rpc_conn = Nanook::Rpc.new
 = Nanook::WalletAccount.new(rpc_conn, wallet_id, )

Instance Method Summary collapse

Constructor Details

#initialize(rpc, wallet, account) ⇒ WalletAccount

Returns a new instance of WalletAccount.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/nanook/wallet_account.rb', line 49

def initialize(rpc, wallet, )
  @rpc = rpc
  @wallet = wallet
  @account = 

  # Initialize an instance to delegate the RPC commands that do not
  # need `enable_control` enabled (the read-only RPC commands).
  @nanook_account_instance = nil

  return if @account.nil?

  # Wallet must contain the account
  unless Nanook::Wallet.new(@rpc, @wallet).contains?(@account)
    raise ArgumentError, "Account does not exist in wallet. Account: #{@account}, wallet: #{@wallet}"
  end

  # An object to delegate account methods that don't
  # expect a wallet param in the RPC call, to allow this
  # class to support all methods that can be called on Nanook::Account
  @nanook_account_instance = Nanook::Account.new(@rpc, @account)
end

Instance Method Details

#balance(unit: Nanook.default_unit) ⇒ Hash{Symbol=>Integer|Float}

The account's balance, including pending (unreceived payments). To receive a pending amount see #receive.

Examples:

.balance

Example response:

{
  balance: 2,
  pending: 1.1
}

Asking for the balance to be returned in raw instead of NANO:

.balance(unit: :raw)

Example response:

{
  balance: 2000000000000000000000000000000,
  pending: 1100000000000000000000000000000
}

Parameters:

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

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

Raises:

  • ArgumentError if an invalid unit was given.



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#block_count ⇒ Integer

Returns number of blocks for this account.

Returns:

  • (Integer) —

    number of blocks for this account



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#change_representative(representative) ⇒ String

Sets the representative for the account.

A representative is an account that will vote on your account's behalf on the nano network if your account is offline and there is a fork of the network that requires voting on.

Returns the change block that was broadcast to the nano network. The block contains the information about the representative change for your account.

Also see Nanook::Wallet#change_default_representative for how to set a default representative for all new accounts created in a wallet.

Example:

.change_representative("nano_...")
  # => "000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"

Parameters:

  • representative (String) —

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

Returns:

  • (String) —

    id of the change block created

Raises:

  • (ArgumentError) —

    if the representative account does not exist



218
219
220
221
222
223
224
 
# File 'lib/nanook/wallet_account.rb', line 218

def change_representative(representative)
  unless Nanook::Account.new(@rpc, representative).exists?
    raise ArgumentError, "Representative account does not exist: #{representative}"
  end

  rpc(:account_representative_set, representative: representative)[:block]
end

#create(n_accounts = 1) ⇒ Nanook::WalletAccount+

Creates a new account, or multiple new accounts, in this wallet.

Examples:

wallet.create     # => Nanook::WalletAccount
wallet.create(2)  # => [Nanook::WalletAccount, Nanook::WalletAccount]

Parameters:

  • n_accounts (Integer) (defaults to: 1) —

    number of accounts to create

Returns:

Raises:

  • (ArgumentError) —

    if n is less than 1



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/nanook/wallet_account.rb', line 85

def create(n_accounts = 1)
  raise ArgumentError, 'number of accounts must be greater than 0' if n_accounts < 1

  if n_accounts == 1
    Nanook::WalletAccount.new(@rpc, @wallet, rpc(:account_create)[:account])
  else
    Array(rpc(:accounts_create, count: n_accounts)[:accounts]).map do ||
      Nanook::WalletAccount.new(@rpc, @wallet, )
    end
  end
end

#delegators(unit: Nanook.default_unit) ⇒ Hash{Symbol=>Integer}

Information about this accounts that have set this account as their representative.

Example:

.delegators

Example response:

{
  :nano_13bqhi1cdqq8yb9szneoc38qk899d58i5rcrgdk5mkdm86hekpoez3zxw5sd=>500000000000000000000000000000000000,
  :nano_17k6ug685154an8gri9whhe5kb5z1mf5w6y39gokc1657sh95fegm8ht1zpn=>961647970820730000000000000000000000
}

Parameters:

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

  • (Hash{Symbol=>Integer}) —

    account ids which delegate to this account, and their account balance



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#destroy ⇒ Boolean

Unlinks the account from the wallet.

Example:

.destroy # => true

Returns:

  • (Boolean) —

    true if action was successful, otherwise false



104
105
106
 
# File 'lib/nanook/wallet_account.rb', line 104

def destroy
  rpc(:account_remove)[:removed] == 1
end

#exists? ⇒ Boolean Also known as: open?

Returns true if the account has an open block.

An open block gets published when an account receives a payment for the first time.

The reliability of this check depends on the node host having synchronized itself with most of the blocks on the nano network, otherwise you may get false when the account does exist. You can check if a node's synchronization is particular low using Node#sync_progress.

Example:

.exists? # => true
# or
.open?   # => true

Returns:

  • (Boolean) —

    Indicates if this account has an open block



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#history(limit: 1000, unit: Nanook.default_unit) ⇒ Array<Hash{Symbol=>String}>

An account's history of send and receive payments.

Example:

.history

Example response:

[
  {
   type: "send",
   account: "nano_1kdc5u48j3hr5r7eof9iao47szqh81ndqgq5e5hrsn1g9a3sa4hkkcotn3uq",
   amount: 2,
   hash: "2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570"
  }
]

Parameters:

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

    maximum number of history items to return

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

  • (Array<Hash{Symbol=>String}>) —

    the history of send and receive payments for this account



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#id ⇒ String

The id of the account.

Example:

.id # => "nano_16u..."

Returns:

  • (String) —

    the id of the account



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#info(detailed: false, unit: Nanook.default_unit) ⇒ Hash{Symbol=>String|Integer|Float}

Information about the account.

Examples:

.info

Example response:

{
  id: "nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5",
  balance: 11.439597000000001,
  block_count: 4,
  frontier: "2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
  modified_timestamp: 1520500357,
  open_block: "C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  representative_block: "C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9"
}

Asking for more detail to be returned:

.info(detailed: true)

Example response:

{
  id: "nano_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5",
  balance: 11.439597000000001,
  block_count: 4,
  frontier: "2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
  modified_timestamp: 1520500357,
  open_block: "C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  pending: 0,
  public_key: "A82C906460046D230D7D37C6663723DC3EFCECC4B3254EBF45294B66746F4FEF",
  representative: "nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh",
  representative_block: "C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  weight: 0
}

Parameters:

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

    (default is false). When true, four additional calls are made to the RPC to return more information

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

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

    information about the account containing:

    id

    The account id

    frontier

    The latest block hash

    open_block

    The first block in every account's blockchain. When this block was published the account was officially open

    representative_block

    The block that named the representative for the account

    balance

    Amount in either NANO or raw (depending on the unit: argument)

    last_modified

    Unix timestamp

    block_count

    Number of blocks in the account's blockchain

    When detailed: true is passed as an argument, this method makes four additional calls to the RPC to return more information about an account:

    weight

    See #weight

    pending

    See #balance

    representative

    See #representative

    public_key

    See #public_key



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#inspect ⇒ String

Returns:

  • (String) 


109
110
111
112
 
# File 'lib/nanook/wallet_account.rb', line 109

def inspect
  "#{self.class.name}(wallet_id: #{@wallet}, account_id: #{id}, object_id: \"#{format('0x00%x',
                                                                                      (object_id << 1))}\")"
end

#last_modified_at ⇒ Time

The last modified time of the account in the time zone of your nano node (usually UTC).

Example:

.last_modified_at # => Time

Returns:

  • (Time) —

    last modified time of the account in the time zone of your nano node (usually UTC).



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#ledger(limit: 1, modified_since: nil, unit: Nanook.default_unit) ⇒ Hash{Symbol=>String|Integer}

Information about the given account as well as other accounts up the ledger. The number of accounts returned is determined by the limit: argument.

Example:

.ledger(limit: 2)

Example response:

 {
  :nano_3c3ek3k8135f6e8qtfy8eruk9q3yzmpebes7btzncccdest8ymzhjmnr196j=>{
    :frontier=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
    :open_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :representative_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :balance=>11439597000000000000000000000000,
    :modified_timestamp=>1520500357,
    :block_count=>4
  },
  :nano_3c3ettq59kijuuad5fnaq35itc9schtr4r7r6rjhmwjbairowzq3wi5ap7h8=>{ ... }
}

Parameters:

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

    number of accounts to return in the ledger (default is 1)

  • modified_since (Time) (defaults to: nil) —

    return only accounts modified in the local database after this time

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

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


45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#pay(to:, amount:, id:, unit: Nanook.default_unit) ⇒ String

Makes a payment from this account to another account on the nano network. Returns a send block hash if successful, or a Error if unsuccessful.

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.

Examples:

.pay(to: "nano_...", amount: 1.1, id: "myUniqueId123") # => "9AE2311..."
.pay(to: "nano_...", amount: 54000000000000, id: "myUniqueId123", unit: :raw) # => "9AE2311..."

Parameters:

  • to (String) —

    account id of the recipient of your payment

  • amount (Integer|Float)
  • id (String) —

    must be unique per payment. It serves an important purpose; it allows you to make the same call multiple times with the same id and be reassured that you will only ever send this nano payment once

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

  • (String) —

    the send block id for the payment

Raises:



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/nanook/wallet_account.rb', line 137

def pay(to:, amount:, id:, unit: Nanook.default_unit)
  raise ArgumentError, "Unsupported unit: #{unit}" unless Nanook::UNITS.include?(unit)

  # Check that to account is a valid address
  response = @rpc.call(:validate_account_number, account: to)
  raise ArgumentError, "Account address is invalid: #{to}" unless response[:valid] == 1

  # Determin amount in raw
  raw = if unit.to_sym.eql?(:nano)
          Nanook::Util.NANO_to_raw(amount)
        else
          amount
        end

  # account is called source, so don't use the normal rpc method
  p = {
    wallet: @wallet,
    source: @account,
    destination: to,
    amount: raw,
    id: id
  }

  response = @rpc.call(:send, p)

  return Nanook::Error.new(response[:error]) if response.key?(:error)

  response[:block]
end

#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ Array<String>, Array<Hash{Symbol=>String|Integer}>

Information about pending blocks (payments) that are waiting to be received by the account.

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

The default response is an Array of block ids.

With the detailed: argument, the method returns an Array of Hashes, which contain the source account id, amount pending and block id.

Examples:

.pending # => ["000D1BA..."]

Asking for more detail to be returned:

.pending(detailed: true)

Example response:

[
  {
    block: "000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F",
    amount: 6,
    source: "nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr"
  },
  { ... }
]

Parameters:

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

    number of pending blocks to return (default is 1000)

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

    return a more complex Hash of pending block information (default is false)

  • unit (Symbol) (defaults to: Nanook.default_unit) —

    default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano. See - What are Nano's Units

Returns:

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


45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#public_key ⇒ String

The public key of the account.

Example:

.public_key # => "3068BB1..."

Returns:

  • (String) —

    public key of the account



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#receive(block = nil) ⇒ String, false

Receives a pending payment for this account.

When called with no block argument, the latest pending payment for the account will be received.

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

You can receive a specific pending block if you know it by passing the block in as an argument.

Examples:

.receive               # => "9AE2311..."
.receive("718CC21...") # => "9AE2311..."

Parameters:

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

    optional block id of pending payment. If not provided, the latest pending payment will be received

Returns:

  • (String) —

    the receive block id

  • (false) —

    if there was no block to receive



188
189
190
191
192
193
194
 
# File 'lib/nanook/wallet_account.rb', line 188

def receive(block = nil)
  if block.nil?
    _receive_without_block
  else
    _receive_with_block(block)
  end
end

#representative ⇒ String

The representative account id for the account. Representatives are accounts that cast votes in the case of a fork in the network.

Example:

.representative # => "nano_3pc..."

Returns:

  • (String) —

    Representative account of the account



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight

#weight ⇒ Integer

The account's weight.

Weight is determined by the account's balance, and represents the voting weight that account has on the network. Only accounts with greater than 256 weight can vote.

Example:

.weight # => 0

Returns:

  • (Integer) —

    the account's weight



45
46
 
# File 'lib/nanook/wallet_account.rb', line 45

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at,
:ledger, :pending, :public_key, :representative, :weight