Core API Reference#

The Core API is low level API implementation based on iotaledger/protocol-rfcs, it helps to process message easily with following key functions:

  • Address conversion

  • Message operations

  • Input/Output operations

  • Common utilities(bech32, slip10)

Address#

int address_from_ed25519_pub(byte_t const pub_key[], byte_t addr[])#

Get address from ed25519 public key.

Parameters

  • pub_key – [in] An ed25519 public key

  • addr – [out] Output address with length of 32 bytes

Returns

int 0 on success

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

Get Ed25519 keypair from given seed and path.

Parameters

  • seed – [in] A seed

  • seed_len – [in] The length of seed

  • path – [in] A string of path, ex: “m/0H/1H/2H” or “m/0’/1’/2’”

  • keypair – [out] The ed25519 keypair

Returns

int 0 on success

int address_from_path(byte_t seed[], size_t seed_len, char path[], byte_t out_addr[])#

Get address from seed and slip10 path.

Parameters

  • seed – [in] An IOTA seed

  • seed_len – [in] The length of seed

  • path – [in] A string of path, ex: “m/0H/1H/2H” or “m/0’/1’/2’”

  • out_addr – [out]

Returns

int 0 on success

int address_from_bech32(char const *hrp, char const *bech32_str, byte_t out_addr[])#

Get an IOTA address from a given bech32 string.

The address is 33 bytes which is a version byte + ed25519 address bytes

Parameters

  • hrp – [in] The human readable prefix

  • bech32_str – [in] An address string

  • out_addr – [out] an ed25519 address with the version byte

Returns

int 0 on success;

int address_2_bech32(byte_t const addr[], char const *hrp, char *bech32_addr)#

Get a bech32 string from a given address.

Parameters

  • addr – [in] An ed25519 address with the version byte

  • hrp – [in] The human readable prefix

  • bech32_addr – [out] An address string

Returns

int 0 on success

int address_bech32_to_hex(char const hrp[], char const bech32[], char hex[], size_t hex_len)#

Convert Bech32 address to ed25519 in hex string form.

Parameters

  • hrp – [in] The HRP prefix

  • bech32 – [in] A Bech32 address string

  • hex – [out] A buffer holds output

  • hex_len – [in] the length of the buffer, should bigger than 65 bytes

Returns

int 0 on success

Message#

struct core_message_t#

A message object.

Public Members

uint64_t network_id#

Network identifier.

It is first 8 bytes of the BLAKE2b-256 hash of the concatenation of the network type and the protocol version string.

UT_array *parents#

parents of this message

payload_t payload_type#

payload type

void *payload#

payload object, NULL is no payload

uint64_t nonce#

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

core_message_t *core_message_new()#

Allocate a core message object.

Returns

core_message_t*

void core_message_free(core_message_t *msg)#

Free a core message object.

Parameters

  • msg – [in] message object

int core_message_sign_transaction(core_message_t *msg)#

Sign a transaction message.

Parameters

  • msg – [in] A message with transaction payload

Returns

int 0 on success

void core_message_add_parent(core_message_t *msg, byte_t const msg_id[])#

Add a parent to the message.

Parameters

  • msg – [in] A message object

  • msg_id – [in] A message ID

size_t core_message_parent_len(core_message_t *msg)#

Get the number of parent.

Parameters

  • msg – [in] A message object

Returns

size_t

Indexation Payload#

struct indexation_t#

Indexation data structure.

The payload type of indexation is 2

Public Members

byte_buf_t *index#

The index key of the message.

byte_buf_t *data#

Data we are attaching.

indexation_t *indexation_new()#

Allocate indexation payload.

Returns

indexation_t*

void indexation_free(indexation_t *idx)#

Free an indexation payload.

Parameters

  • idx – [in] An indexation payload object

indexation_t *indexation_create(char const *index, byte_t data[], uint32_t data_len)#

Create an indexation payload with index and data.

Parameters

  • index – [in] An ASCII string

  • data – [in] A binary array

  • data_len – [in] The length of data

Returns

indexation_t* A pointer to indexation payload object

size_t indexation_serialize_length(indexation_t *idx)#

Get the serialized length of indexation payload.

Parameters

  • idx – [in] An indexation payload object

