Expand description
C bindings for ergo-lib
Macros
ergo-libuses 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 ofcbindgenis 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
u8representation 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
BlockHeaders id - Copy the contents of
transactions_rootfield 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
indexof 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
indexof 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
outputpoints 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
indexof an existing collection - Returns length of an existing collection
- Create a new empty collection
- Drop
CommitmentHint - Drop
ContextExtension - Create new empty ContextExtension instance
- Returns all keys (represented as u8 values) in the map
- Returns the number of elements in the collection
- 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
indexof 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
indexof 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
- 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
indexof 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
indexof 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_lento 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_lento 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_ptris 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
indexof 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
BlockHeaders from the best proof. - Returns the best proof.
- Delete
NipopowVerifier - Create new
NipopowVerifierinstance - Process given proof
- 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_lento 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
reducedtransaction, 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
indexof 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
indexof 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
indexof 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
Walletinstance loading secret key from mnemonic Returns Err if a DlogSecretKey cannot be parsed from the provided phrase - Create
Walletfrom 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