Core API Reference#

The Core API implemented objects, structures, utils for IOTA protocol.

It provides the following functionalities:

  • Address derivation

  • Block creations

  • UTXO Input/Output operations

  • Bech32, Slip10, uint256, and Byte Buffer utils

Address#

enum address_type_t#

Address types that supported by the protocol.

Values:

enumerator ADDRESS_TYPE_ED25519#

Denotes an Ed25519 address.

enumerator ADDRESS_TYPE_ALIAS#

Denotes an Alias address.

enumerator ADDRESS_TYPE_NFT#

Denotes a NFT address.

struct address_t#

Address object.

the address length depends on the type.

  • ADDRESS_TYPE_ED25519: 32 bytes

  • ADDRESS_TYPE_ALIAS: 20 bytes

  • ADDRESS_TYPE_NFT: 20 bytes

Public Members

address_type_t type#

one of address types

byte_t address[ADDRESS_HASH_BYTES]#

address data

int address_keypair_from_path(byte_t seed[], size_t seed_len, char path[], ed25519_keypair_t *keypair)#

Derive ed25519 keypair from slip10 seed and path.

Parameters

  • seed – [in] The seed for slip10

  • seed_len – [in] The length of seed

  • path – [in] The path for slip10

  • keypair – [out] The derived ed25519 keypair

Returns

int 0 on success

int ed25519_address_from_path(byte_t seed[], size_t seed_len, char path[], address_t *addr)#

Derive an ed25519 address from slip10.

Parameters

  • seed – [in] The seed for slip10

  • seed_len – [in] The length of seed

  • path – [in] The path for slip10

  • addr – [out] An ed25519 address object

Returns

int 0 on success

int alias_address_from_output(byte_t const output_id[], uint8_t output_id_len, address_t *addr)#

Derive an Alias address from output ID.

Parameters

  • output_id – [in] A output ID byte array

  • output_id_len – [in] A length of output ID byte array

  • addr – [out] An Alias address object

Returns

int 0 on success

int nft_address_from_output(byte_t const output_id[], uint8_t output_id_len, address_t *addr)#

Derive a NFT address from output ID.

Parameters

  • output_id – [in] A output ID byte array

  • output_id_len – [in] A length of output ID byte array

  • addr – [out] A NFT address object

Returns

int 0 on success

uint8_t address_len(address_t const *const addr)#

Get the length of the given address in bytes.

Parameters

  • addr – [in] An address object

Returns

uint8_t

uint8_t address_serialized_len(address_t *addr)#

Get the serialized length of the given address.

Parameters

  • addr – [in] An address object

Returns

uint8_t

size_t address_serialize(address_t *addr, byte_t bytes[], size_t len)#

Serialize the given address to binary from.

Parameters

  • addr – [in] An address object

  • bytes – [out] A buffer hold serialized data

  • len – [in] The length of the buffer

Returns

size_t The bytes written is returned, 0 on error

address_t *address_deserialize(byte_t bytes[], size_t len)#

Deserialize a binary data to an address object.

The returned address need to be freed after use.

Parameters

  • bytes – [in] A buffer holds binary data

  • len – [in] the length of the buffer

Returns

address_t* A pointer to the deserialized address, NULL on error

int address_from_bech32(char const hrp[], char const bech32[], address_t *addr)#

Create an address object from the given bech32 string.

Parameters

  • hrp – [in] The HRP of bech32

  • bech32 – [in] The string of bech32 address

  • addr – [out] The output address object

Returns

int 0 on success

int address_to_bech32(address_t *addr, char const hrp[], char bech32_buf[], size_t buf_len)#

Get bech32 string from the given address.

Parameters

  • addr – [in] An address object

  • hrp – [in] The HRP of bech32

  • bech32_buf – [out] A buffer hold bech32 string

  • buf_len – [in] The length of the given buffer

Returns

int 0 on success

bool address_equal(address_t *addr1, address_t *addr2)#

Check if two addresses are equal.

Parameters

  • addr1 – [in] Address 1

  • addr2 – [in] Address 2

Returns

true

Returns

false

address_t *address_clone(address_t const *const addr)#

Clone an address object, it should be freed after use.

Parameters

  • addr[in] – The address for clone

Returns

address_t* A new address object

void address_free(address_t *addr)#

Free an address object.

Parameters

  • addr – [in] An address object

void address_print(address_t const *const addr)#

Print an address object.

Parameters

  • addr – [in] An address object

Models#

Block#

enum core_block_payload_type_t#

Values:

enumerator CORE_BLOCK_PAYLOAD_DEPRECATED_0#
enumerator CORE_BLOCK_PAYLOAD_DEPRECATED_1#
enumerator CORE_BLOCK_PAYLOAD_INDEXATION#
enumerator CORE_BLOCK_PAYLOAD_RECEIPT#
enumerator CORE_BLOCK_PAYLOAD_TREASURY#
enumerator CORE_BLOCK_PAYLOAD_TAGGED#
enumerator CORE_BLOCK_PAYLOAD_TRANSACTION#
enumerator CORE_BLOCK_PAYLOAD_MILESTONE#
enumerator CORE_BLOCK_PAYLOAD_UNKNOWN#
struct core_block_t#