Returns

size_t The expect size of serialied data

size_t indexation_payload_serialize(indexation_t *idx, byte_t buf[])#

Serialize an indexation payload.

Parameters

  • idx – [in]

  • buf – [out]

Returns

size_t

Transaction Payload#

Transaction 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_ht for intput and SigLockedSingleOutput for output.

Public Members

uint8_t tx_type#

Set to value 0 to denote a Transaction Essence.

uint32_t payload_len#

The length in bytes of the optional payload.

utxo_input_ht *inputs#

any of UTXO input

outputs_ht *outputs#

any of UTXO output

void *payload#

an indexation payload at this moment

struct unlock_blocks#

An unlock block list object.

Public Members

unlock_block_t type#

0 denotes a Signature Unlock Block, 1 denotes a Reference Unlock Block.

uint16_t reference#

Represents the index of a pervious unlock block.

byte_t *sig_block#

signature type + public key + signature

struct unlock_blocks *next#

point to next block

transaction_essence_t *tx_essence_new()#

Allocate a transaction essence object.

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, byte_t tx_id[], uint8_t index)#

Add an input element to the essence.

Parameters

  • es – [in] An essence object

  • tx_id – [in] A transaction ID

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

Returns

int 0 on success

int tx_essence_add_input_with_key(transaction_essence_t *es, byte_t const tx_id[], uint8_t index, byte_t const pub[], byte_t const priv[])#

Add an input to the essence with ed25519 key pair.

Parameters

  • es – [in] An essence object

  • tx_id – [in] A transaction ID

  • index – [in] The index of the output

  • pub – [in] A ed25519 public key

  • priv – [in] A ed25519 private key

Returns

int 0 on success

int tx_essence_add_output(transaction_essence_t *es, output_type_t type, byte_t addr[], uint64_t amount)#

Add an output element to the essence.

Parameters

  • es – [in] An essence object

  • type – [in] The output type

  • addr – [in] An ed25519 address

  • amount – [in] The amount of tokens to deposit with this SigLockedSingleOutput 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 indexation payload at this moment, type = 2

Parameters

  • es – [in] An essence object

  • type – [in] A payload type

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

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 0 on failed

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

Serialize essence object.

Parameters

  • es – [in] An essence object

  • buf – [out] A buffer holds serialized data

Returns

size_t number of bytes written to the buffer

void tx_essence_print(transaction_essence_t *es)#

Print out a transaction essence.

Parameters

  • es – [in] An essence object

Transaction Payload#

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 Unlock Blocks which unlock the Transaction Essence’s inputs. In case the unlock block contains a signature, it signs the entire Transaction Essence part.

Public Members

payload_t type#

Set to value 0 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_blocks_t *unlock_blocks#

Defines an unlock block containing signature(s) unlocking input(s).

transaction_payload_t *tx_payload_new()#

Allocate a tansaction payload object.

Returns

transaction_payload_t*

int tx_payload_add_input(transaction_payload_t *tx, byte_t tx_id[], uint8_t index)#

Add an input to the transaction payload.

Parameters

  • tx – [in] A transaction payload object

  • tx_id – [in] A transaction ID

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

Returns

int 0 on success

int tx_payload_add_input_with_key(transaction_payload_t *tx, byte_t tx_id[], uint8_t index, byte_t const pub[], byte_t const priv[])#

Add an input with ed25519 keypair to the transaction payload.

Parameters

  • tx – [in] A transaction payload object

  • tx_id – [in] A transaction ID

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

  • pub – [in] The public key

  • priv – [in] The private key

Returns

int 0 on success

int tx_payload_add_output(transaction_payload_t *tx, output_type_t type, byte_t addr[], uint64_t amount)#

Add an output to the transaction payload.

Parameters

  • tx – [in] A transaction payload

  • type – [in] The output type

  • addr – [in] An ed25519 address

  • amount – [in] The amount of tokens to deposit with this SigLockedSingleOutput output

Returns

int 0 on success

int tx_payload_add_sig_block(transaction_payload_t *tx, byte_t *sig_block, size_t sig_len)#

Add a signature unlocked block to the transaction.

