Trait LowLevelWalletWrite 

pub trait LowLevelWalletWrite: LowLevelWalletRead {
    // Required methods
    fn put_block_meta(
        &mut self,
        block_height: BlockHeight,
        block_hash: BlockHash,
        block_time: u32,
        sapling_commitment_tree_size: u32,
        sapling_output_count: u32,
        orchard_commitment_tree_size: u32,
        orchard_action_count: u32,
        ironwood_commitment_tree_size: u32,
        ironwood_action_count: u32,
    ) -> Result<(), Self::Error>;
    fn put_tx_meta(
        &mut self,
        tx: &WalletTx<Self::AccountId>,
        height: BlockHeight,
    ) -> Result<Self::TxRef, Self::Error>;
    fn put_tx_data(
        &mut self,
        tx: &Transaction,
        fee: Option<Zatoshis>,
        created_at: Option<OffsetDateTime>,
        target_height: Option<TargetHeight>,
        observed_height: BlockHeight,
    ) -> Result<Self::TxRef, Self::Error>;
    fn set_transaction_status(
        &mut self,
        txid: TxId,
        status: TransactionStatus,
    ) -> Result<(), Self::Error>;
    fn put_zip318_classification(
        &mut self,
        tx_ref: Self::TxRef,
        classification: Zip318Classification,
    ) -> Result<(), Self::Error>;
    fn put_received_sapling_note<T: ReceivedSaplingOutput<AccountId = Self::AccountId>>(
        &mut self,
        output: &T,
        tx_ref: Self::TxRef,
        target_or_mined_height: Option<BlockHeight>,
        spent_in: Option<Self::TxRef>,
    ) -> Result<(), Self::Error>;
    fn mark_sapling_note_spent(
        &mut self,
        nf: &Nullifier,
        spent_in_tx: Self::TxRef,
    ) -> Result<bool, Self::Error>;
    fn track_block_sapling_nullifiers(
        &mut self,
        block_height: BlockHeight,
        nfs: &[(TxIndex, TxId, Vec<Nullifier>)],
    ) -> Result<(), Self::Error>;
    fn put_received_orchard_note<T: ReceivedOrchardOutput<AccountId = Self::AccountId>>(
        &mut self,
        output: &T,
        tx_ref: Self::TxRef,
        target_or_mined_height: Option<BlockHeight>,
        spent_in: Option<Self::TxRef>,
    ) -> Result<(), Self::Error>;
    fn put_received_ironwood_note<T: ReceivedOrchardOutput<AccountId = Self::AccountId>>(
        &mut self,
        output: &T,
        tx_ref: Self::TxRef,
        target_or_mined_height: Option<BlockHeight>,
        spent_in: Option<Self::TxRef>,
    ) -> Result<(), Self::Error>;
    fn mark_orchard_note_spent(
        &mut self,
        nf: &Nullifier,
        tx_ref: Self::TxRef,
    ) -> Result<bool, Self::Error>;
    fn mark_ironwood_note_spent(
        &mut self,
        nf: &Nullifier,
        tx_ref: Self::TxRef,
    ) -> Result<bool, Self::Error>;
    fn track_block_orchard_nullifiers(
        &mut self,
        block_height: BlockHeight,
        nfs: &[(TxIndex, TxId, Vec<Nullifier>)],
    ) -> Result<(), Self::Error>;
    fn track_block_ironwood_nullifiers(
        &mut self,
        block_height: BlockHeight,
        nfs: &[(TxIndex, TxId, Vec<Nullifier>)],
    ) -> Result<(), Self::Error>;
    fn track_block_transparent_spends(
        &mut self,
        block_height: BlockHeight,
        spends: &[(TxIndex, TxId, Vec<OutPoint>)],
    ) -> Result<(), Self::Error>;
    fn prune_tracked_spends(
        &mut self,
        pruning_depth: u32,
    ) -> Result<(), Self::Error>;
    fn put_sent_output(
        &mut self,
        from_account_uuid: Self::AccountId,
        tx_ref: Self::TxRef,
        output_index: usize,
        recipient: &Recipient<Self::AccountId>,
        value: Zatoshis,
        memo: Option<&MemoBytes>,
    ) -> Result<(), Self::Error>;
    fn update_tx_fee(
        &mut self,
        tx_ref: Self::TxRef,
        fee: Zatoshis,
    ) -> Result<(), Self::Error>;
    fn put_transparent_output(
        &mut self,
        output: &WalletTransparentOutput<Self::AccountId>,
        observation_height: BlockHeight,
        known_unspent: bool,
    ) -> Result<(Self::AccountId, Option<TransparentKeyScope>), Self::Error>;
    fn mark_transparent_utxo_spent(
        &mut self,
        outpoint: &OutPoint,
        spent_in_tx: Self::TxRef,
    ) -> Result<bool, Self::Error>;
    fn generate_transparent_gap_addresses(
        &mut self,
        account_id: Self::AccountId,
        key_scope: TransparentKeyScope,
        request: UnifiedAddressRequest,
    ) -> Result<(), Self::Error>;
    fn queue_tx_retrieval(
        &mut self,
        txids: impl Iterator<Item = TxId>,
        dependent_tx_ref: Option<Self::TxRef>,
    ) -> Result<(), Self::Error>;
    fn queue_tx_status(&mut self, txid: TxId) -> Result<(), Self::Error>;
    fn queue_transparent_spend_detection(
        &mut self,
        receiving_address: TransparentAddress,
        tx_ref: Self::TxRef,
        output_index: u32,
    ) -> Result<(), Self::Error>;
    fn queue_transparent_input_retrieval(
        &mut self,
        tx_ref: Self::TxRef,
        d_tx: &DecryptedTransaction<'_, Transaction, Self::AccountId>,
    ) -> Result<(), Self::Error>;
    fn delete_retrieval_queue_entries(
        &mut self,
        txid: TxId,
    ) -> Result<(), Self::Error>;
    fn notify_scan_complete(
        &mut self,
        range: Range<BlockHeight>,
        wallet_note_positions: &[(ShieldedPool, Position)],
    ) -> Result<(), Self::Error>;
    fn update_gap_limits(
        &mut self,
        gap_limits: &GapLimits,
        txid: TxId,
        observation_height: BlockHeight,
    ) -> Result<(), Self::Error>;
}

