# Withdrawal Flow

## Withdrawal Flow

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

{% @mermaid/diagram content="sequenceDiagram
participant User
participant L2Bridge as L2 Bridge Program
participant WithdrawRelayer
participant L1Bridge as L1 CanonicalBridge
participant BridgeTroll
participant Treasury

```
User->>L2Bridge: Burn tokens
L2Bridge->>WithdrawRelayer: Emit burn event
Note over WithdrawRelayer: Observe L2 burn
WithdrawRelayer->>L1Bridge: Authorize withdrawal
Note over L1Bridge: Start 7-day fraud window
Note over BridgeTroll: Can cancel withdrawal<br/>during fraud window
User->>L1Bridge: Claim withdrawal<br/>(after fraud window)
L1Bridge->>Treasury: Request ETH release
Treasury->>User: Transfer ETH" %}
```

### **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:

     ```solidity
     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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-canonical-bridge/withdrawal-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.