Class: Nanook::Block

Inherits:
Object
  • Object
show all
Includes:
Util
Defined in:
lib/nanook/block.rb

Overview

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

A block is represented by a unique id like this:

"FBF8B0E6623A31AB528EBD839EEAA91CAFD25C12294C46754E45FD017F7939EB"

Initialize this class through the convenient Nanook#block method:

nanook = Nanook.new
block = nanook.block("FBF8B0E...")

Or compose the longhand way like this:

rpc_conn = Nanook::Rpc.new
block = Nanook::Block.new(rpc_conn, "FBF8B0E...")

Constant Summary

Constants included from Util

Util::STEP

Instance Method Summary collapse

Constructor Details

#initialize(rpc, block) ⇒ Block

Returns a new instance of Block.



25
26
27
28
 
# File 'lib/nanook/block.rb', line 25

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

Instance Method Details

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

Returns true if blocks are equal.

Parameters:

Returns:

  • (Boolean) —

    true if blocks are equal



43
44
45
46
 
# File 'lib/nanook/block.rb', line 43

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

#account ⇒ Nanook::Account

Returns the Account of the block.

Example:

block. # => Nanook::Account

Returns:



286
287
288
 
# File 'lib/nanook/block.rb', line 286

def 
  memoized_info[:account]
end

#amount(unit: Nanook.default_unit) ⇒ Float

Returns the amount of the block.

Example:

block.amount # => 3.01

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:

  • (Float)

Raises:



298
299
300
301
302
303
304
305
 
# File 'lib/nanook/block.rb', line 298

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

  amount = memoized_info[:amount]
  return amount unless unit == :nano

  raw_to_NANO(amount)
end

#ancestors(limit: 1000, offset: 0) ⇒ Object Also known as: chain

Returns a consecutive list of block hashes in the account chain from (but not including) block back to count (direction from frontier back to open block, from newer blocks to older). Will list all blocks back to the open block of this chain when count is set to “-1”.

See also #descendants.

Example:

block.ancestors(limit: 2)

Example reponse:

[Nanook::Block, ...]

Parameters:

  • limit (Integer) (defaults to: 1000) —

    maximum number of block hashes to return (default is 1000)

  • offset (Integer) (defaults to: 0) —

    return the account chain block hashes offset by the specified number of blocks (default is 0)



85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/nanook/block.rb', line 85

def ancestors(limit: 1000, offset: 0)
  # The RPC includes this block in its response, and Nanook will remove it from the results.
  # Increment the limit by 1 to account for this (a limit of -1 is valid and means no limit).
  limit += 1 if limit > 0
  params = {
    count: limit,
    offset: offset,
    _access: :blocks,
    _coerce: Array
  }

  response = rpc(:chain, :block, params)[1..].to_a
  response.map { |block| as_block(block) }
end

#balance(unit: Nanook.default_unit) ⇒ Float

Returns the balance of the account at the time the block was created.

Example:

block.balance # => 3.01

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:

  • (Float)

Raises:



315
316
317
318
319
320
321
322
 
# File 'lib/nanook/block.rb', line 315

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

  balance = memoized_info[:balance]
  return balance unless unit == :nano

  raw_to_NANO(balance)
end

#cancel_work ⇒ Boolean

Stop generating work for a block.

Example:

block.cancel_work # => true

Returns:

  • (Boolean) —

    signalling if the action was successful



64
65
66
 
# File 'lib/nanook/block.rb', line 64

def cancel_work
  rpc(:work_cancel, :hash).empty?
end

#change? ⇒ Boolean

Returns true if block is type “change” (change of representative).

Example:

block.change? # => true

Returns:

  • (Boolean) 


473
474
475
 
# File 'lib/nanook/block.rb', line 473

def change?
  type == 'change'
end

#confirm ⇒ Boolean

Request confirmation for a block from online representative nodes. Will return immediately with a boolean to indicate if the request for confirmation was successful. Note that this boolean does not indicate the confirmation status of the block.

Example:

block.confirm # => true

Returns:

  • (Boolean) —

    if the confirmation request was sent successful



110
111
112
 
# File 'lib/nanook/block.rb', line 110

def confirm
  rpc(:block_confirm, :hash, _access: :started) == 1
end

#confirmed? ⇒ Boolean Also known as: checked?

Returns true if block is confirmed.

Example:

block.confirmed # => true

Returns:

  • (Boolean) 


330
331
332
 
# File 'lib/nanook/block.rb', line 330

def confirmed?
  memoized_info[:confirmed]
end

#descendants(limit: 1000, offset: 0) ⇒ Array<Nanook::Block> Also known as: successors

