Class: Sigma::ErgoBox

Inherits:
Object
  • Object
show all
Extended by:
FFI::Library
Defined in:
lib/sigma/ergo_box.rb

Overview

Box (aka coin, or an unspent output) is a basic concept of a UTXO-based cryptocurrency.

In Bitcoin, such an object is associated with some monetary value (arbitrary,
but with predefined precision, so we use integer arithmetic to work with the value),
and also a guarding script (aka proposition) to protect the box from unauthorized opening.

In other way, a box is a state element locked by some proposition (ErgoTree).

In Ergo, box is just a collection of registers, some with mandatory types and semantics,
others could be used by applications in any way.
We add additional fields in addition to amount and proposition~(which stored in the registers R0 and R1).
Namely, register R2 contains additional tokens (a sequence of pairs (token identifier, value)).
Register R3 contains height when block got included into the blockchain and also transaction
identifier and box index in the transaction outputs.
Registers R4-R9 are free for arbitrary usage.

A transaction is unsealing a box. As a box can not be open twice, any further valid transaction
can not be linked to the same box.

Ergo box, that is taking part in some transaction on the chain Differs with “ErgoBoxCandidate“ by added transaction id and an index in the input of that transaction

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#pointer ⇒ Object

Returns the value of attribute pointer.



360
361
362
 
# File 'lib/sigma/ergo_box.rb', line 360

def pointer
  @pointer
end

Class Method Details

.create(box_value:, creation_height:, contract:, tx_id:, index:, tokens:) ⇒ ErgoBox

Create a new box

Parameters:

  • box_value: (BoxValue) —

    amount of money associated with box

  • creation_height: (Integer) —

    height when a transaction containing the box is created

  • contract: (Contract) —

    guarding contract which should be evaluted to true in order to open(spend) this box

  • tx_id: (TxId) —

    transaction id in which this box was “created” (participated in outputs)

  • index: (Integer) —

    index (in outputs) in the transaction

Returns:



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/sigma/ergo_box.rb', line 369

def self.create(box_value:,
               creation_height:,
               contract:,
               tx_id:,
               index:,
               tokens:)

  eb_pointer = FFI::MemoryPointer.new(:pointer)
  error_pointer = ergo_lib_ergo_box_new(box_value.pointer, creation_height,
    contract.pointer, tx_id.pointer, index, tokens.pointer, eb_pointer)
  #ergo_lib_ergo_box_new(nil, 0, nil, nil, 0, nil, eb_pointer)
  #Util.check_error!(error_pointer)
  
  init(eb_pointer) 
end

.with_json(json_str) ⇒ ErgoBox

Parse and create from json. Supports Ergo Node/Explorer API and box values and token amount encoded as strings

Parameters:

  • json_str (String)

Returns:



397
398
399
400
401
402
 
# File 'lib/sigma/ergo_box.rb', line 397

def self.with_json(json_str)
  pointer = FFI::MemoryPointer.new(:pointer)
  error = ergo_lib_ergo_box_from_json(json_str, pointer)
  Util.check_error!(error)
  init(pointer)
end

.with_raw_pointer(unread_pointer) ⇒ ErgoBox

Note:

A user of sigma_rb generally does not need to call this function

Takes ownership of an existing ErgoBox Pointer.

Parameters:

  • pointer (FFI::MemoryPointer)

Returns:



389
390
391
 
# File 'lib/sigma/ergo_box.rb', line 389

def self.with_raw_pointer(unread_pointer)
  init(unread_pointer)
end

Instance Method Details

#==(ergo_box_two) ⇒ bool

Equality check

Parameters:

Returns:

  • (bool) 


485
486
487
 
# File 'lib/sigma/ergo_box.rb', line 485

def ==(ergo_box_two)
  ergo_lib_ergo_box_eq(self.pointer, ergo_box_two.pointer)
end

#get_box_id ⇒ BoxId

Get box id

