Class: Nanook::Account

Inherits:
Object
  • Object
show all
Includes:
Util
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_...")

Constant Summary

Constants included from Util

Util::STEP

Instance Method Summary collapse

Constructor Details

#initialize(rpc, account) ⇒ Account

Returns a new instance of Account.



23
24
25
26
# File 'lib/nanook/account.rb', line 23

def initialize(rpc, )
  @rpc = rpc
  @account = .to_s
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Returns true if accounts are equal.

Parameters:

Returns:

  • (Boolean)

    true if accounts are equal



41
42
43
44
# File 'lib/nanook/account.rb', line 41

def ==(other)
  other.class == self.class &&
    other.id == id
end

#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.

This call returns information that may be based on unconfirmed blocks. These details should not be relied on for any process or integration that requires confirmed blocks. The pending balance is calculated from potentially unconfirmed blocks.

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:



253
254
255
256
257
258
259
260
261
262
# File 'lib/nanook/account.rb', line 253

def balance(unit: Nanook.default_unit)
  validate_unit!(unit)

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

#block_countInteger

Returns number of blocks for this account.

Returns:

  • (Integer)

    number of blocks for this account



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

def block_count
  rpc(:account_block_count, _access: :block_count)
end

#blocks(limit: 1000, sort: :asc) ⇒ Array<Nanook::Block>

Return blocks for the account.

Parameters:

  • limit (Integer) (defaults to: 1000)

    maximum number of history items to return. Defaults to 1000

  • sort (Symbol) (defaults to: :asc)

    default :asc. When set to :desc the blocks will be returned oldest to newest.

Returns:



169
170
171
# File 'lib/nanook/account.rb', line 169

def blocks(limit: 1000, sort: :asc)
  history(limit: limit, sort: sort).map { |i| i[:block] }
end

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

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

Example:

.delegators

Example response:

{
  Nanook::Account=>50.0,
  Nanook::Account=>961.64
}

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:

Raises:



71
72
73
74
75
76
77
78
79
80
81
82
83
# File 'lib/nanook/account.rb', line 71

def delegators(unit: Nanook.default_unit)
  validate_unit!(unit)

  response = rpc(:delegators, _access: :delegators, _coerce: Hash)

  r = response.map do |, balance|
    balance = raw_to_NANO(balance) if unit == :nano

    [(), balance]
  end

  Hash[r]
end

#delegators_countInteger

Number of accounts that have set this account as their representative.

Example:

.delegators_count # => 2

Returns:

  • (Integer)


92
93
94
# File 'lib/nanook/account.rb', line 92

def delegators_count
  rpc(:delegators_count, _access: :count)
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



114
115
116
117
118
119
120
121
122
# File 'lib/nanook/account.rb', line 114

def exists?
  begin
    response = rpc(:account_info)
  rescue Nanook::Error
    return false
  end

  !response.empty? && !response[:open_block].nil?
end

#hashInteger

The hash value is used along with #eql? by the Hash class to determine if two objects reference the same hash key.

Returns:

  • (Integer)


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

def hash
  id.hash
end

#history(limit: 1000, unit: Nanook.default_unit, sort: :asc) ⇒ Array<Hash{Symbol=>String|Float|Integer|Nanook::Account|NanookBlock}>

An account's history of send and receive payments.

This call may return results that include unconfirmed blocks, so it should not be used in any processes or integrations requiring only details from blocks confirmed by the network.

Example:

.history

Example response:

[
  {
   type: "send",
   account: Nanook::Account,
   amount: 2,
   block: Nanook::Block
  }
]

Parameters:

  • limit (Integer) (defaults to: 1000)

    maximum number of history items to return. Defaults to 1000

  • sort (Symbol) (defaults to: :asc)

    default :asc. When set to :desc the history will be returned oldest to newest.

  • 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|Float|Integer|Nanook::Account|NanookBlock}>)

    the history of send and receive payments for this account

Raises:



150
151
152
153
154
155
156
157
158
159
160
161
162
# File 'lib/nanook/account.rb', line 150

def history(limit: 1000, unit: Nanook.default_unit, sort: :asc)
  validate_unit!(unit)

  response = rpc(:account_history, count: limit, reverse: (sort == :desc), _access: :history, _coerce: Array)

  response.map do |history|
    history[:amount] = raw_to_NANO(history[:amount]) if unit == :nano
    history[:account] = (history[:account])
    history[:block] = as_block(history.delete(:hash)) # Rename the key from `hash` to `block`

    history
  end
end

#idString

The id of the account.

Example:

.id # => "nano_16u..."

Returns:

  • (String)

    the id of the account



35
36
37
# File 'lib/nanook/account.rb', line 35

def id
  @account
end

#info(unit: Nanook.default_unit) ⇒ Hash{Symbol=>String|Integer|Float|Nanook::Account|Nanook::Block|Time}

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: Nanook::Block,
  last_modified_at: Time,
  open_block: Nanook::Block,
  pending: 1.0,
  representative: Nanook::Account,
  representative_block: Nanook::Block,
  weight: 0.1
}

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=>String|Integer|Float|Nanook::Account|Nanook::Block|Time})

    information about the account containing:

    id

    The account id

    frontier

    The latest Block

    confirmation_height

    Confirmation height

    confirmation_height_frontier

    The Block of the confirmation height

    pending

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

    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

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

    last_modified_at

    Time of when the account was last modified in UTC

    representative

    Representative Nanook::Account

    block_count

    Number of blocks in the account's blockchain

    weight

    See #weight

Raises:



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