A capability trait that provides low-level wallet write operations. These operations are used to provide standard implementations for certain WalletWrite trait methods.

Required Methods

fn put_block_meta( &mut self, block_height: BlockHeight, block_hash: BlockHash, block_time: u32, sapling_commitment_tree_size: u32, sapling_output_count: u32, orchard_commitment_tree_size: u32, orchard_action_count: u32, ironwood_commitment_tree_size: u32, ironwood_action_count: u32, ) -> Result<(), Self::Error>

Available on crate feature orchard only.

fn put_tx_meta( &mut self, tx: &WalletTx<Self::AccountId>, height: BlockHeight, ) -> Result<Self::TxRef, Self::Error>

Add metadata about a transaction to the wallet data store.

fn put_tx_data( &mut self, tx: &Transaction, fee: Option<Zatoshis>, created_at: Option<OffsetDateTime>, target_height: Option<TargetHeight>, observed_height: BlockHeight, ) -> Result<Self::TxRef, Self::Error>

Adds the given transaction to the wallet.

Parameters

• tx: The transaction to store.
• fee: The fee paid by the transaction, if known. This may be None if the wallet does not have sufficient information to compute the fee (see TxMeta::fee_paid).
• created_at: The time the transaction was created, if known.
• target_height: The target height for the transaction, if it was created by this wallet.
• observed_height: The height at which the transaction was first observed. For mined transactions, this is the mined height; for unmined transactions, this is typically the chain tip height at the time of observation.

fn set_transaction_status( &mut self, txid: TxId, status: TransactionStatus, ) -> Result<(), Self::Error>

Updates transaction metadata to reflect that the given transaction status has been observed.

fn put_zip318_classification( &mut self, tx_ref: Self::TxRef, classification: Zip318Classification, ) -> Result<(), Self::Error>

Records how a transaction classifies against ZIP 318, so that a wallet can label a migration transaction in its history without consulting a migration plan.

A store persists this rather than recomputing it, because the evidence it rests on is only all present at once while the transaction is being decrypted. A store that has not been given a classification for a transaction MUST report it as [Zip318Classification::Unknown] rather than as Nonconforming: the two mean “we never looked” and “we looked and it is not one”, and presenting the first as the second asserts a judgement the wallet has not made.