A block object.

Public Members

uint8_t protocol_version#

Protocol version number of block.

UT_array *parents#

Parents of this block.

uint32_t payload_type#

Payload type, one of core_block_payload_type_t.

void *payload#

Payload object, NULL is no payload.

uint64_t nonce#

The nonce which lets this block fulfill the Proof-of-Work requirement.

core_block_t *core_block_new(uint8_t ver)#

Allocate a core block object.

Parameters

  • ver – [in] A protocol version

Returns

core_block_t*

void core_block_free(core_block_t *blk)#

Free a core block object.

Parameters

  • blk – [in] block object

int core_block_essence_hash_calc(core_block_t *blk, byte_t essence_hash[], uint8_t essence_hash_len)#

Calculate a transaction essence hash.

Parameters

  • blk – [in] A block with transaction payload

  • essence_hash – [out] Calculated essence hash

  • essence_hash_len – [in] Length of an essence hash array

Returns

int 0 on success

void core_block_add_parent(core_block_t *blk, byte_t const blk_id[])#

Add a parent to the block.

Parameters

  • blk – [in] A block object

  • blk_id – [in] A block ID

size_t core_block_parent_len(core_block_t *blk)#

Get the number of parent.

Parameters

  • blk – [in] A block object

Returns

size_t

byte_t *core_block_get_parent_id(core_block_t *blk, size_t index)#

Gets a parent ID by a given index.

Parameters

  • blk – [in] A block object

  • index – [in] A index of a block ID

Returns

byte_t* a pointer to the binary ID

core_block_payload_type_t core_block_get_payload_type(core_block_t *blk)#

Get the block payload type.

Parameters

  • blk – [in] The block object

Returns

core_block_payload_type_t

size_t core_block_serialize_len(core_block_t *blk)#

Get the length of a serialized core block.

Parameters

  • blk – [in] The block object

Returns

size_t The number of bytes of serialized data

size_t core_block_serialize(core_block_t *blk, byte_t buf[], size_t buf_len)#

Serialize core block to a buffer.

Parameters

  • blk – [in] The block object

  • buf – [out] A buffer holds the serialized data

  • buf_len – [in] The length of buffer

Returns

size_t The bytes written is returned, 0 on errors

void core_block_print(core_block_t *blk, uint8_t indentation)#

Print out a core block.

Parameters

  • blk – [in] The block object

  • indentation – [in] Tab indentation when printing core block

Signing#

struct signing_data_t#

A signing data structure.

This data is needed when unlocks are creating and transaction gets signed.

Public Members

address_t unlock_address#

Address in Unlock Condition (Address, Governor, State Controller) - ED25519/NFT/Alias.

byte_t hash[CRYPTO_BLAKE2B_256_HASH_BYTES]#

Optional, a NFT/Alias ID in the utxo_output.

ed25519_keypair_t *keypair#

Optional, ed25519 keypair (this is for ed25519 address)

struct signing_data_list#

A list of signing data.

This list needs to have the same order of signing data for unspent outputs as in utxo_inputs_list_t.

signing_data_list_t *signing_new()#

Initialize a signing data list.

Returns

a NULL pointer

void signing_free(signing_data_list_t *signing_data_list)#

Free a signing data list.

Parameters

  • signing_data_list – Signing data list

int signing_data_add(address_t *unlock_address, byte_t hash[], uint8_t hash_len, ed25519_keypair_t *keypair, signing_data_list_t **sign_data_list)#

Add a signing data into the list.

Parameters

  • unlock_address – [in] Address Unlock Condition Address - ED25519/NFT/Alias

  • hash – [in] Optional, a NFT/Alias ID in the utxo_output

  • hash_len – [in] A length of hash array, 0 if hash is NULL

  • keypair – [in] Optional, ed25519 keypair of this input (this is for ed25519 address)

  • sign_data_list – [out] Signing data list which will be populated by a new element

Returns

int 0 on success

uint8_t signing_data_count(signing_data_list_t *signing_data_list)#

Get number of elements in a signing data list.

Parameters

  • signing_data_list – Signing data list

Returns

uint8_t Number of elements

signing_data_t *signing_get_data_by_index(signing_data_list_t *signing_data_list, uint8_t index)#

Find a signing data by a given index.

Parameters

  • signing_data_list – Signing data list

  • index – [in] An index in the list

Returns

signing_data_t* or NULL pointer

int signing_transaction_sign(byte_t essence_hash[], uint8_t essence_hash_len, utxo_inputs_list_t *inputs, signing_data_list_t *sign_data_list, unlock_list_t **unlock_list)#

Create unlocks and sign transaction.

Parameters

  • essence_hash – [in] An essence hash

  • essence_hash_len – [in] Length of an essence hash array

  • inputs – [in] An UTXO input list

  • sign_data_list – [in] Signing data list

  • unlock_list – A list of unlocks which will be created

