Crate tari_wallet_ffi[−][src]

LibWallet API Definition

This module contains the Rust backend implementations of the functionality that a wallet for the Tari Base Layer will require. The module contains a number of sub-modules that are implemented as async services. These services are collected into the main Wallet container struct which manages spinning up all the component services and maintains a collection of the handles required to interact with those services. This files contains the API calls that will be exposed to external systems that make use of this module. The API will be exposed via FFI and will consist of API calls that the FFI client can make into the Wallet module and a set of Callbacks that the client must implement and provide to the Wallet module to receive asynchronous replies and updates.

Wallet Flow Documentation

This documentation will described the flows of the core tasks that the Wallet library supports and will then describe how to use the test functions to produce the behaviour of a second wallet without needing to set one up.

Generate Test Data

The generate_wallet_test_data(...) function will generate some test data in the wallet. The data generated will be as follows:

Some Contacts
Add outputs to the wallet that make up its Available Balance that can be spent
Create transaction history
- Pending Inbound Transactions
- Pending Outbound Transactions
- Completed Transactions

Send Transaction

To send a transaction your wallet must have available funds and you must had added the recipient's Public Key as a Contact.

To send a transaction:

Call the send_transaction(dest_public_key, amount, fee_per_gram, message) function which will result in a PendingOutboundTransaction being produced and transmitted to the recipient and the funds becoming encumbered and appearing in the PendingOutgoingBalance and any change will appear in the PendingIncomingBalance.
Wait until the recipient replies to the sent transaction which will result in the PendingOutboundTransaction becoming a CompletedTransaction with the Completed status. This means that the transaction has been negotiated between the parties and is now ready to be broadcast to the Base Layer. The funds are still encumbered as pending because the transaction has not been mined yet.
The finalized `CompletedTransaction' will be sent back to the the receiver so that they have a copy.
The wallet will broadcast the CompletedTransaction to a Base Node to be added to the mempool. its status will from Completed to `Broadcast.
Wait until the transaction is mined. The CompleteTransaction status will then move from Broadcast to Mined and the pending funds will be spent and received.

Receive a Transaction

When a transaction is received it will appear as an InboundTransaction and the amount to be received will appear as a PendingIncomingBalance. The wallet backend will be listening for these transactions and will immediately reply to the sending wallet.
The sender will send back the finalized CompletedTransaction
This wallet will also broadcast the CompletedTransaction to a Base Node to be added to the mempool, its status will move from Completed to Broadcast. This is done so that the Receiver can be sure the finalized transaction is broadcast.
This wallet will then monitor the Base Layer to see when the transaction is mined which means the CompletedTransaction status will become Mined and the funds will then move from the PendingIncomingBalance to the AvailableBalance.

Using the test functions

The above two flows both require a second wallet for this wallet to interact with. Because we do not yet have a live Test Net and the communications layer is not quite ready the library supplies four functions to help simulate the second wallets role in these flows. The following will describe how to use these functions to produce the flows.

Send Transaction with test functions

Send Transaction as above to produce a PendingOutboundTransaction.
Call the complete_sent_transaction(...) function with the tx_id of the sent transaction to simulate a reply. This will move the PendingOutboundTransaction to become a CompletedTransaction with the Completed status.
Call the 'broadcast_transaction(...)` function with the tx_id of the sent transaction and its status will move from 'Completed' to 'Broadcast' which means it has been broadcast to the Base Layer Mempool but not mined yet. from 'Completed' to 'Broadcast' which means it has been broadcast to the Base Layer Mempool but not mined yet.
Call the mined_transaction(...) function with the tx_id of the sent transaction which will change the status of the CompletedTransaction from Broadcast to Mined. The pending funds will also become finalized as spent and available funds respectively.

Receive Transaction with test functions

Under normal operation another wallet would initiate a Receive Transaction flow by sending you a transaction. We will use the receive_test_transaction(...) function to initiate the flow:

Calling receive_test_transaction(...) will produce an InboundTransaction, the amount of the transaction will appear under the PendingIncomingBalance.
To simulate detecting the InboundTransaction being broadcast to the Base Layer Mempool call broadcast_transaction(...) function. This will change the InboundTransaction to a CompletedTransaction with the Broadcast status. The funds will still reflect in the pending balance.
Call the mined_transaction(...) function with the tx_id of the received transaction which will change the status of the CompletedTransaction from Broadcast to Mined. The pending funds will also become finalized as spent and available funds respectively

Structs

ByteVector
EmojiSet
TariCompletedTransactions
TariContacts
TariPendingInboundTransactions
TariPendingOutboundTransactions
TariSeedWords
TariWallet

Functions

