Expand description
C bindings for ergo-lib
Macros
ergo-lib
uses a number of collection types that are simple wrappers around Vec
. We have a
generic type for such a collection in ergo-lib-c-core::collections::Collection
. A limitation
of cbindgen
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
Traits
Functions
Serializes a BatchMerkleProof to json representation
Delete
BlockHeader
Parse BlockHeader array from JSON (Node API)
Get
BlockHeader
s idCopy the contents of
transactions_root
field to output
. Key assumption: exactly 32 bytes of
memory have been 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 collectionReturns 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 collectionReturns 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 collectionReturns 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
index
of an existing collectionReturns 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 collectionReturns 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 box
contract
- guarding contract, which should be evaluated to true in order
to open(spend) this box
creation_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 collectionReturns 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 box
contract
- guarding contract, which should be evaluated to true in order
to open(spend) this box
creation_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 transactionReturns 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 collectionReturns 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
. Use ergo_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
. Use ergo_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 collectionReturns 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 4Get suffix head
JSON representation as text
Returns chain of
BlockHeader
s from the best proof.Returns the best proof.
Delete
NipopowVerifier
Create new
NipopowVerifier
instanceProcess 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
. Use ergo_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 collectionReturns 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 collectionReturns 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 boxes
output_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 collectionReturns 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 phraseCreate
Wallet
from secretsGenerate 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