This is called at most once per transaction. Every input to the classification is fixed by the time a transaction is decrypted, so the value never needs revisiting; in particular it does not depend on the mined height, which would otherwise make it change under the store.

fn put_received_sapling_note<T: ReceivedSaplingOutput<AccountId = Self::AccountId>>( &mut self, output: &T, tx_ref: Self::TxRef, target_or_mined_height: Option<BlockHeight>, spent_in: Option<Self::TxRef>, ) -> Result<(), Self::Error>

Adds information about a received Sapling note to the wallet, or updates any existing record for that output.

fn mark_sapling_note_spent( &mut self, nf: &Nullifier, spent_in_tx: Self::TxRef, ) -> Result<bool, Self::Error>

Updates the backing store to indicate that the Sapling output having the given nullifier is spent in the transaction referenced by spent_in_tx. This may result in multiple distinct transactions being recorded as having spent the note; only one of these transactions will end up having been mined (by consensus). If an attempt is made to associate a nullifier with a mined transaction, and another mined transaction reveals the same nullifier, implementations of this method must return an error.

Returns Ok(true) if a a new record was added to the data store.

fn track_block_sapling_nullifiers( &mut self, block_height: BlockHeight, nfs: &[(TxIndex, TxId, Vec<Nullifier>)], ) -> Result<(), Self::Error>

Causes the given Sapling output nullifiers to be tracked by the wallet.

When scanning the chain out-of-order, it is necessary to store any nullifiers observed after a gap in the scanned blocks until the blocks in that gap have been fully scanned, in order to be able to immediately detect that a received output has already been spent. The data store should track a mapping from each nullifier to the block, the index of the transaction in the block, and the transaction ID, so when a note is received within that “gap” its spentness can be determined by checking in the store. For space efficiency, the backing store may use the combination of block height and index within the block instead of the txid for transaction identification.

Parameters

• block_height: The height of the block containing the nullifiers.
• nfs: A slice of tuples, where each tuple contains:
  • The transaction ID of the transaction revealing the nullifiers.
  • The index of the transaction within the block.
  • The vector of nullifiers revealed by the spends in that transaction.

fn put_received_orchard_note<T: ReceivedOrchardOutput<AccountId = Self::AccountId>>( &mut self, output: &T, tx_ref: Self::TxRef, target_or_mined_height: Option<BlockHeight>, spent_in: Option<Self::TxRef>, ) -> Result<(), Self::Error>

Available on crate feature orchard only.

Adds information about a received Orchard note to the wallet, or updates any existing record for that output.

fn put_received_ironwood_note<T: ReceivedOrchardOutput<AccountId = Self::AccountId>>( &mut self, output: &T, tx_ref: Self::TxRef, target_or_mined_height: Option<BlockHeight>, spent_in: Option<Self::TxRef>, ) -> Result<(), Self::Error>

Available on crate feature orchard only.

Adds information about a received Ironwood note to the wallet, or updates any existing record for that output. Ironwood notes are Orchard-shaped but are stored as a separate pool.

fn mark_orchard_note_spent( &mut self, nf: &Nullifier, tx_ref: Self::TxRef, ) -> Result<bool, Self::Error>

Available on crate feature orchard only.

Updates the backing store to indicate that the Orchard output having the given nullifier is spent in the transaction referenced by spent_in_tx. This may result in multiple distinct transactions being recorded as having spent the note; only one of these transactions will end up having been mined (by consensus). If an attempt is made to associate a nullifier with a mined transaction, and another mined transaction reveals the same nullifier, implementations of this method must return an error.

Returns Ok(true) if a a new record was added to the data store.

fn mark_ironwood_note_spent( &mut self, nf: &Nullifier, tx_ref: Self::TxRef, ) -> Result<bool, Self::Error>

Available on crate feature orchard only.

Updates the backing store to indicate that the Ironwood output having the given nullifier is spent in the transaction referenced by spent_in_tx. Behaves like mark_orchard_note_spent but for the Ironwood pool.

fn track_block_orchard_nullifiers( &mut self, block_height: BlockHeight, nfs: &[(TxIndex, TxId, Vec<Nullifier>)], ) -> Result<(), Self::Error>