Parameters

  • tx – [in] A transaction payload

  • sig_block – [in] An ed25519 signature block

  • sig_len – [in] the length of ed25519 signature block

Returns

int 0 on success

int tx_payload_add_ref_block(transaction_payload_t *tx, uint16_t ref)#

Add a reference unlocked block to the transaction.

Parameters

  • tx – [in] A transaction payload

  • ref – [in] The index of reference

Returns

int 0 on success

size_t tx_payload_serialize_length(transaction_payload_t *tx)#

Get the 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[])#

Serialize a transaction payload.

Parameters

  • tx – [in] A transaction payload

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

Returns

size_t number of bytes written to the buffer

void tx_payload_print(transaction_payload_t *tx)#

Print out a transaction payload.

Parameters

  • tx – [in] A transaction payload

Outputs#

struct outputs_ht#

Stores deposit outputs in a hash table.

Public Members

uint8_t output_type#

0: SigLockedSingleOutput, 1: SigLockedDustAllowanceOutput

byte_t address[ED25519_ADDRESS_BYTES]#

Ed25519 address.

uint64_t amount#

The amount of tokens to deposit with this output.

static outputs_ht *utxo_outputs_new()#

Initialize an utxo output hash table.

Returns

outputs_ht* a NULL pointer

static void utxo_outputs_free(outputs_ht **ht)#

Free an utxo output hash table.

Parameters

  • utxo_ins – [in] An utxo output hash table.

int utxo_outputs_add(outputs_ht **ht, output_type_t type, byte_t addr[], uint64_t amount)#

Append an utxo output element to the table.

Parameters

  • ht – [in] An utxo output hash table

  • type – [in] output type

  • addr – [in] An ED25519 address

  • amount – [in] The amount of tokens to deposit

Returns

int 0 on success

static outputs_ht *utxo_outputs_find_by_addr(outputs_ht **ht, byte_t addr[])#

Find an utxo output by a given address.

Parameters

  • ht – [in] An utxo output hash table

  • addr – [in] An address for searching

Returns

outputs_ht*

static uint16_t utxo_outputs_count(outputs_ht **ht)#

Get the size of utxo outputs.

Parameters

  • ht – [in] An utxo output hash table.

Returns

uint16_t

size_t utxo_outputs_serialization(outputs_ht **ht, byte_t buf[])#

Serialize outputs to a buffer.

Parameters

  • ht – [in] An utxo output hash table

  • buf – [out] A buffer for serialization

Returns

size_t number of bytes write to the buffer

void utxo_outputs_print(outputs_ht **ht)#

Print an utxo output hash table.

Parameters

  • ht – [in] An utxo output hash table.

Inputs#

struct ed25519_keypair_t#

ED25519 keypair structure.

Public Members

byte_t pub_key[ED_PUBLIC_KEY_BYTES]#

The public key of the Ed25519 keypair which is used to verify the signature.

byte_t priv[ED_PRIVATE_KEY_BYTES]#

The private key for signing the serialized Unsigned Transaction.

struct utxo_input_ht#

UTXO input structure.

Public Members

byte_t tx_id[TRANSACTION_ID_BYTES]#

The transaction reference from which the UTXO comes from.

uint16_t output_index#

The index of the output on the referenced transaction to consume 0<= x < 127.

ed25519_keypair_t keypair#

ed25519 keypair of this input

static utxo_input_ht *utxo_inputs_new()#

Initialize an utxo input hash table.

Returns

utxo_inputs_t* a NULL pointer

static void utxo_inputs_free(utxo_input_ht **ht)#

Free an utxo input hash table.

Parameters

  • utxo_ins – [in] An utxo input hash table.

static utxo_input_ht *utxo_inputs_find_by_id(utxo_input_ht **inputs, byte_t const tx_id[])#

Find an utxo input by a given transaction ID.

Parameters

  • inputs – [in] An utxo input hash table

  • tx_id – [in] A transaction ID

Returns

utxo_input_ht*

static uint16_t utxo_inputs_count(utxo_input_ht **ht)#

Get the size of utxo inputs.

Parameters

  • ht – [in] An utxo input hash table.

Returns

uint16_t

int utxo_inputs_add(utxo_input_ht **inputs, byte_t tx_id[], uint16_t index)#

