Trait bdk_chain::Anchor

source ·

pub trait Anchor: Debug + Clone + Eq + PartialOrd + Ord + Hash {
    fn anchor_block(&self) -> BlockId;

    fn confirmation_height_upper_bound(&self) -> u32 { ... }
}

Expand description

Trait that “anchors” blockchain data to a specific block of height and hash.

If transaction A is anchored in block B, and block B is in the best chain, we can assume that transaction A is also confirmed in the best chain. This does not necessarily mean that transaction A is confirmed in block B. It could also mean transaction A is confirmed in a parent block of B.

Every Anchor implementation must contain a BlockId parameter, and must implement Ord. When implementing Ord, the anchors’ BlockIds should take precedence over other elements inside the Anchors for comparison purposes, i.e., you should first compare the anchors’ BlockIds and then care about the rest.

The example shows different types of anchors:

// Initialize the local chain with two blocks.
let chain = LocalChain::from_blocks(
    [
        (1, Hash::hash("first".as_bytes())),
        (2, Hash::hash("second".as_bytes())),
    ]
    .into_iter()
    .collect(),
);

// Transaction to be inserted into `TxGraph`s with different anchor types.
let tx = tx_from_hex(RAW_TX_1);

// Insert `tx` into a `TxGraph` that uses `BlockId` as the anchor type.
// When a transaction is anchored with `BlockId`, the anchor block and the confirmation block of
// the transaction is the same block.
let mut graph_a = TxGraph::<BlockId>::default();
let _ = graph_a.insert_tx(tx.clone());
graph_a.insert_anchor(
    tx.txid(),
    BlockId {
        height: 1,
        hash: Hash::hash("first".as_bytes()),
    },
);

// Insert `tx` into a `TxGraph` that uses `ConfirmationHeightAnchor` as the anchor type.
// This anchor records the anchor block and the confirmation height of the transaction.
// When a transaction is anchored with `ConfirmationHeightAnchor`, the anchor block and
// confirmation block can be different. However, the confirmation block cannot be higher than
// the anchor block and both blocks must be in the same chain for the anchor to be valid.
let mut graph_b = TxGraph::<ConfirmationHeightAnchor>::default();
let _ = graph_b.insert_tx(tx.clone());
graph_b.insert_anchor(
    tx.txid(),
    ConfirmationHeightAnchor {
        anchor_block: BlockId {
            height: 2,
            hash: Hash::hash("second".as_bytes()),
        },
        confirmation_height: 1,
    },
);

// Insert `tx` into a `TxGraph` that uses `ConfirmationTimeHeightAnchor` as the anchor type.
// This anchor records the anchor block, the confirmation height and time of the transaction.
// When a transaction is anchored with `ConfirmationTimeHeightAnchor`, the anchor block and
// confirmation block can be different. However, the confirmation block cannot be higher than
// the anchor block and both blocks must be in the same chain for the anchor to be valid.
let mut graph_c = TxGraph::<ConfirmationTimeHeightAnchor>::default();
let _ = graph_c.insert_tx(tx.clone());
graph_c.insert_anchor(
    tx.txid(),
    ConfirmationTimeHeightAnchor {
        anchor_block: BlockId {
            height: 2,
            hash: Hash::hash("third".as_bytes()),
        },
        confirmation_height: 1,
        confirmation_time: 123,
    },
);