Struct bdk_wallet::wallet::Wallet

source ·
pub struct Wallet { /* private fields */ }
Expand description

A Bitcoin wallet

The Wallet acts as a way of coherently interfacing with output descriptors and related transactions. Its main components are:

  1. output descriptors from which it can derive addresses.
  2. signers that can contribute signatures to addresses instantiated from the descriptors.

Implementations§

Creates a wallet that does not persist data.

Creates a wallet that does not persist data, with a custom genesis hash.

Initialize an empty Wallet.

Initialize an empty Wallet with a custom genesis hash.

This is like Wallet::new with an additional genesis_hash parameter. This is useful for syncing from alternative networks.

Load Wallet from the given persistence backend.

Note that the descriptor secret keys are not persisted to the db; this means that after calling this method the Wallet won’t know the secret keys, and as such, won’t be able to sign transactions.

If you wish to use the wallet to sign transactions, you need to add the secret keys manually to the Wallet:

let secp = Secp256k1::new();

let (external_descriptor, external_keymap) = Descriptor::parse_descriptor(&secp, "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/0/*)").unwrap();
let (internal_descriptor, internal_keymap) = Descriptor::parse_descriptor(&secp, "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/1'/0'/1/*)").unwrap();

let external_signer_container = SignersContainer::build(external_keymap, &external_descriptor, &secp);
let internal_signer_container = SignersContainer::build(internal_keymap, &internal_descriptor, &secp);

let mut wallet = Wallet::load(db)?;

external_signer_container.signers().into_iter()
    .for_each(|s| wallet.add_signer(KeychainKind::External, SignerOrdering::default(), s.clone()));
internal_signer_container.signers().into_iter()
    .for_each(|s| wallet.add_signer(KeychainKind::Internal, SignerOrdering::default(), s.clone()));

Alternatively, you can call Wallet::new_or_load, which will add the private keys of the passed-in descriptors to the Wallet.

Either loads Wallet from persistence, or initializes it if it does not exist.

This method will fail if the loaded Wallet has different parameters to those provided.

Either loads Wallet from persistence, or initializes it if it does not exist, using the provided descriptor, change descriptor, network, and custom genesis hash.

This method will fail if the loaded Wallet has different parameters to those provided. This is like Wallet::new_or_load with an additional genesis_hash parameter. This is useful for syncing from alternative networks.

Get the Bitcoin network the wallet is using.

Iterator over all keychains in this wallet

Peek an address of the given keychain at index without revealing it.

For non-wildcard descriptors this returns the same address at every provided index.

Panics

This panics when the caller requests for an address of derivation index greater than the BIP32 max index.

Attempt to reveal the next address of the given keychain.

This will increment the internal derivation index. If the keychain’s descriptor doesn’t contain a wildcard or every address is already revealed up to the maximum derivation index defined in BIP32, then returns the last revealed address.

Errors

If writing to persistent storage fails.

Reveal addresses up to and including the target index and return an iterator of newly revealed addresses.

If the target index is unreachable, we make a best effort to reveal up to the last possible index. If all addresses up to the given index are already revealed, then no new addresses are returned.

Errors

If writing to persistent storage fails.

Get the next unused address for the given keychain, i.e. the address with the lowest derivation index that hasn’t been used.

This will attempt to derive and reveal a new address if no newly revealed addresses are available. See also reveal_next_address.

Errors

If writing to persistent storage fails.

Marks an address used of the given keychain at index.

Returns whether the given index was present and then removed from the unused set.

Undoes the effect of mark_used and returns whether the index was inserted back into the unused set.

Since this is only a superficial marker, it will have no effect if the address at the given index was actually used, i.e. the wallet has previously indexed a tx output for the derived spk.

List addresses that are revealed but unused.

Note if the returned iterator is empty you can reveal more addresses by using reveal_next_address or reveal_addresses_to.

Return whether or not a script is part of this wallet (either internal or external)

Finds how the wallet derived the script pubkey spk.

Will only return Some(_) if the wallet has given out the spk.

Return the list of unspent outputs of this wallet

List all relevant outputs (includes both spent and unspent, confirmed and unconfirmed).

To list only unspent outputs (UTXOs), use Wallet::list_unspent instead.

Get all the checkpoints the wallet is currently storing indexed by height.

Returns the latest checkpoint.

Get unbounded script pubkey iterators for both Internal and External keychains.

This is intended to be used when doing a full scan of your addresses (e.g. after restoring from seed words). You pass the BTreeMap of iterators to a blockchain data source (e.g. electrum server) which will go through each address until it reaches a stop gap.

Note carefully that iterators go over all script pubkeys on the keychains (not what script pubkeys the wallet is storing internally).

Get an unbounded script pubkey iterator for the given keychain.

See all_unbounded_spk_iters for more documentation

Returns the utxo owned by this wallet corresponding to outpoint if it exists in the wallet’s database.

Inserts a [TxOut] at [OutPoint] into the wallet’s transaction graph.

This is used for providing a previous output’s value so that we can use calculate_fee or calculate_fee_rate on a given transaction. Outputs inserted with this method will not be returned in list_unspent or list_output.

