Module transaction

builder::transaction

This module provides the core logic for constructing, handling, and signing the various Bitcoin transactions required by the Clementine bridge protocol. It defines the creation, and validation of transaction flows involving operators, verifiers, watchtowers, and the security council, aimed to make it easy to create transactions and sign them properly.

Overview

The transaction builder is responsible for:

• Defining all transaction types and their flows in the protocol (see TransactionType).
• Building and signing transactions for deposit, withdrawal, challenge, reimbursement, and related operations.
• Storing transaction inputs/outputs, scripts, and Taproot spend information.
• Providing utilities to speed up transaction creating during a deposit using caching tx and db data.

Main Components

• [mod.rs] - The main entry point, re-exporting key types and functions. Defines some helper functions for creating taproot outputs.
• [creator.rs] - Contains the functions to create multiple TxHandler’s for a deposit and related structs for caching. In particular, it contains the functions to create TxHandler’s for all transactions generated during a deposit from a single kickoff.
• [operator_collateral.rs] - Handles the creation of operator-specific collateral-related transactions, such as round, ready-to-reimburse, and unspent kickoff transactions.
• [operator_reimburse.rs] - Implements the creation of reimbursement and payout transactions, including logic for operator compensation and optimistic payouts.
• [operator_assert.rs] - Provides functions for creating BitVM assertion and timeout transactions.
• [challenge.rs] - Handles the creation of challenge, disprove, and watchtower challenge transactions, supporting protocol dispute resolution and fraud proofs.
• [sign.rs] - Contains logic for signing transactions using data in the TxHandler.
• [txhandler.rs] - Defines the TxHandler abstraction, which wraps a transaction and its metadata, and provides methods for signing, finalizing, and extracting transaction data.
• [input.rs] - Defines types and utilities for transaction inputs used in the TxHandler.
• [output.rs] - Defines types and utilities for transaction outputs used in the TxHandler.
• [deposit_signature_owner.rs] - Maps which TxIn signatures are signed by which protocol entities, additionally supporting different Sighash types.

Modules

challenge

Challenge Transaction Logic

creator 🔒

Transaction Handler Creation Logic

deposit_signature_owner

Deposit Signature Ownership Mapping

input

Transaction Input Types and Utilities

operator_assert 🔒

This module contains the creation of BitVM operator assertion transactions and timeout transactions related to assertions.

operator_collateral 🔒

Collaterals

operator_reimburse 🔒

Operator Reimburse Transactions

output

Transaction Output Types and Utilities

sign

Transaction Signing Utilities

txhandler 🔒

Transaction Handler Module

Structs

ContractContext

Context for a single operator and round, and optionally a single deposit. Data about deposit and kickoff idx is needed to create the deposit-related transactions. For non deposit related transactions, like the round tx and ready to reimburse tx, the round idx is enough.

KickoffWinternitzKeys

Helper struct to get specific kickoff winternitz keys for a sequential collateral tx

ReimburseDbCache

Struct to retrieve and cache data from DB for creating TxHandlers on demand It can only store information for one deposit and operator pair. It has two context modes, for rounds or for deposits. Deposit context needs additional information, like the deposit outpoint, which is not needed for rounds. Round context can only create transactions that do not depend on the deposit, like the round tx and ready to reimburse tx. Deposit context can create all transactions. Note: This cache is specific to a single operator, for each operator a new cache is needed.

Signed

Marker type for signed transactions.

TxHandler

Handler for protocol transactions, wrapping inputs, outputs, and cached transaction data.

TxHandlerBuilder

Builder for TxHandler, allowing stepwise construction of inputs and outputs.

TxHandlerCache

Stores and manages cached transaction handlers for efficient flow construction.

Unsigned

Marker type for unsigned transactions.

Enums

TransactionType

Types of all transactions that can be created. Some transactions have a (usize) index as there are multiple instances of the same transaction type per kickoff.

TxError

Constants

DEFAULT_SEQUENCE

Traits

State

Functions

anchor_output

Creates a P2A (anchor) output for Child Pays For Parent (CPFP) fee bumping.

combine_emergency_stop_txhandler

Combines multiple emergency stop transactions into a single transaction.

create_burn_unused_kickoff_connectors_txhandler

Creates a TxHandler for burning unused kickoff connectors.

create_disprove_taproot_output

Creates a Taproot output for a disprove path, combining a script, an additional disprove script, and a hidden node containing the BitVM disprove scripts.

create_emergency_stop_txhandler

Creates a TxHandler for the emergency_stop_tx.

create_move_to_vault_txhandler

Creates a TxHandler for the move_to_vault_tx.

create_optimistic_payout_txhandler

Creates a TxHandler for the optimistic_payout_tx.

create_payout_txhandler

Creates a TxHandler for the payout_tx.

create_replacement_deposit_txhandler

Creates a TxHandler for the replacement_deposit_tx.

create_round_nth_txhandler

Creates the nth (1-indexed) round_txhandler and reimburse_generator_txhandler pair for a specific operator.

create_round_txhandlers

Creates the round and ready-to-reimburse txhandlers for a specific operator and round index. These transactions currently include round tx, ready to reimburse tx, and unspent kickoff txs.

create_taproot_output_with_hidden_node

Helper function to create a Taproot output that combines a single script and a root hash containing any number of scripts. The main use case for this function is to speed up the tx creating during a deposit. We don’t need to create and combine all the scripts in the taproot repeatedly, but cache and combine the common scripts for each kickoff tx to a root hash, and add an additional script that depends on the specific operator or nofn_pk that is signing the deposit.

create_txhandlers

Creates all required transaction handlers for a given context and transaction type.

non_ephemeral_anchor_output

A non-ephemeral anchor output. It is used in tx’s that should have a non-ephemeral anchor. Because ephemeral anchors force the tx to have 0 fee.

op_return_txout

Creates an OP_RETURN output with the given data slice.

remove_txhandler_from_map

Removes a TxHandler from a map by transaction type, returning an error if not found.

Type Aliases

HiddenNode 🔒

SighashCalculator