Struct ChangeSet 

pub struct ChangeSet {
    pub descriptor: Option<Descriptor<DescriptorPublicKey>>,
    pub change_descriptor: Option<Descriptor<DescriptorPublicKey>>,
    pub network: Option<Network>,
    pub local_chain: ChangeSet,
    pub tx_graph: ChangeSet<ConfirmationBlockTime>,
    pub indexer: ChangeSet,
    pub locked_outpoints: ChangeSet,
}

A change set for Wallet.

Definition

The change set is responsible for transmitting data between the persistent storage layer and the core library components. Specifically, it serves two primary functions:

1. Recording incremental changes to the in-memory representation that need to be persisted to disk
2. Applying aggregate changes from the persistence layer to the in-memory representation at startup

Contract

The change set maintains and enforces the following properties:

• Change sets must implement Serialize and Deserialize to meet the definition from above.
• Change sets must implement Default as a way of instantiating new empty objects.
• Change sets must implement Merge so that many instances can be aggregated into a single instance.
• A change set is composed of a number of individual “sub-change sets” that adhere to the same rules as above. This is for increased modularity and portability. For example the core modules each have their own change set (tx_graph, local_chain, etc).

Members and required fields

The change set has certain required fields without which a Wallet cannot function. These include the descriptor and the bitcoin::Network in use. These are required to be non-empty in the aggregate, meaning the field must be present and non-null in the union of all persisted changes, but may be empty in any one change set, where “empty” is defined by the Merge implementation of that change set. This requirement also applies to the local_chain field in that the aggregate change set must include a genesis block.

For example, the descriptor and bitcoin::Network are present in the first change set after wallet creation, but are usually omitted in subsequent updates, as they are not permitted to change at any point thereafter.

Other fields of the change set are not required to be non-empty, that is they may be empty even in the aggregate. However, in practice they should contain the data needed to recover a wallet state between sessions. These include:

• tx_graph
• indexer

The change_descriptor is special in that its presence is optional, however the value of the change descriptor should be defined at wallet creation time and respected for the life of the wallet, meaning that if a change descriptor is originally defined, it must also be present in the aggregate change set.

Staging

For greater efficiency the Wallet is able to stage the to-be-persisted changes. Many operations result in staged changes which require persistence on the part of the user. These include address revelation, applying an Update, and introducing transactions and chain data to the wallet. To get the staged changes see Wallet::staged and similar methods. Once the changes are committed to the persistence layer the contents of the stage should be discarded.

Users should persist early and often generally speaking, however in principle there is no limit to the number or type of changes that can be staged prior to persisting or the order in which they’re staged. This is because change sets are designed to be merged. The change that is ultimately persisted will encompass the combined effect of each change individually.

Extensibility

Existing fields may be extended in the future with additional sub-fields. New top-level fields are likely to be added as new features and core components are implemented. Existing fields may be removed in future versions of the library following the deprecation policy below.

Version Compatibility

Any change to the ChangeSet data structure MUST correlate with a major version bump per Semantic Versioning. We guarantee that version N can read and deserialize ChangeSet data written by version N-1 (one major version back), but this guarantee does NOT extend to version N-2 or earlier. New fields added in version N must implement Default so that when reading N-1 data, absent fields are populated with default values.

Limited forward compatibility is provided for downgrades: version N-1 will successfully deserialize version N data without errors by ignoring unknown fields. Users should be aware that features introduced in version N will not be available when downgrading to N-1, and that downgrading can result in loss of data if not backed up. For this reason we recommend carefully planning major upgrades and backing up necessary data to avoid compatibility issues.

Fields can be removed using a 3-version deprecation cycle: fields are marked deprecated in version N with a reason and instructions for migrating, the field is retained in version N+1 for compatibility where it deserializes but may not be used, and finally removed in version N+2. This ensures the standard backwards compatibility guarantees while allowing the removal of deprecated fields.

Responsibilities

Library authors SHOULD test all upgrade paths using the persistence test suite and in CI. Library authors MUST document API changes prominently in the release notes and CHANGELOG, clearly mark deprecated fields including migration instructions, and follow the 3-version deprecation cycle before removing fields.

