Struct Operator

pub struct Operator<C: CitreaClientT> {
    pub rpc: ExtendedBitcoinRpc,
    pub db: Database,
    pub signer: Actor,
    pub config: BridgeConfig,
    pub collateral_funding_outpoint: OutPoint,
    pub(crate) reimburse_addr: Address,
    pub tx_sender: TxSenderClient,
    pub header_chain_prover: HeaderChainProver,
    pub citrea_client: C,
}

Fields

rpc: ExtendedBitcoinRpc

db: Database

signer: Actor

config: BridgeConfig

collateral_funding_outpoint: OutPoint

reimburse_addr: Address

tx_sender: TxSenderClient

header_chain_prover: HeaderChainProver

citrea_client: C

Implementations

impl<C> Operator<C>

where C: CitreaClientT,

pub async fn create_assert_commitment_txs( &self, assert_data: TransactionRequestData, commit_data: Vec<Vec<Vec<u8>>>, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<Vec<(TransactionType, Transaction)>, BridgeError>

Creates and signs all the assert commitment transactions for a single kickoff of an operator.

Arguments

• assert_data - Data to identify the deposit and kickoff.
• commit_data - BitVM assertions for the kickoff, for each assert tx.

Returns

A vector of tuples: 1. TransactionType: MiniAssert(idx) for idx’th assert commitment 2. Transaction: Signed assert commitment transaction

pub async fn create_latest_blockhash_tx( &self, assert_data: TransactionRequestData, block_hash: BlockHash, dbtx: Option<DatabaseTransaction<'_, '_>>, ) -> Result<(TransactionType, Transaction), BridgeError>

Creates and signs the latest blockhash transaction for a single kickoff of an operator.

Arguments

• assert_data - Data to identify the deposit and kickoff.
• block_hash - Block hash to commit using winternitz signatures.

Returns

A tuple of: 1. TransactionType: LatestBlockhash 2. Transaction: Signed latest blockhash transaction

impl<C> Operator<C>

where C: CitreaClientT,

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

Creates a new Operator.

pub async fn send_initial_round_tx( &self, round_tx: &Transaction, ) -> Result<(), BridgeError>

pub async fn get_params( &self, ) -> Result<(Receiver<PublicKey>, Receiver<Signature>), BridgeError>

Returns an operator’s winternitz public keys and challenge ackpreimages & hashes.

Returns

• [mpsc::Receiver]: A [tokio] data channel with a type of [winternitz::PublicKey] and size of operator’s winternitz public keys count
• [mpsc::Receiver]: A [tokio] data channel with a type of PublicHash and size of operator’s challenge ack preimages & hashes count

pub async fn deposit_sign( &self, deposit_data: DepositData, ) -> Result<Receiver<Signature>, BridgeError>

pub async fn track_rounds(&self) -> Result<(), BridgeError>

Creates the round state machine by adding a system event to the database

fn is_profitable( input_amount: Amount, withdrawal_amount: Amount, bridge_amount_sats: Amount, operator_withdrawal_fee_sats: Amount, ) -> bool

Checks if the withdrawal amount is within the acceptable range.

pub async fn withdraw( &self, withdrawal_index: u32, in_signature: Signature, in_outpoint: OutPoint, out_script_pubkey: ScriptBuf, out_amount: Amount, ) -> Result<Transaction, BridgeError>

Prepares a withdrawal by:

1. Checking if the withdrawal has been made on Citrea
2. Verifying the given signature
3. Checking if the withdrawal is profitable or not
4. Funding the withdrawal transaction using TxSender RBF option

Parameters

• withdrawal_idx: Citrea withdrawal UTXO index
• in_signature: User’s signature that is going to be used for signing withdrawal transaction input
• in_outpoint: User’s input for the payout transaction
• out_script_pubkey: User’s script pubkey which will be used in the payout transaction’s output
• out_amount: Payout transaction output’s value

Returns

• Ok(()) if the withdrawal checks are successful and a payout transaction is added to the TxSender
• Err(BridgeError) if the withdrawal checks fail

pub fn generate_assert_winternitz_pubkeys( &self, deposit_outpoint: OutPoint, ) -> Result<Vec<PublicKey>, BridgeError>

Generates Winternitz public keys for every BitVM assert tx for a deposit.

Returns

• Vec<Vec<winternitz::PublicKey>>: Winternitz public keys for watchtower index row and BitVM assert tx index column.

pub fn generate_kickoff_winternitz_pubkeys( &self, ) -> Result<Vec<PublicKey>, BridgeError>

Generates Winternitz public keys for every blockhash commit to be used in kickoff utxos. Unique for each kickoff utxo of operator.

Returns

• Vec<Vec<winternitz::PublicKey>>: Winternitz public keys for round_index row and kickoff_idx column.

pub fn generate_unspent_kickoff_sigs( &self, kickoff_wpks: &KickoffWinternitzKeys, ) -> Result<Vec<Signature>, BridgeError>

pub fn generate_challenge_ack_preimages_and_hashes( &self, deposit_data: &DepositData, ) -> Result<Vec<PublicHash>, BridgeError>

pub async fn handle_finalized_payout<'a>( &'a self, dbtx: DatabaseTransaction<'a, '_>, deposit_outpoint: OutPoint, payout_tx_blockhash: BlockHash, ) -> Result<Txid, BridgeError>

