Wallet API Reference#

The Wallet API provides some helper methods for developers to create wallet alllications.

Wallet Configuration#

struct iota_wallet_t#

IOTA wallet setting.

Public Members

byte_t seed[64]#

the mnemonic seed of this wallet

char bech32HRP[8]#

The Bech32 HRP of the network. iota for mainnet, atoi for testnet.

uint32_t account_index#

wallet account index

uint32_t coin_type#

the path component of SLIP44 coin type

iota_client_conf_t endpoint#

IOTA node endpoint.

uint8_t protocol_version#

Network protocol version of the connected node.

uint64_t network_id#

Network ID of the connected node.

byte_cost_config_t byte_cost#

The byte cost configuration of the network.

char indexer_path[32]#

The indexer plugins api path.

Create and Destory Methods#

iota_wallet_t *wallet_create(char const ms[], char const pwd[], uint32_t coin_type, uint32_t account_index)#

Create a wallet instance from the given mnemonic, password, and account index.

Parameters

  • ms – [in] A string of mnemonic, NULL for generating a random mnemonic

  • pwd – [in] A passphrase for seed derivation

  • coin_type – [in] The path component of SLIP44 coin type

  • account_index – [in] The account index

Returns

iota_wallet_t*

void wallet_destroy(iota_wallet_t *w)#

Destroy the wallet account.

Parameters

  • w – [in] A wallet instance

int wallet_set_endpoint(iota_wallet_t *w, char const host[], uint16_t port, bool use_tls)#

Set a node endpoint, if not calling this method default is “http://localhost:14265/”.

Parameters

  • w – [in] A wallet instance

  • host – [in] The hostname of the node

  • port – [in] The port number of the node

  • use_tls – [in] if use TLS or not

Returns

int 0 on success

int wallet_update_node_config(iota_wallet_t *w)#

Update configurations of connected node.

Parameters

  • w – [in] A wallet instance

Returns

int 0 on success

Address Methods#

int wallet_ed25519_address_from_index(iota_wallet_t *w, bool change, uint32_t index, address_t *addr)#

Get an ed25519 address from the given account, change, and index.

Parameters

  • w – [in] A wallet instance

  • change – [in] The change index which is {0, 1}, also known as wallet chain.

  • index – [in] Address index

  • addr – [out] A buffer holds ed25519 address

Returns

int 0 on success

int wallet_get_address_and_keypair_from_index(iota_wallet_t *w, bool change, uint32_t index, address_t *addr, ed25519_keypair_t *keypair)#

Get an ed25519 address and keypair from the given account, change, and index.

Parameters

  • w – [in] A wallet instance

  • change – [in] The change index which is {0, 1}, also known as wallet chain.

  • index – [in] Address index

  • addr – [out] A created ed25519 address

  • keypair – [out] A created keypair

Returns

int 0 on success

UTXO Methods#

bool wallet_is_collected_balance_sufficient(iota_wallet_t *w, uint64_t send_amount, uint64_t collected_amount, uint64_t remainder_amount, native_tokens_list_t *send_native_tokens, native_tokens_list_t *collected_native_tokens, native_tokens_list_t *remainder_native_tokens)#

Check if collected balance is sufficient for newly created outputs.

Parameters

  • w – [in] A wallet instance

  • send_amount – [in] Wanted amount to send

  • collected_amount – [in] A collected amount to be sent

  • remainder_amount – [in] A remainder amount to be sent

  • send_native_tokens – [in] A list of wanted native tokens to be sent

  • collected_native_tokens – [in] A list of collected native tokens to be sent

  • remainder_native_tokens – [in] A list of remainder native tokens to be sent

Returns

true if balance is sufficient otherwise false

int wallet_calculate_remainder_amount(uint64_t send_amount, uint64_t collected_amount, native_tokens_list_t *send_native_tokens, native_tokens_list_t *collected_native_tokens, uint64_t *remainder_amount, native_tokens_list_t **remainder_native_tokens)#

Calculate a remainder amount.

Parameters

  • send_amount – [in] Wanted amount to send

  • collected_amount – [in] A collected amount to be sent

  • send_native_tokens – [in] A list of wanted native tokens to be sent

  • collected_native_tokens – [in] A list of collected native tokens to be sent

  • remainder_amount – [out] A remainder amount of base tokens

  • remainder_native_tokens – [out] A remainder amount of native tokens

Returns

true if balance is sufficient otherwise false

int wallet_send(iota_wallet_t *w, address_t *sender_addr, ed25519_keypair_t *sender_keypair, utxo_inputs_list_t *inputs, utxo_outputs_list_t *outputs, native_tokens_list_t *minted_tokens, byte_t transaction_id[], res_send_block_t *blk_res)#

Send a block to the network with options.