Available on crate feature orchard only.

Causes the given Orchard output nullifiers to be tracked by the wallet.

When scanning the chain out-of-order, it is necessary to store any nullifiers observed after a gap in the scanned blocks until the blocks in that gap have been fully scanned, in order to be able to immediately detect that a received output has already been spent. The data store should track a mapping from each nullifier to the block, the index of the transaction in the block, and the transaction ID, so when a note is received within that “gap” its spentness can be determined by checking in the store. For space efficiency, the backing store may use the combination of block height and index within the block instead of the txid for transaction identification.

Parameters

• block_height: The height of the block containing the nullifiers.
• nfs: A slice of tuples, where each tuple contains:
  • The transaction ID of the transaction revealing the nullifiers.
  • The index of the transaction within the block.
  • The vector of nullifiers revealed by the actions in that transaction.

fn track_block_ironwood_nullifiers( &mut self, block_height: BlockHeight, nfs: &[(TxIndex, TxId, Vec<Nullifier>)], ) -> Result<(), Self::Error>

Available on crate feature orchard only.

Causes the given Ironwood output nullifiers to be tracked by the wallet. Behaves like track_block_orchard_nullifiers but for the Ironwood pool.

fn track_block_transparent_spends( &mut self, block_height: BlockHeight, spends: &[(TxIndex, TxId, Vec<OutPoint>)], ) -> Result<(), Self::Error>

Available on crate feature transparent-inputs only.

Causes the given transparent spends to be tracked by the wallet.

This is the transparent counterpart of the track_block_*_nullifiers methods (track_block_sapling_nullifiers and its Orchard and Ironwood equivalents), and exists for the same reason: a transparent output created in a block range the wallet has not yet scanned cannot be recognized as its own at the time its spend is observed, so the spending transaction must be recorded against the outpoint and resolved if the output is later discovered.

The spending transactions here are in general not transactions the wallet stores, so an implementation must be able to record them without a corresponding transaction record; for space efficiency it may use the combination of block height and index within the block instead of the txid, as for the nullifier maps. Entries are removed by prune_tracked_spends.

Parameters

• block_height: The height of the block containing the spending transactions.
• spends: A slice of tuples, where each tuple contains:
  • The index of the transaction within the block.
  • The transaction ID of the transaction effecting the spends.
  • The outpoints spent by that transaction’s transparent inputs that do not spend any output the wallet already knows of.

fn prune_tracked_spends( &mut self, pruning_depth: u32, ) -> Result<(), Self::Error>

Removes tracked spends that are no longer needed for spend detection.

This function prunes the entries recorded by track_block_sapling_nullifiers and its per-pool counterparts, and by track_block_transparent_spends, that were recorded at block heights less than (fully_scanned_height - pruning_depth), where fully_scanned_height is the height of the wallet’s fully scanned chain state. These entries are no longer needed because any wallet output they could have spent would already have been discovered during scanning.

Parameters

• pruning_depth: The number of blocks below the fully scanned height at which to prune tracked spends.

fn put_sent_output( &mut self, from_account_uuid: Self::AccountId, tx_ref: Self::TxRef, output_index: usize, recipient: &Recipient<Self::AccountId>, value: Zatoshis, memo: Option<&MemoBytes>, ) -> Result<(), Self::Error>

Records information about a transaction output that your wallet created, from the constituent properties of that output.

Parameters

• tx_ref: The identifier for the transaction that produced the output.
• output_index: The index of the output in the bundle corresponding to the pool where the output was created.
• recipient: Information about the address or account that the output is being sent to.
• value: The value of the output.
• memo: The memo attached to the output, if any.

fn update_tx_fee( &mut self, tx_ref: Self::TxRef, fee: Zatoshis, ) -> Result<(), Self::Error>

Updates the wallet’s view of a transaction to indicate the miner’s fee paid by the transaction.

fn put_transparent_output( &mut self, output: &WalletTransparentOutput<Self::AccountId>, observation_height: BlockHeight, known_unspent: bool, ) -> Result<(Self::AccountId, Option<TransparentKeyScope>), Self::Error>

Available on crate feature transparent-inputs only.

