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):

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:

     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