search
WebsiteBlogJoin The Community

Glossary

hashtag
Architecture & Core Components

  • Batch Prover: A dedicated node that generates zero-knowledge proofs attesting to the correctness of Citrea blocks in batches. After sequencer commitments are finalized on Bitcoin, the batch prover fetches the corresponding batch of Citrea blocks, replays their execution inside a zkVM, and produces a succinct proof for the entire state transition.

  • Batch Proof: A succinct ZK proof proving that if one starts from the previous proven state and executes all transactions in a batch, the resulting state matches the sequencer's claims. Includes the state diff, initial/final state roots, and the batch block range.

  • Batch Proof Method ID: A unique 256-bit identifier for a specific version of the batch proof circuit. When the batch proof circuit is upgraded (e.g., during a fork), the method ID changes. Updates to the method ID are authorized by the Security Council via a 3-of-5 multisig (size of the multisig is prone to changes) and published to Bitcoin, specifying the new method ID and the L2 activation height.

  • Bitcoin Light Client: Citrea's on-chain smart contract that maintains a record of finalized Bitcoin blocks. Each finalized Bitcoin block is pushed into this contract via system transactions, storing the block hash and witness root so other contracts (like the bridge) can prove Bitcoin transactions.

  • Clementine: Citrea's native BitVM-based trust-minimized two-way peg for BTC ↔ cBTC that enables optimistic verification of ZK proofs directly on Bitcoin without consensus changes. Uses a 1-of-N trust model where one honest Signer, Watchtower, and Challenger can protect funds.

  • Full Node: A permissionless participant that keeps a complete copy of Citrea's state and transaction history, verifies all rollup blocks by replaying transactions, monitors Bitcoin for finalized sequencer commitments and batch proofs, and exposes a standard JSON-RPC API.

  • Light Client Prover: A specialized node that produces a recursive proof of the entire Citrea rollup state. Continuously processes each new Bitcoin block along with the previous light client proof, producing a new proof that verifies the correct Citrea state root for that block, forming an unbroken chain of proofs from genesis.

  • Light Client Proof: A recursive proof of the entire Citrea Rollup state, while keeping its own JMT state. Verifies the relation between sequencer commitments and batch proofs and transitions the state accordingly. Includes L2 state root, circuit state root, method id of the previous light client proof, latest da state, last l2 height and sequencer commitment index from the last transitioned state.

  • Mempool: A private memory pool serving as a temporary staging area for pending transactions before inclusion in a block. Citrea uses Reth's transaction poolarrow-up-right architecture underneath with some modificationsarrow-up-right

  • Security Council: A trusted multisignature committee responsible for safeguarding critical operations across the Citrea network. Operating under a 3-of-5 threshold scheme, the Security Council manages emergency responses, system contract upgrades, bridge signer operations, and vault security on both Bitcoin L1 and Citrea L2.

The council's authority includes upgrading system contracts (Bridge, Fee Vaults, Bitcoin Light Client), managing Clementine bridge signers, controlling emergency vault operations, and updating the batch prover Method ID when ZK circuits change.

  • Sequencer: A specialized full node responsible for ordering user transactions and constructing rollup blocks. Every 2 seconds, it selects valid transactions prioritized by fees, injects system transactions, executes them against current state, updates the state root, and generates L2 Blocks.

  • Sequencer Commitment: A Merkle root of L2 Block hashes covering a sequence of Citrea blocks, posted to Bitcoin to secure transaction ordering. Includes the batch window's height and a sequential index. Once finalized on Bitcoin, the ordering of blocks in that window is pinned.

  • State Transition Function: The function that updates the Citrea state by applying transactions. Full nodes and batch proof circuit execute this function on each block by replaying transactions, applying state changes, and recomputing the state root.

  • zkEVM: Citrea's special EVM implementation (Type 2 zkEVM) that makes the full VM implementation provable. Built using RISC Zero, it provides full equivalency to Ethereum while enabling scalable and trustless proofs based on zk-STARKs.

  • Type 2 zkEVM: A zkEVM classification indicating full equivalency to Ethereum with a scalable and trustless proof system based on zk-STARKs (zero-knowledge Scalable Transparent Arguments of Knowledge).