Any inserted TxOuts are not persisted until commit is called.

WARNING: This should only be used to add TxOuts that the wallet does not own. Only insert TxOuts that you trust the values for!

Calculates the fee of a given transaction. Returns 0 if tx is a coinbase transaction.

To calculate the fee for a [Transaction] with inputs not owned by this wallet you must manually insert the TxOut(s) into the tx graph using the insert_txout function.

Note tx does not have to be in the graph for this to work.

Examples
let tx = wallet.get_tx(txid).expect("transaction").tx_node.tx;
let fee = wallet.calculate_fee(&tx).expect("fee");
let tx = &psbt.clone().extract_tx().expect("tx");
let fee = wallet.calculate_fee(tx).expect("fee");

Calculate the [FeeRate] for a given transaction.

To calculate the fee rate for a [Transaction] with inputs not owned by this wallet you must manually insert the TxOut(s) into the tx graph using the insert_txout function.

Note tx does not have to be in the graph for this to work.

Examples
let tx = wallet.get_tx(txid).expect("transaction").tx_node.tx;
let fee_rate = wallet.calculate_fee_rate(&tx).expect("fee rate");
let tx = &psbt.clone().extract_tx().expect("tx");
let fee_rate = wallet.calculate_fee_rate(tx).expect("fee rate");

Compute the tx’s sent and received [Amount]s.

This method returns a tuple (sent, received). Sent is the sum of the txin amounts that spend from previous txouts tracked by this wallet. Received is the summation of this tx’s outputs that send to script pubkeys tracked by this wallet.

Examples
let tx = wallet.get_tx(txid).expect("tx exists").tx_node.tx;
let (sent, received) = wallet.sent_and_received(&tx);
let tx = &psbt.clone().extract_tx().expect("tx");
let (sent, received) = wallet.sent_and_received(tx);

Get a single transaction from the wallet as a CanonicalTx (if the transaction exists).

CanonicalTx contains the full transaction alongside meta-data such as:

  • Blocks that the transaction is Anchored in. These may or may not be blocks that exist in the best chain.
  • The ChainPosition of the transaction in the best chain - whether the transaction is confirmed or unconfirmed. If the transaction is confirmed, the anchor which proves the confirmation is provided. If the transaction is unconfirmed, the unix timestamp of when the transaction was last seen in the mempool is provided.
use bdk_chain::Anchor;
use bdk_wallet::{chain::ChainPosition, Wallet};

let canonical_tx = wallet.get_tx(my_txid).expect("panic if tx does not exist");

// get reference to full transaction
println!("my tx: {:#?}", canonical_tx.tx_node.tx);

// list all transaction anchors
for anchor in canonical_tx.tx_node.anchors {
    println!(
        "tx is anchored by block of hash {}",
        anchor.anchor_block().hash
    );
}

// get confirmation status of transaction
match canonical_tx.chain_position {
    ChainPosition::Confirmed(anchor) => println!(
        "tx is confirmed at height {}, we know this since {}:{} is in the best chain",
        anchor.confirmation_height, anchor.anchor_block.height, anchor.anchor_block.hash,
    ),
    ChainPosition::Unconfirmed(last_seen) => println!(
        "tx is last seen at {}, it is unconfirmed as it is not anchored in the best chain",
        last_seen,
    ),
}

Add a new checkpoint to the wallet’s internal view of the chain. This stages but does not commit the change.

Returns whether anything changed with the insertion (e.g. false if checkpoint was already there).

Add a transaction to the wallet’s internal view of the chain. This stages but does not commit the change.

Returns whether anything changed with the transaction insertion (e.g. false if the transaction was already inserted at the same position).

A tx can be rejected if position has a height greater than the latest_checkpoint. Therefore you should use insert_checkpoint to insert new checkpoints before manually inserting new transactions.

WARNING: If position is confirmed, we anchor the tx to a the lowest checkpoint that is >= the position’s height. The caller is responsible for ensuring the tx exists in our local view of the best chain’s history.

Iterate over the transactions in the wallet.

Return the balance, separated into available, trusted-pending, untrusted-pending and immature values.

Add an external signer

See the signer module for an example.

Get the signers

Example
let wallet = Wallet::new_no_persist("wpkh(tprv8ZgxMBicQKsPe73PBRSmNbTfbcsZnwWhz5eVmhHpi31HW29Z7mc9B4cWGRQzopNUzZUT391DeDJxL2PefNunWyLgqCKRMDkU1s2s8bAfoSk/84'/0'/0'/0/*)", None, Network::Testnet)?;
for secret_key in wallet.get_signers(KeychainKind::External).signers().iter().filter_map(|s| s.descriptor_secret_key()) {
    // secret_key: tprv8ZgxMBicQKsPe73PBRSmNbTfbcsZnwWhz5eVmhHpi31HW29Z7mc9B4cWGRQzopNUzZUT391DeDJxL2PefNunWyLgqCKRMDkU1s2s8bAfoSk/84'/0'/0'/0/*
    println!("secret_key: {}", secret_key);
}

Ok::<(), Box<dyn std::error::Error>>(())

Start building a transaction.