Returns

int 0 on success

Unlocks#

enum unlock_type_t#

Unlock types that are supported by the protocol.

Values:

enumerator UNLOCK_SIGNATURE_TYPE#

Denotes a signature unlock.

enumerator UNLOCK_REFERENCE_TYPE#

Denotes a reference unlock.

enumerator UNLOCK_ALIAS_TYPE#

Denotes a alias unlock.

enumerator UNLOCK_NFT_TYPE#

Denotes a NFT unlock.

struct unlock_t#

An unlock object which points to a consumed output.

Public Members

unlock_type_t type#

The type of the unlock object.

void *obj#

A pointer to an unlock object.

struct unlock_list#

A list of unlocks.

Public Members

unlock_t current#

Represents a current unlock.

struct unlock_list *next#

Points to next unlock.

int unlock_list_add(unlock_list_t **list, unlock_t *unlock)#

Add an unlock to the list.

Parameters

  • list – [in] The head of the unlock list

  • block – [in] An unlock to be added to the list

Returns

int 0 on success

int unlock_list_add_signature(unlock_list_t **list, byte_t *sig, size_t sig_len)#

Add an ed25519 signature unlock.

Parameters

  • list – [in] The head of list

  • sig – [in] An ed25519 signature unlock

  • sig_len – [in] The length of signature unlock

Returns

int 0 on success

int unlock_list_add_reference(unlock_list_t **list, uint16_t index)#

Add a reference unlock.

Parameters

  • list – [in] The head of list

  • index – [in] The index of reference unlock

Returns

int 0 on success.

int unlock_list_add_alias(unlock_list_t **list, uint16_t index)#

Add an alias unlock.

Parameters

  • list – [in] The head of list

  • index – [in] The index of alias unlock

Returns

int 0 on success.

int unlock_list_add_nft(unlock_list_t **list, uint16_t index)#

Add a NFT unlock.

Parameters

  • list – [in] The head of list

  • index – [in] The index of NFT unlock

Returns

int 0 on success.

uint16_t unlock_list_count(unlock_list_t *list)#

Get the length of unlock list.

Parameters

  • list – [in] The head of list

Returns

uint16_t

unlock_t *unlock_list_get(unlock_list_t *list, uint16_t index)#

Get the pointer of an unlock in the list.

Parameters

  • list – [in] An unlock list

  • index – [in] The index of the unlock object

Returns

unlock_t* A pointer to an unlock

int32_t unlock_list_find_pub(unlock_list_t *list, byte_t const *const pub_key)#

Get the unlock index of a given public key.

Parameters

  • list – [in] The head of list

  • pub_key – [in] A ed25519 public key

Returns

int32_t if not found return -1 else return the index

size_t unlock_list_serialize_length(unlock_list_t *list)#

Get the serialized length of an unlock list.

Parameters

  • list – [in] The head of list

Returns

size_t 0 on failed

size_t unlock_list_serialize(unlock_list_t *list, byte_t buf[])#

Serialize an unlock list.

Parameters

  • list – [in] The head of list

  • buf – [out] A buffer holds serialized data

Returns

size_t number of bytes written to the buffer

unlock_list_t *unlock_list_deserialize(byte_t buf[], size_t buf_len)#

Deserialize a binary data to an unlock list object.

Parameters

  • buf – [in] The unlock list data in binary

  • buf_len – [in] The length of the data

Returns

unlock_list_t* or NULL on failure

void unlock_list_free(unlock_list_t *list)#

Free an unlock list.

Parameters

  • list – [in] An unlock list object

void unlock_list_print(unlock_list_t *list, uint8_t indentation)#

Print out an unlock list list.

Parameters

  • list – [in] An unlock list

  • indentation – [in] Tab indentation when printing unlock list

Inputs#

struct utxo_input_t#

UTXO input structure.

Public Members

uint8_t input_type#

The input type. Set to value 0 to denote an UTXO Input.

byte_t tx_id[IOTA_TRANSACTION_ID_BYTES]#

The BLAKE2b-256 hash of the transaction payload containing the referenced output.

uint16_t output_index#

The output index of the referenced output.

struct utxo_inputs_list#

A list of UTXO inputs.

utxo_inputs_list_t *utxo_inputs_new()#

Initialize an UTXO input list.

Returns

a NULL pointer

void utxo_inputs_free(utxo_inputs_list_t *inputs)#

Free an UTXO input list.

Parameters

  • inputs – [in] An UTXO input list.

int utxo_inputs_add(utxo_inputs_list_t **inputs, uint8_t type, byte_t id[], uint16_t index)#

Append an UTXO input element to the list.

Parameters

  • inputs – [in] An UTXO input list

  • type – [in] An input type

  • id – [in] A transaction ID

  • index – [in] An output index of the referenced output

Returns

int 0 on success

uint16_t utxo_inputs_count(utxo_inputs_list_t *inputs)#

Get number of elements in an utxo input list.

