Bridge Reference

Bridge2, Withdrawals, and Validator-Set Updates

This page condenses the Bridge2 control plane into one staged flow: user withdrawal entry, validator signatures, finalized-vote state, validator-set update signatures, and the current trust model around dispute-period invalidation and signer reuse.

Bridge Note Action Types Paper Withdrawal Flow Open Claims

Signer reuse confirmed

Withdrawal finalization stages confirmed

Dispute invalidation risk active

Bridge2 field oaw bool confirmed, meaning open

1. Bridge2 State Surface

Field family	Role
`eth_id_to_deposit_votes`	Deposit confirmation tracking.
`finished_deposits_data`	Completed-deposit state.
`withdrawal_signatures`	Collected validator signatures for pending withdrawals.
`withdrawal_finalized_votes`	Finalization vote state after the signature stage.
`finished_withdrawal_to_time`	Timing/tracking surface for completed withdrawals.
`validator_set_signatures`	Signature collection for bridge validator-set changes.
`validator_set_finalized_votes`	Finalization votes for validator-set updates.
`bal`	Bridge balance as a `UsdcNtl` tuple `[usdc, ntl]`; observed `[990593662988097, 0]`.
`last_pruned_deposit_block_number`	Deposit pruning watermark.
`oaw`	Boolean "only allow withdrawals" flag. When true, deposits are disabled and only withdrawals remain enabled.

2. Withdrawal and Validator-Set Flow

flowchart TD A[withdraw3] --> B[ValidatorSignWithdrawal] B --> C[withdrawal_signatures accumulates] C --> D[Threshold reached] D --> E[VoteEthFinalizedWithdrawal] E --> F[withdrawal_finalized_votes] F --> G[Dispute period and release] H[Epoch or signer-set change] --> I[SignValidatorSetUpdate] I --> J[validator_set_signatures] J --> K[VoteEthFinalizedValidatorSetUpdate] K --> L[validator_set_finalized_votes] L --> M[Ethereum-side validator set update]

The current repo truth keeps withdrawal signing and finalized voting as separate bridge phases.
Validator-set updates are a first-class bridge flow, not just an implied governance side effect.
Bridge signing is currently documented as reusing validator signer keys.

3. Action Families

Action	Purpose
`withdraw3`	User bridge withdrawal entrypoint.
`ValidatorSignWithdrawal`	Validator signature on a pending withdrawal.
`VoteEthFinalizedWithdrawal`	Finalize the staged withdrawal path.
`SignValidatorSetUpdate`	Signature lane for bridge validator-set changes.
`VoteEthFinalizedValidatorSetUpdate`	Finalize the validator-set update path.

4. Current Risk Surface

Question	Current answer
Is the bridge trust-minimized?	No. The current docs keep dispute-period invalidation and no-escape-hatch risk explicit.
Is finalization a one-step action?	No. Signatures and finalized-vote state are separate surfaces.
Are all Bridge2 fields fully decoded?	The Bridge2 tracker shells, pair lists, and nested tuple payloads are now modeled in code. The remaining gap is the exact leaf encoding for fields like `chain`, `tx_hash`, `destination`, `usd`, and signature limbs, which are still preserved as JSON-backed leaves.