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
• deposit_signature_owner
  Deposit Signature Ownership Mapping
• input
  Transaction Input Types and Utilities
• output
  Transaction Output Types and Utilities
• sign
  Transaction Signing Utilities

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 an (usize) as they are created multiple times 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

• SighashCalculator