Parameters

  • inputs – [in] An UTXO input list.

Returns

uint16_t A count of elements

utxo_input_t *utxo_inputs_find_by_id(utxo_inputs_list_t *inputs, byte_t id[])#

Find an UTXO input by a given transaction ID.

Parameters

  • inputs – [in] An UTXO input hash table

  • id – [in] A transaction ID

Returns

utxo_input_t* or NULL for not found

utxo_input_t *utxo_inputs_find_by_index(utxo_inputs_list_t *inputs, uint16_t index)#

Find an UTXO input by a given index.

Parameters

  • inputs – [in] An UTXO input hash table

  • index – [in] An output index

Returns

utxo_input_t* or NULL for not found

size_t utxo_inputs_serialize_len(utxo_inputs_list_t *inputs)#

Get the length of a serialized UTXO input list.

Parameters

  • inputs – [in] A list of UTXO inputs

Returns

size_t The number of bytes of a serialized data

size_t utxo_inputs_serialize(utxo_inputs_list_t *inputs, byte_t buf[], size_t buf_len)#

Serialize an UTXO input list to a buffer.

Parameters

  • inputs – [in] An UTXO input list

  • buf – [out] A buffer for serialization

  • buf_len – [in] The length of buffer

Returns

size_t number of bytes written to the buffer

utxo_inputs_list_t *utxo_inputs_deserialize(byte_t buf[], size_t buf_len)#

Deserialize binary data to a UTXO input list object.

Parameters

  • buf – [in] The buffer holds a serialized data

  • buf_len – [in] The length of the buffer

Returns

utxo_inputs_list_t* The deserialized UTXO input list, NULL on errors

void utxo_inputs_print(utxo_inputs_list_t *inputs, uint8_t indentation)#

Print an UTXO input list.

Parameters

  • inputs – [in] An UTXO input list.

  • indentation – [in] Tab indentation when printing utxo output list

bool utxo_inputs_syntactic(utxo_inputs_list_t *inputs)#

UTXO inputs syntactic validation.

Parameters

  • inputs – [in] A list of UTXO input

Returns

true Valid

Returns

false Invalid

Outputs#

enum utxo_output_type_t#

UTXO output types.

SigLockedSingleOutput: Defines an output (with a certain amount) to a single target address which is unlocked via a signature proving ownership over the given address. SigLockedDustAllowanceOutput: Works in the same way as a SigLockedSingleOutput but additionally controls the dust allowance on the target address. Treasury output: Describes an output which holds the treasury of a network. Basic output: Describes a deposit to a single address. The output might contain optional features and native tokens. Alias output: Describes an alias account in the ledger. Foundry output: Describes a foundry that controls supply of native tokens. NFT output: Describes a unique, non-fungible token deposit to a single address.

Values:

enumerator OUTPUT_SINGLE_OUTPUT#

SigLockedSingleOutput, deprecated.

enumerator OUTPUT_DUST_ALLOWANCE#

SigLockedDustAllowanceOutput, deprecated.

enumerator OUTPUT_TREASURY#

Treasury output, not supported in this library.

enumerator OUTPUT_BASIC#

Basic output.

enumerator OUTPUT_ALIAS#

Alias output.

enumerator OUTPUT_FOUNDRY#

Foundry output.

enumerator OUTPUT_NFT#

NFT output.

struct utxo_output_t#

An UTXO output.

Public Members

utxo_output_type_t output_type#

3: Basic output, 4: Alias output, 5: Foundry output, 6: NFT output

struct utxo_outputs_list#

A list of UTXO outputs.

utxo_outputs_list_t *utxo_outputs_new()#

Initialize an UTXO output list.

Returns

A NULL pointer

void utxo_outputs_free(utxo_outputs_list_t *outputs)#

Free an UTXO output list.

Parameters

  • outputs – [in] A list of UTXO outputs

int utxo_outputs_add(utxo_outputs_list_t **outputs, utxo_output_type_t type, void *output)#

Add an output to an UTXO output table.

Parameters

  • outputs – [in] A list of UTXO outputs

  • type – [in] An UTXO output type

  • output – [in] A pointer to an output

Returns

int 0 on success, -1 on failure

uint16_t utxo_outputs_count(utxo_outputs_list_t *outputs)#

Get number of elements in an UTXO output list.

Parameters

  • outputs – [in] A list of UTXO outputs

Returns

uint16_t A number of elements

utxo_output_t *utxo_outputs_get(utxo_outputs_list_t *outputs, uint16_t index)#

Get an output pointer in the list from a given index.

Parameters

  • outputs – [in] A list of UTXO outputs

  • index – [in] An index of an output

Returns

utxo_output_t* A pointer to an output

size_t utxo_outputs_serialize_len(utxo_outputs_list_t *outputs)#

Get a length of a serialized UTXO output list.

Parameters

  • outputs – [in] A list of UTXO outputs

Returns

size_t The number of bytes of a serialized data

size_t utxo_outputs_serialize(utxo_outputs_list_t *outputs, byte_t buf[], size_t buf_len)#

