Withdrawal Flow

Withdrawal Flow

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

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