def info(unit: Nanook.default_unit)
  validate_unit!(unit)

  response = rpc(:account_info, representative: true, weight: true, pending: true)
  response.merge!(id: @account)
  response[:frontier] = as_block(response[:frontier]) if response[:frontier]
  response[:open_block] = as_block(response[:open_block]) if response[:open_block]
  response[:representative_block] = as_block(response[:representative_block]) if response[:representative_block]
  response[:representative] = (response[:representative]) if response[:representative]
  response[:confirmation_height_frontier] = as_block(response[:confirmation_height_frontier]) if response[:confirmation_height_frontier]
  response[:last_modified_at] = as_time(response.delete(:modified_timestamp))

  if unit == :nano
    response.merge!(
      balance: raw_to_NANO(response[:balance]),
      pending: raw_to_NANO(response[:pending]),
      weight: raw_to_NANO(response[:weight])
    )
  end

  response
end

#last_modified_atTime

The last modified time of the account in UTC. For many accounts on the node this will be the timestamp of when the node bootstrapped.

Example:

.last_modified_at # => Time

Returns:

  • (Time)

    last modified time of the account in UTC. Can be nil



188
189
190
# File 'lib/nanook/account.rb', line 188

def last_modified_at
  as_time(rpc(:account_info, _access: :modified_timestamp))
end

#ledger(limit: 1000, modified_since: 0, unit: Nanook.default_unit, sort: :asc) ⇒ Hash{Nanook::Account=>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:

 {
  Nanook::Account => {
    :frontier => Nanook::Block,
    :open_block => Nanook::Block,
    :representative_block => Nanook::Block,
    :representative => Nanook::Account,
    :balance => 1143.7,
    :last_modified_at => Time,
    :block_count => 4
    :weight => 5
    :pending => 2.0
  },
  Nanook::Account => { ... }
}

Parameters:

  • limit (Integer) (defaults to: 1000)

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

  • modified_since (Time) (defaults to: 0)

    optional. Return only accounts modified in the local database after this time (default is from the unix epoch)

  • sort (Symbol) (defaults to: :asc)

    default :asc. When set to :desc the ledger will be returned oldest to newest.

  • 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:

Raises:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
# File 'lib/nanook/account.rb', line 382

def ledger(limit: 1000, modified_since: 0, unit: Nanook.default_unit, sort: :asc)
  validate_unit!(unit)

  params = {
    count: limit,
    sorting: (sort == :desc),
    modified_since: modified_since.to_i,
    _access: :accounts,
    _coerce: Hash
  }

  response = rpc(:ledger, params)

  r = response.map do |, ledger|
    if unit == :nano
      ledger[:balance] = raw_to_NANO(ledger[:balance])
      ledger[:pending] = raw_to_NANO(ledger[:pending])
      ledger[:weight] = raw_to_NANO(ledger[:weight])
    end

    ledger[:last_modified_at] = as_time(ledger.delete(:modified_timestamp))
    ledger[:representative] = (ledger[:representative]) if ledger[:representative]
    ledger[:representative_block] = as_block(ledger[:representative_block]) if ledger[:representative_block]
    ledger[:open_block] = as_block(ledger[:open_block]) if ledger[:open_block]
    ledger[:frontier] = as_block(ledger[:frontier]) if ledger[:frontier]

    [(), ledger]
  end

  Hash[r]
end

#open_blockNanook::Block

Returns the open block for the account if it exists on the node.

Returns:



176
177
178
# File 'lib/nanook/account.rb', line 176

def open_block
  blocks(limit: 1, sort: :desc).first
end

#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ Array<Nanook::Block>, Array<Hash{Symbol=>Nanook::Block|Nanook::Account|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 # => [Nanook::Block, ..."]

Asking for more detail to be returned:

.pending(detailed: true)

Example response:

[
  {
    block: Nanook::Block,
    amount: 6,
    source: Nanook::Account
  },
  { ... }
]

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:

Raises:



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
# File 'lib/nanook/account.rb', line 451

def pending(limit: 1000, detailed: false, unit: Nanook.default_unit)
  validate_unit!(unit)

  params = {
    count: limit,
    _access: :blocks,
    _coerce: (detailed ? Hash : Array)
  }
  params[:source] = true if detailed

  response = rpc(:pending, params)

  unless detailed
    return response.map do |block|
      as_block(block)
    end
  end

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

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

#public_keyNanook::PublicKey

The public key of the account.

Example:

.public_key # => Nanook::PublicKey

Returns:



199
200
201
# File 'lib/nanook/account.rb', line 199

def public_key
  as_public_key(rpc(:account_key, _access: :key))
end

#representativeNanook::Account

The representative for the account.

Example:

.representative # => Nanook::Account

Returns:



210
211
212
213
# File 'lib/nanook/account.rb', line 210

def representative
  representative = rpc(:account_representative, _access: :representative)
  (representative) if representative
end

#to_sString Also known as: inspect

Returns:

  • (String)


346
347
348
# File 'lib/nanook/account.rb', line 346

def to_s
  "#{self.class.name}(id: \"#{short_id}\")"
end

#weight(unit: Nanook.default_unit) ⇒ Integer|Float

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 0.1% of the online voting weight and are on a node configured to vote can vote.

Example:

.weight # => 0

Returns:

  • (Integer|Float)

    the account's weight

Raises:



493
494
495
496
497
498
499
500
501
# File 'lib/nanook/account.rb', line 493

def weight(unit: Nanook.default_unit)
  validate_unit!(unit)

  weight = rpc(:account_weight, _access: :weight)

  return weight unless unit == :nano

  raw_to_NANO(weight)
end