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) ⇒ Object

Returns a Hash containing the account’s balance.

Example:

.balance

# =>
# {
#   balance=>2,   # Account balance
#   pending=>1.1  # Amount pending and not yet received by the account
# }

Example balance returned in raw:

.balance(unit: :raw)

# =>
# {
#   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

Raises:

  • ArgumentError if an invalid unit was given.



164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/nanook/account.rb', line 164

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

#delegators ⇒ Hash{Symbol=>String}

Returns information about this account’s delegators.

Example response:

{
  :xrb_13bqhi1cdqq8yb9szneoc38qk899d58i5rcrgdk5mkdm86hekpoez3zxw5sd=>500000000000000000000000000000000000,
  :xrb_17k6ug685154an8gri9whhe5kb5z1mf5w6y39gokc1657sh95fegm8ht1zpn=>961647970820730000000000000000000000
}

Returns:

  • (Hash{Symbol=>String}) —

    Delegators



32
33
34
 
# File 'lib/nanook/account.rb', line 32

def delegators
  rpc(:delegators)[:delegators]
end

#exists? ⇒ Boolean

Returns a boolean indicating if the account exists.

Existence is determined by if the account has an open block. An open block is a special kind of block that 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.

Returns:

  • (Boolean) —

    Indicates if this account exists in the nano network



49
50
51
52
 
# File 'lib/nanook/account.rb', line 49

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

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

Returns an account’s history of send and receive payments.

Example:

.history
.history(limit: 1)

Example response:

[
  {
   :type=>"send",
   :account=>"xrb_1kdc5u48j3hr5r7eof9iao47szqh81ndqgq5e5hrsn1g9a3sa4hkkcotn3uq",
   :amount=>2,
   :hash=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570"
  }
]

Example:

.history
.history(unit: :raw)

Example response:

[
  {
   :type=>"send",
   :account=>"xrb_1kdc5u48j3hr5r7eof9iao47szqh81ndqgq5e5hrsn1g9a3sa4hkkcotn3uq",
   :amount=>2000000000000000000000000000000,
   :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



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/nanook/account.rb', line 88

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

Returns the id of the account.

Returns:

  • (String) —

    the id of the account



179
180
181
 
# File 'lib/nanook/account.rb', line 179

def id
  @account
end

#info(detailed: false, unit: Nanook.default_unit) ⇒ Hash

Returns a Hash containing information about the account.

Example 1

.info

Example 1 response

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

Example 2

.info(detailed: true)

Example 2 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) —

    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 NANO

    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



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/nanook/account.rb', line 239

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 



266
267
268
 
# File 'lib/nanook/account.rb', line 266

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

#last_modified_at ⇒ Time

Returns last modified time of the account in UTC time zone.

Returns:

  • (Time) —

    last modified time of the account in UTC time zone.



106
107
108
109
 
# File 'lib/nanook/account.rb', line 106

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

#ledger(limit: 1) ⇒ Object

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

The information in each Hash is the same as what the #info(detailed: false) method returns.

Arguments

limit:

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

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=>{ ... }
}



297
298
299
 
# File 'lib/nanook/account.rb', line 297

def ledger(limit: 1)
  rpc(:ledger, count: limit)[:accounts]
end

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

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

See also the #receive method of this class 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.

Example 1:

.pending # => ["000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"]

Example 2:

.pending(detailed: true)
# =>
# [
#   {
#     :block=>"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F",
#     :amount=>6,
#     :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr"
#   },
#   { ... }
# ]

Example 3:

.pending(detailed: true, unit: raw).first[:amount] # => 6000000000000000000000000000000

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


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

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

Returns the public key belonging to an account.

Example response:

"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039"

Returns:

  • (String) —

    public key of this account



117
118
119
 
# File 'lib/nanook/account.rb', line 117

def public_key
  rpc(:account_key)[:key]
end

#representative ⇒ String

Returns the representative account for the account. Representatives are accounts which cast votes in the case of a fork in the network.

Example response

"xrb_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh"

Returns:

  • (String) —

    Representative account of this account



130
131
132
 
# File 'lib/nanook/account.rb', line 130

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

#weight ⇒ Integer

Returns 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



371
372
373
 
# File 'lib/nanook/account.rb', line 371

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