# Application Flow

## Application Flow

Understanding the operational flows of the Syzygy Canonical Bridge is essential for developers integrating with the system. The bridge supports two primary flows: deposits (L1 to L2) and withdrawals (L2 to L1).

### Deposit Flow

The deposit flow transfers ETH from Ethereum (L1) to Eclipse (L2):

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

```
User->>L1Bridge: Deposit ETH
Note over L1Bridge: Verify minimum 2M lamports
L1Bridge->>Treasury: Store ETH
L1Bridge->>DepositRelayer: Emit deposit event
Note over DepositRelayer: Observe L1 event
DepositRelayer->>L2Bridge: Request mint with authority
Note over L2Bridge: Mint tokens to user on L2" %}
```

**Technical Deep Dive - Deposit Flow:**

1. **User Initiates Deposit**
   * The user calls the `deposit(bytes32 recipient, uint256 amountWei)` function on the CanonicalBridge contract
   * The function requires a minimum deposit amount (2M lamports) to prevent dust attacks and ensure economic viability
   * The recipient parameter is a bytes32 representation of the L2 address where tokens will be minted
   * The function is payable and expects the exact ETH amount specified in the amountWei parameter
2. **CanonicalBridge Validation**
   * The contract validates that the deposit amount meets the minimum requirement
   * It calculates the equivalent amount in lamports (the L2 native unit) using a conversion function
   * It verifies that the recipient address is valid (not empty)
   * It checks that the sent ETH matches the specified amount
   * These validations prevent common errors and potential attacks
3. **Treasury Storage**
   * The CanonicalBridge calls `depositEth()` on the Treasury contract with the deposited ETH
   * The Treasury contract stores the ETH and emits a TreasuryDeposit event
   * This separation ensures that funds are isolated from the business logic
   * The Treasury only accepts deposits from entities with the DEPOSITOR\_ROLE (typically the CanonicalBridge)
4. **Event Emission**
   * The CanonicalBridge emits a Deposited event with the following parameters:

     ```solidity
     event Deposited(
         address indexed sender,
         bytes32 indexed recipient,
         uint256 amountWei,
         uint256 amountLamports
     );
     ```
   * This event includes all necessary information for the L2 minting process
   * The event is indexed for efficient filtering by the Deposit Relayer
   * This event-based communication pattern is a common approach for cross-chain bridges
5. **Relayer Processing**
   * The Deposit Relayer observes the Deposited event using an event filter
   * It validates the event parameters to ensure they meet L2 requirements
   * It constructs a message for the L2 Bridge Program with the recipient and amount
   * It submits this message to the L2 chain
   * The relayer implements retry mechanisms to handle temporary network issues
6. **L2 Token Minting**
   * The L2 Bridge Program receives the message from the Deposit Relayer
   * It verifies that the message comes from an authorized relayer
   * It mints tokens equivalent to the deposited amount
   * The tokens are minted to the recipient address specified in the deposit
   * It emits an event on L2 to confirm the minting operation

**Implementation Considerations:**

* **Reentrancy Protection**: The deposit function is non-reentrant to prevent reentrancy attacks that could manipulate the deposit process
* **Access Control**: The Treasury uses the DEPOSITOR\_ROLE to restrict who can deposit funds, preventing unauthorized deposits
* **Reliability**: The Deposit Relayer should implement retry mechanisms for reliability in case of temporary network issues
* **Gas Optimization**: The deposit function is optimized for gas efficiency while maintaining security


---

# 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/application-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.