hashtag
Transaction Finality

  • Confirmed: The first level of finality when a transaction appears inside a sequencer-signed L2 Block. The transaction has been executed in the zkEVM and assigned an order, but is not yet anchored to Bitcoin.

  • Finalized: The second level of finality when a batch window containing a transaction is finalized on Bitcoin. A sequencer commitment (Merkle root of L2 block hashes) reaches the required confirmation depth on Bitcoin, pinning the transaction's ordering immutably.

  • Proven: The highest level of finality when a batch's execution is proven via a succinct ZK proof inscribed on Bitcoin with sufficient confirmations. The entire state transition is cryptographically validated end-to-end, and the necessary state data is available on Bitcoin for state reconstruction.

  • L2 Block: A rollup block produced by the sequencer. It contains a signed header and a vector of transactions. The header includes the header hash, signature, block height, previous block header hash, state root at the end of that block, L1 fee rate, transactions merkle root, and timestamp.

  • Soft Confirmation: The old name of L2 Block may be seen in some old comments throughout the codebase.

  • State Root: The root hash of the rollup state after applying transactions in an L2 Block or batch proof. Used as a public input to circuits and helps nodes verify that they are applying the correct batch in sequence.

hashtag
Proofs & Cryptography

  • Groth16: A succinct non-interactive zero-knowledge proof system used by Citrea. Citrea's batch proof circuit running in RISC Zero zkVM generates STARK proofs initially then another circuit in the zkVM wraps the stark proof with recursive proof composition to produce the Groth16 proof that prove correctness of Citrea blocks

  • RISC Zero: A zkVM (zero-knowledge virtual machine) environment that Citrea uses to generate batch proofs, light client proofs and bridge proofs. Runs Groth16 circuits to prove the validity of state transitions, with proofs later wrapped into SNARKs for Bitcoin verification via Clementine.

  • SNARK: Succinct Non-Interactive Argument of Knowledge. Citrea generates STARK proofs for transactions, then wraps them into succinct SNARK proofs for publication to Bitcoin in an inscription-like envelope for efficient verification.

  • STARK: Scalable Transparent Argument of Knowledge. Citrea generates STARK proofs for batches of zkEVM transactions, which are then wrapped into SNARK proofs for publication to Bitcoin.

  • Zero-Knowledge Proof: A cryptographic proof that demonstrates knowledge of a fact without revealing the fact itself. Citrea uses ZK proofs to prove the correctness of state transitions without requiring verification of every transaction individually.