Append an utxo input element to the list.

Parameters

  • inputs – [in] An input hash table

  • tx_id – [in] A transaction ID

  • index – [in] An index

Returns

int 0 on success

int utxo_inputs_add_with_key(utxo_input_ht **inputs, byte_t const tx_id[], uint16_t index, byte_t const pub[], byte_t const priv[])#

Append an utxo input with keypair to hash table.

Parameters

  • inputs – [in] An input hash table

  • tx_id – [in] A transaction ID

  • index – [in] An index

  • pub – [in] An ed25519 public key

  • priv – [in] An ed25519 private key

Returns

int 0 on success

size_t utxo_inputs_serialization(utxo_input_ht **inputs, byte_t buf[])#

Serialize inputs to a buffer.

Parameters

  • inputs – [in] An utxo input hash table

  • buf – [out] A buffer for serialization

Returns

size_t number of bytes write to the buffer

void utxo_inputs_print(utxo_input_ht **inputs)#

Print an utxo input hash table.

Parameters

  • inputs – [in] An utxo input hash table.

Unlock Block#

unlock_blocks_t *unlock_blocks_new()#

Initialize a unlock block list object.

Returns

unlock_blocks_t* a NULL pointer

int unlock_blocks_add_signature(unlock_blocks_t **blocks, byte_t *sig, size_t sig_len)#

Add an ed25519 signature block.

Parameters

  • blocks – [in] The head of list

  • sig – [in] An ed25519 signature block

  • sig_len – [in] The length of signature block

Returns

int 0 on success

int unlock_blocks_add_reference(unlock_blocks_t **blocks, uint16_t ref)#

Add a reference block.

Parameters

  • blocks – [in] The head of list

  • ref – [in] The index of reference

Returns

int 0 on success.

uint16_t unlock_blocks_count(unlock_blocks_t *blocks)#

Get the length of unlock blocks.

Parameters

  • blocks – [in] The head of list

Returns

uint16_t

int32_t unlock_blocks_find_pub(unlock_blocks_t *blocks, byte_t const *const pub_key)#

Get the block index of a given public key.

Parameters

  • blocks – [in] The head of list

  • pub_key – [in] A ed25519 public key

Returns

int32_t if not found return -1 else retrun the index

size_t unlock_blocks_serialize_length(unlock_blocks_t *blocks)#

Get the serialized length of unlocked blocks.

Parameters

  • blocks – [in] The head of list

Returns

size_t 0 on failed

size_t unlock_blocks_serialize(unlock_blocks_t *blocks, byte_t buf[])#

Serialize unlock blocks.

Parameters

  • blocks – [in] The head of list

  • buf – [out] A buffer holds serialized data

Returns

size_t number of bytes written to the buffer

void unlock_blocks_free(unlock_blocks_t *blocks)#

Free an unlock block list.

Parameters

  • blocks – [in] An unlock block object

void unlock_blocks_print(unlock_blocks_t *blocks)#

Print out unlocked blocks object.

Parameters

  • blocks – [in] An unlock block object

Utils#

Bech32#

int iota_addr_bech32_encode(char *output, const char *hrp, const uint8_t *addr, size_t addr_len)#

Encode IOTA address to bech32 string.

Parameters

  • output – [out] An output buffer holds bech32 address string

  • hrp – [in] A string of human-readable prefixe

  • addr – [in] An address in bytes

  • addr_len – [in] The length of IOTA address which is 33

Returns

int 1 on success

int iota_addr_bech32_decode(uint8_t *addr_data, size_t *addr_len, const char *hrp, const char *addr_str)#

Decode a bech32 string to address byte data.

Parameters

  • addr_data – [out] A buffer holds the address byte data

  • addr_len – [out] the number bytes of address data

  • hrp – [in] An expected string of human-readable prefixe

  • addr_str – [in] A string of bech32 address

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_PIB32_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

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, 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

  • 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 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

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

  • buf_len – [in] The length of the buffer

Returns

int 0 on success

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] Inital 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.

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*

static 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

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*

void byte_buf_print(byte_buf_t *buf)#

Dumps buffer infomation for debug propose.

Parameters

  • buf – [in] A byte buffer