> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/for-developers/architecture.md).

# Architecture Overview

AstralBeam is a decentralized cross-chain bridge connecting EVM-compatible blockchains (Ethereum, Base, etc.) with Casper Network. This section provides a comprehensive overview of the system architecture.

## High-Level Architecture

The bridge consists of four main layers:

```mermaid
flowchart TB
    subgraph Users[User Layer]
        WebApp[Web Application astralbeam.io]
        CLI[Bridge CLI]
        DirectAPI[Direct API/Contract Calls]
    end

    subgraph Relayers[Relayer Network M-of-N]
        R1[Relayer 1]
        R2[Relayer 2]
        R3[Relayer N]
        P2P[P2P Network HTTPS/TLS]
        R1 <--> P2P
        R2 <--> P2P
        R3 <--> P2P
    end

    subgraph EVMContracts[EVM Contracts]
        Locker[MultiSigLocker Lock/Unlock ERC-20]
        Wrapped[Wrapped Tokens Casper-native on EVM]
    end

    subgraph CasperContracts[Casper Contracts]
        EthClient[EthClient Store EVM Block Headers]
        TokenFactory[TokenFactory Mint/Burn CEP-18]
        CEP18[CEP-18 Tokens Wrapped Tokens]
    end

    WebApp --> Locker
    WebApp --> TokenFactory
    CLI --> Locker
    CLI --> TokenFactory
    DirectAPI --> Locker
    DirectAPI --> TokenFactory

    R1 --> Locker
    R1 --> EthClient
    R1 --> TokenFactory
    R2 --> Locker
    R2 --> EthClient
    R2 --> TokenFactory
    R3 --> Locker
    R3 --> EthClient
    R3 --> TokenFactory

    TokenFactory --> EthClient
    TokenFactory --> CEP18
```

## Core Components

### 1. Smart Contracts

| Chain  | Contract       | Purpose                                                      |
| ------ | -------------- | ------------------------------------------------------------ |
| EVM    | MultiSigLocker | Lock ERC-20 tokens, unlock with M-of-N signatures            |
| EVM    | Wrapped Tokens | ERC-20 representations of Casper-native tokens               |
| Casper | EthClient      | Store EVM block headers with receipts roots for verification |
| Casper | TokenFactory   | Mint/burn CEP-18 wrapped tokens with proof verification      |

### 2. Relayer Network

A decentralized network of relayers that:

* Monitor blockchain events on all chains
* **Verify MPT proofs independently** (EVM → Casper direction)
* Exchange signatures via P2P network
* Submit cross-chain transactions with M-of-N attestation

### 3. Verification Systems

The bridge uses a **consensus-aware verification model**:

| Direction    | Verification Method        | Details                                                                                      |
| ------------ | -------------------------- | -------------------------------------------------------------------------------------------- |
| EVM → Casper | **MPT Proof Verification** | Each relayer independently verifies Merkle Patricia Trie proofs against stored block headers |
| Casper → EVM | **M-of-N Attestation**     | Relayers attest to burn events; signatures verified on-chain                                 |

**Key Security Property**: For EVM → Casper, the EthClient stores block headers with receipts roots. The TokenFactory verifies that the receipts root in attestations matches the stored block header - this is the **consensus-aware** aspect of the security model.

## Bridge Flow Summary

### EVM → Casper (Lock and Mint)

```mermaid
sequenceDiagram
    participant User
    participant EVM as EVM Chain
    participant Relayers as Relayer Network
    participant Casper as Casper Network

    User->>EVM: 1. Lock ERC-20 tokens
    EVM-->>EVM: 2. Wait for finality
    Relayers->>EVM: 3. Detect finalized lock event
    Relayers->>Relayers: 4. Verify MPT proof independently
    Relayers->>Relayers: 5. Exchange signatures (P2P)
    Relayers->>Casper: 6. Submit block header + signatures
    Relayers->>Casper: 7. Submit mint attestation
    Note over Casper: TokenFactory verifies receipts root matches stored block header
    Casper->>User: 8. Receive CEP-18 tokens
```