Returns an Array of block hashes in the account chain from (but not including) this block up to count (direction from open block up to frontier, from older blocks to newer). Will list all blocks up to frontier (latest block) of this chain when count is set to -1.

See also #ancestors.

Example:

block.descendants # => [Nanook::Block, .. ]

Parameters:

  • limit (Integer) (defaults to: 1000) —

    maximum number of send/receive block hashes to return in the chain (default is 1000)

  • offset (Integer) (defaults to: 0) —

    return the account chain block hashes offset by the specified number of blocks (default is 0)

Returns:

  • (Array<Nanook::Block>) —

    blocks in the account chain ending at this block



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/nanook/block.rb', line 253

def descendants(limit: 1000, offset: 0)
  # The RPC includes this block in its response, and Nanook will remove it from the results.
  # Increment the limit by 1 to account for this (a limit of -1 is valid and means no limit).
  limit += 1 if limit > 0

  params = {
    count: limit,
    offset: offset,
    _access: :blocks,
    _coerce: Array
  }

  response = rpc(:successors, :block, params)[1..].to_a
  response.map { |block| as_block(block) }
end

#epoch? ⇒ Boolean

Returns true if block is type “epoch”.

Example:

block.epoch? # => true

Returns:

  • (Boolean) 


483
484
485
 
# File 'lib/nanook/block.rb', line 483

def epoch?
  type == 'epoch'
end

#exists?(allow_unchecked: false) ⇒ Boolean

Returns true if block exists in the node's ledger. This will return false for blocks that exist on the nano ledger but have not yet synchronized to the node.

Example:

block.exists? # => false
block.exists?(allow_unchecked: true) # => true

Parameters:

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

    defaults to false

Returns:

  • (Boolean) 


357
358
359
360
361
362
363
364
365
 
# File 'lib/nanook/block.rb', line 357

def exists?(allow_unchecked: false)
  begin
    allow_unchecked ? memoized_info : info
  rescue Nanook::NodeRpcError
    return false
  end

  true
end

#generate_work(use_peers: false) ⇒ String

Generate work for a block.

Example:

block.generate_work # => "2bf29ef00786a6bc"

Parameters:

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

    if set to true, then the node will query its work peers (if it has any, see WorkPeer#list). When false, the node will only generate work locally (default is false)

Returns:

  • (String) —

    the work id of the work completed.



123
124
125
 
# File 'lib/nanook/block.rb', line 123

def generate_work(use_peers: false)
  rpc(:work_generate, :hash, use_peers: use_peers, _access: :work)
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) 


53
54
55
 
# File 'lib/nanook/block.rb', line 53

def hash
  id.hash
end

#height ⇒ Integer

Returns the height of the block.

Example:

block.height # => 5

Returns:

  • (Integer) 


383
384
385
 
# File 'lib/nanook/block.rb', line 383

def height
  memoized_info[:height]
end

#id ⇒ String

Returns the block hash id.

Example:

block.id #=> "FBF8B0E..."

Returns:

  • (String) —

    the block hash id



37
38
39
 
# File 'lib/nanook/block.rb', line 37

def id
  @block
end

#info(allow_unchecked: false, unit: Nanook.default_unit) ⇒ Object

Returns a Hash of information about the block.

Examples:

block.info
block.info(allow_unchecked: true)

Example response:

{
  "account": Nanook::Account,
  "amount": 34.2,
  "balance": 2.3
  "height": 58,
  "local_timestamp": Time,
  "confirmed": true,
  "type": "send",
  "account": Nanook::Account,
  "previous": Nanook::Block,
  "representative": Nanook::Account,
  "link": Nanook::Block,
  "link_as_account": Nanook::Account,
  "signature": "82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501",
  "work": "8a142e07a10996d5"
}

Parameters:

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

    (default is false). If true, information can be returned about blocks that are unchecked (unverified).

Raises:



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/nanook/block.rb', line 157

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

  # Params for both `unchecked_get` and `block_info` calls
  params = {
    json_block: true,
    _coerce: Hash
  }

  begin
    response = rpc(:block_info, :hash, params)
    response.merge!(confirmed: true)
  rescue Nanook::NodeRpcError => e
    raise e unless allow_unchecked

    response = rpc(:unchecked_get, :hash, params)
    response.merge!(confirmed: false)
  end

  parse_info_response(response, unit)
end

#next ⇒ Nanook::Block

Returns the Nanook::Block of the next (newer) block in the account chain.

Example:

block.next # => Nanook::Block

Returns:

  • (Nanook::Block) —

    next (newer) block in the account chain. Can be nil.



373
374
375
 
# File 'lib/nanook/block.rb', line 373

def next
  successors(limit: 1).first
end

#open? ⇒ Boolean

