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

Constant Summary collapse

MAX_TOKENS_COUNT =

Safe maximum number of tokens in the box Calculated from the max box size (4kb) limit and the size of the token (32 bytes)

100

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:



373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/sigma/ergo_box.rb', line 373

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:



401
402
403
404
405
406
 
# File 'lib/sigma/ergo_box.rb', line 401

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:



393
394
395
 
# File 'lib/sigma/ergo_box.rb', line 393

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

Instance Method Details

#==(ergo_box_two) ⇒ bool

Equality check

Parameters:

Returns:

  • (bool) 


489
490
491
 
# File 'lib/sigma/ergo_box.rb', line 489

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

#get_box_id ⇒ BoxId

Get box id

Returns:



410
411
412
413
414
 
# File 'lib/sigma/ergo_box.rb', line 410

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:



418
419
420
421
422
 
# File 'lib/sigma/ergo_box.rb', line 418

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) 


426
427
428
 
# File 'lib/sigma/ergo_box.rb', line 426

def get_creation_height
  ergo_lib_ergo_box_creation_height(self.pointer)
end

#get_ergo_tree ⇒ ErgoTree

Get ergo tree for box

Returns:



455
456
457
458
459
 
# File 'lib/sigma/ergo_box.rb', line 455

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:



434
435
436
437
438
439
440
441
442
443
 
# File 'lib/sigma/ergo_box.rb', line 434

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:



447
448
449
450
451
 
# File 'lib/sigma/ergo_box.rb', line 447

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) 


463
464
465
466
467
468
469
470
471
 
# File 'lib/sigma/ergo_box.rb', line 463

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:



476
477
478
479
480
481
482
483
484
 
# File 'lib/sigma/ergo_box.rb', line 476

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