Serialize an UTXO output list to a binary data.

Parameters

  • outputs – [in] A list of UTXO outputs

  • buf – [out] A buffer holds the serialized data

  • buf_len – [in] The length of buffer

Returns

size_t The bytes written is returned, 0 on errors

utxo_outputs_list_t *utxo_outputs_deserialize(byte_t buf[], size_t buf_len)#

Deserialize binary data to an UTXO output list object.

Parameters

  • buf – [in] The buffer holds a serialized data

  • buf_len – [in] The length of the buffer

Returns

utxo_outputs_list_t* The deserialized UTXO output list, NULL on errors

void utxo_outputs_print(utxo_outputs_list_t *outputs, uint8_t indentation)#

Print an UTXO output list.

Parameters

  • outputs – [in] A list of UTXO outputs

  • indentation – [in] Tab indentation when printing UTXO output list

bool utxo_outputs_syntactic(utxo_outputs_list_t *outputs, byte_cost_config_t *byte_cost)#

UTXO Output syntactic validation.

Parameters

  • outputs – [in] A list of UTXO outputs

  • byte_cost – [in] The Byte Cost configure

Returns

true Valid

Returns

false Invalid

Payloads#

Milestone#

struct milestone_payload_t#

Public Members

uint8_t protocol_version#

Protocol version number of the network.

milestone_payload_t *milestone_payload_new()#

Allocate a milestone payload object.

Returns

milestone_payload_t*

void milestone_payload_free(milestone_payload_t *ms)#

Free a milestone payload object.

Parameters

  • ms – [in] A milestone object

size_t milestone_payload_get_parents_count(milestone_payload_t *ms)#

Get parents count in a milestone.

Parameters

  • ms – [in] The milestone object

Returns

size_t

byte_t *milestone_payload_get_parent(milestone_payload_t *ms, size_t index)#

Get a parent string from a milestone at index.

Parameters

  • ms – [in] The milestone object

  • index – [in] The index of parent

Returns

byte_t* NULL on failed.

size_t milestone_payload_get_signatures_count(milestone_payload_t *ms)#

Get signatures count in a milestone.

Parameters

  • ms – [in] The milestone object

Returns

size_t

byte_t *milestone_payload_get_signature(milestone_payload_t *ms, size_t index)#

Get a signature string from a milestone at index.

Parameters

  • ms – [in] The milestone object

  • index – [in] The index of signature

Returns

byte_t* NULL on failed.

void milestone_payload_print(milestone_payload_t *ms, uint8_t indentation)#

Print out a milestone milestone.

Parameters

  • ms – [in] The milestone object

  • indentation – [in] Tab indentation when printing milestone payload

Tagged Data Payload#

struct tagged_data_payload_t#

Tagged data structure.

The payload type of tagged data is 5

Public Members

byte_buf_t *tag#

The tag of the data.

byte_buf_t *data#

Binary data.

tagged_data_payload_t *tagged_data_new(byte_t tag[], uint8_t tag_len, byte_t data[], uint32_t data_len)#

Create a tagged data object with tag and binary data.

Parameters

  • tag – [in] The binary tag in tagged data payload

  • tag_len – [in] The length of the binary tag

  • data – [in] The binary data in tagged data payload

  • data_len – [in] The length of the binary data

Returns

tagged_data_payload_t* A pointer to tagged data object

void tagged_data_free(tagged_data_payload_t *tagged_data)#

Free a tagged data object.

Parameters

  • tagged_data – [in] A tagged data object

size_t tagged_data_serialize_len(tagged_data_payload_t *tagged_data)#

Get a serialized length of a tagged data.

Parameters

  • tagged_data – [in] A tagged data object

Returns

size_t The number of bytes of serialized data

size_t tagged_data_serialize(tagged_data_payload_t *tagged_data, byte_t buf[], size_t buf_len)#

Serialize a tagged data to a binary data.

Parameters

  • tagged_data – [in] A tagged data object

  • buf – [out] A buffer holds the serialized data

  • buf_len – [in] The length of buffer

Returns

size_t The bytes written is returned, 0 on errors

tagged_data_payload_t *tagged_data_deserialize(byte_t buf[], size_t buf_len)#

Deserialize a binary data to a tagged data object.

Parameters

  • buf – [in] The block data in binary

  • buf_len – [in] The length of the data

Returns

tagged_data_payload_t* or NULL on failure

tagged_data_payload_t *tagged_data_clone(tagged_data_payload_t const *const tagged_data)#

Clone tagged data object, it should be freed after use.

Parameters

  • tagged_data – [in] tagged data object for clone

Returns

tagged_data_payload_t* New tagged data object

void tagged_data_print(tagged_data_payload_t *tagged_data, uint8_t indentation)#

Print a tagged data object.

Parameters

  • tagged_data – [in] A tagged data object

  • indentation – [in] Tab indentation when printing a tagged data

Transaction Payload#

Essence#
struct transaction_essence_t#