async fn start_first_round( &self, dbtx: DatabaseTransaction<'_, '_>, kickoff_wpks: KickoffWinternitzKeys, ) -> Result<(), BridgeError>

pub async fn end_round<'a>( &'a self, dbtx: DatabaseTransaction<'a, '_>, ) -> Result<(), BridgeError>

async fn send_asserts( &self, kickoff_data: KickoffData, deposit_data: DepositData, watchtower_challenges: HashMap<usize, Transaction>, _payout_blockhash: Witness, latest_blockhash: Witness, ) -> Result<(), BridgeError>

fn data(&self) -> OperatorData

async fn send_latest_blockhash( &self, kickoff_data: KickoffData, deposit_data: DepositData, latest_blockhash: BlockHash, ) -> Result<(), BridgeError>

async fn validate_payer_is_operator( &self, dbtx: Option<DatabaseTransaction<'_, '_>>, deposit_id: u32, ) -> Result<(BlockHash, Txid), BridgeError>

For a deposit_id checks that the payer for that deposit is the operator, and the payout blockhash and kickoff txid are set.

async fn get_next_txs_to_send( &self, dbtx: Option<DatabaseTransaction<'_, '_>>, deposit_data: &mut DepositData, payout_blockhash: BlockHash, kickoff_txid: Txid, current_round_idx: RoundIndex, ) -> Result<Vec<(TransactionType, Transaction)>, BridgeError>

pub async fn get_reimbursement_txs( &self, deposit_outpoint: OutPoint, ) -> Result<Vec<(TransactionType, Transaction)>, BridgeError>

For a given deposit outpoint, get the txs that are needed to reimburse the deposit. To avoid operator getting slashed, this function only returns the next tx that needs to be sent This fn can track and enable sending of these transactions during a normal reimbursement process.

• First, if the current round is less than the round of the kickoff assigned to the deposit by PayoutCheckerTask, it returns the Round TX.
• After Round tx is sent, it returns the Kickoff tx.
• After Kickoff tx is sent, it returns the challenge timeout tx.
• After challenge timeout tx is sent, it returns BurnUnusedKickoffConnectors tx. If challenge timeout tx is not sent, and but challenge utxo was spent, it means the kickoff was challenged, thus the fn returns an error as it cannot handle the challenge process. Automation is required to answer the challenge.
• After all kickoff utxos are spent, and for any live kickoff, all kickoff finalizers are spent, it returns the ReadyToReimburse tx.
• After ReadyToReimburse tx is sent, it returns the next Round tx to generate reimbursement utxos.
• Finally, after the next round tx is sent, it returns the Reimburse tx.

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

Checks the current round status, and returns the next txs that are safe to send to be able to advance to the next round.

async fn find_and_mark_unspent_kickoff_utxos( &self, dbtx: Option<DatabaseTransaction<'_, '_>>, round_idx: RoundIndex, round_txid: Txid, current_chain_height: u32, ) -> Result<(Vec<usize>, bool), BridgeError>

Finds unspent kickoff UTXOs and marks spent ones as used in the database. Returns the unspent kickoff utxos (doesn’t matter if finalized or unfinalized) and a boolean to mark if all utxos are spent and finalized

async fn create_burn_unused_kickoff_connectors_tx( &self, round_idx: RoundIndex, unspent_kickoff_utxos: &[usize], ) -> Result<Vec<(TransactionType, Transaction)>, BridgeError>

Creates a transaction that burns unused kickoff connectors.

async fn validate_all_kickoff_finalizers_spent( &self, dbtx: Option<DatabaseTransaction<'_, '_>>, round_idx: RoundIndex, current_chain_height: u32, ) -> Result<(), BridgeError>

Validates that all kickoff finalizers are spent for the given round.

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

Checks if the next round tx is on chain, if it is, updates the database, otherwise returns the round tx that needs to be sent.

Trait Implementations

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

fn clone(&self) -> Operator<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 Operator<C>

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

Formats the value using the given formatter.

impl<C> From<Operator<C>> for OperatorParams

where C: CitreaClientT,

fn from(operator: Operator<C>) -> Self

Converts to this type from the input type.

impl<C> NamedEntity for Operator<C>

where C: CitreaClientT,

const ENTITY_NAME: &'static str = "operator"

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 = "operator_finalized_block_fetcher_automation"

Consumer ID for the finalized block task with automation.

const FINALIZED_BLOCK_CONSUMER_ID_NO_AUTOMATION: &'static str = "operator_finalized_block_fetcher_no_automation"

Consumer ID for the finalized block task with no automation.

impl<C> Owner for Operator<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