Struct MintClientModule

pub struct MintClientModule {
    pub(crate) federation_id: FederationId,
    pub(crate) cfg: MintClientConfig,
    pub(crate) secret: DerivableSecret,
    pub(crate) secp: Secp256k1<All>,
    pub(crate) notifier: ModuleNotifier<MintClientStateMachines>,
    pub client_ctx: ClientContext<Self>,
}

The MintClientModule is responsible for handling e-cash minting operations. It interacts with the mint server to issue, reissue, and validate e-cash notes.

Derivable Secret

The DerivableSecret is a cryptographic secret that can be used to derive other secrets. In the context of the MintClientModule, it is used to derive the blinding and spend keys for e-cash notes. The DerivableSecret is initialized when the MintClientModule is created and is kept private within the module.

Blinding Key

The blinding key is derived from the DerivableSecret and is used to blind the e-cash note during the issuance process. This ensures that the mint server cannot link the e-cash note to the client that requested it, providing privacy for the client.

Spend Key

The spend key is also derived from the DerivableSecret and is used to spend the e-cash note. Only the client that possesses the DerivableSecret can derive the correct spend key to spend the e-cash note. This ensures that only the owner of the e-cash note can spend it.

Fields

federation_id: FederationId

cfg: MintClientConfig

secret: DerivableSecret

secp: Secp256k1<All>

notifier: ModuleNotifier<MintClientStateMachines>

client_ctx: ClientContext<Self>

Implementations

impl MintClientModule