Transaction Essence, the essence data making up a transaction by defining its inputs and outputs and an optional payload.

Based on protocol design, we can have different types of input and output in a transaction. At this moment, we have only utxo_input_list for input. For output we have basic, alias, foundry and nft output.

Public Members

uint8_t tx_type#

Set to value 1 to denote a Transaction Essence.

uint64_t network_id#

Network identifier.

It is first 8 bytes of the BLAKE2b-256 hash of the network name (identifier string of the network).

utxo_inputs_list_t *inputs#

An UTXO input list.

byte_t inputs_commitment[CRYPTO_BLAKE2B_256_HASH_BYTES]#

BLAKE2b-256 hash of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index).

utxo_outputs_list_t *outputs#

An UTXO output list.

uint32_t payload_len#

The length in bytes of the optional payload.

void *payload#

An tagged data payload at this moment.

transaction_essence_t *tx_essence_new(uint64_t network_id)#

Allocate a transaction essence object.

Parameters

  • network_id – [in] A network ID

Returns

transaction_essence_t*

void tx_essence_free(transaction_essence_t *es)#

Free an essence object.

Parameters

  • es – [in] An essence object

int tx_essence_add_input(transaction_essence_t *es, uint8_t type, byte_t tx_id[], uint8_t index)#

Add an input element to the essence.

Parameters

  • es – [in] An essence object

  • type – [in] An input type

  • tx_id – [in] A transaction ID

  • index – [in] The index of the output of the referenced transaction

Returns

int 0 on success

int tx_essence_add_output(transaction_essence_t *es, utxo_output_type_t type, void *output)#

Add an output element to the essence.

Parameters

  • es – [in] An essence object

  • type – [in] An output type

  • output – [in] Pointer to an output

Returns

int 0 on success

int tx_essence_add_payload(transaction_essence_t *es, uint32_t type, void *payload)#

Add a payload to essence.

support tagged data payload at this moment

Parameters

  • es – [in] An essence object

  • type – [in] A payload type

  • payload – [in] A pointer to a payload object

Returns

int 0 on success

int tx_essence_inputs_commitment_calculate(transaction_essence_t *es, utxo_outputs_list_t *unspent_outputs)#

Calculate inputs commitment for transaction essence.

Parameters

  • es – [in] An essence object

  • unspent_outputs – [in] List of unspent outputs which will be used as transaction inputs

Returns

int 0 on success

size_t tx_essence_serialize_length(transaction_essence_t *es)#

Get the serialized length of the essence.

Parameters

  • es – [in] An essence object

Returns

size_t The number of bytes of a serialized data

size_t tx_essence_serialize(transaction_essence_t *es, byte_t buf[], size_t buf_len)#

Serialize an essence object.

Parameters

  • es – [in] An essence object

  • buf – [out] A buffer to hold the serialized data

  • buf_len – [in] The length of the buffer

Returns

size_t number of bytes written to the buffer

transaction_essence_t *tx_essence_deserialize(byte_t buf[], size_t buf_len)#

Deserialize binary data to a transaction essence object.

Parameters

  • buf – [in] The buffer holds a serialized data

  • buf_len – [in] The length of the buffer

Returns

transaction_essence_t* The deserialized txn essence, NULL on errors

bool tx_essence_syntactic(transaction_essence_t *es, byte_cost_config_t *byte_cost)#

Transaction Essence syntactic validation.

Parameters

  • es – [in] An essence object

  • byte_cost – [in] The Byte Cost configure

Returns

true Valid

Returns

false Invalid

void tx_essence_print(transaction_essence_t *es, uint8_t indentation)#

Print out a transaction essence.

Parameters

  • es – [in] An essence object

  • indentation – [in] Tab indentation when printing transaction essence

Transaction#
struct transaction_payload_t#

A Transaction payload is made up of two parts:

  1. The The Transaction Essence part which contains the inputs, outputs and an optional embedded payload.

  2. The Unlocks which unlock the Transaction Essence’s inputs. In case the unlock contains a signature, it signs the entire Transaction Essence part.

Public Members

uint32_t type#

Set to value 6 to denote a Transaction payload.

transaction_essence_t *essence#

Describes the essence data making up a transaction by defining its inputs and outputs and an optional payload.

unlock_list_t *unlocks#

Defines a list of unlocks (signature, reference, alias, NFT) which unlock the inputs of the transaction essence.

transaction_payload_t *tx_payload_new(uint64_t network_id)#

Allocate a transaction payload object.

Parameters

  • network_id – [in] A network ID

Returns

transaction_payload_t*

void tx_payload_free(transaction_payload_t *tx)#

Free a transaction payload object.

Parameters

  • tx – [in] A transaction payload

size_t tx_payload_serialize_length(transaction_payload_t *tx)#

Get the serialized length of a transaction payload.

Parameters

  • tx – [in] A transaction payload

Returns

size_t The number of bytes of serialized data

size_t tx_payload_serialize(transaction_payload_t *tx, byte_t buf[], size_t buf_len)#

