Layered Settlement and Bridges
BTX bridge protocol: BridgeBatchStatement, BridgeBatchCommitment, authenticated roots, mass exit capacity, three egress modes, and settlement without fraud windows.
Overview
BTX implements a layered settlement system that enables cross-domain value transfers between the base chain and external domains (L2s, sidechains, application-specific rollups). The bridge protocol uses batch-oriented settlement with cryptographic commitments rather than fraud proofs, eliminating challenge windows and enabling instant finality on the base layer.
BridgeBatchStatement (v5)
A BridgeBatchStatement is the top-level settlement request that encodes
a batch of cross-domain transfers. Each statement carries:
| Field | Type | Description |
|---|---|---|
version | uint8 | Statement version (current: 1, wire protocol supports up to v5 semantics) |
direction | BridgeDirection | BRIDGE_IN (deposit) or BRIDGE_OUT (withdrawal) |
ids | BridgePlanIds | Plan and batch identifiers for cross-referencing |
entry_count | uint32 | Number of individual transfers in the batch |
total_amount | CAmount | Sum of all transfer amounts (consensus-verified) |
batch_root | uint256 | Merkle root of individual transfer entries |
domain_id | uint256 | Identifier of the external domain |
source_epoch | uint32 | Source-domain epoch for ordering guarantees |
data_root | uint256 | Root of associated data availability blob |
verifier_set | BridgeVerifierSetCommitment | Commitment to the verifier set authorized to attest |
proof_policy | BridgeProofPolicyCommitment | Descriptor root for the proof acceptance policy |
aggregate_commitment | BridgeBatchAggregateCommitment | Five authenticated roots (see below) |
The statement hash (ComputeBridgeBatchStatementHash) is the canonical
identifier used to bind settlement proofs, receipts, and synthetic credit notes
to a specific batch.
BridgeBatchAggregateCommitment (v3)
The aggregate commitment contains five authenticated roots that bind the batch to specific state transitions and policies:
| Root | Purpose |
|---|---|
action_root | Merkle root of the ordered list of settlement actions (transfers, mints, burns). Validators verify that all claimed actions are included and correctly ordered. |
data_availability_root | Commitment to the full data availability blob for the batch. Ensures that all data needed to independently verify and reconstruct transfers is published and retrievable. |
recovery_or_exit_root | Merkle root of recovery paths and exit claims. Enables users to reclaim funds if the external domain becomes unavailable, without relying on the domain operator's cooperation. |
policy_commitment | Descriptor root of the proof acceptance policy. Defines which proof types, verifier thresholds, and attestation schemes are accepted for this batch. |
extension_digest | Forward-compatible extension field for additional commitments. Set to null in current deployments; future versions can bind additional state without breaking existing verification logic. |
Extension flags (FLAG_HAS_RECOVERY_OR_EXIT_ROOT,
FLAG_HAS_POLICY_COMMITMENT, FLAG_CUSTOM_ACTION_ROOT,
FLAG_CUSTOM_DATA_AVAILABILITY_ROOT) indicate which optional roots
are populated, enabling compact serialization when fields are unused.
Verification Model
Bridge batches support two verification paths, both of which produce cryptographically bound receipts:
Signed Receipt Path
An authorized verifier set attests to batch validity by producing signed receipts.
The BridgeVerificationBundle contains a signed_receipt_root
(Merkle root of all signed attestations) and a proof_receipt_root
(for proof-based attestations). Verification checks:
- Each receipt's statement hash matches the batch statement hash.
- Signatures are valid under the committed verifier set.
- The verifier threshold defined by the proof policy is met.
Proof Receipt Path
Alternatively, a cryptographic proof (ZK or otherwise) can attest to batch validity without requiring a trusted verifier set. The proof is verified against the proof policy descriptor, and the result is encoded as a proof receipt.
No Fraud Window
Both verification paths produce receipts that are verified at inclusion time. There is no optimistic assumption and no challenge period: invalid batches are rejected immediately by consensus, and valid batches are final once included in a block.
Settlement Binding
Bridge settlement integrates with the SMILE v2 proof system through settlement binding digests:
- Ingress batches (BRIDGE_IN) create synthetic credit notes in the shielded pool. These notes are bound to the statement hash and are indistinguishable from regular shielded outputs.
- Egress batches (BRIDGE_OUT) consume shielded notes and produce transparent outputs or cross-domain transfer claims.
- The
settlement_binding_digestin each proof envelope binds the shielded proof to the specific bridge batch statement.
Three Egress Modes
| Mode | Description | Use Case |
|---|---|---|
| Standard Egress | Batch-processed withdrawal through the normal bridge settlement path. Creates transparent outputs on the base chain. | Normal withdrawals, treasury operations |
| Direct Unshield | Proves ownership of shielded notes and produces transparent outputs without going through the batch mechanism. Uses the SMILE v2 unshield path. | Individual withdrawals, immediate liquidity needs |
| Mass Exit | Emergency exit path using the recovery_or_exit_root. Users can
claim funds by providing a Merkle proof of their entry in the exit tree,
bypassing the external domain entirely. | Domain failure, operator unresponsiveness, emergency recovery |
Mass Exit Capacity
The mass exit mechanism is designed for the worst case: a complete external domain failure requiring all users to exit simultaneously. Key properties:
- Exit claims reference the
recovery_or_exit_rootfrom the most recent valid batch commitment. - Each claim is a Merkle inclusion proof plus the user's spending authorization (P2MR signature).
- Claims are processed as standard base-chain transactions, subject to normal block capacity limits (24 MW weight, 24 MB serialized).
- No cooperation from the external domain operator is required.
Batch Leaf Structure
Individual transfers within a batch are encoded as BatchLeaf entries:
| Field | Type | Description |
|---|---|---|
version | uint8 | Wire version |
family_id | TransactionFamily | V2_INGRESS_BATCH or V2_EGRESS_BATCH |
l2_id | uint256 | Source-domain transaction identifier |
destination_commitment | uint256 | Commitment to the destination address/key |
amount_commitment | uint256 | Committed transfer amount |
fee_commitment | uint256 | Committed fee amount |
position | uint32 | Ordered position within the batch |
nonce | uint256 | Replay protection nonce |
settlement_domain | uint256 | Target settlement domain identifier |
The batch Merkle root is computed over the ordered set of leaf hashes, binding every individual transfer to the batch statement.
Transaction Families
Bridge operations map to specific SMILE v2 transaction families:
V2_INGRESS_BATCH— inbound batch settlement (external domain → BTX shielded pool)V2_EGRESS_BATCH— outbound batch settlement (BTX shielded pool → external domain)BATCH_SMILE— direct shielded-pool deposit via bridge path
Each family has its own proof envelope requirements and settlement binding rules, ensuring that cross-family replay is impossible.
Security Properties
- No fraud window: Settlement is verified at inclusion time. Invalid batches are rejected by consensus; valid batches are immediately final.
- Replay protection: Per-entry nonces and per-batch epoch ordering prevent replay of settlement claims across batches or domains.
- Domain isolation: The
domain_idfield ensures that batches from different external domains cannot interfere with each other. - Binding integrity: The statement hash cryptographically binds all components (entries, proofs, receipts, synthetic notes) to a single batch.
- Unilateral exit: The recovery/exit root enables users to reclaim funds without operator cooperation, providing a hard guarantee against domain-operator censorship or failure.