External client for sending new transactions to the system. More...

#include <client.hpp>

Inheritance diagram for cbdc::client:

[legend]

Public Types
enum class	address_type : uint8_t { public_key = 0 }
	Client address type signifier. More...

Public Member Functions
	client (cbdc::config::options opts, std::shared_ptr< logging::log > logger, std::string wallet_file, std::string client_file)
	Constructor.

virtual	~client ()=default

	client (const client &)=delete

auto	operator= (const client &) -> client &=delete

	client (client &&)=delete

auto	operator= (client &&) -> client &=delete

auto	init () -> bool
	Initializes the client.

auto	mint (size_t n_outputs, uint32_t output_val) -> transaction::full_tx
	Creates the specified number spendable outputs each with the specified value.

auto	send (uint32_t value, const pubkey_t &payee) -> std::pair< std::optional< transaction::full_tx >, std::optional< cbdc::sentinel::execute_response > >
	Send a specified amount from this client's wallet to a target address.

auto	fan (uint32_t count, uint32_t value, const pubkey_t &payee) -> std::pair< std::optional< transaction::full_tx >, std::optional< cbdc::sentinel::execute_response > >
	Send a specified number of fixed-value outputs from this client's wallet to a target address.

void	import_send_input (const transaction::input &in)
	Imports transaction data from a sender.

virtual auto	sync () -> bool=0
	Checks the status of pending transactions and updates the wallet's balance with the result.

auto	new_address () -> pubkey_t
	Generates a new wallet address that other clients can use to send money to this client using send.

auto	balance () -> uint64_t
	Returns the balance in this client's wallet.

auto	utxo_count () -> size_t
	Returns the number of UTXOs in this client's wallet.

auto	pending_tx_count () -> size_t
	Returns the number of unconfirmed transactions.

auto	pending_input_count () -> size_t
	Returns the number of pending received inputs.

auto	confirm_transaction (const hash_t &tx_id) -> bool
	Confirms the transaction with the given ID.

auto	create_transaction (uint32_t value, const pubkey_t &payee) -> std::optional< transaction::full_tx >
	Create a new transaction.

auto	send_transaction (const transaction::full_tx &tx) -> std::optional< cbdc::sentinel::execute_response >
	Send the given transaction to the sentinel.

auto	abandon_transaction (const hash_t &tx_id) -> bool
	Abandons a transaction currently awaiting confirmation.

auto	check_pending (const transaction::input &inp) -> bool
	Checks the client's pending transaction set for the specified transaction.

void	sign_transaction (transaction::full_tx &tx)
	Signs the given transaction for as far as client's wallet contains the transaction's keys.

Static Public Member Functions
static auto	print_amount (uint64_t val) -> std::string
	Format a value given in currency base units as USD.

static auto	export_send_inputs (const transaction::full_tx &send_tx, const pubkey_t &payee) -> std::vector< transaction::input >
	Extracts the transaction data that recipients need from senders to confirm pending transfers.

Protected Member Functions
virtual auto	init_derived () -> bool=0
	Initializes the derived class.

virtual auto	send_mint_tx (const transaction::full_tx &mint_tx) -> bool=0
	Sends the given minting transaction to a service that will accept and process it.

auto	pending_txs () const -> std::unordered_map< hash_t, transaction::full_tx, hashing::null >
	Returns the set of transactions pending confirmation.

auto	pending_inputs () const -> std::unordered_map< hash_t, transaction::input, hashing::null >
	Returns the set of imported inputs from senders.

Detailed Description

External client for sending new transactions to the system.

Definition at line 23 of file uhs/client/client.hpp.

Member Enumeration Documentation

◆ address_type

enum class cbdc::client::address_type : uint8_t

strong

Client address type signifier.

Prefixes client address data, indicating which addressing regime clients should use to transact with the address.

Enumerator
public_key	Pay-to-Public-Key (P2PK) address data.

Definition at line 232 of file uhs/client/client.hpp.

Constructor & Destructor Documentation

◆ client() [1/3]