This returns a blank TxBuilder from which you can specify the parameters for the transaction.

Example
let psbt = {
   let mut builder =  wallet.build_tx();
   builder
       .add_recipient(to_address.script_pubkey(), Amount::from_sat(50_000));
   builder.finish()?
};

// sign and broadcast ...

Bump the fee of a transaction previously created with this wallet.

Returns an error if the transaction is already confirmed or doesn’t explicitly signal replace by fee (RBF). If the transaction can be fee bumped then it returns a TxBuilder pre-populated with the inputs and outputs of the original transaction.

Example
let mut psbt = {
    let mut builder = wallet.build_tx();
    builder
        .add_recipient(to_address.script_pubkey(), Amount::from_sat(50_000))
        .enable_rbf();
    builder.finish()?
};
let _ = wallet.sign(&mut psbt, SignOptions::default())?;
let tx = psbt.clone().extract_tx().expect("tx");
// broadcast tx but it's taking too long to confirm so we want to bump the fee
let mut psbt =  {
    let mut builder = wallet.build_fee_bump(tx.txid())?;
    builder
        .fee_rate(FeeRate::from_sat_per_vb(5).expect("valid feerate"));
    builder.finish()?
};

let _ = wallet.sign(&mut psbt, SignOptions::default())?;
let fee_bumped_tx = psbt.extract_tx();
// broadcast fee_bumped_tx to replace original

Sign a transaction with all the wallet’s signers, in the order specified by every signer’s SignerOrdering. This function returns the Result type with an encapsulated bool that has the value true if the PSBT was finalized, or false otherwise.

The SignOptions can be used to tweak the behavior of the software signers, and the way the transaction is finalized at the end. Note that it can’t be guaranteed that every signers will follow the options, but the “software signers” (WIF keys and xprv) defined in this library will.

Example
let mut psbt = {
    let mut builder = wallet.build_tx();
    builder.add_recipient(to_address.script_pubkey(), Amount::from_sat(50_000));
    builder.finish()?
};
let finalized = wallet.sign(&mut psbt, SignOptions::default())?;
assert!(finalized, "we should have signed all the inputs");

Return the spending policies for the wallet’s descriptor

Return the “public” version of the wallet’s descriptor, meaning a new descriptor that has the same structure but with every secret key removed

This can be used to build a watch-only version of a wallet

Finalize a PSBT, i.e., for each input determine if sufficient data is available to pass validation and construct the respective scriptSig or scriptWitness. Please refer to BIP174 for further information.

Returns true if the PSBT could be finalized, and false otherwise.

The SignOptions can be used to tweak the behavior of the finalizer.

Return the secp256k1 context used for all signing operations

Returns the descriptor used to create addresses for a particular keychain.

The derivation index of this wallet. It will return None if it has not derived any addresses. Otherwise, it will return the index of the highest address it has derived.

The index of the next address that you would get if you were to ask the wallet for a new address

Informs the wallet that you no longer intend to broadcast a tx that was built from it.

This frees up the change address used when creating the tx for use in future transactions.

get the corresponding PSBT Input for a LocalUtxo

Return the checksum of the public descriptor associated to keychain

Internally calls Self::get_descriptor_for_keychain to fetch the right descriptor

Applies an update to the wallet and stages the changes (but does not commit them).

Usually you create an update by interacting with some blockchain data source and inserting transactions related to your wallet into it.

Commits all currently staged changed to the persistence backend returning and error when this fails.

This returns whether the update resulted in any changes.

Returns the changes that will be committed with the next call to commit.

Get a reference to the inner TxGraph.

Get a reference to the inner KeychainTxOutIndex.

Get a reference to the inner LocalChain.

Introduces a block of height to the wallet, and tries to connect it to the prev_blockhash of the block’s header.

This is a convenience method that is equivalent to calling apply_block_connected_to with prev_blockhash and height-1 as the connected_to parameter.

Applies relevant transactions from block of height to the wallet, and connects the block to the internal chain.

The connected_to parameter informs the wallet how this block connects to the internal LocalChain. Relevant transactions are filtered from the block and inserted into the internal TxGraph.

Apply relevant unconfirmed transactions to the wallet.

Transactions that are not relevant are filtered out.

This method takes in an iterator of (tx, last_seen) where last_seen is the timestamp of when the transaction was last seen in the mempool. This is used for conflict resolution when there is conflicting unconfirmed transactions. The transaction with the later last_seen is prioritized.

Methods to construct sync/full-scan requests for spk-based chain sources.

Create a partial SyncRequest for this wallet for all revealed spks.

This is the first step when performing a spk-based wallet partial sync, the returned SyncRequest collects all revealed script pubkeys from the wallet keychain needed to start a blockchain sync with a spk based blockchain client.

Create a `FullScanRequest for this wallet.

This is the first step when performing a spk-based wallet full scan, the returned `FullScanRequest collects iterators for the wallet’s keychain script pub keys needed to start a blockchain full scan with a spk based blockchain client.

This operation is generally only used when importing or restoring a previously used wallet in which the list of used scripts is not known.

Trait Implementations§

Converts this type into a shared reference of the (usually inferred) input type.
Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.