System Components

This page provides detailed documentation of each component in the AstralBeam architecture.

EVM Smart Contracts

MultiSigLocker

The MultiSigLocker contract manages token locking and unlocking on EVM chains.

flowchart TB
    subgraph MultiSigLocker
        Lock[locktoken, amount, recipient]
        Unlock[unlockattestation, signatures]
        Admin[Admin Functions]

        subgraph State
            Lockers[Per-Token Lockers]
            Relayers[Registered Relayers]
            Threshold[M-of-N Threshold]
            ProcessedNonces[Processed Nonces]
        end
    end

    User[User] --> Lock
    Relayer[Relayers] --> Unlock
    Owner[Owner] --> Admin

    Lock --> Lockers
    Unlock --> ProcessedNonces
    Admin --> Relayers
    Admin --> Threshold

Key Functions:

Events: exposure-control lockers emit TransferCommitted and send the transfer as an ERC-7786 message (see EVM Locker). Deployed V17 lockers emit:

event Locked(
    address indexed token,
    address indexed sender,
    uint256 amount,
    uint8 casperRecipientType,
    bytes32 indexed casperRecipient,
    uint256 nonce,
    uint256 chainId
);

event Unlocked(
    address indexed token,
    address indexed recipient,
    uint256 amount,
    bytes32 indexed casperStateRoot,
    bytes32 eventKey
);

Wrapped Tokens

For Casper-native tokens bridged to EVM chains, wrapped ERC-20 tokens are deployed:

Key Properties:

• Deployed by MultiSigLocker when first bridging a Casper-native token
• Standard ERC-20 interface with mint/burn controlled by the locker
• Token metadata (name, symbol, decimals) mirrors the Casper CEP-18 token

Casper Smart Contracts

EthClient

Stores EVM block headers and verifies MPT (Merkle Patricia Trie) proofs.

flowchart TB
    subgraph EthClient
        Submit["submit_block_header_with_signatures()"]
        Verify["verify_receipt_proof()"]
        Query[Query Functions/Read-Only]

        subgraph Storage[Per-Chain Storage]
            Headers["Block Headers chain_id, block_number → Header"]
            Latest[Latest Block per chain]
        end
    end

    Relayers[Relayers] --> Submit
    TokenFactory[TokenFactory] --> Verify
    Anyone[Anyone] --> Query

    Submit --> Headers
    Submit --> Latest
    Verify --> Headers

Key Functions:

Storage:

The EthClient stores block headers keyed by chain ID and block number, tracks the latest stored block per chain, and maintains the authorized relayer set with its signature threshold.

TokenFactory

Manages CEP-18 token deployment, minting, and burning.

flowchart TB
    subgraph TokenFactory
        Mint["mint_with_signatures()"]
        Burn["burn()"]
        LockNative["lock_native()"]
        UnlockNative["unlock_native_with_signatures()"]
        Deploy["deploy_token()"]

        subgraph TokenRegistry
            Mappings[EVM Token → CEP-18 Mapping]
            Deployed[Deployed CEP-18 Contracts]
        end
    end

    Relayers[Relayers] --> Mint
    Relayers --> UnlockNative
    User[User] --> Burn
    User --> LockNative
    Admin[Admin] --> Deploy

    Mint --> TokenRegistry
    Burn --> TokenRegistry

Key Functions:

Events/Deploys:

// Lock event (for Casper → EVM)
BurnEvent {
    cep18_token: ContractHash,
    evm_token: Address,
    sender: AccountHash,
    evm_recipient: Address,
    amount: U256,
    nonce: u64,
    source_chain_id: u64,
}

// Mint event (EVM → Casper)
MintEvent {
    cep18_token: ContractHash,
    recipient: AccountHash,
    amount: U256,
    source_chain_id: u64,
    evm_tx_hash: H256,
}

Relayer Infrastructure

Relayer Node

Each relayer node runs multiple workers and services:

flowchart TB
    subgraph RelayerNode[Relayer Node]
        subgraph Workers
            EVM2Casper[EVM→Casper Worker]
            Casper2EVM[Casper→EVM Worker]
        end

        subgraph Services
            P2PService[P2P Service HTTP/HTTPS]
            MetricsService[Metrics Service]
        end

        subgraph Storage
            JSONFiles[JSON Files data/]
            StateCache[State Cache]
        end
    end

    EVM2Casper <--> P2PService
    Casper2EVM <--> P2PService
    EVM2Casper --> JSONFiles
    Casper2EVM --> JSONFiles
    MetricsService --> Prometheus[Prometheus]

