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

#accountNanook::Account

Returns the Account of the block.

Example:

block. # => Nanook::Account

Returns:



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

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:



284
285
286
287
288
289
290
291
# File 'lib/nanook/block.rb', line 284

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:



301
302
303
304
305
306
307
308
# File 'lib/nanook/block.rb', line 301

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

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

  raw_to_NANO(balance)
end

#cancel_workBoolean

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)


449
450
451
# File 'lib/nanook/block.rb', line 449

def change?
  type == 'change'
end

#confirmBoolean

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)


316
317
318
# File 'lib/nanook/block.rb', line 316

def confirmed?
  memoized_info[:confirmed]
end

#epoch?Boolean

Returns true if block is type “epoch”.

Example:

block.epoch? # => true

Returns:

  • (Boolean)


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

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)


343
344
345
346
347
348
349
350
351
# File 'lib/nanook/block.rb', line 343

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

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


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

def hash
  id.hash
end

#heightInteger

Returns the height of the block.

Example:

block.height # => 5

Returns:

  • (Integer)


359
360
361
# File 'lib/nanook/block.rb', line 359

def height
  memoized_info[:height]
end

#idString

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:



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)


429
430
431
# File 'lib/nanook/block.rb', line 429

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.



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

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

#previousNanook::Block

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

Example:

block.previous # => Nanook::Block

Returns:



399
400
401
# File 'lib/nanook/block.rb', line 399

def previous
  memoized_info[:previous]
end

#receive?Boolean

Returns true if block is type “receive”.

Example:

block.receive? # => true

Returns:

  • (Boolean)


439
440
441
# File 'lib/nanook/block.rb', line 439

def receive?
  type == 'receive'
end

#representativeNanook::Account

Returns the Account of the block representative.

Example:

block.representative # => Nanook::Account

Returns:



262
263
264
# File 'lib/nanook/block.rb', line 262

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:



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

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)


419
420
421
# File 'lib/nanook/block.rb', line 419

def send?
  type == 'send'
end

#signatureString

Returns the block signature.

Example:

block.signature # => "82D41BC16F313E4B2243D14DFFA2FB04679C540C2095FEE7EAE0F2F26880AD56DD48D87A7CC5DD760C5B2D76EE2C205506AA557BF00B60D8DEE312EC7343A501"

Returns:

  • (String)


379
380
381
# File 'lib/nanook/block.rb', line 379

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



243
244
245
246
247
248
249
250
251
252
253
254
# File 'lib/nanook/block.rb', line 243

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

#timestampTime

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.



389
390
391
# File 'lib/nanook/block.rb', line 389

def timestamp
  memoized_info[:local_timestamp]
end

#to_sString Also known as: inspect

Returns:

  • (String)


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

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

#typeString

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.



409
410
411
# File 'lib/nanook/block.rb', line 409

def type
  memoized_info[:type]
end

#unconfirmed?Boolean Also known as: unchecked?

Returns true if block is unconfirmed.

Example:

block.unconfirmed? # => true

Returns:

  • (Boolean)


327
328
329
# File 'lib/nanook/block.rb', line 327

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



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

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

#workString

Returns the block work.

Example:

block.work # => "8a142e07a10996d5"

Returns:

  • (String)


369
370
371
# File 'lib/nanook/block.rb', line 369

def work
  memoized_info[:work]
end