cbdc::client::client	(	cbdc::config::options	opts,
		std::shared_ptr< logging::log >	logger,
		std::string	wallet_file,
		std::string	client_file )

Constructor.

Parameters

opts	configuration options.
logger	pointer shared logger.
wallet_file	name of .dat file in which to store the wallet data.
client_file	name of .dat file in which to store the internal state data.

Definition at line 61 of file uhs/client/client.cpp.

◆ ~client()

virtual cbdc::client::~client ( )

virtualdefault

◆ client() [2/3]

cbdc::client::client ( const client & )

delete

◆ client() [3/3]

cbdc::client::client ( client && )

delete

Member Function Documentation

◆ abandon_transaction()

auto cbdc::client::abandon_transaction ( const hash_t & tx_id ) -> bool

Abandons a transaction currently awaiting confirmation.

Releases the lock on the transactions input UTXOs so the client can attempt to use them again in a subsequent transaction.

Warning: Client implementations should only call this function when certain the transaction processing system has rejected or otherwise failed to process the specified transaction.

Parameters

tx_id ID of the transaction to abandon.

Returns: true if the transaction was in the client's pending transaction set and has been removed.

Definition at line 253 of file uhs/client/client.cpp.

References cbdc::transaction::full_tx::m_inputs.

◆ balance()

auto cbdc::client::balance ( ) -> uint64_t

Returns the balance in this client's wallet.

Returns: balance in base currency units.

See also: transaction::wallet::balance

Definition at line 218 of file uhs/client/client.cpp.

◆ check_pending()

auto cbdc::client::check_pending ( const transaction::input & inp ) -> bool

Checks the client's pending transaction set for the specified transaction.

Searches the client's pending transaction set and returns true if there is a transaction that contains the passed input as one of its inputs

Parameters

inp	the input to look for.

Returns: true if there the client has a pending transaction that contains inp.

Definition at line 239 of file uhs/client/client.cpp.

◆ confirm_transaction()

auto cbdc::client::confirm_transaction ( const hash_t & tx_id ) -> bool

Confirms the transaction with the given ID.

Searches the client's pending transactions and pending input sets for the specified transaction ID and confirms it. Erases spent outputs and adds confirmed inputs to the wallet and makes them available to spend.

Note: Does not query the transaction system to verify confirmation. Implementations should define sync methods to do so.

Parameters

tx_id the ID of the transaction to confirm.

Returns: true if the transaction was confirmed.

Definition at line 280 of file uhs/client/client.cpp.

◆ create_transaction()

auto cbdc::client::create_transaction	(	uint32_t	value,
		const pubkey_t &	payee ) -> std::optional<transaction::full_tx>

Create a new transaction.

Creates a signed transaction that constitutes sending a specified amount from this client's wallet to a target address. Selects a set of UTXOs to spend as transaction inputs, and locks them so they will not be used in further calls to this function.

Parameters

value	the amount to send in the base unit of the currency.
payee	the destination address of the transfer.

Returns: the transaction created.

Definition at line 121 of file uhs/client/client.cpp.

◆ export_send_inputs()

auto cbdc::client::export_send_inputs	(	const transaction::full_tx &	send_tx,
		const pubkey_t &	payee ) -> std::vector<transaction::input>

static

Extracts the transaction data that recipients need from senders to confirm pending transfers.

Returns the outputs of the send transaction intended for the target recipient, converted to inputs. Senders transmit this data to recipients, who then call import_send_input to receive the transfer.

Parameters

send_tx	the send transaction generated by send.
payee	the destination address of the transfer.

Returns: inputs to transmit to the send transaction recipient, or empty vector if there is no transaction output with the corresponding payee information.

Definition at line 197 of file uhs/client/client.cpp.

References cbdc::transaction::wallet::export_send_inputs().

Referenced by print_tx_result().

Here is the call graph for this function:

◆ fan()

auto cbdc::client::fan	(	uint32_t	count,
		uint32_t	value,
		const pubkey_t &	payee ) -> std::pair<std::optional<transaction::full_tx>, std::optional<cbdc::sentinel::execute_response>>