EVM → Casper Worker

Handles the EVM to Casper bridge direction:

Responsibilities:

1. Monitor EVM chains for Locked events
2. Wait for finality (64 blocks on Ethereum)
3. Generate MPT proofs for receipts
4. Create and sign block header attestations
5. Exchange signatures via P2P
6. Submit block headers to EthClient
7. Submit mint attestations to TokenFactory

State Machine:

stateDiagram-v2
    [*] --> Monitoring: Start
    Monitoring --> EventDetected: Lock event found
    EventDetected --> WaitingFinality: Record pending
    WaitingFinality --> ProofGeneration: Finality reached
    ProofGeneration --> SignatureCollection: Proof generated
    SignatureCollection --> Submission: M signatures collected
    Submission --> Monitoring: Success
    Submission --> SignatureCollection: Retry on failure

Casper → EVM Worker

Handles the Casper to EVM bridge direction:

Responsibilities:

1. Monitor Casper for Burn events
2. Generate state proofs
3. Create and sign unlock attestations
4. Exchange signatures via P2P
5. Submit unlock transactions to MultiSigLocker

State Machine:

stateDiagram-v2
    [*] --> Monitoring: Start
    Monitoring --> EventDetected: Burn event found
    EventDetected --> ProofGeneration: Instant finality
    ProofGeneration --> SignatureCollection: Proof generated
    SignatureCollection --> Submission: M signatures collected
    Submission --> Monitoring: Success
    Submission --> SignatureCollection: Retry on failure

P2P Network

Relayers communicate via an HTTP/HTTPS-based P2P network with TLS encryption:

flowchart TB
    subgraph P2PNetwork[P2P Network HTTP/HTTPS + TLS]
        subgraph Endpoints
            Signatures[Signature Exchange]
            Status[Status & Health]
            Sync[State Synchronization]
            Auth[Authentication]
        end

        R1[Relayer 1] <--> Signatures
        R2[Relayer 2] <--> Signatures
        R3[Relayer 3] <--> Signatures

        R1 <--> Status
        R2 <--> Status
        R3 <--> Status
    end

Architecture:

• Express-based HTTP/HTTPS server on each relayer
• TLS encryption for secure communication
• Mutual authentication via auth challenges
• Direct peer-to-peer messaging (no pubsub topics)

Announcement discovery: Each direction maintains its own peer view and needs confirmation from two distinct authorized identities before admitting an announced endpoint. An origin announcement plus an unchanged signed copy from another mTLS-authenticated relayer can satisfy this requirement for both workers. Repeated copies from the same source do not add trust. Without mTLS, only the signed origin identity is available, so forwarding alone cannot supply a second identity.

Replay protection rejects repeat deliveries from the same hop to the same receiving server. Other message types retain process-wide replay protection. Gossip suppression is shared across workers, independently of their confirmation sets. Endpoint/DNS validation and on-chain authorization still run before recording evidence.

Message Types:

Attestation Types:

API Server

The API server provides REST endpoints for the frontend and integrators:

flowchart LR
    subgraph APIServer[API Server]
        Routes[Routes]
        Swagger[Swagger UI]

        subgraph Endpoints
            Tokens["/api/v1/tokens"]
            Transactions["/api/v1/transactions"]
            Stats["/api/v1/stats"]
            Chains["/api/v1/chains"]
            Health["/api/v1/stats/health"]
        end
    end

    Client[Client] --> Routes
    Routes --> Endpoints
    Routes --> Swagger
    Endpoints --> DB[MySQL/Aurora]

Endpoints:

Monitoring Stack

Prometheus Metrics

Key metrics exposed by relayers:

Grafana Dashboards

Pre-configured dashboards for:

• Bridge Overview (transactions, volume, success rate)
• Per-Chain Metrics (blocks, events, latency)
• Relayer Health (P2P connectivity, signatures)
• Security Alerts (invalid attestations, replay attempts)

Component Dependencies

flowchart TD
    subgraph External
        EVM[EVM RPC Nodes]
        Casper[Casper RPC Nodes]
    end

    subgraph Infrastructure
        DB[MySQL/Aurora]
        Prometheus[Prometheus]
        Grafana[Grafana]
    end

    subgraph Application
        Relayers[Relayer Nodes]
        API[API Server]
        Web[Web Frontend]
    end

    Relayers --> EVM
    Relayers --> Casper
    Relayers --> Prometheus
    API --> DB
    Web --> API
    Prometheus --> Grafana