byte_vector_create ^⚠	-------------------------------------------------------------------------------------------- /// -------------------------------- ByteVector ------------------------------------------------ /// Creates a ByteVector
byte_vector_destroy ^⚠	Frees memory for a ByteVector
byte_vector_get_at ^⚠	Gets a c_uchar at position in a ByteVector
byte_vector_get_length ^⚠	Gets the number of elements in a ByteVector
comms_config_create ^⚠	---------------------------------------------------------------------------------------------/// ----------------------------------- CommsConfig ---------------------------------------------/// Creates a TariCommsConfig. The result from this function is required when initializing a TariWallet.
comms_config_destroy ^⚠	Frees memory for a TariCommsConfig
comms_config_set_secret_key ^⚠	Set the Comms Secret Key for an existing TariCommsConfig. Usually this key is maintained by the backend but if it is required to set a specific new one this function can be used.
completed_transaction_destroy ^⚠	Frees memory for a TariCompletedTransaction
completed_transaction_get_amount ^⚠	Gets the amount of a TariCompletedTransaction
completed_transaction_get_destination_public_key ^⚠	Gets the destination TariPublicKey of a TariCompletedTransaction
completed_transaction_get_excess ^⚠	Gets the TariExcess of a TariCompletedTransaction
completed_transaction_get_fee ^⚠	Gets the fee of a TariCompletedTransaction
completed_transaction_get_message ^⚠	Gets the message of a TariCompletedTransaction
completed_transaction_get_public_nonce ^⚠	Gets the TariExcessPublicNonce of a TariCompletedTransaction
completed_transaction_get_signature ^⚠	Gets the TariExcessSignature of a TariCompletedTransaction
completed_transaction_get_source_public_key ^⚠	Gets the source TariPublicKey of a TariCompletedTransaction
completed_transaction_get_status ^⚠	Gets the status of a TariCompletedTransaction
completed_transaction_get_timestamp ^⚠	Gets the timestamp of a TariCompletedTransaction
completed_transaction_get_transaction_id ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- CompletedTransaction ------------------------------------- /// Gets the TransactionID of a TariCompletedTransaction
completed_transaction_is_outbound ^⚠	This function checks to determine if a TariCompletedTransaction was originally a TariPendingOutboundTransaction
completed_transactions_destroy ^⚠	Frees memory for a TariCompletedTransactions
completed_transactions_get_at ^⚠	Gets a TariCompletedTransaction from a TariCompletedTransactions at position
completed_transactions_get_length ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- CompletedTransactions ----------------------------------- /// Gets the length of a TariCompletedTransactions
contact_create ^⚠	----------------------------------- Contact -------------------------------------------------/// Creates a TariContact
contact_destroy ^⚠	Frees memory for a TariContact
contact_get_alias ^⚠	Gets the alias of the TariContact
contact_get_public_key ^⚠	Gets the TariPublicKey of the TariContact
contacts_destroy ^⚠	Frees memory for a TariContacts
contacts_get_at ^⚠	Gets a TariContact from TariContacts at position
contacts_get_length ^⚠	----------------------------------- Contacts -------------------------------------------------/// Gets the length of TariContacts
emoji_id_to_public_key ^⚠	Creates a TariPublicKey from a char array in emoji format
emoji_set_destroy ^⚠	Frees memory for a EmojiSet
emoji_set_get_at ^⚠	Gets a ByteVector at position in a EmojiSet
emoji_set_get_length ^⚠	Gets the length of the current emoji set
excess_destroy ^⚠	Frees memory for a TariExcess
file_partial_backup ^⚠	This function will produce a partial backup of the specified wallet database file. This backup will be written to the provided file (full path must include the filename and extension) and will include the full wallet db but will clear the sensitive Comms Private Key
get_emoji_set ^⚠	Gets the current emoji set
log_debug_message ^⚠	This function will log the provided string at debug level. To be used to have a client log messages to the LibWallet logs.
nonce_destroy ^⚠	Frees memory for a TariExcessPublicNonce
pending_inbound_transaction_destroy ^⚠	Frees memory for a TariPendingInboundTransaction
pending_inbound_transaction_get_amount ^⚠	Gets the amount of a TariPendingInboundTransaction
pending_inbound_transaction_get_message ^⚠	Gets the message of a TariPendingInboundTransaction
pending_inbound_transaction_get_source_public_key ^⚠	Gets the source TariPublicKey of a TariPendingInboundTransaction
pending_inbound_transaction_get_status ^⚠	Gets the status of a TariPendingInboundTransaction
pending_inbound_transaction_get_timestamp ^⚠	Gets the timestamp of a TariPendingInboundTransaction
pending_inbound_transaction_get_transaction_id ^⚠	-------------------------------------------------------------------------------------------- ///
pending_inbound_transactions_destroy ^⚠	Frees memory for a TariPendingInboundTransactions
pending_inbound_transactions_get_at ^⚠	Gets a TariPendingInboundTransaction of a TariPendingInboundTransactions
pending_inbound_transactions_get_length ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- InboundTransactions ------------------------------------- /// Gets the length of a TariPendingInboundTransactions
pending_outbound_transaction_destroy ^⚠	Frees memory for a TariPendingOutboundTransaction
pending_outbound_transaction_get_amount ^⚠	Gets the amount of a TariPendingOutboundTransaction
pending_outbound_transaction_get_destination_public_key ^⚠	Gets the destination TariPublicKey of a TariPendingOutboundTransaction
pending_outbound_transaction_get_fee ^⚠	Gets the fee of a TariPendingOutboundTransaction
pending_outbound_transaction_get_message ^⚠	Gets the message of a TariPendingOutboundTransaction
pending_outbound_transaction_get_status ^⚠	Gets the status of a TariPendingOutboundTransaction
pending_outbound_transaction_get_timestamp ^⚠	Gets the timestamp of a TariPendingOutboundTransaction
pending_outbound_transaction_get_transaction_id ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- OutboundTransaction ------------------------------------- /// Gets the TransactionId of a TariPendingOutboundTransaction
pending_outbound_transactions_destroy ^⚠	Frees memory for a TariPendingOutboundTransactions
pending_outbound_transactions_get_at ^⚠	Gets a TariPendingOutboundTransaction of a TariPendingOutboundTransactions
pending_outbound_transactions_get_length ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- OutboundTransactions ------------------------------------ /// Gets the length of a TariPendingOutboundTransactions
private_key_create ^⚠	-------------------------------------------------------------------------------------------- /// -------------------------------- Private Key ----------------------------------------------- /// Creates a TariPrivateKey from a ByteVector
private_key_destroy ^⚠	Frees memory for a TariPrivateKey
private_key_from_hex ^⚠	Creates a TariPrivateKey from a char array
private_key_generate ^⚠	Generates a TariPrivateKey
private_key_get_bytes ^⚠	Gets a ByteVector from a TariPrivateKey
public_key_create ^⚠	-------------------------------------------------------------------------------------------- /// -------------------------------- Public Key ------------------------------------------------ /// Creates a TariPublicKey from a ByteVector
public_key_destroy ^⚠	Frees memory for a TariPublicKey
public_key_from_hex ^⚠	Creates a TariPublicKey from a char array
public_key_from_private_key ^⚠	Creates a TariPublicKey from a TariPrivateKey
public_key_get_bytes ^⚠	Gets a ByteVector from a TariPublicKey
public_key_to_emoji_id ^⚠	Creates a char array from a TariPublicKey in emoji format
seed_words_destroy ^⚠	Frees memory for a TariSeedWords
seed_words_get_at ^⚠	Gets a seed word from TariSeedWords at position
seed_words_get_length ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- Seed Words ----------------------------------------------/// Gets the length of TariSeedWords
signature_destroy ^⚠	Frees memory for a TariExcessSignature
string_destroy ^⚠	-------------------------------- Strings ------------------------------------------------ /// Frees memory for a char array
transport_memory_create ^⚠	-------------------------------------------------------------------------------------------- /// ----------------------------------- Transport Types -----------------------------------------/// Creates a memory transport type
transport_memory_get_address ^⚠	Gets the address for a memory transport type
transport_tcp_create ^⚠	Creates a tcp transport type
transport_tor_create ^⚠	Creates a tor transport type
transport_type_destroy ^⚠	Frees memory for a TariTransportType
wallet_add_base_node_peer ^⚠	Adds a base node peer to the TariWallet
wallet_apply_encryption ^⚠	Apply encryption to the databases used in this wallet using the provided passphrase. If the databases are already encrypted this function will fail.
wallet_cancel_pending_transaction ^⚠	Cancel a Pending Transaction
wallet_clear_value ^⚠	Clears a Value for the provided Key Value in the Wallet storage used for Client Key Value store
wallet_coin_split ^⚠	This function will tell the wallet to do a coin split.
wallet_create ^⚠	---------------------------------------------------------------------------------------------- /// ------------------------------------- Wallet -------------------------------------------------/// Creates a TariWallet
wallet_destroy ^⚠	Frees memory for a TariWallet
wallet_get_available_balance ^⚠	Gets the available balance from a TariWallet. This is the balance the user can spend.
wallet_get_cancelled_transaction_by_id ^⚠	Get a Cancelled transaction from a TariWallet by its TransactionId. Pending Inbound or Outbound transaction will be converted to a CompletedTransaction
wallet_get_cancelled_transactions ^⚠	Get the all Cancelled Transactions from a TariWallet. This function will also get cancelled pending inbound and outbound transaction and include them in this list by converting them to CompletedTransactions
wallet_get_completed_transaction_by_id ^⚠	Get the TariCompletedTransaction from a TariWallet by its' TransactionId
wallet_get_completed_transactions ^⚠	Get the TariCompletedTransactions from a TariWallet
wallet_get_contacts ^⚠	Get the TariContacts from a TariWallet
wallet_get_fee_estimate ^⚠	Gets a fee estimate for an amount
wallet_get_pending_inbound_transaction_by_id ^⚠	Get the TariPendingInboundTransaction from a TariWallet by its' TransactionId
wallet_get_pending_inbound_transactions ^⚠	Get the TariPendingInboundTransactions from a TariWallet
wallet_get_pending_incoming_balance ^⚠	Gets the incoming balance from a `TariWallet`. This is the uncleared balance of Tari that is expected to come into the `TariWallet` but is not yet spendable.
wallet_get_pending_outbound_transaction_by_id ^⚠	Get the TariPendingOutboundTransaction from a TariWallet by its' TransactionId
wallet_get_pending_outbound_transactions ^⚠	Get the TariPendingOutboundTransactions from a TariWallet
wallet_get_pending_outgoing_balance ^⚠	Gets the outgoing balance from a `TariWallet`. This is the uncleared balance of Tari that has been spent
wallet_get_public_key ^⚠	Get the TariPublicKey from a TariWallet
wallet_get_seed_words ^⚠	Gets the seed words representing the seed private key of the provided `TariWallet`.
wallet_get_tor_identity ^⚠	Gets the private key for tor
wallet_get_value ^⚠	get a stored Value that was previously stored in the Wallet storage used for Client Key Value store
wallet_import_utxo ^⚠	Import a UTXO into the wallet. This will add a spendable UTXO and create a faux completed transaction to record the event.
wallet_remove_contact ^⚠	Removes a TariContact from the TariWallet
wallet_remove_encryption ^⚠	Remove encryption to the databases used in this wallet. If this wallet is currently encrypted this encryption will be removed. If it is not encrypted then this function will still succeed to make the operation idempotent
wallet_send_transaction ^⚠	Sends a TariPendingOutboundTransaction
wallet_set_key_value ^⚠	Set a Key Value in the Wallet storage used for Client Key Value store
wallet_set_low_power_mode ^⚠	Set the power mode of the wallet to Low Power mode which will reduce the amount of network operations the wallet performs to conserve power
wallet_set_normal_power_mode ^⚠	Set the power mode of the wallet to Normal Power mode which will then use the standard level of network traffic
wallet_sign_message ^⚠	Signs a message using the public key of the TariWallet
wallet_sync_with_base_node ^⚠	This function will tell the wallet to query the set base node to confirm the status of wallet data. For example this will check that Unspent Outputs stored in the wallet are still available as UTXO's on the blockchain. This will also trigger a request for outstanding SAF messages to you neighbours
wallet_test_broadcast_transaction ^⚠	This function will simulate the process when a completed transaction is broadcast to the base layer mempool. The function will update the status of the completed transaction
wallet_test_complete_sent_transaction ^⚠	This function simulates a receiver accepting and replying to a `TariPendingOutboundTransaction`. This results in that transaction being "completed" and it's status set to `Broadcast` which indicated it is in a base_layer mempool.
wallet_test_finalize_received_transaction ^⚠	This function will simulate the process when a completed transaction is broadcast to the base layer mempool. The function will update the status of the completed transaction
wallet_test_generate_data ^⚠	This function will generate some test data in the wallet. The data generated will be as follows:
wallet_test_mine_transaction ^⚠	This function will simulate the process when a completed transaction is detected as mined on the base layer. The function will update the status of the completed transaction AND complete the transaction on the Output Manager Service which will update the status of the outputs
wallet_test_receive_transaction ^⚠	This function simulates an external `TariWallet` sending a transaction to this `TariWallet` which will become a `TariPendingInboundTransaction`
wallet_upsert_contact ^⚠	Upserts a TariContact to the TariWallet. If the contact does not exist it will be Inserted. If it does exist the Alias will be updated.
wallet_verify_message_signature ^⚠	Verifies the signature of the message signed by a TariWallet

Type Definitions

TariCommsConfig
TariCompletedTransaction
TariContact
TariExcess
TariExcessPublicNonce
TariExcessSignature
TariPendingInboundTransaction
TariPendingOutboundTransaction
TariPrivateKey
TariPublicKey
TariTransportType