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.("xrb_...")

Or compose the longhand way like this:

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

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.



190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/nanook/account.rb', line 190

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

  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



204
205
206
 
# File 'lib/nanook/account.rb', line 204

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:

{
  :xrb_13bqhi1cdqq8yb9szneoc38qk899d58i5rcrgdk5mkdm86hekpoez3zxw5sd=>500000000000000000000000000000000000,
  :xrb_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



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

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

  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



75
76
77
78
 
# File 'lib/nanook/account.rb', line 75

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: "xrb_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



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/nanook/account.rb', line 101

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

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

  if unit == :raw
    return response
  end

  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 # => "xrb_16u..."

Returns:

  • (String) —

    the id of the account



215
216
217
 
# File 'lib/nanook/account.rb', line 215

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: "xrb_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: "xrb_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5",
  balance: 11.439597000000001,
  block_count: 4,
  frontier: "2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
  modified_timestamp: 1520500357,
  open_block: "C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  pending: 0,
  public_key: "A82C906460046D230D7D37C6663723DC3EFCECC4B3254EBF45294B66746F4FEF",
  representative: "xrb_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



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/nanook/account.rb', line 277

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

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

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

  # 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 



304
305
306
 
# File 'lib/nanook/account.rb', line 304

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



127
128
129
130
 
# File 'lib/nanook/account.rb', line 127

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:

 {
  :xrb_3c3ek3k8135f6e8qtfy8eruk9q3yzmpebes7btzncccdest8ymzhjmnr196j=>{
    :frontier=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
    :open_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :representative_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :balance=>11439597000000000000000000000000,
    :modified_timestamp=>1520500357,
    :block_count=>4
  },
  :xrb_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}) 


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

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

  params = { count: limit }

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

  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: "xrb_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}>) 


394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/nanook/account.rb', line 394

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

  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)

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

    p
  end
end

#public_key ⇒ String

The public key of the account.

Example:

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

Returns:

  • (String) —

    public key of the account



139
140
141
 
# File 'lib/nanook/account.rb', line 139

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 # => "xrb_3pc..."

Returns:

  • (String) —

    Representative account of the account



152
153
154
 
# File 'lib/nanook/account.rb', line 152

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



429
430
431
 
# File 'lib/nanook/account.rb', line 429

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