hashtag
Bitcoin Integration

  • Bitcoin Data Availability: Citrea's use of Bitcoin as its data availability layer. Instead of posting full transactions, Citrea publishes Brotli compressed state differences (state diffs) plus the latest state root to Bitcoin, allowing full nodes to reconstruct the entire rollup state from Bitcoin alone.

  • BitVM: A breakthrough technology enabling optimistic verification of complex computations directly on Bitcoin without consensus changes. Citrea uses BitVM (specifically BitVM2) to verify ZK proofs on Bitcoin for the Clementine bridge, allowing off-chain computation with on-chain dispute resolution.

  • BitVM2: An enhanced version of BitVM that significantly reduces on-chain footprint and improves permissionlessness. While both BitVM1 and BitVM2 use optimistic verification (assuming validity unless challenged), BitVM2 introduces key improvements: (1) SNARK verification instead of arbitrary computation - focuses specifically on verifying succinct proofs rather than general computation, (2) Permissionless challenges - anyone can challenge fraudulent claims, not just designated parties, and (3) Reduced transaction complexity - requires far fewer pre-signed transactions and on-chain interactions. Clementine is built on BitVM2 to create a trust-minimized bridge.

  • Coinbase Depth: The position/depth of the coinbase transaction within a Bitcoin block's Merkle tree. Stored by the Bitcoin Light Client and used to enforce proof lengths for witness verification, preventing Merkle tree attacks explained in this blogarrow-up-right..

  • Covenant: A Bitcoin mechanism that restricts how a UTXO can be spent. Clementine emulates covenant-like restrictions using pre-signed transactions and MuSig2 aggregation, ensuring funds can only follow pre-approved spend paths.

  • Finality Depth: The number of Bitcoin block confirmations required before Citrea considers a Bitcoin block finalized. Set to 6 on mainnet and 100 on testnet4 to withstand deep reorgs. The sequencer and full nodes only process Bitcoin blocks that have reached this depth.

  • MuSig2: A two-round multi-signature scheme for creating aggregate Schnorr signatures from multiple keys, improving on the original MuSig protocol by reducing the number of communication rounds required. Clementine uses MuSig2 for pre-signed transactions, enabling n-of-n multisig functionality where all signers must participate to produce a single valid signature, with key deletion providing covenant-like spending restrictions.

  • Schnorr Signature: A digital signature scheme used by Citrea for transaction verification. Citrea includes a Schnorr precompile and uses Schnorr signatures in the Clementine bridge for transaction authorization.

  • Taproot: A Bitcoin upgrade enabling Taproot addresses that support multiple spending paths and Schnorr signatures. Clementine uses Taproot addresses encoding two paths: bridge paths (pre-signed by signers) and refund paths (user timelock).

  • Witness Root: The Merkle root of a Bitcoin block's witness data (wtxids). Stored by the Bitcoin Light Client for each block to enable verification of transaction inclusion via witness Merkle trees.

  • Txid: Transaction ID - The hash of a Bitcoin transaction not including its witness data.

  • Wtxid: Witness transaction ID - the hash of a Bitcoin transaction including its witness data. Used by Citrea's Bitcoin Light Client for transaction inclusion proofs and verification against the witness root.

  • BIP 340: Bitcoin Improvement Proposal defining Schnorr signature scheme used in Taproot (BIP 341).

  • BIP 341: Bitcoin Improvement Proposal defining Taproot script path spending; used for bridge deposit/withdrawal witness structure and sighash reconstruction.

hashtag
Bridge & Cross-Chain

  • cBTC: Citrea Bitcoin, the native asset on Citrea representing 1:1-backed Bitcoin from the Clementine bridge. Used for gas fees and transfers on Citrea, with 18 decimals (unlike 8 in Bitcoin mainnet).

  • Peg-In: The process of depositing BTC to the Clementine bridge to mint cBTC on Citrea. User sends BTC to a Taproot address with two paths (bridge path and refund timeout), operators move it to a vault, and the bridge mints equivalent cBTC.

  • Peg-Out: The process of withdrawing BTC by burning cBTC through the Clementine bridge smart contract on Citrea. User burns cBTC, submits withdrawal request to operators with a payout transaction template, and receives BTC on Bitcoin.

  • Bridge Contract: The smart contract on Citrea (at address 0x3100000000000000000000000000000000000002arrow-up-right) that validates Bitcoin deposits using the on-chain light client, mints cBTC for deposits, and records withdrawal intents for peg-outs.

  • Failed Deposit Vault: A system contract that receives cBTC if a deposit transfer reverts (e.g., due to contract rejection). Allows operators and administrators to recover failed deposit funds rather than burning them.

hashtag
Clementine Bridge Roles

  • Challenger: An entity who detects fraudulent reimbursement claims by operators on Bitcoin and initiates a Challenge transaction to force the operator to prove their intent in a dispute resolution game.

  • Operator: An entity that facilitates fast peg-outs by fronting BTC payments to users and later claiming reimbursement from the bridge vault. Posts a KickOff claim transaction and can be slashed if proven fraudulent via challenge-response game. Requires a collateral bond (~2 BTC).

  • Signer: A member of the n-signer committee in Clementine that pre-signs allowed spend rules for bridge funds. Ensures funds can only move along approved paths via covenant-like restrictions. One honest signer protects funds against theft under 1-of-N assumption.

  • Watchtower: An entity that monitors both Citrea and Bitcoin for malicious operator behavior. Publishes compact Bitcoin header-chain proofs with total work in response to fraud challenges, enabling challengers to prove invalid operator claims.