Returns:



406
407
408
409
410
 
# File 'lib/sigma/ergo_box.rb', line 406

def get_box_id
  box_id_ptr = FFI::MemoryPointer.new(:pointer)
  ergo_lib_ergo_box_id(self.pointer, box_id_ptr)
  Sigma::BoxId.with_raw_pointer(box_id_ptr)
end

#get_box_value ⇒ BoxValue

Get box value

Returns:



414
415
416
417
418
 
# File 'lib/sigma/ergo_box.rb', line 414

def get_box_value
  box_value_ptr = FFI::MemoryPointer.new(:pointer)
  ergo_lib_ergo_box_value(self.pointer, box_value_ptr)
  Sigma::BoxValue.with_raw_pointer(box_value_ptr)
end

#get_creation_height ⇒ Integer

Get box creation height

Returns:

  • (Integer) 


422
423
424
 
# File 'lib/sigma/ergo_box.rb', line 422

def get_creation_height
  ergo_lib_ergo_box_creation_height(self.pointer)
end

#get_ergo_tree ⇒ ErgoTree

Get ergo tree for box

Returns:



451
452
453
454
455
 
# File 'lib/sigma/ergo_box.rb', line 451

def get_ergo_tree
  ergo_tree_ptr = FFI::MemoryPointer.new(:pointer)
  ergo_lib_ergo_box_ergo_tree(self.pointer, ergo_tree_ptr)
  Sigma::ErgoTree.with_raw_pointer(ergo_tree_ptr)
end

#get_register_value(register_id) ⇒ Constant?

Returns value (ErgoTree constant) stored in the register or ‘nil` if the register is empty

Parameters:

  • register_id (Integer)

Returns:

See Also:



430
431
432
433
434
435
436
437
438
439
 
# File 'lib/sigma/ergo_box.rb', line 430

def get_register_value(register_id)
  constant_ptr = FFI::MemoryPointer.new(:pointer)
  res = ergo_lib_ergo_box_register_value(self.pointer, register_id, constant_ptr)
  Util.check_error!(res[:error])
  if res[:is_some]
    Sigma::Constant.with_raw_pointer(constant_ptr)
  else
    nil
  end
end

#get_tokens ⇒ Tokens

Get tokens for box

Returns:



443
444
445
446
447
 
# File 'lib/sigma/ergo_box.rb', line 443

def get_tokens
  tokens_ptr = FFI::MemoryPointer.new(:pointer)
  ergo_lib_ergo_box_tokens(self.pointer, tokens_ptr)
  Sigma::Tokens.with_raw_pointer(tokens_ptr)
end

#to_json ⇒ String

JSON representation as text (compatible with Ergo Node/Explorer API, numbers are encoded as numbers)

Returns:

  • (String) 


459
460
461
462
463
464
465
466
467
 
# File 'lib/sigma/ergo_box.rb', line 459

def to_json
  s_ptr = FFI::MemoryPointer.new(:pointer, 1)
  error = ergo_lib_ergo_box_to_json(self.pointer, s_ptr)
  Util.check_error!(error)
  s_ptr = s_ptr.read_pointer()
  str = s_ptr.read_string().force_encoding('UTF-8')
  Util.ergo_lib_delete_string(s_ptr)
  str
end

#to_json_eip12 ⇒ String

JSON representation according to EIP-12

Returns:

  • (String)

See Also:



472
473
474
475
476
477
478
479
480
 
# File 'lib/sigma/ergo_box.rb', line 472

def to_json_eip12
  s_ptr = FFI::MemoryPointer.new(:pointer, 1)
  error = ergo_lib_ergo_box_to_json_eip12(self.pointer, s_ptr)
  Util.check_error!(error)
  s_ptr = s_ptr.read_pointer()
  str = s_ptr.read_string().force_encoding('UTF-8')
  Util.ergo_lib_delete_string(s_ptr)
  str
end