Parameters

  • w – [in] A wallet instance

  • sender_addr – [in] The sender address

  • sender_keypair – [in] The sender keypair

  • inputs – [in] The inputs of the block

  • outputs – [in] The outputs of the block

  • minted_tokens – [in] A list of native tokens

  • transaction_id – [in] The transaction ID

  • blk_res – [out] the response object

Returns

int 0 on success

core_block_t *wallet_create_core_block(iota_wallet_t *w, transaction_payload_t *tx, utxo_outputs_list_t *unspent_outputs, signing_data_list_t *sign_data)#

Create and prepare core block.

Parameters

  • w – [in] A wallet instance

  • tx – [in] A transaction payload

  • unspent_outputs – [in] A list of unspent outputs

  • sign_data – [in] A list of signing data

Returns

core_block_t*

int wallet_send_block(iota_wallet_t *w, core_block_t *core_block, res_send_block_t *blk_res)#

Send core block to a network.

Parameters

  • w – [in] A wallet instance

  • core_block – [in] A core block which will be sent

  • blk_res – [out] A response of the transfer

Returns

int 0 on success

int wallet_alias_output_create(iota_wallet_t *w, bool sender_change, uint32_t sender_index, uint64_t const send_amount, address_t *state_ctrl_addr, address_t *govern_addr, uint32_t foundry_counter, address_t *alias_addr, res_send_block_t *blk_res)#

Send transaction which creates a new alias output.

Parameters

  • w – [in] A wallet instance

  • sender_change – [in] A sender change index which is {0, 1}, also known as a wallet chain

  • sender_index – [in] A sender address index

  • send_amount – [in] An amount to transfer

  • state_ctrl_addr – [in] A state controller address

  • govern_addr – [in] A governor address

  • foundry_counter – [in] A foundry counter

  • alias_addr – [out] A newly created alias address

  • blk_res – [out] A response of a transfer

Returns

int 0 on success

int wallet_alias_output_state_transition(iota_wallet_t *w, byte_t alias_id[], bool state_ctrl_change, uint32_t state_ctrl_index, address_t *govern_addr, uint32_t foundry_counter, uint64_t send_amount, utxo_outputs_list_t *outputs, native_tokens_list_t *minted_native_tokens, res_send_block_t *blk_res)#

Send alias state transition transaction.

Parameters

  • w – [in] A wallet instance

  • alias_id – [in] An alias identifier

  • state_ctrl_change – [in] A state controller change index which is {0, 1}, also known as a wallet chain

  • state_ctrl_index – [in] A state controller address index

  • govern_addr – [in] A governor address

  • foundry_counter – [in] A foundry counter number

  • send_amount – [in] An amount to transfer

  • outputs – [in] An outputs which will be created in a transaction in addition of possible remainder output

  • minted_native_tokens – [in] A list of minted native tokens which will be created in a transaction

  • blk_res – [out] A response of a transfer

Returns

int 0 on success

int wallet_alias_output_destroy(iota_wallet_t *w, byte_t alias_id[], bool govern_change, uint32_t govern_index, address_t *recv_addr, res_send_block_t *blk_res)#

Send transaction which destroys alias output.

Parameters

  • w – [in] A wallet instance

  • alias_id – [in] An alias identifier

  • govern_change – [in] A governor change index which is {0, 1}, also known as a wallet chain

  • govern_index – [in] A governor address index

  • recv_addr – [in] A receiver address

  • blk_res – [out] A response of a transfer

Returns

int 0 on success

output_basic_t *wallet_basic_output_create(address_t *recv_addr, uint64_t amount, native_tokens_list_t *native_tokens)#

Create and return a basic output.

Parameters

  • recv_addr – [in] A receiver address

  • amount – [in] An amount to sent

  • native_tokens – [in] A native tokens to sent

Returns

output_basic_t* or NULL on failure

res_outputs_id_t *wallet_get_unspent_basic_output_ids(iota_wallet_t *w, address_t *send_addr)#

Get all senders unspent basic output IDs from a network.

Parameters

  • w – [in] A wallet instance

  • send_addr – [in] A sender address

Returns

res_outputs_id_t* or NULL on failure

int wallet_basic_output_send(iota_wallet_t *w, bool sender_change, uint32_t sender_index, uint64_t send_amount, native_tokens_list_t *send_native_tokens, address_t *recv_addr, res_send_block_t *blk_res)#

Send basic transaction which transfers IOTA tokens to an address.

Parameters

  • w – [in] A wallet instance

  • sender_change – [in] A sender change index which is {0, 1}, also known as a wallet chain

  • sender_index – [in] A sender address index

  • send_amount – [in] An amount to sent

  • send_native_tokens – [in] A native tokens to sent

  • recv_addr – [in] A receiver address

  • blk_res – [out] A response of a block transfer

Returns

int 0 on success

int wallet_foundry_output_mint_native_tokens(iota_wallet_t *w, address_t *alias_addr, bool state_ctrl_change, uint32_t state_ctrl_index, address_t *govern_addr, address_t *receiver_addr, uint256_t *max_supply, uint256_t *minted_tokens, uint32_t serial_number, uint32_t foundry_counter, res_send_block_t *blk_res)#

Send mint native token transaction.

Parameters

  • w – [in] A wallet instance

  • alias_addr – [in] The alias address

  • state_ctrl_change – [in] The state controller change index which is {0, 1}, also known as wallet chain

  • state_ctrl_index – [in] The state controller address index

  • govern_addr – [in] The governor address

  • receiver_addr – [in] The receiver address to which newly minted native tokens will be transferred

  • max_supply – [in] The maximum supply of newly minted native tokens

  • minted_tokens – [in] The number of newly minted native tokens

  • serial_number – [in] The serial number of new foundry

  • foundry_counter – [in] The foundry counter number

  • blk_res – [out] The response of the transfer

Returns

int 0 on success

Mnemonic Sentence#

enum ms_lan_t#

Mnemonic supported languages with ISO 639-1 suffixes.

Values:

enumerator MS_LAN_EN#

English.

enumerator MS_LAN_KO#

Korean.

enumerator MS_LAN_ES#

Spanish.

enumerator MS_LAN_ZH_HANT#

Chinese Traditional.

enumerator MS_LAN_ZH_HANS#

Chinese Simplified.

enumerator MS_LAN_FR#

French.

enumerator MS_LAN_IT#

Italian.

enumerator MS_LAN_CS#

Czech.

enumerator MS_LAN_PT#

Portuguese.

enum ms_entropy_t#

Init entropy of mnemonic sentense.

With more entropy security is improved but the sentence length increases.

Values:

enumerator MS_ENTROPY_128#

12 mnemonic words

enumerator MS_ENTROPY_160#

15 mnemonic words

enumerator MS_ENTROPY_192#

18 mnemonic words

enumerator MS_ENTROPY_224#

21 mnemonic words

enumerator MS_ENTROPY_256#

24 mnemonic words

int mnemonic_to_seed(char const ms[], char const pwd[], byte_t seed[], size_t seed_len)#

Drive seed from a given mnemonic sentence.

Parameters

  • ms – [in] A mnemonic sentence

  • pwd – [in] A password string

  • seed – [out] A buffer holds output seed

  • seed_len – [in] the length of seed buffer

Returns

int

int mnemonic_generator(ms_entropy_t ent_len, ms_lan_t lang, char ms[], size_t ms_len)#

Generate a random word list from given entropy length.

Parameters

  • ent_len – [in] the init entropy length

  • lang – [in] the language of mnemonic

  • ms – [out] a buffer holds the mnemonic string

  • ms_len – [in] the length of mnemonic buffer

Returns

int 0 on success

int mnemonic_encode(byte_t const entropy[], ms_entropy_t ent_len, ms_lan_t lan, char ms_out[], size_t ms_len)#

encode mnemonic sentence from a given entropy.

Parameters

  • entropy – [in] the input entroty

  • ent_len – [in] the length of entroty, should be one of 16, 20, 24, 28, 32.

  • lan – [in] The expected language of mnemonic sentence

  • ms_out – [out] The output string of mnemonic sentence

  • ms_len – [in] the output buffer length

Returns

int 0 on success

size_t mnemonic_decode(char const ms_strs[], ms_lan_t lan, byte_t entropy[], size_t ent_len)#

decode mnemonic sentence to the entropy.

Parameters

  • ms_strs – [in] A string of mnemonic sentence

  • lan – [in] The language of the mnemonic sentence

  • entropy – [out] the output buffer, should bigger than 33 bytes(ENT+CS)

  • ent_len – [in] the size of the entropy buffer

Returns

size_t the bytes written to output buffer, 0 on failed.

int mnemonic_convertor(char const from[], ms_lan_t lan_from, char to[], size_t to_len, ms_lan_t lan_to)#

Convert mnemonic to another language.

Parameters

  • from – [in] A source mnemonic sentence

  • lan_from – [in] The language of source mnemonic

  • lan_to – [in] The language of target mnemonic

  • to – [out] A buffer for target mnemonic

  • to_len – [out] The length of target buffer

Returns

int

bool mnemonic_validation(char const ms[], ms_lan_t language)#

Check if mnemonic sentence is valid.

Parameters

  • ms – [in] A string of mnemonic sentence

  • language – [in] The language of the given mnemonic

Returns

true valid sentence

Returns

false invalid sentence