Returns true if block is type “open”.

Example:

block.open? # => true

Returns:

  • (Boolean) 


453
454
455
 
# File 'lib/nanook/block.rb', line 453

def open?
  type == 'open'
end

#pending?(allow_unconfirmed: false) ⇒ Boolean

Returns true if block is a pending block.

Example:

block.pending? #=> false

Parameters:

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

    false by default. When false, will only include blocks which have their confirmation height set or are undergoing confirmation height processing.

Returns:

  • (Boolean) —

    signalling if the block is a pending block.



229
230
231
232
233
234
235
236
 
# File 'lib/nanook/block.rb', line 229

def pending?(allow_unconfirmed: false)
  params = {
    include_only_confirmed: !allow_unconfirmed,
    _access: :exists
  }

  rpc(:pending_exists, :hash, params) == 1
end

#previous ⇒ Nanook::Block

Returns the Nanook::Block of the previous (older) block in the account chain.

Example:

block.previous # => Nanook::Block

Returns:

  • (Nanook::Block) —

    previous (older) block in the account chain. Can be nil.



423
424
425
 
# File 'lib/nanook/block.rb', line 423

def previous
  memoized_info[:previous]
end

#receive? ⇒ Boolean

Returns true if block is type “receive”.

Example:

block.receive? # => true

Returns:

  • (Boolean) 


463
464
465
 
# File 'lib/nanook/block.rb', line 463

def receive?
  type == 'receive'
end

#representative ⇒ Nanook::Account

Returns the Account of the block representative.

Example:

block.representative # => Nanook::Account

Returns:



276
277
278
 
# File 'lib/nanook/block.rb', line 276

def representative
  memoized_info[:representative]
end

#republish(destinations: nil, sources: nil) ⇒ Array<Nanook::Block>

Republish blocks starting at this block up the account chain back to the nano network.

Example:

block.republish # => [Nanook::Block, ...]

Returns:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/nanook/block.rb', line 200

def republish(destinations: nil, sources: nil)
  if !destinations.nil? && !sources.nil?
    raise ArgumentError, 'You must provide either destinations or sources but not both'
  end

  params = {
    _access: :blocks,
    _coerce: Array
  }

  params[:destinations] = destinations unless destinations.nil?
  params[:sources] = sources unless sources.nil?
  params[:count] = 1 if destinations || sources

  rpc(:republish, :hash, params).map do |block|
    as_block(block)
  end
end

#send? ⇒ Boolean

Returns true if block is type “send”.

Example:

block.send? # => true

Returns:

  • (Boolean) 


443
444
445
 
# File 'lib/nanook/block.rb', line 443

def send?
  type == 'send'
end

#signature ⇒ String

Returns the block signature.

Example:

block.signature # => "82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501"

Returns:

  • (String) 


403
404
405
 
# File 'lib/nanook/block.rb', line 403

def signature
  memoized_info[:signature]
end

#timestamp ⇒ Time

Returns the timestamp of when the node saw the block.

Example:

block.timestamp # => 2018-05-30 16:41:48 UTC

Returns:

  • (Time) —

    Time in UTC of when the node saw the block. Can be nil.



413
414
415
 
# File 'lib/nanook/block.rb', line 413

def timestamp
  memoized_info[:local_timestamp]
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


488
489
490
 
# File 'lib/nanook/block.rb', line 488

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

#type ⇒ String

Returns the type of the block. One of “open”, “send”, “receive”, “change”, “epoch”.

Example:

block.type # => "open"

Returns:

  • (String) —

    type of block. Returns nil for unconfirmed blocks.



433
434
435
 
# File 'lib/nanook/block.rb', line 433

def type
  memoized_info[:type]
end

#unconfirmed? ⇒ Boolean Also known as: unchecked?

Returns true if block is unconfirmed.

Example:

block.unconfirmed? # => true

Returns:

  • (Boolean) 


341
342
343
 
# File 'lib/nanook/block.rb', line 341

def unconfirmed?
  !confirmed?
end

#valid_work?(work) ⇒ Boolean

Returns true if work is valid for the block.

Example:

block.valid_work?("2bf29ef00786a6bc") # => true

Parameters:

  • work (String) —

    the work id to check is valid

Returns:

  • (Boolean) —

    signalling if work is valid for the block



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

def valid_work?(work)
  response = rpc(:work_validate, :hash, work: work)
  response[:valid_all] == 1 || response[:valid_receive] == 1
end

#work ⇒ String

Returns the block work.

Example:

block.work # => "8a142e07a10996d5"

Returns:

  • (String) 


393
394
395
 
# File 'lib/nanook/block.rb', line 393

def work
  memoized_info[:work]
end