Send a specified number of fixed-value outputs from this client's wallet to a target address.

Generates, transmits, and, if possible, confirms a full transaction. Returns the transaction and system response data.

Parameters

count	number of outputs to generate.
value	the amount to send per output, in the base unit of the currency.
payee	the destination address of the transfer.

Returns: the transaction sent to the network for verification and the response from the sentinel client, or std::nullopt if generating or transmitting the transaction failed.

Definition at line 153 of file uhs/client/client.cpp.

◆ import_send_input()

void cbdc::client::import_send_input ( const transaction::input & in )

Imports transaction data from a sender.

Expects data generated by a sender's export_send_inputs. Stores the provided input as a credit awaiting confirmation from the transaction processing system using sync or a call to confirm_transaction.

Parameters

in	a spendable input generated by a sender.

Definition at line 203 of file uhs/client/client.cpp.

References cbdc::transaction::wallet::is_spendable(), cbdc::transaction::input::m_prevout, and cbdc::transaction::out_point::m_tx_id.

Here is the call graph for this function:

◆ init()

auto cbdc::client::init ( ) -> bool

Initializes the client.

Attempts to load the data files and establish connections to the system components.

Returns: true if initialization succeeded.

Definition at line 71 of file uhs/client/client.cpp.

Referenced by cbdc::sentinel::controller::init(), and cbdc::sentinel_2pc::controller::init().

◆ init_derived()

virtual auto cbdc::client::init_derived ( ) -> bool

protectedpure virtual

Initializes the derived class.

Called at the end of init. Subclasses should define custom initialization logic here.

Returns: true if the initialization succeeded.

Implemented in cbdc::atomizer_client, and cbdc::twophase_client.

◆ mint()

auto cbdc::client::mint	(	size_t	n_outputs,
		uint32_t	output_val ) -> transaction::full_tx

Creates the specified number spendable outputs each with the specified value.

Generates a transaction with the specified outputs and no inputs. Saves the transaction in the client's internal state. Submits the transaction to the system via send_mint_tx.

Parameters

n_outputs	number of new spendable outputs to create.
output_val	value of the amount to associate with each output in the base unit of the currency.

Returns: the completed transaction.

Definition at line 95 of file uhs/client/client.cpp.

◆ new_address()

auto cbdc::client::new_address ( ) -> pubkey_t

Generates a new wallet address that other clients can use to send money to this client using send.

Returns: a wallet address.

See also: transaction::wallet::generate_key

Definition at line 212 of file uhs/client/client.cpp.

Referenced by newaddress_command().

◆ operator=() [1/2]

auto cbdc::client::operator= ( client && ) -> client &=delete

delete

◆ operator=() [2/2]

auto cbdc::client::operator= ( const client & ) -> client &=delete

delete

◆ pending_input_count()

auto cbdc::client::pending_input_count ( ) -> size_t

Returns the number of pending received inputs.

Returns the number of inputs received from senders for which this client is awaiting confirmation from the transaction processing system.

Returns: number of unconfirmed inputs.

See also: import_send_input

Definition at line 230 of file uhs/client/client.cpp.

◆ pending_inputs()

auto cbdc::client::pending_inputs ( ) const -> std::unordered_map<hash_t, transaction::input, hashing::null>

nodiscardprotected

Returns the set of imported inputs from senders.

Returns the current set of pending inputs imported into this client via the import_send_input method which the system has yet to confirm.

Returns: a map of transaction ID to pending input.

Definition at line 346 of file uhs/client/client.cpp.

◆ pending_tx_count()

auto cbdc::client::pending_tx_count ( ) -> size_t

Returns the number of unconfirmed transactions.

Returns: number of unconfirmed transactions.

Definition at line 226 of file uhs/client/client.cpp.

◆ pending_txs()

auto cbdc::client::pending_txs ( ) const -> std::unordered_map<hash_t, transaction::full_tx, hashing::null>

nodiscardprotected

Returns the set of transactions pending confirmation.

Returns the set of pending transactions sent to the transaction processing system via the send or mint methods which the system has yet to confirm.