Serialize a transaction payload.

Parameters

  • tx – [in] A transaction payload

  • buf – [out] A buffer holds the serialized data

  • buf_len – [in] The length of buffer

Returns

size_t number of bytes written to the buffer

transaction_payload_t *tx_payload_deserialize(byte_t buf[], size_t buf_len)#

Deserialize binary data to a transaction payload object.

Parameters

  • buf – [in] The buffer holds a serialized data

  • buf_len – [in] The length of the buffer

Returns

transaction_payload_t* The deserialized tx payload, NULL on errors

void tx_payload_print(transaction_payload_t *tx, uint8_t indentation)#

Print out a transaction payload.

Parameters

  • tx – [in] A transaction payload

  • indentation – [in] Tab indentation when printing transaction payload

bool tx_payload_syntactic(transaction_payload_t *tx, byte_cost_config_t *byte_cost)#

Transaction payload syntactic validation.

Parameters

  • tx – [in] A transaction payload

  • byte_cost – [in] The Byte Cost configure

Returns

true Valid

Returns

false Invalid

Utils#

uint256#

struct uint256_t#

A 256 bit number object.

Custom implementation for 256 bit number representation. Only a little endian format is supported at the moment.

Public Members

uint64_t bits[4]#

256 bit number represented in a little endian format

uint256_t *uint256_from_str(char const *str)#

New uint256 object from c_string representing a 256 bit number.

Parameters

  • str – [in] A c_string representing a 256 bit number.

Returns

uint256_t* Pointer to uint256 object, NULL on failed.

bool uint256_add(uint256_t *sum, uint256_t *a, uint256_t *b)#

Perform addition on two uint256 numbers.

Parameters

  • sum – [out] The sum of two numbers.

  • a – [in] The summand A.

  • b – [in] The summand B.

Returns

true On success

Returns

false On failed

bool uint256_sub(uint256_t *diff, uint256_t *min, uint256_t *sub)#

Perform subtraction on two uint256 numbers.

Parameters

  • diff – [out] The difference of two numbers.

  • min – [in] The minuend.

  • sub – [in] The subtrahend.

Returns

true On success

Returns

false On failed

int uint256_equal(uint256_t const *a, uint256_t const *b)#

Compare two uint256 objects (numbers)

Parameters

  • a – [in] A pointer to uint256 object

  • b – [in] A pointer to uint256 object

Returns

int < 0 if a is smaller then b

Returns

int > 0 if a is greater than b

Returns

int 0 if a is equal to b

char *uint256_to_str(uint256_t *num)#

Converts uint256 number to a string.

Parameters

  • num – [in] A pointer to uint256 object

Returns

Pointer to string object, NULL on failed.

uint256_t *uint256_clone(uint256_t const *const num)#

Clone uint256 object, it should be freed after use.

Parameters

  • num – [in] A pointer to uint256 object for clone

Returns

uint256_t* New uint256 object

void uint256_free(uint256_t *num)#

Free a unit256_t object.

Parameters

  • num – [in] A pointer to uint256 object

Bech32#

int bech32_encode(char *output, const char *hrp, const uint8_t *data, size_t data_len)#

bech32 encode

Parameters

  • output – [out] The output bech32 string

  • hrp – [in] A human-readable string

  • data – [in] The encode data in bytes

  • data_len – [in] The length of data

Returns

int 1 on success

int bech32_decode(char *hrp, uint8_t *data, size_t *data_len, const char *input)#

bech32 decode

Parameters

  • hrp – [out] The human-readable part

  • data – [out] The data in bytes

  • data_len – [out] The length of data

  • input – [in] A bech32 string

Returns

int 1 on success

int bech32_convert_bits(uint8_t *out, size_t *outlen, int outbits, const uint8_t *in, size_t inlen, int inbits, int pad)#

Convert raw binary to X bit per byte encoded byte string.

Parameters

  • out – [out] A outout buffer hold the encoded string

  • outlen – [in] The length of output buffer

  • outbits – [in] The output bits per byte

  • in – [in] The input data buffer

  • inlen – [in] The length of input buffer

  • inbits – [in] The input bits per byte

  • pad – [in] set 1 to add padding

Returns

int 1 on success

Slip10#

struct slip10_key_t#

Slip10 key structure.

Public Members

byte_t key[SLIP10_PRIVATE_KEY_BYTES]#

private key, 32 bytes

byte_t chain_code[SLIP10_CHAIN_CODE_BYTES]#

chain code, 32 bytes

struct bip32_path_t#

BIP32 path structure.

Public Members

uint32_t path[MAX_BIP32_PATH]#

the string of path, 32 bytes

int len#

the length of the path

int slip10_parse_path(char str[], bip32_path_t *path)#

Gets bip32 path from string.

Parameters

  • str – [in] A bip32 path string

  • path – [out] The output path

Returns

int 0 on successful

int slip10_key_from_path(byte_t seed[], size_t seed_len, char path[], slip10_curve_t curve, slip10_key_t *key)#

