> 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/smart-contracts/contracts.md).

# Contract Overview

This section documents the smart contracts that power AstralBeam on both EVM chains and Casper Network.

## Contract Overview

```mermaid
flowchart TB
    subgraph EVM[EVM Chains Solidity]
        Locker[MultiSigERC20Locker Lock/Unlock ERC-20]
        Wrapped[WrappedToken wCSPR, etc.]
    end

    subgraph Casper[Casper Network Rust]
        EthClient[EthClient Store EVM Block Headers]
        TokenFactory[TokenFactory Mint/Burn CEP-18]
        CEP18[CEP-18 Tokens Wrapped ERC-20]
    end

    Locker <--> TokenFactory
    Locker --> Wrapped
    TokenFactory --> CEP18
    EthClient --> TokenFactory
```

## EVM Contracts

### [MultiSigERC20Locker](/smart-contracts/evm-locker.md)

The primary bridge contract on EVM chains. Handles:

* Locking ERC-20 tokens for bridging to Casper
* Unlocking ERC-20 tokens based on M-of-N signatures
* Managing wrapped Casper-native tokens (e.g. wCSPR and sCSPR)
* Fee collection for bridge operations

**Key Functions:**

| Function        | Description                      |
| --------------- | -------------------------------- |
| `lock()`        | Lock ERC-20 tokens for bridging  |
| `unlock()`      | Unlock tokens with signatures    |
| `mintWrapped()` | Mint wrapped Casper tokens       |
| `burnWrapped()` | Burn wrapped to unlock on Casper |

***

## Casper Contracts

### [EthClient](/smart-contracts/casper-eth-client.md)

EVM block header storage on Casper. Provides:

* Per-chain block header storage
* MPT proof verification
* M-of-N signature verification for submissions

**Key Functions:**

| Function                                | Description                                |
| --------------------------------------- | ------------------------------------------ |
| `submit_block_header_with_signatures()` | Submit block header with M-of-N signatures |
| `get_receipts_root()`                   | Get stored receipts root for a block       |
| `is_block_known()`                      | Check if block header exists               |
| `get_latest_block()`                    | Get latest block number for chain          |

***

### [TokenFactory](/smart-contracts/casper-token-factory.md)

CEP-18 token management on Casper. Handles:

* Minting wrapped tokens from EVM locks
* Burning tokens for unlock on EVM
* Native CSPR bridging support
* Per-chain token mappings

**Key Functions:**

| Function                          | Description                                 |
| --------------------------------- | ------------------------------------------- |
| `mint_with_signatures()`          | Mint tokens with attestation and signatures |
| `burn()`                          | Burn tokens to unlock on EVM                |
| `lock_native()`                   | Lock native CSPR for bridging               |
| `unlock_native_with_signatures()` | Unlock native CSPR                          |

***

## Deployed Addresses

### Testnet

**EVM Chains:**

| Contract            | Chain                   | Address                                                                                   |
| ------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| MultiSigERC20Locker | Ethereum Sepolia        | `0x6aaea12cF566C9fddbC7082c15d38F1447a57D10`                                              |
| MultiSigERC20Locker | Base Sepolia            | `0x5208f75aEa0c2AeC5f71494B5f1B7DCF07cC6000`                                              |
| MultiSigERC20Locker | Polygon Amoy            | `0x5208f75aEa0c2AeC5f71494B5f1B7DCF07cC6000`                                              |
| MultiSigERC20Locker | Arbitrum Sepolia        | Staged — disabled by default                                                              |
| MultiSigERC20Locker | BSC Testnet             | Staged — disabled by default                                                              |
| MultiSigERC20Locker | Robinhood Chain         | **Not deployed; disabled pending separate mainnet approval**                              |
| MultiSigERC20Locker | Robinhood Chain Testnet | `0xaF0856690910F75DFA48e5F7CA4Af669be6c338d` (V16, verified 3-of-5; round trip certified) |

Base Sepolia and Polygon Amoy share a proxy address (deterministic CREATE2 deployment); domain separation binds each signature to its chain ID.

Robinhood mainnet intentionally has no placeholder address. The testnet address above was read back on chain after CREATE2 deployment; deterministic tooling alone is never treated as deployment evidence.

**Casper Testnet:**

| Contract     | Hash                                                                    |
| ------------ | ----------------------------------------------------------------------- |
| EthClient    | `hash-fa183fe46e92b65da88265deb0d48c7ae44bf44d7917f19875f4457321497aa2` |
| TokenFactory | `hash-bf16ba78a7ecfb0e64756aa8468251110f29639f38ccaf9bdb01b6f38a15c2f2` |

***

## Contract Interaction Patterns

### Lock and Mint (EVM → Casper)

```typescript
// 1. User approves tokens
await erc20.approve(lockerAddress, amount);

// 2. User locks tokens
const tx = await locker.lock(
    tokenAddress,
    amount,
    casperRecipientBytes32,
    { value: bridgeFee }
);

// 3. Relayers detect Locked event
// 4. Relayers submit to TokenFactory on Casper
// 5. User receives CEP-18 tokens
```

### Burn and Unlock (Casper → EVM)

```rust
// 1. User burns CEP-18 tokens on Casper
let tx = token_factory.burn(
    cep18_token,
    amount,
    evm_recipient,
    destination_chain_id
);

// 2. Relayers detect BurnEvent
// 3. Relayers submit unlock to EVM
// 4. User receives ERC-20 tokens
```

***

## Security Features

All contracts implement:

| Feature           | Description                         |
| ----------------- | ----------------------------------- |
| M-of-N Multi-sig  | Threshold signatures for operations |
| Pause Mechanism   | Emergency stop capability           |
| Replay Protection | Nonces prevent double-processing    |
| Access Control    | Admin-only sensitive functions      |
| Event Emission    | Full audit trail on-chain           |

***

## Upgradeability

| Contract            | Upgradeable | Proxy Type                 |
| ------------------- | ----------- | -------------------------- |
| MultiSigERC20Locker | Yes         | UUPS                       |
| EthClient           | Yes         | Casper Upgradable Contract |
| TokenFactory        | Yes         | Casper Upgradable Contract |

***

## Development Resources

### Source Code

* EVM Contracts: `/contracts/eth/`
* Casper Contracts: `/contracts/casper/`

### Build & Test

**EVM (Foundry):**

```bash
cd contracts/eth
forge build
forge test
```

**Casper (Odra):**

```bash
cd contracts/casper
cargo odra build
cargo odra test
```

### ABI Files

EVM contract ABIs are available at:

* `/contracts/eth/out/MultiSigERC20Locker.sol/`


---

# 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/smart-contracts/contracts.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.