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:



278
279
280
 
# File 'lib/nanook/block.rb', line 278

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:



290
291
292
293
294
295
296
297
 
# File 'lib/nanook/block.rb', line 290

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:



307
308
309
310
311
312
313
314
 
# File 'lib/nanook/block.rb', line 307

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) 


465
466
467
 
# File 'lib/nanook/block.rb', line 465

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) 


322
323
324
 
# File 'lib/nanook/block.rb', line 322

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



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/nanook/block.rb', line 245

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) 


475
476
477
 
# File 'lib/nanook/block.rb', line 475

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) 


349
350
351
352
353
354
355
356
357
 
# File 'lib/nanook/block.rb', line 349

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) 


375
376
377
 
# File 'lib/nanook/block.rb', line 375

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.



365
366
367
 
# File 'lib/nanook/block.rb', line 365

def next
  successors(limit: 1).first
end

#open? ⇒ Boolean

Returns true if block is type “open”.

Example:

block.open? # => true

Returns:

  • (Boolean) 


445
446
447
 
# File 'lib/nanook/block.rb', line 445

def open?
  type == 'open'
end

#pending? ⇒ Boolean

Returns true if block is a pending block.

Example:

block.pending? #=> false

Returns:

  • (Boolean) —

    signalling if the block is a pending block.



226
227
228
 
# File 'lib/nanook/block.rb', line 226

def pending?
  rpc(:pending_exists, :hash, _access: :exists) == 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.



415
416
417
 
# File 'lib/nanook/block.rb', line 415

def previous
  memoized_info[:previous]
end

#receive? ⇒ Boolean

Returns true if block is type “receive”.

Example:

block.receive? # => true

Returns:

  • (Boolean) 


455
456
457
 
# File 'lib/nanook/block.rb', line 455

def receive?
  type == 'receive'
end

#representative ⇒ Nanook::Account

Returns the Account of the block representative.

Example:

block.representative # => Nanook::Account

Returns:



268
269
270
 
# File 'lib/nanook/block.rb', line 268

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) 


435
436
437
 
# File 'lib/nanook/block.rb', line 435

def send?
  type == 'send'
end

#signature ⇒ String

Returns the block signature.

Example:

block.signature # => "82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501"

Returns:

  • (String) 


395
396
397
 
# File 'lib/nanook/block.rb', line 395

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.



405
406
407
 
# File 'lib/nanook/block.rb', line 405

def timestamp
  memoized_info[:local_timestamp]
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


480
481
482
 
# File 'lib/nanook/block.rb', line 480

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.



425
426
427
 
# File 'lib/nanook/block.rb', line 425

def type
  memoized_info[:type]
end

#unconfirmed? ⇒ Boolean Also known as: unchecked?

Returns true if block is unconfirmed.

Example:

block.unconfirmed? # => true

Returns:

  • (Boolean) 


333
334
335
 
# File 'lib/nanook/block.rb', line 333

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) 


385
386
387
 
# File 'lib/nanook/block.rb', line 385

def work
  memoized_info[:work]
end