Bridge

Serves as a facilitator of deposits and withdrawals between Bitcoin and Citrea. It verifies Bitcoin transactions for deposits and manages withdrawal requests to be processed on the Bitcoin network.

You can find the contract in the address 0x31000...0002, here.

Deposit Structure

The following is an explanation regarding the TransactionParams structure, which is used to represent deposits made to Citrea from the Bitcoin network using Clementine.

To understand more, please check the way deposit params are used along with the BitcoinLightClient contract from both our documentation and explorer.

State Structure

bool public initialized;

A flag indicating whether the contract has been initialized.

address public operator;

The address of the privileged operator who can process user deposits.

bool[1000] public isOperatorMalicious;

A list of values indicating if a operator is marked as malicious.

uint256 public depositAmount;

The fixed amount for deposits and withdrawals, set to 10 ether (cBTC) for Citrea Testnet.

uint256 currentDepositId;

Index of the latest processed deposit.

bytes public scriptPrefix;

The prefix part of deposit script for all L1 (Bitcoin) deposits.

bytes public scriptSuffix;

The suffix part of the deposit script that follows the receiver address.

bytes public slashOrTakeScript;

Script that is used for "slash or take" transactions on Bitcoin. These transactions are sent after an operator proves that they covered a withdrawal through declareWithdrawFiller and it is used as a part of the process that enables the operator to get back the amount they covered from N-of-N multisig on Bitcoin.

UTXO[] public withdrawalUTXOs;

An array to store ANYONE_CAN_PAY UTXOs on Bitcoin that are utilized as withdraw intents that are covered by operators later on. This stored UTXO information is used to prove that an operator covered a certain withdrawal through declareWithdrawFiller.

mapping(bytes32 => uint256) public txIdToDepositId;

A mapping that maps the transaction IDs of deposit transactions on Bitcoin to their deposit IDs on Citrea side.

mapping(uint256 => uint256) public withdrawFillers;

A mapping that maps the withdraw ID to operator ID that covered the withdrawal with that withdraw ID.

Access Control Structure

modifier onlySystem()

Ensures that only the system caller (0xdeaDDeADDEaDdeaDdEAddEADDEAdDeadDEADDEaD) can call the function.

modifier onlyOperator()

Ensures that only the designated operator can call the function.

modifier onlyOwner()

Ensures that only the contract owner can call the function (inherited from Ownable).

Functions

function initialize(bytes calldata _scriptPrefix, bytes calldata _scriptSuffix, uint256 _depositAmount) external onlySystem

Initializes the bridge contract and sets the initial deposit script parameters.

function setDepositScript(bytes calldata _scriptPrefix, bytes calldata _scriptSuffix) external onlyOwner

Updates the expected deposit script parameters.

function setSlashOrTakeScript(bytes calldata _slashOrTakeScript) external onlyOwner

Updates the expected slash or take script. See slashOrTakeScript in State Structure for detailed information.

function deposit(TransactionParams calldata moveTp) external onlyOperator

Processes a deposit from Bitcoin to Citrea by verifying the Bitcoin transaction and sending configured bridge amount of cBTC to the recipient. Can only be called by the designated operator.

function withdraw(bytes32 txId, bytes4 outputId) external payable

Accepts configured bridge amount of cBTC from the sender and records a withdrawal request to be processed on Bitcoin. This recording is done by storing a UTXO consisting of a txId and an outputId which is the input for the ANYONE_CAN_PAY withdraw transaction on Bitcoin.

function batchWithdraw(bytes32[] calldata txIds, bytes4[] calldata outputIds) external payable

Batch version of withdraw that can accept multiple withdrawal requests at once.

function getWithdrawalCount() external view returns (uint256)

Returns the total number of withdrawal requests made so far.

function setOperator(address _operator) external onlyOwner

Sets the operator address that can process user deposits.

function declareWithdrawFiller(TransactionParams calldata withdrawTp, uint256 inputIndex, uint256 withdrawId) external

Stores which operator filled a certain withdraw request. Operators should make sure this function is called before sending a "slash or take" transaction on Bitcoin to avoid being marked as malicious.

function markMaliciousOperator(TransactionParams calldata slashOrTakeTp) external

Marks an operator as malicious if they sent a "slash or take" transaction on Bitcoin without first proving that they covered a withdrawal through declareWithdrawFiller. This information is later on used as evidence in the process of BitVM challenges on the Bitcoin side to prevent the operator stealing user funds from N-of-N multisig, as not being able to successfully call declareWithdrawFiller indicates that the operator is trying to claim funds from multisig even though they didn't cover a withdrawal request.

function validateAndCheckInclusion(TransactionParams calldata tp) internal view returns (bytes32, uint256)

Reverts if the provided transaction is not properly structured or not an actual Bitcoin transaction that happened according to BitcoinLightClient.

function extractRecipientAddress(bytes memory _script) internal view returns (address)

Extracts the recipient from a given script.

Events

event Deposit(bytes32 wtxId, bytes32 txId, address recipient, uint256 timestamp, uint256 depositId)

Emitted when a deposit is successfully processed.

event Withdrawal(UTXO utxo, uint256 index, uint256 timestamp)

Emitted when a withdrawal request is recorded.

event DepositScriptUpdate(bytes scriptPrefix, bytes scriptSuffix)

Emitted when the deposit script parameters are updated.

event OperatorUpdated(address oldOperator, address newOperator)

Emitted when the operator address is updated.

event WithdrawFillerDeclared(uint256 withdrawId, uint256 withdrawFillerId)

Emitted when the operator filled a withdrawal request is declared.

event MaliciousOperatorMarked(uint256 operatorId)

Emitted when an operator is marked as malicious.

event SlashOrTakeScriptUpdate(bytes slashOrTakeScript)

Emitted when slash or take script is updated.