Adds a transparent output observed by the wallet to the data store, or updates any existing record for that output.

Parameters

• output: The output data.
• observation_height: This should be set to the mined height, if known. If the TXO is known to be mined but the height at which it was mined is unknown, this should be set to the chain tip height at the time of the observation; if the utxo is known to be unmined, this should be set to the mempool height.
• known_unspent: Set to true if the output is known to be a member of the UTXO set as of the given observation height.

fn mark_transparent_utxo_spent( &mut self, outpoint: &OutPoint, spent_in_tx: Self::TxRef, ) -> Result<bool, Self::Error>

Available on crate feature transparent-inputs only.

Updates the backing store to indicate that the UTXO referred to by outpoint is spent in the transaction referenced by spent_in_tx.

fn generate_transparent_gap_addresses( &mut self, account_id: Self::AccountId, key_scope: TransparentKeyScope, request: UnifiedAddressRequest, ) -> Result<(), Self::Error>

Available on crate feature transparent-inputs only.

Updates the wallet backend by generating and caching addresses for the given key scope such that at least the backend’s configured gap limit worth of addresses exist at indices successive from that of the last address that received a mined transaction.

Parameters

• account_id: The ID of the account holding the UFVK from which addresses should be generated.
• key_scope: The transparent key scope for addresses to generate. Implementations may choose to only support the external, internal, and ephemeral key scopes and return an error if an unrecognized scope is used.
• request: A request for the Unified Address that will be generated with a diversifier index equal to the BIP 44 address_index of each generated address.

fn queue_tx_retrieval( &mut self, txids: impl Iterator<Item = TxId>, dependent_tx_ref: Option<Self::TxRef>, ) -> Result<(), Self::Error>

Adds a TransactionDataRequest::Enhancement request for the enhancement of the given transaction to the transaction data request queue. The dependent_tx_ref parameter specifies the transaction that caused this request to be generated, likely as part of the process of traversing the transparent transaction graph by inspecting the inputs of a transaction with outputs that were received by the wallet.

fn queue_tx_status(&mut self, txid: TxId) -> Result<(), Self::Error>

Adds a TransactionDataRequest::GetStatus request for a transaction whose mined status cannot be learned through ordinary compact-block scanning.

The request intent must remain durable while the transaction is mined, so that it becomes active again if a chain rewind un-mines the transaction.

fn queue_transparent_spend_detection( &mut self, receiving_address: TransparentAddress, tx_ref: Self::TxRef, output_index: u32, ) -> Result<(), Self::Error>

Available on crate feature transparent-inputs only.

Adds a TransactionDataRequest::TransactionsInvolvingAddress request to the transaction data request queue. When the transparent output of tx_ref at output index output_index (which must have been received at receiving_address) is detected as having been spent, this request will be considered fulfilled.

NOTE: The somewhat awkward API of this method is a historical artifact; if the light wallet protocol is in the future updated to expose a mechanism to find the transaction that spends a particular OutPoint, the TransactionsInvolvingAddress variant and this method will likely be removed.

fn queue_transparent_input_retrieval( &mut self, tx_ref: Self::TxRef, d_tx: &DecryptedTransaction<'_, Transaction, Self::AccountId>, ) -> Result<(), Self::Error>

Available on crate feature transparent-inputs only.

Adds TransactionDataRequest::Enhancement requests for transactions that generated the transparent inputs to the provided DecryptedTransaction to the transaction data request queue.

fn delete_retrieval_queue_entries( &mut self, txid: TxId, ) -> Result<(), Self::Error>

Deletes the TransactionDataRequest::Enhancement request for the given transaction ID from the transaction data request queue, without removing any durable status-observation intent for the transaction.

fn notify_scan_complete( &mut self, range: Range<BlockHeight>, wallet_note_positions: &[(ShieldedPool, Position)], ) -> Result<(), Self::Error>

Updates the state of the wallet backend to indicate that the given range of blocks has been fully scanned, identifying the position in the note commitment tree of any notes belonging to the wallet that were discovered in the process of scanning.

fn update_gap_limits( &mut self, gap_limits: &GapLimits, txid: TxId, observation_height: BlockHeight, ) -> Result<(), Self::Error>

Available on crate feature transparent-inputs only.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors