Expand description
C bindings for ergo-lib
Macros§
ergo-lib
uses a number of collection types that are simple wrappers aroundVec
. We have a generic type for such a collection inergo-lib-c-core::collections::Collection
. A limitation ofcbindgen
is that it cannot process generic functions. This macro generates a C-compatible interface for such a collection for any desired type T.- Generates an equality function for FFI
Structs§
- Address wrapper
- Convenience type to allow us to pass Rust bools (with possible error) through FFI to the C side.
- Convenience type to allow us to pass Rust enums with
u8
representation through FFI to the C side. - Convenience type to allow us to pass Rust
Option<_>
types through FFI to C side. - Convenience type to allow us to pass Rust CStrings through FFI to C side (as pointers). Note it is the responsibility of the caller to free the Rust CString. For an example, see MnemonicGenerator in the Swift bindings.
Enums§
- Network type
Traits§
Functions§
- Serializes a BatchMerkleProof to json representation
- Delete
BlockHeader
- Parse BlockHeader array from JSON (Node API)
- Get
BlockHeader
s id - Copy the contents of
transactions_root
field tooutput
. Key assumption: exactly 32 bytes of memory have been allocated at the address pointed-to byoutput
. - Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Delete
BlockId
- Convert a hex string into a BlockId
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Drop
BoxId
- Parse box id (32 byte digest) from base16-encoded string
- Returns byte array (32 bytes) Note: it’s imperative that
output
points to a valid block of memory of 32 bytes. - Base16 encoded string
- Selected boxes to spend as transaction inputs
- Selected boxes to use as change
- Drop
BoxSelection
- Create a selection to easily inject custom selection algorithms
- Get value as signed 64-bit long
- Drop
BoxValue
- 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, with bounds check.
- Number of units inside one ERGO (i.e. one ERG using nano ERG representation)
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Drop
CommitmentHint
- Drop
ContextExtension
- Create new empty ContextExtension instance
- Returns constant with given key or None if key doesn’t exist or error if constants parsing were failed
- Returns all keys (represented as u8 values) in the map
- Returns the number of elements in the collection
- Set the supplied pair in the ContextExtension
- Compiles a contract from ErgoScript source code
- Drop
Contract
- Get the ErgoTree of the contract
- Create new contract from ErgoTree
- Create new contract that allow spending of the guarded box by a given recipient
- Get box id
- Drop
DataInput
- Parse box id (32 byte digest)
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Drop
ErgoBoxAssetsData
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Create new instance
- Tokens part of the box
- Value part of the box
- Calculate serialized box size(in bytes)
- Get box value in nanoERGs
- Add given token id and token amount
- Build the box candidate
- Calculate serialized box size(in bytes)
- Drop
ErgoBoxCandidateBuilder
- Delete register value(make register empty) for the given register id (R4-R9)
- Get minimal value (per byte of the serialized box size)
- Mint token, as defined in https://github.com/ergoplatform/eips/blob/master/eip-0004.md
token
- token id(box id of the first input box in transaction) and token amount,token_name
- token name (will be encoded in R4),token_desc
- token description (will be encoded in R5),num_decimals
- number of decimals (will be encoded in R6) - Create builder with required box parameters:
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. It should not exceed height of the block, containing the transaction with this box. - Returns register value for the given register id (R4-R9), or None if the register is empty
- Set minimal value (per byte of the serialized box size)
- Set register with a given id (R4-R9) to the given value
- Set new box value
- Get box value
- Calculate minimal box value for the current box serialized size(in bytes)
- Get box creation height
- Drop
ErgoBoxCandidate
- Get ergo tree for box
- Returns value (ErgoTree constant) stored in the register or None if the register is empty
- Get tokens for box
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Get box creation height
- Drop
ErgoBox
- Get ergo tree for box
- Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
- Get box id
- 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
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Create new context from pre-header
- Determine number of bytes of the serialized ErgoTree
- Get constants number as stored in serialized ErgoTree or error if the parsing of constants is failed
- Drop
ErgoTree
- Decode from base16 encoded serialized ErgoTree
- Decode from encoded serialized ErgoTree
- Returns constant with given index (as stored in serialized ErgoTree) or None if index is out of bounds or error if constants parsing were failed
- Serialized proposition expression of SigmaProp type with ConstantPlaceholder nodes instead of Constant nodes. Key assumption: enough memory has been allocated at the address pointed-to by
output
. Useergo_lib_ergo_tree_template_bytes_len
to determine the length of the byte array. - Returns the number of bytes of the Serialized proposition expression of SigmaProp type with ConstantPlaceholder nodes instead of Constant nodes.
- Get Base16-encoded serialized bytes
- Convert to serialized bytes. Key assumption: enough memory has been allocated at the address pointed-to by
output
. Useergo_lib_ergo_tree_bytes_len
to determine the length of the byte array. - Returns new ErgoTree instance with a new constant value for a given index in constants list (as stored in serialized ErgoTree), or an error. Note that the original ErgoTree instance pointed-at by
ergo_tree_ptr
is untouched. - Add commitment hint to the bag
- Drop
HintsBag
- Empty HintsBag
- Get commitment
- Length of HintsBag
- Get box id
- Drop
Input
- Get spending proof
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Create new MnemonicGenerator instance
- Free a previously-created CString. Intended to be paired with one of the mnemonic generation functions. Called by the client.
- Generate mnemonic sentence using random entropy
- Generate mnemonic sentence using provided entropy
- Delete
NipopowProof
- Parse from JSON.
- Implementation of the ≥ algorithm from
KMZ17
, see Algorithm 4 - Get suffix head
- JSON representation as text
- Returns chain of
BlockHeader
s from the best proof. - Returns the best proof.
- Delete
NipopowVerifier
- Create new
NipopowVerifier
instance - Process given proof
- Return default blockchain parameters that were set at genesis
- Parse parameters from JSON. Supports Ergo Node API/Explorer API
- Create new parameters from provided blockchain parameters
- Drop
PreHeader
- Create instance using data from block header
- Adding new proposition
- Drop
Propositions
- Create empty proposition holder
- Get extension
- Drop
ProverResult
- Get proof. Key assumption: enough memory has been allocated at the address pointed-to by
output
. Useergo_lib_prover_result_proof_len
to determine the length of the byte array. - Return the number of bytes that make up the proof.
- JSON representation as text (compatible with Ergo Node/Explorer API, numbers are encoded as numbers)
- Drop
ReducedTransaction
- Returns
reduced
transaction, i.e. unsigned transaction where each unsigned input is augmented with ReducedInput which contains a script reduction result. - Returns the unsigned transation
- Drop
SecretKey
- Parse dlog secret key from bytes (SEC-1-encoded scalar)
- Generate random key
- Address (encoded public image)
- Encode from a serialized key. Key assumption: 32 bytes must be allocated at the address pointed-to by
output
. - Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Drop
SignedMessage
- Drop
SimpleBoxSelector
- Naive box selector, collects inputs until target balance is reached
- Selects inputs to satisfy target balance and tokens.
inputs
- available inputs (returns an error, if empty),target_balance
- coins (in nanoERGs) needed,target_tokens
- amount of tokens needed. Returns selected inputs and box assets(value+tokens) with change. - Get value as signed 64-bit long
- Drop
TokenAmount
- Create from i64 with bounds check
- Drop
Token
- Get token amount
- Get token id
- Drop
TokenId
- Create token id from ergo box id (32 byte digest)
- Parse token id (32 byte digest) from base16-encoded string
- Base16 encoded string
- Create a token with given token id and amount
- JSON representation according to EIP-12 https://github.com/ergoplatform/eips/pull/23
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Extract hints from signed transaction
- Adding hints for input
- Get HintsBag corresponding to input index
- Drop
TransactionHintsBag
- Empty TransactionHintsBag
- Get box selection
- Build the unsigned transaction
- Get change address
- Get current height
- Get data inputs
- Drop
TxBuilder
- Get fee amount
- Creates new TxBuilder
box_selection
- selected input boxesoutput_candidates
- output boxes to be “created” in this transaction,current_height
- chain height that will be used in additionally created boxes (change, miner’s fee, etc.),fee_amount
- miner’s fee,change_address
- change (inputs - outputs) will be sent to this address, will be given to miners, - Get outputs EXCLUDING fee and change
- Set context extension for a given input
- Set transaction’s data inputs
- Permits the burn of the given token amount, i.e. allows this token amount to be omitted in the outputs
- Suggested transaction fee (semi-default value used across wallets and dApps as of Oct 2020)
- Drop
Transaction
- Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
- Create Transaction from UnsignedTransaction and an array of proofs in the same order as UnsignedTransaction.inputs with empty proof indicated with empty byte array
- Get id for transaction
- Drop
TxId
- Convert a hex string into a TxId
- Get the tx id as bytes
- 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 box id
- Get extension
- Drop
UnsignedInput
- Add an element to collection
- Delete an existing collection
- Returns element at position
index
of an existing collection - Returns length of an existing collection
- Create a new empty collection
- Data inputs for transaction
- Drop
UnsignedTransaction
- Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
- Get id for transaction
- Inputs for transaction
- Output candidates for transaction
- 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
- Verify that the signature is presented to satisfy SigmaProp conditions.
- Drop
Wallet
- Create
Wallet
instance loading secret key from mnemonic Returns Err if a DlogSecretKey cannot be parsed from the provided phrase - Create
Wallet
from secrets - Generate Commitments for unsigned tx
- Generate Commitments for reduced transaction
- Sign an arbitrary message using a P2PK address
- Signs a reduced transaction (generating proofs for inputs)
- Signs a multi signature reduced transaction
- Signs a transaction
- Signs a multi signature transaction
- Adds a new node (above the current level). Hash must be exactly 32 bytes. side represents the side node is on in the tree, 0 = Left, 1 = Right
- Deserializes a MerkleProof from its json representation (see /blocks/{headerId}/proofFor/{txId} node api)
- Creates a new MerkleProof with given leaf data. Use ergo_merkle_proof_add_node to add levelnodes to the proof. leaf_data must be 32 bytes
- Serializes a MerkleProof to json representation
- Checks the merkleproof against the expected root_hash
- Checks the merkleproof against a base16 root_hash