Struct Verifier

pub struct Verifier<C: CitreaClientT> {
    rpc: ExtendedBitcoinRpc,
    pub(crate) signer: Actor,
    pub(crate) db: Database,
    pub(crate) config: BridgeConfig,
    pub(crate) nonces: Arc<Mutex<AllSessions>>,
    pub tx_sender: TxSenderClient,
    pub header_chain_prover: HeaderChainProver,
    pub citrea_client: C,
}

Fields

rpc: ExtendedBitcoinRpc

signer: Actor

db: Database

config: BridgeConfig

nonces: Arc<Mutex<AllSessions>>

tx_sender: TxSenderClient

header_chain_prover: HeaderChainProver

citrea_client: C

Implementations

impl<C> Verifier<C>

where C: CitreaClientT,

pub async fn create_watchtower_challenge( &self, transaction_data: TransactionRequestData, commit_data: &[u8], dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<(TransactionType, Transaction, RbfSigningInfo), BridgeError>

Creates and signs the watchtower challenge with the given commit data.

Arguments

• transaction_data - Data to identify the deposit and kickoff.
• commit_data - Commit data for the watchtower challenge.

Returns

A tuple of: 1. TransactionType: WatchtowerChallenge 2. Transaction: Signed watchtower challenge transaction 3. RbfSigningInfo: Rbf signing info for the watchtower challenge (for re-signing the transaction after a rbf input is added to the tx)

pub async fn create_and_sign_unspent_kickoff_connector_txs( &self, round_idx: RoundIndex, operator_xonly_pk: XOnlyPublicKey, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<Vec<(TransactionType, Transaction)>, BridgeError>

Creates and signs all the unspent kickoff connector (using the previously saved signatures from operator during setup) transactions for a single round of an operator.

Arguments

• round_idx - Index of the round.
• operator_xonly_pk - Operator’s x-only public key.

Returns

A vector of tuples: 1. TransactionType: UnspentKickoff(idx) for idx’th kickoff in the round 2. Transaction: Signed unspent kickoff connector transaction

impl<C> Verifier<C>

where C: CitreaClientT,

pub async fn new(config: BridgeConfig) -> Result<Self, BridgeError>

fn verify_unspent_kickoff_sigs( &self, collateral_funding_outpoint: OutPoint, operator_xonly_pk: XOnlyPublicKey, wallet_reimburse_address: Address, unspent_kickoff_sigs: Vec<Signature>, kickoff_wpks: &KickoffWinternitzKeys, ) -> Result<Vec<TaggedSignature>, BridgeError>

Verifies all unspent kickoff signatures sent by the operator, converts them to TaggedSignature as they will be saved as TaggedSignatures to the db.

async fn is_deposit_valid( &self, deposit_data: &mut DepositData, ) -> Result<(), BridgeError>

Checks if all operators in verifier’s db that are still in protocol are in the deposit. Checks if all operators in the deposit data from aggregator are in the verifier’s DB. Afterwards, it checks if the given deposit outpoint is valid. First it checks if the tx exists on chain, then it checks if the amount in TxOut is equal to bridge_amount and if the script is correct.

Arguments

• deposit_data - The deposit data to check.

Returns

• () if the deposit is valid, BridgeError::InvalidDeposit if the deposit is invalid.

pub async fn set_operator( &self, collateral_funding_outpoint: OutPoint, operator_xonly_pk: XOnlyPublicKey, wallet_reimburse_address: Address, operator_winternitz_public_keys: Vec<PublicKey>, unspent_kickoff_sigs: Vec<Signature>, ) -> Result<(), BridgeError>

pub async fn nonce_gen( &self, num_nonces: u32, ) -> Result<(u128, Vec<PublicNonce>), BridgeError>

pub async fn deposit_sign( &self, deposit_data: DepositData, session_id: u128, agg_nonce_rx: Receiver<AggregatedNonce>, ) -> Result<Receiver<PartialSignature>, BridgeError>

pub async fn deposit_finalize( &self, deposit_data: &mut DepositData, session_id: u128, sig_receiver: Receiver<Signature>, agg_nonce_receiver: Receiver<AggregatedNonce>, operator_sig_receiver: Receiver<Signature>, ) -> Result<(PartialSignature, PartialSignature), BridgeError>

pub async fn sign_optimistic_payout( &self, nonce_session_id: u128, agg_nonce: AggregatedNonce, deposit_id: u32, input_signature: Signature, input_outpoint: OutPoint, output_script_pubkey: ScriptBuf, output_amount: Amount, verification_signature: Option<PrimitiveSignature>, ) -> Result<PartialSignature, BridgeError>

pub async fn set_operator_keys( &self, deposit_data: DepositData, keys: OperatorKeys, operator_xonly_pk: XOnlyPublicKey, ) -> Result<(), BridgeError>

async fn is_kickoff_malicious( &self, kickoff_witness: Witness, deposit_data: &mut DepositData, kickoff_data: KickoffData, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<bool, BridgeError>

Checks if the operator who sent the kickoff matches the payout data saved in our db Payout data in db is updated during citrea sync.

pub async fn handle_kickoff<'a>( &'a self, dbtx: DatabaseTransaction<'a, '_>, kickoff_witness: Witness, deposit_data: DepositData, kickoff_data: KickoffData, challenged_before: bool, ) -> Result<bool, BridgeError>

Checks if the kickoff is malicious and sends the appropriate txs if it is. Returns true if the kickoff is malicious.

async fn send_watchtower_challenge( &self, kickoff_data: KickoffData, deposit_data: DepositData, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<(), BridgeError>

async fn queue_watchtower_challenge( &self, kickoff_data: KickoffData, deposit_data: DepositData, commit_data: Vec<u8>, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<(), BridgeError>

async fn update_citrea_deposit_and_withdrawals( &self, dbtx: &mut DatabaseTransaction<'_, '_>, l2_height_start: u64, l2_height_end: u64, block_height: u32, ) -> Result<(), BridgeError>

async fn update_finalized_payouts( &self, dbtx: &mut DatabaseTransaction<'_, '_>, block_id: u32, block_cache: &BlockCache, ) -> Result<(), BridgeError>

async fn send_unspent_kickoff_connectors( &self, round_idx: RoundIndex, operator_xonly_pk: XOnlyPublicKey, used_kickoffs: HashSet<usize>, ) -> Result<(), BridgeError>

async fn verify_additional_disprove_conditions( &self, deposit_data: &mut DepositData, kickoff_data: &KickoffData, latest_blockhash: &Witness, payout_blockhash: &Witness, operator_asserts: &HashMap<usize, Witness>, operator_acks: &HashMap<usize, Witness>, txhandlers: &BTreeMap<TransactionType, TxHandler>, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<Option<Witness>, BridgeError>

Verifies the conditions required to disprove an operator’s actions using the “additional” disprove path.

This function handles specific, non-Groth16 challenges. It reconstructs a unique challenge script based on on-chain data and constants (deposit_constant). It then validates the operator’s provided assertions (operator_asserts) and acknowledgements (operator_acks) against this script. The goal is to produce a spendable witness for the disprove transaction if the operator is found to be at fault.

Arguments

• deposit_data - Mutable data for the specific deposit being challenged.
• kickoff_data - Information about the kickoff transaction that initiated this challenge.
• latest_blockhash - The witness containing Winternitz signature for the latest Bitcoin blockhash.
• payout_blockhash - The witness containing Winternitz signature for the payout transaction’s blockhash.
• operator_asserts - A map of witnesses from the operator, containing their assertions (claims).
• operator_acks - A map of witnesses from the operator, containing their acknowledgements of watchtower challenges.
• txhandlers - A map of transaction builders, used here to retrieve TXIDs of dependent transactions.

Returns

• Ok(Some(bitcoin::Witness)) if the operator’s claims are successfully proven false, returning the complete witness needed to spend the disprove script path.
• Ok(None) if the operator’s claims are valid under this specific challenge, and no disprove is possible.
• Err(BridgeError) if any error occurs during script reconstruction or validation.

async fn send_disprove_tx_additional( &self, txhandlers: &BTreeMap<TransactionType, TxHandler>, kickoff_data: KickoffData, deposit_data: DepositData, additional_disprove_witness: Witness, ) -> Result<(), BridgeError>

Constructs, signs, and broadcasts the “additional” disprove transaction.

This function is called after verify_additional_disprove_conditions successfully returns a witness. It takes this witness, places it into the disprove transaction’s script spend path, adds the required operator and verifier signatures, and broadcasts the finalized transaction to the Bitcoin network.

Arguments

• txhandlers - A map containing the pre-built Disprove transaction handler.
• kickoff_data - Contextual data from the kickoff transaction.
• deposit_data - Contextual data for the deposit being challenged.
• additional_disprove_witness - The witness generated by verify_additional_disprove_conditions, proving the operator’s fault.

Returns

• Ok(()) on successful broadcast of the transaction.
• Err(BridgeError) if signing or broadcasting fails.

async fn verify_disprove_conditions( &self, deposit_data: &mut DepositData, operator_asserts: &HashMap<usize, Witness>, ) -> Result<Option<(usize, StructuredScript)>, BridgeError>

Performs the primary G16 proof verification to disprove an operator’s claim.

This is a complex function that aggregates all of the operator’s assertions, which are commitments from a Winternitz one-time signature scheme. It meticulously parses and reorganizes these commitments into the precise input format required by the underlying Groth16 SNARK verifier (validate_assertions). It then invokes the verifier to check for a faulty computation.

Arguments

• deposit_data - Mutable data for the specific deposit being challenged.
• operator_asserts - A map containing all 33 required operator assertion witnesses.

Returns

• Ok(Some((index, script))) if the ZK proof is faulty. The tuple contains the StructuredScript that can be executed on-chain and its index in the Taproot tree.
• Ok(None) if the ZK proof is valid.
• Err(BridgeError) if any error occurs during data processing or ZK proof verification.

async fn send_disprove_tx( &self, txhandlers: &BTreeMap<TransactionType, TxHandler>, kickoff_data: KickoffData, deposit_data: DepositData, disprove_script: (usize, StructuredScript), ) -> Result<(), BridgeError>

Constructs, signs, and broadcasts the primary disprove transaction based on the operator assertions.

This function takes the StructuredScript and its index returned by verify_disprove_conditions. It compiles the script, extracts the witness data (the push-only elements), and places it into the correct script path (index) of the disprove transaction. It then adds the necessary operator and verifier signatures before broadcasting the transaction to the Bitcoin network.

Arguments

• txhandlers - A map containing the pre-built Disprove transaction handler.
• kickoff_data - Contextual data from the kickoff transaction.
• deposit_data - Contextual data for the deposit being challenged.
• disprove_script - A tuple containing the executable StructuredScript and its Taproot leaf index, as returned by verify_disprove_conditions.

Returns

• Ok(()) on successful broadcast of the transaction.
• Err(BridgeError) if signing or broadcasting fails.

async fn handle_finalized_block( &self, dbtx: DatabaseTransaction<'_, '_>, block_id: u32, block_height: u32, block_cache: Arc<BlockCache>, light_client_proof_wait_interval_secs: Option<u32>, ) -> Result<(), BridgeError>

Trait Implementations

impl<C: Clone + CitreaClientT> Clone for Verifier<C>

fn clone(&self) -> Verifier<C>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C: Debug + CitreaClientT> Debug for Verifier<C>

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

Formats the value using the given formatter.

impl<C> NamedEntity for Verifier<C>

where C: CitreaClientT,

const ENTITY_NAME: &'static str = "verifier"

A string identifier for this owner type used to distinguish between state machines with different owners in the database.

const TX_SENDER_CONSUMER_ID: &'static str = "verifier_tx_sender"

Consumer ID for the tx sender task.

const FINALIZED_BLOCK_CONSUMER_ID_AUTOMATION: &'static str = "verifier_finalized_block_fetcher_automation"

Consumer ID for the finalized block task with automation.

const FINALIZED_BLOCK_CONSUMER_ID_NO_AUTOMATION: &'static str = "verifier_finalized_block_fetcher_no_automation"

Consumer ID for the finalized block task with no automation.

impl<C> Owner for Verifier<C>

where C: CitreaClientT,

fn handle_duty<'life0, 'async_trait>( &'life0 self, duty: Duty, ) -> Pin<Box<dyn Future<Output = Result<DutyResult, BridgeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handle a protocol-related duty

fn create_txhandlers<'life0, 'async_trait>( &'life0 self, tx_type: TransactionType, contract_context: ContractContext, ) -> Pin<Box<dyn Future<Output = Result<BTreeMap<TransactionType, TxHandler>, BridgeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Create the transactions for an instance of the L1 contract

fn handle_finalized_block<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dbtx: DatabaseTransaction<'life1, 'life2>, block_id: u32, block_height: u32, block_cache: Arc<BlockCache>, light_client_proof_wait_interval_secs: Option<u32>, ) -> Pin<Box<dyn Future<Output = Result<(), BridgeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Handle a new finalized block

impl<C> TryFrom<&Verifier<C>> for VerifierParams

where C: CitreaClientT,

type Error = Status

The type returned in the event of a conversion error.

fn try_from(verifier: &Verifier<C>) -> Result<Self, Self::Error>

Performs the conversion.