Returns: a map of transaction ID to pending transaction.

Definition at line 341 of file uhs/client/client.cpp.

◆ print_amount()

auto cbdc::client::print_amount ( uint64_t val ) -> std::string

static

Format a value given in currency base units as USD.

Assumes the atomic (base) unit of the currency is equivalent to $0.01 (one USD cent). Ex. 10000 <=> $100.00.

Parameters

val	value in currency base units.

Returns: USD formatted value.

Definition at line 88 of file uhs/client/client.cpp.

Referenced by confirmtx_command(), and main().

◆ send()

auto cbdc::client::send	(	uint32_t	value,
		const pubkey_t &	payee ) -> std::pair<std::optional<transaction::full_tx>, std::optional<cbdc::sentinel::execute_response>>

Send a specified amount from this client's wallet to a target address.

Generates, transmits, and, if possible, confirms a full transaction. Returns the transaction and system response data.

Parameters

value	the amount to send, in the base unit of the currency.
payee	the destination address of the transfer.

Returns: the transaction sent to the network for verification and the response from the sentinel client, or std::nullopt if generating or transmitting the transaction failed.

Definition at line 133 of file uhs/client/client.cpp.

◆ send_mint_tx()

virtual auto cbdc::client::send_mint_tx ( const transaction::full_tx & mint_tx ) -> bool

protectedpure virtual

Sends the given minting transaction to a service that will accept and process it.

Called by mint to send the resulting transaction. Subclasses should define custom transmission logic here.

Parameters

mint_tx invalid transaction that mints new coins.

Returns: true if the transaction was sent successfully.

Implemented in cbdc::atomizer_client, and cbdc::twophase_client.

◆ send_transaction()

auto cbdc::client::send_transaction ( const transaction::full_tx & tx ) -> std::optional<cbdc::sentinel::execute_response>

Send the given transaction to the sentinel.

Note: This function adds the transaction to the client's pending transaction set. It does not confirm the transaction. Call sync to do so.

Parameters

tx	the transaction to send.

Returns: the sentinel's response to the transaction, if any.

Definition at line 175 of file uhs/client/client.cpp.

References cbdc::sentinel::confirmed, cbdc::sentinel::to_string(), cbdc::to_string(), and cbdc::transaction::tx_id().

Here is the call graph for this function:

◆ sign_transaction()

void cbdc::client::sign_transaction ( transaction::full_tx & tx )

Signs the given transaction for as far as client's wallet contains the transaction's keys.

Parameters

tx	the transaction to sign.

Definition at line 108 of file uhs/client/client.cpp.

References cbdc::transaction::wallet::sign().

Here is the call graph for this function:

◆ sync()

virtual auto cbdc::client::sync ( ) -> bool

pure virtual

Checks the status of pending transactions and updates the wallet's balance with the result.

Implementations should combine their own system querying logic with the confirm_transaction abandon_transaction functions to update the client and wallet state.

Returns: false if the request failed.

Implemented in cbdc::atomizer_client, and cbdc::twophase_client.

◆ utxo_count()

auto cbdc::client::utxo_count ( ) -> size_t

Returns the number of UTXOs in this client's wallet.

Does not include those locked in pending transactions.

Returns: the number of available UTXOs.

See also: transaction::wallet::count

Definition at line 222 of file uhs/client/client.cpp.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ address_type

Constructor & Destructor Documentation

◆ client() [1/3]

◆ ~client()

◆ client() [2/3]

◆ client() [3/3]

Member Function Documentation

◆ abandon_transaction()

◆ balance()

◆ check_pending()

◆ confirm_transaction()

◆ create_transaction()

◆ export_send_inputs()

◆ fan()

◆ import_send_input()

◆ init()

◆ init_derived()

◆ mint()

◆ new_address()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pending_input_count()

◆ pending_inputs()

◆ pending_tx_count()

◆ pending_txs()

◆ print_amount()

◆ send()

◆ send_mint_tx()

◆ send_transaction()

◆ sign_transaction()

◆ sync()

◆ utxo_count()