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(allow_unconfirmed: false, 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:

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

    false by default. When false, balance will only include blocks on this account that have already been confirmed and pending will only include incoming send blocks that have already been confirmed on the sending account.

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



256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/nanook/account.rb', line 256

def balance(allow_unconfirmed: false, unit: Nanook.default_unit)
  validate_unit!(unit)

  params = {
    include_only_confirmed: !allow_unconfirmed
  }

  rpc(:account_balance, params).tap do |r|
    if unit == :nano
      r[:balance] = raw_to_NANO(r[:balance])
      r[:pending] = 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



272
273
274
 
# File 'lib/nanook/account.rb', line 272

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_count ⇒ Integer

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

#hash ⇒ Integer

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

#id ⇒ String

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(allow_unconfirmed: false, 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:

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

    false by default. When false only confirmed balance pending, and representative values are returned.

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



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/nanook/account.rb', line 331

def info(allow_unconfirmed: false, unit: Nanook.default_unit)
  validate_unit!(unit)

  params = {
    representative: true,
    weight: true,
    pending: true,
    include_confirmed: !allow_unconfirmed
  }

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

  # The RPC returned confirmed data when the `include_confirmed: true`
  # has been passed. Normalize this data to the same keys as when
  # unconfirmed data can be returned.
  unless allow_unconfirmed
    response[:balance] = response.delete(:confirmed_balance)
    response[:pending] = response.delete(:confirmed_pending)
    response[:representative] = response.delete(:confirmed_representative)
    response[:frontier] = response.delete(:confirmed_frontier)
    response[:confirmation_height] = response.delete(:confirmed_height)
  end

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

  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.compact
end

#last_modified_at ⇒ Time

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:



410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/nanook/account.rb', line 410

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])
    ledger[:representative_block] = as_block(ledger[:representative_block])
    ledger[:open_block] = as_block(ledger[:open_block])
    ledger[:frontier] = as_block(ledger[:frontier])

    [(), ledger]
  end

  Hash[r]
end

#open_block ⇒ Nanook::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, allow_unconfirmed: false, unit: Nanook.default_unit, sorted: false) ⇒ 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)

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

    false by default. When false only returns block which have their confirmation height set or are undergoing confirmation height processing.

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

    false by default. Additionally sorts the blocks by their amounts in descending order.

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



482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
 
# File 'lib/nanook/account.rb', line 482

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

  params = {
    count: limit,
    sorting: sorted,
    include_only_confirmed: !allow_unconfirmed,
    _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_key ⇒ Nanook::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

#representative ⇒ Nanook::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)
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


374
375
376
 
# File 'lib/nanook/account.rb', line 374

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:



526
527
528
529
530
531
532
533
534
 
# File 'lib/nanook/account.rb', line 526

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