Trait bdk_chain::Anchor

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

    // Provided method
    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.compute_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.compute_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.compute_txid(),
    ConfirmationTimeHeightAnchor {
        anchor_block: BlockId {
            height: 2,
            hash: Hash::hash("third".as_bytes()),
        },
        confirmation_height: 1,
        confirmation_time: 123,
    },
);

Required Methods§

source

fn anchor_block(&self) -> BlockId

Returns the BlockId that the associated blockchain data is “anchored” in.

Provided Methods§

source

fn confirmation_height_upper_bound(&self) -> u32

Get the upper bound of the chain data’s confirmation height.

The default definition gives a pessimistic answer. This can be overridden by the Anchor implementation for a more accurate value.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source§

impl<'a, A: Anchor> Anchor for &'a A

Implementors§