Class: Nanook::Account

Inherits:
Object
  • Object
show all
Defined in:
lib/nanook/account.rb

Overview

The Nanook::Account class contains methods to discover publicly-available information about accounts on the nano network.

Initializing

Initialize this class through the convenient #account method:

nanook = Nanook.new
 = nanook.("nano_...")

Or compose the longhand way like this:

rpc_conn = Nanook::Rpc.new
 = Nanook::Account.new(rpc_conn, "nano_...")

Instance Method Summary collapse

Constructor Details

#initialize(rpc, account) ⇒ Account

Returns a new instance of Account.



19
20
21
22
 
# File 'lib/nanook/account.rb', line 19

def initialize(rpc, )
  @rpc = 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 WalletAccount#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.



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/nanook/account.rb', line 184

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

  rpc(:account_balance).tap do |r|
    if unit == :nano
      r[:balance] = Nanook::Util.raw_to_NANO(r[:balance])
      r[:pending] = Nanook::Util.raw_to_NANO(r[:pending])
    end
  end
end

#block_count ⇒ Integer

Returns number of blocks for this account.

Returns:

  • (Integer) —

    number of blocks for this account



196
197
198
 
# File 'lib/nanook/account.rb', line 196

def block_count
  rpc(:account_block_count)[:block_count]
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

Raises:

  • (ArgumentError) 


39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/nanook/account.rb', line 39

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

  response = rpc(:delegators)[:delegators]

  return response if unit == :raw

  r = response.map do |, balance|
    balance = Nanook::Util.raw_to_NANO(balance)

    [, balance]
  end

  Hash[r].to_symbolized_hash
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



73
74
75
76
 
# File 'lib/nanook/account.rb', line 73

def exists?
  response = rpc(:account_info)
  !response.empty? && !response[:open_block].nil?
end

#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

Raises:

  • (ArgumentError) 


99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/nanook/account.rb', line 99

def history(limit: 1000, unit: Nanook.default_unit)
  raise ArgumentError, "Unsupported unit: #{unit}" unless Nanook::UNITS.include?(unit)

  response = rpc(:account_history, count: limit)[:history]

  return response if unit == :raw

  response.map! do |history|
    history[:amount] = Nanook::Util.raw_to_NANO(history[:amount])
    history
  end
end

#id ⇒ String

The id of the account.

Example:

.id # => "nano_16u..."

Returns:

  • (String) —

    the id of the account



207
208
209
 
# File 'lib/nanook/account.rb', line 207

def id
  @account
end

#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

Raises:

  • (ArgumentError) 


269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/nanook/account.rb', line 269

def info(detailed: false, unit: Nanook.default_unit)
  raise ArgumentError, "Unsupported unit: #{unit}" unless Nanook::UNITS.include?(unit)

  response = rpc(:account_info)
  response.merge!(id: @account)

  response[:balance] = Nanook::Util.raw_to_NANO(response[:balance]) if unit == :nano

  # Return the response if we don't need any more info
  return response unless detailed

  # Otherwise make additional calls
  response.merge!({
                    weight: weight,
                    pending: balance(unit: unit)[:pending],
                    representative: representative,
                    public_key: public_key
                  })

  # Sort this new hash by keys
  Hash[response.sort].to_symbolized_hash
end

#inspect ⇒ Object 



292
293
294
 
# File 'lib/nanook/account.rb', line 292

def inspect
  "#{self.class.name}(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).



121
122
123
124
 
# File 'lib/nanook/account.rb', line 121

def last_modified_at
  response = rpc(:account_info)
  Time.at(response[:modified_timestamp])
end

#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})

Raises:

  • (ArgumentError) 


322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/nanook/account.rb', line 322

def ledger(limit: 1, modified_since: nil, unit: Nanook.default_unit)
  raise ArgumentError, "Unsupported unit: #{unit}" unless Nanook::UNITS.include?(unit)

  params = { count: limit }

  params[:modified_since] = modified_since.to_i unless modified_since.nil?

  response = rpc(:ledger, params)[:accounts]

  return response if unit == :raw

  r = response.map do |, l|
    l[:balance] = Nanook::Util.raw_to_NANO(l[:balance])

    [, l]
  end

  Hash[r].to_symbolized_hash
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 WalletAccount#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}>)

Raises:

  • (ArgumentError) 


378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/nanook/account.rb', line 378

def pending(limit: 1000, detailed: false, unit: Nanook.default_unit)
  raise ArgumentError, "Unsupported unit: #{unit}" unless Nanook::UNITS.include?(unit)

  params = { count: limit }
  params[:source] = true if detailed

  response = rpc(:pending, params)[:blocks]
  response = Nanook::Util.coerce_empty_string_to_type(response, (detailed ? Hash : Array))

  return response unless detailed

  response.map do |key, val|
    p = val.merge(block: key.to_s)

    p[:amount] = Nanook::Util.raw_to_NANO(p[:amount]) if unit == :nano

    p
  end
end

#public_key ⇒ String

The public key of the account.

Example:

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

Returns:

  • (String) —

    public key of the account



133
134
135
 
# File 'lib/nanook/account.rb', line 133

def public_key
  rpc(:account_key)[:key]
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



146
147
148
 
# File 'lib/nanook/account.rb', line 146

def representative
  rpc(:account_representative)[:representative]
end

#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



409
410
411
 
# File 'lib/nanook/account.rb', line 409

def weight
  rpc(:account_weight)[:weight]
end