hashtag
Security & Dispute Resolution

  • Challenge-Response Game: A BitVM2-based dispute resolution process triggered when a challenger contests an operator's reimbursement claim. The operator must prove correctness by posting Assert transactions that reveal intermediate computation results. If any step is incorrect, challengers can post a Disprove transaction to verify that single step on-chain and slash the operator's collateral. The operator's Bridge Proof must demonstrate their Header Chain Proof has more total work than Watchtower challenges and that the payout transaction is valid.

  • Bridge Proof: A Groth16 zero-knowledge proof generated by an operator to defend their reimbursement claim during the BitVM2 challenge-response game. The proof verifies: (1) the operator's Header Chain Proof has more total work than the highest valid Watchtower challenge, (2) the payout transaction is included in the claimed Bitcoin block via SPV, (3) the Light Client Proof confirming the L1 block hash matches the payout transaction's block, and (4) EVM storage proofs showing the withdrawal data on Citrea matches the payout transaction. If any verification fails, challengers can use a Disprove transaction to slash the operator's collateral. For detailed information see Bridge Circuitarrow-up-right

  • Collateral Bond: BTC locked by each operator in Clementine (approximately 2 BTC) to back their reimbursement claims. If any claim in a round is proven fraudulent, the entire bond is slashed, preventing the operator from claiming reimbursements.

  • Optimistic Verification: The process of accepting state updates optimistically (without immediate verification) and allowing them to be disputed within a challenge period. Clementine uses optimistic verification of ZK proofs on Bitcoin via BitVM.

  • Slashing: Economic punishment mechanism in Clementine where an operator's entire collateral bond is forfeited if their reimbursement claim is proven fraudulent via the challenge-response game, and they are kicked out of the operator set.

  • Trust-Minimized: A security model that minimizes the number and power of trusted entities. Clementine achieves trust-minimization through 1-of-N trust assumption, where only one honest participant per role is needed to protect the system.

  • 1-of-N Trust Assumption: A security model where the system remains secure as long as one honest participant exists among N participants. Clementine's bridge requires one honest Signer (prevents theft), one honest Watchtower (prevents chain anchoring to wrong fork), and one rational Challenger (forces honest operator behavior).

hashtag
Clementine Transactions

hashtag
Deposit & Collateral Transactions

  • Round: A Bitcoin transaction that creates collateral for withdrawals, kickoff UTXOs for the current round, and reimburse connectors for the previous round. Chains rounds together using the first output of the previous ready-to-reimburse transaction.

  • Move to Vault: A Bitcoin transaction that moves deposited BTC from the user's Taproot deposit address into the bridge vault UTXO, which is only spendable via the bridge's allowed exit paths. Requires all verifier signatures via MuSig2 aggregation.

  • Replacement Deposit: A Bitcoin transaction that replaces a previous deposit when an emergency stop is triggered. Commits the old move-to-vault txid it replaces, allowing funds to be redeposited after security issues are resolved.

  • Emergency Stop: A Bitcoin transaction that moves funds from a move-to-vault address to a security council controlled address, halting the deposit process in case of a security issue. Funds can later be redeposited via a replacement deposit.

hashtag
Payout & Reimbursement Transactions

  • Payout: A Bitcoin transaction where an operator fronts a peg-out (withdrawal) to a user. The input is the user's withdrawal UTXO committed in Citrea, and the output goes to the user's address with an OP_RETURN containing the operator's x-only pubkey.

  • Optimistic Payout: A Bitcoin transaction where verifiers give deposited funds directly to a withdrawing user without the operator/BitVM process. Requires all verifier signatures and uses the move-to-vault output as collateral.

  • Reimburse: A Bitcoin transaction where an operator claims reimbursement after no challenge is sent, or after a challenge is sent but no disprove follows. Spends the move-to-vault, kickoff reimburse connector, and round reimburse connector outputs.

  • Ready to Reimburse: A Bitcoin transaction that spends the operator's collateral burn connector from the round transaction and returns collateral to the operator after a timeout period expires.

  • Kickoff Not Finalized: A Bitcoin transaction that burns an operator's collateral if they send a ready-to-reimburse transaction while not all round kickoffs are finalized.

  • Unspent Kickoff: A Bitcoin transaction that burns unused kickoff connectors when an operator sends ready-to-reimburse without spending all kickoff UTXOs.

  • Burn Unused Kickoff Connectors: A Bitcoin transaction that burns multiple unused kickoff connectors from a single round transaction and returns change to a provided address.