Users SHOULD back up wallet data before major version upgrades, test upgrades in non-production environments first, and monitor the release notes for warnings and updates. Users MUST complete migrations within the compatibility window, and not skip major versions (i.e. upgrade major versions sequentially).

Custom Persistence Implementations

The resulting interface is designed to give the user more control of what to persist and when to persist it. Custom implementations should consider and account for the possibility of partial or repeat writes, the atomicity of persistence operations, and the order of reads and writes among the fields of the change set. BDK comes with support for SQLite that handles the details for you and is recommended for many users. If implementing your own persistence, please refer to the documentation for WalletPersister and PersistedWallet for more information.

Fields

descriptor: Option<Descriptor<DescriptorPublicKey>>

Descriptor for recipient addresses.

change_descriptor: Option<Descriptor<DescriptorPublicKey>>

Descriptor for change addresses.

network: Option<Network>

Stores the network type of the transaction data.

local_chain: ChangeSet

Changes to the LocalChain.

tx_graph: ChangeSet<ConfirmationBlockTime>

Changes to TxGraph.

indexer: ChangeSet

Changes to KeychainTxOutIndex.

locked_outpoints: ChangeSet

Changes to locked outpoints.

Implementations

impl ChangeSet

pub const WALLET_SCHEMA_NAME: &'static str = "bdk_wallet"

Available on crate feature rusqlite only.

Schema name for wallet.

pub const WALLET_TABLE_NAME: &'static str = "bdk_wallet"

Available on crate feature rusqlite only.

Name of table to store wallet descriptors and network.

pub const WALLET_OUTPOINT_LOCK_TABLE_NAME: &'static str = "bdk_wallet_locked_outpoints"

Available on crate feature rusqlite only.

Name of table to store wallet locked outpoints.

pub fn schema_v0() -> String

Available on crate feature rusqlite only.

Get v0 sqlite ChangeSet schema

pub fn schema_v1() -> String

Available on crate feature rusqlite only.

Get v1 sqlite ChangeSet schema. Schema v1 adds a table for locked outpoints.

pub fn init_sqlite_tables(db_tx: &Transaction<'_>) -> Result<()>

Available on crate feature rusqlite only.

Initialize sqlite tables for wallet tables.

pub fn from_sqlite(db_tx: &Transaction<'_>) -> Result<Self>

Available on crate feature rusqlite only.

Recover a ChangeSet from sqlite database.

pub fn persist_to_sqlite(&self, db_tx: &Transaction<'_>) -> Result<()>

Available on crate feature rusqlite only.

Persist ChangeSet to sqlite database.

Trait Implementations

impl Clone for ChangeSet

fn clone(&self) -> ChangeSet

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChangeSet

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

Formats the value using the given formatter.

impl Default for ChangeSet

fn default() -> ChangeSet

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ChangeSet

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<ChangeSet<ConfirmationBlockTime>> for ChangeSet

fn from(tx_graph: ChangeSet<ConfirmationBlockTime>) -> Self

Converts to this type from the input type.

impl From<ChangeSet<ConfirmationBlockTime, ChangeSet>> for ChangeSet

fn from(indexed_tx_graph: ChangeSet<ConfirmationBlockTime, ChangeSet>) -> Self

Converts to this type from the input type.

impl From<ChangeSet> for ChangeSet

fn from(chain: ChangeSet) -> Self

Converts to this type from the input type.

impl From<ChangeSet> for ChangeSet

fn from(indexer: ChangeSet) -> Self

Converts to this type from the input type.

impl From<ChangeSet> for ChangeSet

fn from(locked_outpoints: ChangeSet) -> Self

Converts to this type from the input type.

impl Merge for ChangeSet

fn merge(&mut self, other: Self)

Merge another ChangeSet into itself.

fn is_empty(&self) -> bool

Returns whether the structure is considered empty.

fn take(&mut self) -> Option<Self>

Take the value, replacing it with the default value.

impl PartialEq for ChangeSet

fn eq(&self, other: &ChangeSet) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ChangeSet

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ChangeSet