Derives key from given seed and path.

Parameters

  • seed – [in] A seed in byte array

  • seed_len – [in] The length of seed

  • path – [in] The string of path

  • curve – [in] The type of curve, only support ed25519

  • key – [out] The derived key

Returns

int 0 on successful

int slip10_public_key(slip10_curve_t curve, slip10_key_t *key, byte_t pub_key[])#

Get public key from the derived key.

Parameters

  • curve – [in] The type of curve, only support ed25519

  • key – [in] A slip-10 key

  • pub_key – [out] The public key

Returns

int 0 on successful

Byte Buffer#

struct byte_buf_t#

byte buffer object

Public Members

size_t len#

the length of data

size_t cap#

the capacity of this object

byte_t *data#

a pointer to the data

byte_buf_t *byte_buf_new()#

Allocates data buffer.

Returns

byte_buf_t*

void byte_buf_free(byte_buf_t *buf)#

Frees data buffer.

Parameters

  • buf – [in] A byte buffer object

byte_buf_t *byte_buf_new_with_data(byte_t data[], size_t len)#

Allocates data buffer with given data.

Parameters

  • data – [in] Initial data

  • len – [in] The size of data

Returns

byte_buf_t*

bool byte_buf_append(byte_buf_t *buf, byte_t const data[], size_t len)#

Appends data to buffer.

Parameters

  • buf – [in] A buffer object

  • data – [in] The data for appending

  • len – [in] The size of data

Returns

true On success

Returns

false On failed

bool byte_buf_set(byte_buf_t *buf, byte_t const data[], size_t len)#

Sets data to the buffer.

Parameters

  • buf – [in] A buffer object

  • data – [in] The data to set

  • len – [in] The length of data

Returns

true On success

Returns

false On failed

bool byte_buf2str(byte_buf_t *buf)#

Converts byte buffer to string.

Appending a null terminator to the end of data

Parameters

  • buf – [out] A byte buffer object

Returns

true

Returns

false

byte_buf_t *byte_buf_clonen(byte_buf_t *buf, size_t length)#

Duplicates N bytes from buffer.

Parameters

  • buf – [in] A byte buffer

  • length – [in] The cloned length

Returns

byte_buf_t*

byte_buf_t *byte_buf_clone(byte_buf_t *buf)#

Duplicates a byte buffer.

Parameters

  • buf – [in] A byte buffer

Returns

byte_buf_t*

bool byte_buf_reserve(byte_buf_t *buf, size_t len)#

Changes the buffer capacity.

Parameters

  • buf – [in] A byte buffer

  • len – [in] The expect size of this buffer

Returns

true On success

Returns

false On failed

void byte_buf_print(byte_buf_t *buf)#

Dumps buffer information for debug propose.

Parameters

  • buf – [in] A byte buffer

byte_buf_t *byte_buf_str2hex(byte_buf_t *buf)#

Duplicates and converts the data from bin to hex string, the returned object need to be freed.

Parameters

  • buf – [in] A byte buffer

Returns

byte_buf_t*

byte_buf_t *byte_buf_hex2str(byte_buf_t *hex)#

Duplicates and converts the data from hex to text, the returned object need to be freed.

Parameters

  • hex – [in] A byte buffer

Returns

byte_buf_t*

int hex2string(char const str[], uint8_t array[], size_t arr_len)#

Converts a hex string to C string, “48656c6c6f” -> “Hello”.

Parameters

  • str – [in] A hex string

  • array – [out] An output buffer holds text data

  • arr_len – [in] The length of text buffer

Returns

int 0 on success

int string2hex(char const str[], byte_t hex[], size_t hex_len)#

Converts a text to hex string, “Hello” -> “48656c6c6f”.

Parameters

  • str – [in] A text string

  • hex – [out] The hex string from text

  • hex_len – [in] The length of hex buffer

Returns

int 0 on success

int hex_2_bin(char const str[], size_t str_len, char const *prefix, byte_t bin[], size_t bin_len)#

Converts hex string to a byte array.

Parameters

  • str – [in] A hex string

  • str_len – [in] The length of the hex string

  • prefix – [in] A prefix which will be skipped when converting hex string to a byte array

  • bin – [out] A byte array buffer

  • bin_len – [in] The length of byte array

Returns

int 0 on success

int bin_2_hex(byte_t const bin[], size_t bin_len, char const *prefix, char str_buf[], size_t buf_len)#

Converts a byte array to hex string.

Parameters

  • bin – [in] A byte array

  • bin_len – [in] The length of byte array

  • prefix – [in] A prefix which will be inserted at the beginning of hex string

  • str_buf – [out] A buffer holds hex string data

  • buf_len – [in] The length of the buffer

Returns

int 0 on success

bool buf_all_zeros(uint8_t array[], size_t arr_len)#

Checks if buffer has only zeros.

Parameters

  • array – [in] A buffer holds data

  • arr_len – [in] The length of buffer

Returns

true If buffer has only zeros

Returns

false If buffer has also some other numbers