hashtag
Challenge & Dispute Transactions

  • KickOff: A Bitcoin transaction that initializes the protocol state when an operator fronts a peg-out seeking reimbursement. Sets up outputs for challenge, reimbursement, asserts, watchtower challenges, and latest blockhash commitments.

  • Challenge: A Bitcoin transaction initiated by a challenger to dispute a fraudulent operator reimbursement claim (KickOff transaction). Covers the challenger's costs and includes an OP_RETURN with the challenger's EVM address for reimbursement if the challenge is valid.

  • Challenge Timeout: A Bitcoin transaction that finalizes a kickoff if no challenge is submitted in time, allowing the operator to proceed faster to the next round. Uses the challenge timeout and kickoff finalizer outputs.

  • Watchtower Challenge: A Bitcoin transaction where a watchtower submits a challenge proof (Groth16 proof with public inputs). Encodes 144 bytes as Taproot outputs (32+32 bytes) and OP_RETURN (80 bytes).

  • Watchtower Challenge Timeout: A Bitcoin transaction where an operator claims timeout if a watchtower doesn't submit a challenge in time. Uses the watchtower challenge and challenge ack outputs.

  • Operator Challenge Ack: A Bitcoin transaction where an operator acknowledges a watchtower challenge and reveals a preimage. Spends the watchtower challenge ack output.

  • Operator Challenge Nack: A Bitcoin transaction where the N-of-N signers burn an operator's collateral if the operator doesn't reveal a preimage within the timelock. Spends challenge ack, kickoff finalizer, and burn connector outputs.

  • Disprove: A Bitcoin transaction where the N-of-N signers penalize a malicious operator by burning their collateral. Uses BitVM disprove scripts or additional disprove scripts for invalid proofs. Spends disprove and burn connector outputs.

  • Disprove Timeout: A Bitcoin transaction that an operator sends to enable the reimburse transaction if their proof wasn't disproved in time. Spends disprove and kickoff finalizer outputs.

  • No Challenge: A Bitcoin transaction posted by an operator after the challenge window expires without disputes, using a timelock to unlock reimbursement funds from the bridge vault.

hashtag
BitVM Assertion Transactions

  • Assert Timeout: A Bitcoin transaction where the N-of-N signers burn an operator's collateral if the operator doesn't provide valid assertion proofs within the timelock. Spends assert, kickoff finalizer, and burn connector outputs.

  • Mini Assert: A Bitcoin transaction that commits a BitVM assertion of an operator's proof showing they paid the payout. Lightweight assertion transactions that create an anchor for CPFP (Child Pays For Parent).

  • Latest Blockhash: A Bitcoin transaction where an operator commits the latest Bitcoin blockhash to reduce the time available for building a private fork. Used in the operator's bridge proof.

  • Latest Blockhash Timeout: A Bitcoin transaction where the N-of-N signers burn an operator's collateral if the latest blockhash is not submitted in time. Spends blockhash, kickoff finalizer, and burn connector outputs.

hashtag
System Contracts

hashtag
State Management

  • Jellyfish Merkle Tree: Citrea's state tree structure (instead of Ethereum's Patricia Merkle Tree) used for efficient state representation and zero-knowledge proofs.

  • Merkle Proof: Cryptographic proof of inclusion containing intermediate tree nodes needed to verify a leaf's membership in a Merkle tree.

  • Merkle Root: The root hash of a Merkle tree summarizing all transactions or state changes in a batch.

  • State Diff: Compressed representation of state changes between pre-state and post-state, posted to Bitcoin instead of full transaction data to minimize L1 footprint.

  • Witness Merkle Path: The path of intermediate hashes from a transaction's wtxid to the witness root used in SPV inclusion proofs.

hashtag
Transaction & Block Structure

  • Batch Window: A period of Citrea blocks whose ordering is locked by a single sequencer commitment inscription on Bitcoin.

  • Block Height: Sequential index of a block starting from genesis; Citrea tracks Bitcoin block heights for finality anchoring.

  • Inscription: Data inscribed on Bitcoin via transaction witness data, used for sequencer commitments and batch proofs.

  • nLockTime: Bitcoin transaction field specifying the earliest time/block height at which the transaction can be mined.

  • Transaction Merkle Root: Merkle root of all transaction hashes in a block; in Bitcoin, there are both transaction roots and witness transaction roots.

  • UTXO: Unspent Transaction Output on Bitcoin; represented as (txId, outputId) pair for bridge withdrawal intents and coin management.