pub async fn prepare_plaintext_ecash_backup( &self, dbtx: &mut DatabaseTransaction<'_>, ) -> Result<EcashBackup>

impl MintClientModule

pub(crate) async fn create_sufficient_input( &self, dbtx: &mut DatabaseTransaction<'_>, operation_id: OperationId, min_amount: Amount, ) -> Result<ClientInputBundle<MintInput, MintClientStateMachines>>

pub async fn get_notes_tier_counts( &self, dbtx: &mut DatabaseTransaction<'_>, ) -> TieredCounts

Returns the number of held e-cash notes per denomination

pub async fn get_available_notes_by_tier_counts( &self, dbtx: &mut DatabaseTransaction<'_>, counts: TieredCounts, ) -> (TieredMulti<SpendableNoteUndecoded>, TieredCounts)

Pick SpendableNotes by given counts, when available

Return the notes picked, and counts of notes that were not available.

pub async fn create_exact_output( &self, dbtx: &mut DatabaseTransaction<'_>, operation_id: OperationId, notes_per_denomination: u16, exact_amount: Amount, ) -> Vec<ClientOutput<MintOutput, MintClientStateMachines>>

Creates a mint output with exactly the given amount, issuing e-cash notes such that the client holds notes_per_denomination notes of each e-cash note denomination held.

pub async fn get_wallet_summary( &self, dbtx: &mut DatabaseTransaction<'_>, ) -> TieredCounts

Returns the number of held e-cash notes per denomination

pub async fn await_output_finalized( &self, operation_id: OperationId, out_point: OutPoint, ) -> Result<Amount>

Wait for the e-cash notes to be retrieved. If this is not possible because another terminal state was reached an error describing the failure is returned.

pub async fn consolidate_notes( &self, dbtx: &mut DatabaseTransaction<'_>, operation_id: OperationId, ) -> Result<ClientInputBundle<MintInput, MintClientStateMachines>>

Provisional implementation of note consolidation

When a certain denomination crosses the threshold of notes allowed, spend some chunk of them as inputs.

Return notes and the sume of their amount.

pub fn create_input_from_notes( &self, operation_id: OperationId, notes: TieredMulti<SpendableNote>, ) -> Result<ClientInputBundle<MintInput, MintClientStateMachines>>

Create a mint input from external, potentially untrusted notes

pub(crate) async fn spend_notes_oob( &self, dbtx: &mut DatabaseTransaction<'_>, notes_selector: &impl NotesSelector, amount: Amount, try_cancel_after: Duration, ) -> Result<(OperationId, Vec<MintClientStateMachines>, TieredMulti<SpendableNote>)>

pub async fn await_spend_oob_refund( &self, operation_id: OperationId, ) -> SpendOOBRefund

pub(crate) async fn select_notes( dbtx: &mut DatabaseTransaction<'_>, notes_selector: &impl NotesSelector, requested_amount: Amount, fee_per_note_input: Amount, ) -> Result<TieredMulti<SpendableNote>>

Select notes with requested_amount using notes_selector.

pub(crate) async fn get_all_spendable_notes( dbtx: &mut DatabaseTransaction<'_>, ) -> TieredMulti<SpendableNoteUndecoded>

pub(crate) async fn get_next_note_index( &self, dbtx: &mut DatabaseTransaction<'_>, amount: Amount, ) -> NoteIndex

pub fn new_note_secret_static( secret: &DerivableSecret, amount: Amount, note_idx: NoteIndex, ) -> DerivableSecret

Derive the note DerivableSecret from the Mint’s secret the amount tier and note_idx

Static to help re-use in other places, that don’t have a whole Self available

E-Cash Note Creation

When creating an e-cash note, the MintClientModule first derives the blinding and spend keys from the DerivableSecret. It then creates a NoteIssuanceRequest containing the blinded spend key and sends it to the mint server. The mint server signs the blinded spend key and returns it to the client. The client can then unblind the signed spend key to obtain the e-cash note, which can be spent using the spend key.

pub(crate) async fn new_note_secret( &self, amount: Amount, dbtx: &mut DatabaseTransaction<'_>, ) -> DerivableSecret

We always keep track of an incrementing index in the database and use it as part of the derivation path for the note secret. This ensures that we never reuse the same note secret twice.

pub async fn new_ecash_note( &self, amount: Amount, dbtx: &mut DatabaseTransaction<'_>, ) -> (NoteIssuanceRequest, BlindNonce)

pub async fn reissue_external_notes<M: Serialize + Send>( &self, oob_notes: OOBNotes, extra_meta: M, ) -> Result<OperationId>

Try to reissue e-cash notes received from a third party to receive them in our wallet. The progress and outcome can be observed using MintClientModule::subscribe_reissue_external_notes. Can return error of type ReissueExternalNotesError

pub async fn subscribe_reissue_external_notes( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<ReissueExternalNotesState>>

Subscribe to updates on the progress of a reissue operation started with MintClientModule::reissue_external_notes.

pub async fn spend_notes<M: Serialize + Send>( &self, min_amount: Amount, try_cancel_after: Duration, include_invite: bool, extra_meta: M, ) -> Result<(OperationId, OOBNotes)>

👎Deprecated since 0.5.0: Use spend_notes_with_selector instead, with SelectNotesWithAtleastAmount to maintain the same behavior

Fetches and removes notes of at least amount min_amount from the wallet to be sent to the recipient out of band. These spends can be canceled by calling MintClientModule::try_cancel_spend_notes as long as the recipient hasn’t reissued the e-cash notes themselves yet.

The client will also automatically attempt to cancel the operation after try_cancel_after time has passed. This is a safety mechanism to avoid users forgetting about failed out-of-band transactions. The timeout should be chosen such that the recipient (who is potentially offline at the time of receiving the e-cash notes) had a reasonable timeframe to come online and reissue the notes themselves.

pub async fn spend_notes_with_selector<M: Serialize + Send>( &self, notes_selector: &impl NotesSelector, requested_amount: Amount, try_cancel_after: Duration, include_invite: bool, extra_meta: M, ) -> Result<(OperationId, OOBNotes)>

Fetches and removes notes from the wallet to be sent to the recipient out of band. The not selection algorithm is determined by note_selector. See the NotesSelector trait for available implementations.

These spends can be canceled by calling MintClientModule::try_cancel_spend_notes as long as the recipient hasn’t reissued the e-cash notes themselves yet.

The client will also automatically attempt to cancel the operation after try_cancel_after time has passed. This is a safety mechanism to avoid users forgetting about failed out-of-band transactions. The timeout should be chosen such that the recipient (who is potentially offline at the time of receiving the e-cash notes) had a reasonable timeframe to come online and reissue the notes themselves.

pub fn validate_notes(&self, oob_notes: &OOBNotes) -> Result<Amount>

Validate the given notes and return the total amount of the notes. Validation checks that:

• the federation ID is correct
• the note has a valid signature
• the spend key is correct.

pub async fn try_cancel_spend_notes(&self, operation_id: OperationId)

Try to cancel a spend operation started with MintClientModule::spend_notes_with_selector. If the e-cash notes have already been spent this operation will fail which can be observed using MintClientModule::subscribe_spend_notes.

pub async fn subscribe_spend_notes( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<SpendOOBState>>

Subscribe to updates on the progress of a raw e-cash spend operation started with MintClientModule::spend_notes_with_selector.

pub(crate) async fn mint_operation( &self, operation_id: OperationId, ) -> Result<OperationLogEntry>

pub(crate) async fn delete_spendable_note( client_ctx: &ClientContext<MintClientModule>, dbtx: &mut DatabaseTransaction<'_>, amount: Amount, note: &SpendableNote, )

pub async fn advance_note_idx(&self, amount: Amount) -> Result<DerivableSecret>

Trait Implementations

impl ClientModule for MintClientModule

type Init = MintClientInit

type Common = MintModuleTypes

Common module types shared between client and server

type Backup = EcashBackup

Data stored in regular backups so that restoring doesn’t have to start from epoch 0

type ModuleStateMachineContext = MintClientContext

Data and API clients available to state machine transitions of this module

type States = MintClientStateMachines

All possible states this client can submit to the executor

fn context(&self) -> Self::ModuleStateMachineContext

fn input_fee( &self, _amount: Amount, _input: &<Self::Common as ModuleCommon>::Input, ) -> Option<Amount>

Returns the fee the processing of this input requires.

fn output_fee( &self, _output: &<Self::Common as ModuleCommon>::Output, ) -> Option<Amount>

Returns the fee the processing of this output requires.

fn handle_cli_command<'life0, 'life1, 'async_trait>( &'life0 self, args: &'life1 [OsString], ) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn supports_backup(&self) -> bool

fn backup<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<EcashBackup>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn supports_being_primary(&self) -> bool

Does this module support being a primary module

fn create_final_inputs_and_outputs<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dbtx: &'life1 mut DatabaseTransaction<'life2>, operation_id: OperationId, input_amount: Amount, output_amount: Amount, ) -> Pin<Box<dyn Future<Output = Result<(ClientInputBundle<MintInput, MintClientStateMachines>, Vec<ClientOutput<MintOutput, MintClientStateMachines>>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Creates all inputs and outputs necessary to balance the transaction. The function returns an error if and only if the client’s funds are not sufficient to create the inputs necessary to fully fund the transaction.

fn await_primary_module_output<'life0, 'async_trait>( &'life0 self, operation_id: OperationId, out_point: OutPoint, ) -> Pin<Box<dyn Future<Output = Result<Amount>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Waits for the funds from an output created by Self::create_final_inputs_and_outputs to become available. This function returning typically implies a change in the output of Self::get_balance.

fn get_balance<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dbtx: &'life1 mut DatabaseTransaction<'life2>, ) -> Pin<Box<dyn Future<Output = Amount> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Returns the balance held by this module and available for funding transactions.

fn subscribe_balance_changes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = BoxStream<'static, ()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Returns a stream that will output the updated module balance each time it changes.

fn leave<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dbtx: &'life1 mut DatabaseTransaction<'life2>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Leave the federation

fn handle_rpc<'life0, 'async_trait>( &'life0 self, method: String, request: Value, ) -> Pin<Box<dyn Future<Output = BoxStream<'_, Result<Value>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn decoder() -> Decoder

fn kind() -> ModuleKind

fn start<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

Initialize client.

impl Debug for MintClientModule

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.