Updated architecture docs are now live!

Withdrawal Flow

Withdrawal Flow

The withdrawal flow transfers tokens from Eclipse (L2) back to ETH on Ethereum (L1):

spinner

Technical Deep Dive - Withdrawal Flow:

  1. User Burns Tokens on L2

    • The user interacts with the L2 Bridge Program to burn their tokens

    • The burn operation requires specifying the L1 destination address where ETH will be sent

    • The L2 bridge program generates a unique withdrawal ID to prevent replay attacks

    • The L2 Bridge Program burns the tokens and emits a burn event

  2. Withdrawal Relayer Observation

    • The Withdrawal Relayer monitors the L2 Bridge Program for burn events

    • It validates the burn parameters to ensure they meet L1 requirements

    • The relayer can specify a fee receiver and fee amount for gas cost reimbursement

      • Both the user withdraw amount and gas reimbursement are subject to the 7-day fraud window

    • The relayer constructs a WithdrawMessage struct with all necessary information:

      struct WithdrawMessage {
          bytes32 from;           // L2 sender address
          address destination;    // L1 recipient address
          uint256 amountWei;      // Amount in wei
          uint64 withdrawId;      // Unique identifier
          address feeReceiver;    // Fee recipient (optional)
          uint256 feeWei;         // Fee amount (optional)
      }
  3. Withdrawal Authorization

    • The Withdrawal Relayer calls authorizeWithdraw(WithdrawMessage message) on the CanonicalBridge

    • This function requires the WITHDRAW_AUTHORITY_ROLE, which the relayer must have

    • The CanonicalBridge validates the message and starts the 7-day fraud window

    • The withdrawal status is set to PROCESSING

    • A WithdrawAuthorized event is emitted with the message hash and start time

    • This event allows for tracking the withdrawal through the process

  4. Fraud Window Period

    • The withdrawal remains in PROCESSING state for the duration of the fraud window

    • During this period, the Bridge Troll monitors for suspicious withdrawals

    • If a suspicious withdrawal is detected, the Bridge Troll can call deleteWithdrawMessage()

    • After the fraud window expires, the withdrawal status automatically transitions to PENDING

    • This time-lock mechanism plus Bridge Troll introspection of withdraw events on both L1 and L2 is the critical security feature that protects user withdrawals.

  5. User Claims Withdrawal

    • After the fraud window expires, the user calls claimWithdraw(WithdrawMessage message)

    • The CanonicalBridge verifies that the fraud window has passed

    • It changes the withdrawal status to CLOSED to prevent double-claiming

    • It calls withdrawEth(address to, uint256 amountWei) on the Treasury

    • It handles fee distribution if specified in the withdrawal message

    • It emits a WithdrawClaimed event for tracking

  6. Treasury Transfers ETH

    • The Treasury validates that the caller has the WITHDRAW_AUTHORITY_ROLE

    • It checks that it has sufficient balance to fulfill the withdrawal

    • It transfers the specified amount of ETH to the destination address

    • It emits a TreasuryWithdraw event for tracking

    • This completes the withdrawal process

Security Considerations:

  • Fraud Window: The fraud window creates a time buffer for security interventions, allowing for detection and prevention of fraudulent withdrawals

  • Independent Security Check: The Bridge Troll provides an independent security check, able to cancel suspicious withdrawals during the fraud window

  • Multi-Step Process: The withdrawal process requires multiple steps and authorizations, creating defense in depth

  • Restricted Access: The Treasury only accepts withdrawal requests from authorized entities, preventing unauthorized withdrawals

  • Unique Identifiers: Each withdrawal has a unique identifier generated by the L2 to prevent replay attacks

Last updated

Was this helpful?