Skip to main content

Withdrawals

Users can withdraw assets back to Ethereum by interacting with the Atlas Bridge SPL program on Atlas L2. Withdrawals involve a multi-step process to ensure the security of user funds and integrity of the Atlas state. Once a withdrawal is initiated, the user will automatically receive assets to a specified Ethereum address after the withdrawal is proven and finalized.

note

Withdrawals are currently supported for assets originating from Sepolia testnet.

Program Interface​

The withdrawal process is initiated on the Atlas L2 with the withdraw instruction in the atlas-bridge-spl program:

pub struct Withdraw {
    pub eth_to_address: [u8; 20], // Ethereum recipient address
    pub eth_token_address: [u8; 20], // Token contract address on Ethereum
    pub padding: [u8; 24], // Reserved for future use
    pub native_burn_amount: u64, // Amount of SOL to withdraw
    pub token_burn_amount: u64 // Amount of tokens to withdraw
}

Key actions performed by the withdraw instruction:

  • Burns tokens from user's Associated Token Account (ATA) if withdrawing SPL tokens
  • Transfers ETH from user to the native vault PDA if withdrawing ETH
  • Updates the EVM state account to track withdrawal counts
  • Returns the withdrawal data via set_return_data and creates a WithdrawalAccount

Withdrawal Flow​

Initiation on Atlas L2​

  1. User initiates withdrawal via the Altlas Bridge SPL program.
  2. Program processes tokens and assigns withdrawal ID in WithdrawalAccount
  3. Withdrawal data is merkleized and prepared for submission to L1

Finalization on Ethereum L1​

  1. Atlas state root and withdrawal root are committed to the L1 via the Atlas Oracle contract
  2. Withdrawals are proven against the Atlas state in the Oracle and stored in the Bridge contract
  3. Assets are released from the Bridge after finalization period ends

Withdrawal Proofs​

The withdrawal process on L1 is handled by the Oracle and Bridge contracts and involves three steps:

1. Commiting Atlas State​

The Atlas Oracle contract maintains the state of the Atlas L2 chain. A Proposer node is responsible for committing state proposals to the Oracle at a specified slot interval. Each state proposal contains a hash of the state root and withdrawal root which is used to verify withdrawals on Ethereum.

2. Proving Withdrawals​

Withdrawals are proven to the Bridge contract by supplying an Atlas state proof and a withdrawal merkle proof. The Bridge verifies these proofs against the Oracle and records the proven withdrawal with a timestamp, emitting a WithdrawalsProven event.

3. Finalizing Withdrawals​

Withdrawals are finalized after the finalization period has passed for both the proven withdrawals and the Atlas state that was used to prove them. Once final checks are passed, the Bridge releases funds to the recipient's address and emits a WithdrawalFinalized event.

Events​

The Bridge emits events for each step of the withdrawal process:

event WithdrawalsProven(
    uint64 indexed atlasStateIndex,
    bytes32 indexed atlasStateOutput,
    uint64 indexed atlasBlockNumber,
    bytes32[] withdrawalHashes
);

event WithdrawalFinalized(
    uint64 indexed withdrawalId,
    bytes32 indexed withdrawalHash,
    address indexed toAddress,
    address tokenAddress,
    uint256 ethAmount,
    uint256 tokenAmount
);

Security Considerations​

  1. Finalization Period: A mandatory waiting period (set in the Atlas Oracle) must pass between proving and finalizing a withdrawal. This allows time for fraud challenges.

  2. Merkle Proofs: Withdrawals are proven using Merkle proofs against a root hash stored in the Atlas Oracle, ensuring only valid withdrawals can be processed.

  3. State Verification: The withdrawal proof is validated against a specific Atlas state index, which must remain unchanged during finalization.

  4. Double-Spend Prevention: The contract tracks finalized withdrawals to prevent double-spending.