Skip to content

Latest commit

 

History

History
359 lines (263 loc) · 12.1 KB

File metadata and controls

359 lines (263 loc) · 12.1 KB

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.

Parameters Description
version Version field of a transaction
flag Marker + Flag of a segregated witness transaction
vin Transaction inputs
vout Transaction outputs
witness Transaction witness
locktime Transaction locktime
intermediate_nodes The proof's intermediate nodes
block_height Block Height
index The leaf's index in the tree (0-indexed)

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.

Parameters Description
bytes _scriptPrefix The prefix part of deposit script for all L1 (Bitcoin) deposits.
bytes _scriptSuffix The suffix part of the deposit script that follows the receiver address
uint256 _depositAmount The fixed amount for deposits and withdrawals, set to 10 ether (cBTC) for Citrea Testnet.

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

Updates the expected deposit script parameters.

Parameters Description
bytes _scriptPrefix The prefix part of new deposit script for all L1 (Bitcoin) deposits.
bytes _scriptSuffix The suffix part of the new deposit script that follows the receiver address.

function setSlashOrTakeScript(bytes calldata _slashOrTakeScript) external onlyOwner

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

Parameters Description
bytes _slashOrTakeScript New expected slash or take script.

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.

Parameters Description
TransactionParams moveTp Struct containing deposit transaction details from Bitcoin

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.

Parameters Description
bytes32 txId Transaction ID for the input of the withdraw transaction on Bitcoin
bytes4 outputId Output index for the input of the 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.

Parameters Description
bytes32[] txIds Array of transaction IDs for the inputs of the withdraw transactions on Bitcoin
bytes4[] outputIds Array of output indexes for the inputs of the withdraw transactions on Bitcoin

function getWithdrawalCount() external view returns (uint256)

Returns the total number of withdrawal requests made so far.

Returns Description
uint256 The count of withdrawals happened so far

function setOperator(address _operator) external onlyOwner

Sets the operator address that can process user deposits.

Parameters Description
address _operator Address of the privileged operator

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.

Parameters Description
TransactionParams withdrawTp Struct containing withdraw transaction details from Bitcoin
uint256 inputIndex Input of the withdraw transaction that corresponds to the stored UTXO for the withdraw request denoted with withdrawId
uint256 withdrawId The ID of stored withdraw request

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.

Parameters Description
TransactionParams slashOrTakeTp Struct containing slash or take transaction details from Bitcoin

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.

Parameters Description
TransactionParams tp Struct containing transaction details from Bitcoin
Returns Description
bytes32 Witness transaction ID of the provided transaction
uint256 Number of inputs of the provided transaction

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

Extracts the recipient from a given script.

Parameters Description
bytes memory _script The script to be processed
Returns Description
address The recipient

Events

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

Emitted when a deposit is successfully processed.

Parameters Description
bytes32 wtxId The witness transaction ID of the Bitcoin transaction
bytes32 txId The transaction ID of the Bitcoin transaction
address recipient The Citrea address receiving the deposited cBTC
uint256 timestamp The timestamp of the deposit
uint256 depositId The ID of the deposit

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

Emitted when a withdrawal request is recorded.

Parameters Description
UTXO utxo UTXO to store for the withdrawal request
uint256 index The index of the withdrawal in the withdrawalUTXOs array
uint256 timestamp The timestamp of the withdraw call

event DepositScriptUpdate(bytes scriptPrefix, bytes scriptSuffix)

Emitted when the deposit script parameters are updated.

Parameters Description
bytes scriptPrefix The new script prefix
bytes scriptSuffix The new script suffix

event OperatorUpdated(address oldOperator, address newOperator)

Emitted when the operator address is updated.

Parameters Description
address oldOperator The previous operator address
address newOperator The new operator address

event WithdrawFillerDeclared(uint256 withdrawId, uint256 withdrawFillerId)

Emitted when the operator filled a withdrawal request is declared.

Parameters Description
uint256 withdrawId The withdraw ID
uint256 withdrawFillerId ID of the operator that filled the withdrawal request

event MaliciousOperatorMarked(uint256 operatorId)

Emitted when an operator is marked as malicious.

Parameters Description
uint256 operatorId ID of the operator that is marked as malicious

event SlashOrTakeScriptUpdate(bytes slashOrTakeScript)

Emitted when slash or take script is updated.

Parameters Description
bytes slashOrTakeScript New expected slash or take script