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:



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

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:



280
281
282
283
284
285
286
287
 
# File 'lib/nanook/block.rb', line 280

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

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

  raw_to_NANO(amount)
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:



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

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

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

Returns a consecutive list of block hashes in the account chain starting at 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”. The requested block hash is included in the answer.

See also #successors.

Example:

block.chain(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)



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

def chain(limit: 1000, offset: 0)
  params = {
    count: limit,
    offset: offset,
    _access: :blocks,
    _coerce: Array
  }

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

#change? ⇒ Boolean

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

Example:

block.change? # => true

Returns:

  • (Boolean) 


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

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



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

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) 


312
313
314
 
# File 'lib/nanook/block.rb', line 312

def confirmed?
  memoized_info[:confirmed]
end

#epoch? ⇒ Boolean

Returns true if block is type “epoch”.

Example:

block.epoch? # => true

Returns:

  • (Boolean) 


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

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) 


339
340
341
342
343
344
345
346
347
 
# File 'lib/nanook/block.rb', line 339

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.



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

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) 


355
356
357
 
# File 'lib/nanook/block.rb', line 355

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::,
  "amount": 34.2,
  "balance": 2.3
  "height": 58,
  "local_timestamp": Time,
  "confirmed": true,
  "type": "send",
  "account": Nanook::,
  "previous": Nanook::Block,
  "representative": Nanook::,
  "link": Nanook::Block,
  "link_as_account": Nanook::,
  "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:



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

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

#open? ⇒ Boolean

Returns true if block is type “open”.

Example:

block.open? # => true

Returns:

  • (Boolean) 


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

def open?
  type == 'open'
end

#pending? ⇒ Boolean

Example:

block.pending? #=> false

Returns:

  • (Boolean) —

    signalling if the block is a pending block.



221
222
223
 
# File 'lib/nanook/block.rb', line 221

def pending?
  rpc(:pending_exists, :hash, _access: :exists) == 1
end

#previous ⇒ Nanook::Block

Returns the Nanook::Block of the previous block in the chain.

Example:

block.previous # => Nanook::Block

Returns:



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

def previous
  memoized_info[:previous]
end

#receive? ⇒ Boolean

Returns true if block is type “receive”.

Example:

block.receive? # => true

Returns:

  • (Boolean) 


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

def receive?
  type == 'receive'
end

#representative ⇒ Nanook::Account

Returns the Account of the block representative.

Example:

block.representative # => Nanook::Account

Returns:



258
259
260
 
# File 'lib/nanook/block.rb', line 258

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:



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

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) 


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

def send?
  type == 'send'
end

#signature ⇒ String

Returns the block signature.

Example:

block.signature # => "82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501"

Returns:

  • (String) 


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

def signature
  memoized_info[:signature]
end

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

Returns an Array of block hashes in the account chain ending at this block.

See also #chain.

Example:

block.successors # => [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



239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/nanook/block.rb', line 239

def successors(limit: 1000, offset: 0)
  params = {
    count: limit,
    offset: offset,
    _access: :blocks,
    _coerce: Array
  }

  rpc(:successors, :block, params).map do |block|
    as_block(block)
  end
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.



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

def timestamp
  memoized_info[:local_timestamp]
end

#to_s ⇒ String Also known as: inspect

Returns:

  • (String) 


460
461
462
 
# File 'lib/nanook/block.rb', line 460

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.



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

def type
  memoized_info[:type]
end

#unconfirmed? ⇒ Boolean Also known as: unchecked?

Returns true if block is unconfirmed.

Example:

block.unconfirmed? # => true

Returns:

  • (Boolean) 


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

def unconfirmed?
  !confirmed?
end

#valid_work?(work) ⇒ Boolean

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



184
185
186
187
 
# File 'lib/nanook/block.rb', line 184

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) 


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

def work
  memoized_info[:work]
end