Module ergo_lib_c_core::ergo_box
source · Expand description
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.
Structs
- Box id (32-byte digest)
- Box value in nanoERGs with bound checks
- 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 - Pair of <value, tokens> for a box
- Contains the same fields as
ErgoBox
, except for transaction id and index, that will be calculated after full transaction formation. UseErgoBoxCandidateBuilder
to create an instance.
Enums
- Type for representing box registers R4 - R9
Functions
- Parse box id (32 byte digest) from base16-encoded string
- Convert to serialized bytes. Key assumption: 32 bytes have been allocated at the address pointed-to by
output
. - Base16 encoded string
- Get value as signed 64-bit long
- Create from i64 with bounds check
- Recommended (safe) minimal box value to use in case box size estimation is unavailable. Allows box size upto 2777 bytes with current min box value per byte of 360 nanoERGs
- Create a new box value which is the sum of the arguments, returning error if value is out of bounds.
- Number of units inside one ERGO (i.e. one ERG using nano ERG representation)
- Create new instance
- Tokens part of the box
- Value part of the box
- Get box id
- Get box value in nanoERGs
- Get box creation height
- Get ergo tree for box
- Returns value (ErgoTree constant) stored in the register or None if the register is empty
- Get tokens for box
- Get box creation height
- Get ergo tree for box
- Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
- Make a new box with:
value
- amount of money associated with the boxcontract
- guarding contract, which should be evaluated to true in order to open(spend) this boxcreation_height
- height when a transaction containing the box is created.tx_id
- transaction id in which this box was “created” (participated in outputs)index
- index (in outputs) in the transaction - Returns value (ErgoTree constant) stored in the register or None if the register is empty
- JSON representation as text (compatible with Ergo Node/Explorer API, numbers are encoded as numbers)
- JSON representation according to EIP-12 https://github.com/ergoplatform/eips/pull/23
- Get tokens for box
- Get box value in nanoERGs