hashtag
Fees & Gas

  • Base Fee: Per-byte cost applied to all transactions on Citrea, accumulated in the Base Fee Vault; varies with network congestion.

  • Diff Size: Size of the state diff in bytes posted to Bitcoin for a transaction, used to calculate L1 fees.

  • L1 Fee: Cost charged per transaction to cover Bitcoin data availability postings, calculated as l1FeeRate * diffSize; deducted at transaction end.

  • L1 Fee Rate: Variable rate (wei per byte) for state diff costs on Bitcoin; reflects current Bitcoin transaction fees.

  • Priority Fee: Tip amount paid to sequencers for transaction ordering priority, accumulated in the Priority Fee Vault.

hashtag
EVM & Execution

  • EIP-2935: Ethereum Improvement Proposal for block hash historical access; NOT supported on Citrea.

  • EIP-4844: Ethereum blob transaction standard for cheap data availability; NOT supported on Citrea (no blob pool).

  • KZG Precompile: Kate-Zaverucha-Goldberg commitment verification precompile for EIP-4844; NOT available on Citrea (address 0x0A behaves as EOA).

  • Precompile: Pre-compiled smart contract at a fixed address providing cryptographic operations at reduced gas cost.

hashtag
Precompiles

  • secp256r1 Precompile: Precompile at 0x0000000000000000000000000000000000000100 (RIP-7212) for ECDSA signature verification on the secp256r1 curve; enables hardware/biometric authentication and passkeys at 3,450 gas.

  • Schnorr Precompile: Precompile at 0x0000000000000000000000000000000000000200 for Bitcoin-native Schnorr signature verification (BIP 340); enables scriptless atomic swaps and Taproot key verification at 4,600 base gas.

hashtag
Network & Connectivity

  • Chain ID: Network identifier: 4114 for Citrea Mainnet (hex: 0x1012) and 5115 for Citrea Testnet (hex: 0x13FB).

  • Testnet4: Bitcoin's longest-lived testnet with frequent deep reorgs; Citrea Testnet uses 100-block finality depth as buffer against Testnet4 reorgs.

hashtag
Data & Availability

  • Reorg Resistance: System's ability to withstand Bitcoin reorgs without halting.

  • State Reconstruction: Ability to rebuild Citrea state independently from Bitcoin L1 by replaying state diffs and batch proofs from genesis.

  • Blockspace: The limited data capacity within each Bitcoin block that Citrea competes for when posting sequencer commitments, batch proofs, and state diffs. Bitcoin's ~4MB block weight limit constrains how much rollup data can be inscribed per block, directly affecting Citrea's throughput and L1 fees.

hashtag
Future Research

  • Decentralized Sequencer Network: Multiple sequencers sharing block production and transaction ordering via consensus algorithm instead of single sequencer; addresses liveness challenges.

  • Lightning Integration: HTLC-based trustless atomic swaps between Citrea and Lightning Network for off-ramp/on-ramp without Bitcoin L1.

  • Multi-Prover System: Combining multiple ZK proof systems (RISC Zero + SP1) to reduce single-point-of-failure risk in soundness; template implementation exists, SP1 activation post-mainnet.

  • Multi-VM Approach: Future research into supporting multiple virtual machines beyond EVM on Citrea for broader developer ecosystem.

  • Trustless Settlement: End-goal of fully trustless Bitcoin bridge without 1-of-N trust assumptions; requires Bitcoin opcodes like OP_CAT for covenant-based proof verification.

  • Volition Model: Hybrid data availability allowing users to choose between on-chain (Bitcoin) or off-chain DA branches; offers cost/security tradeoff.

  • Force Transactions: Mechanism for users to bypass sequencer censorship by forcing transactions through a timeout-based mechanism.

PreviousCode of Conduct

Last updated

Was this helpful?