### Casper → EVM (Burn and Unlock)

```mermaid
sequenceDiagram
    participant User
    participant Casper as Casper Network
    participant Relayers as Relayer Network
    participant EVM as EVM Chain

    User->>Casper: 1. Burn CEP-18 tokens
    Casper-->>Casper: 2. Instant Finality
    Relayers->>Casper: 3. Detect burn event
    Relayers->>Relayers: 4. Sign attestation
    Relayers->>Relayers: 5. Exchange signatures (P2P)
    Relayers->>EVM: 6. Submit unlock + M-of-N signatures
    Note over EVM: Locker verifies 3-of-5 valid signatures
    EVM->>User: 7. Receive ERC-20 tokens
```

## Design Principles

### 1. Security First

* **M-of-N Multi-signature**: Requires threshold signatures (3-of-5) to prevent single points of failure
* **MPT Proof Verification**: Each relayer independently verifies transaction receipts against block headers
* **Consensus-Aware**: Block headers stored on Casper; TokenFactory validates receipts roots
* **Finality Protection**: Waits for finality-threshold EVM blocks before processing
* **Replay Prevention**: Nonces and chain IDs included in attestation hashes

### 2. Decentralization

* **Independent Relayers**: Each relayer operates independently and verifies proofs
* **P2P Communication**: No central coordinator for signature exchange
* **Permissionless Verification**: Anyone can verify bridge operations

### 3. Transparency

* **On-chain State**: All bridge state stored on-chain
* **Event Emission**: All operations emit verifiable events
* **Open Source**: All code publicly available

### 4. Multi-Chain Ready

* **Chain ID Awareness**: All operations include source chain identification
* **Per-Chain Contracts**: Separate lockers for each EVM chain
* **Unified Casper Entry**: Single TokenFactory handles all chains

## Technology Stack

### Smart Contracts

| Component        | Technology                            |
| ---------------- | ------------------------------------- |
| EVM Contracts    | Solidity 0.8.x, OpenZeppelin          |
| Casper Contracts | Rust, Odra Framework                  |
| Deployment       | Foundry (EVM), casper-client (Casper) |

### Relayer Infrastructure

| Component         | Technology                   |
| ----------------- | ---------------------------- |
| Runtime           | Node.js 20+, TypeScript      |
| P2P Network       | HTTP/HTTPS with TLS          |
| Cryptography      | ethers.js, casper-js-sdk     |
| State Persistence | File-based JSON              |
| Process Manager   | systemd (via Docker Compose) |

### Monitoring & Operations

| Component  | Technology              |
| ---------- | ----------------------- |
| Metrics    | Prometheus              |
| Dashboards | Grafana                 |
| Logging    | Structured JSON logs    |
| Alerts     | Prometheus Alertmanager |

## Network Architecture

```mermaid
flowchart LR
    subgraph Internet
        Users[Users]
        API[Bridge API]
    end

    subgraph AWS[AWS Infrastructure]
        subgraph RelayerNodes[Relayer Nodes]
            R1[Relayer 1]
            R2[Relayer 2]
            R3[Relayer 3]
            R4[Relayer 4]
            R5[Relayer 5]
        end
        DB[MySQL/Aurora]
        Grafana[Grafana]
        Prometheus[Prometheus]
    end

    subgraph Blockchains
        Sepolia[Ethereum Sepolia]
        Base[Base Sepolia]
        Polygon[Polygon Amoy]
        Casper[Casper Testnet]
    end

    Users --> API
    Users --> Blockchains
    API --> DB

    Sepolia --> R1
    Base --> R1
    Polygon --> R1
    Casper --> R1

    RelayerNodes --> Prometheus
    Prometheus --> Grafana
```

## Further Reading

* [System Components](/for-developers/system-components.md) - Detailed component descriptions
* [Bridge Flows](/for-developers/bridge-flows.md) - Complete flow documentation
* [Multi-Chain Support](/for-developers/multi-chain.md) - Multi-chain architecture
* [Security Model](/security/security.md) - Security architecture


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/for-developers/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.