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[], char path[], iota_keypair_t *keypair)

Get Ed25519 keypair from given seed and path.

Parameters
  • seed[in] A 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[], char path[], byte_t out_addr[])

Get address from seed and slip10 path.

Parameters
  • seed[in] An IOTA 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

Transaction Payload

struct ed25519_signature_t

Public Members

signature_t type

Set to value 0 to denote an Ed25519 Signature.

byte_t pub_key[ED_PUBLIC_KEY_BYTES]

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

byte_t signature[ED_SIGNATURE_BYTES]

The signature signing the serialized Unsigned Transaction.

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 to denote a Signature Unlock Block, 1 for a Reference Unlock Block.

ed25519_signature_t signature

For signature unlock block, public key and signature for a specific input.

uint16_t reference

For reverence unlock block, the index of a previous unlock block.

struct unlock_blocks *prev

point to previous block

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

void tx_essence_print(transaction_essence_t *es)

Print out a transaction essence.

Parameters
  • es[in] An essence object

tx_unlock_blocks_t *tx_blocks_new()

Initialize a block list object.

Returns

tx_unlock_blocks_t* a NULL pointer

void tx_blocks_free(tx_unlock_blocks_t *blocks)

Free an unlock block list.

Parameters
  • blocks[in] An unlock block object

int tx_blocks_add_signature(tx_unlock_blocks_t **blocks, ed25519_signature_t *sig)

Add a signature block.

Parameters
  • blocks[in] The head of list

  • sig[in] A ed25519 signature object

Returns

int 0 on success

int tx_blocks_add_reference(tx_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 tx_blocks_count(tx_unlock_blocks_t *blocks)

Get the length of unlock blocks.

Parameters
  • blocks[in] The head of list

Returns

uint16_t

void tx_blocks_print(tx_unlock_blocks_t *blocks)

Print out unlocked blocks object.

Parameters
  • blocks[in] An unlock block 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.

tx_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, ed25519_signature_t *sig)

Add a signature unlocked block to the transaction.

Parameters
  • tx[in] A transaction payload

  • sig[in] An 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

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.

void utxo_outputs_print(outputs_ht **ht)

Print an utxo output hash table.

Parameters
  • ht[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

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.

void utxo_inputs_print(utxo_input_ht **inputs)

Print an utxo input hash table.

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

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

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

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*

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

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