> 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/operators/local-setup.md).

# Local Setup

This guide walks through setting up a local bridge development environment.

## Prerequisites

### Required Software

```bash
# Node.js 20+
node --version  # v20.x.x

# npm 10+
npm --version  # 10.x.x

# Git
git --version

# MySQL 8.0+ (only if running the API server)
mysql --version  # 8.0.x+
```

> **Note**: Relayers use file-based JSON persistence and do not require a database. MySQL is only needed if you're running the API server for transaction indexing.

### RPC Endpoints

You'll need RPC access for:

| Chain            | Required | Example Provider    |
| ---------------- | -------- | ------------------- |
| Ethereum Sepolia | Yes      | Infura, Alchemy     |
| Base Sepolia     | Optional | Alchemy, Public RPC |
| Casper Testnet   | Yes      | Public node         |

## Step 1: Clone Repository

```bash
git clone https://github.com/make-software/cspr-bridge.git
cd bridge
```

## Step 2: Install Dependencies

```bash
cd cli
npm install
```

## Step 3: State Persistence

### Relayer Persistence (Automatic)

Relayers automatically store state in JSON files in the `data/` directory:

```
data/
├── evm2casper-addr-XXXXXXXX.json   # EVM→Casper worker state
└── casper2evm-addr-XXXXXXXX.json   # Casper→EVM worker state
```

No database setup is required for relayer operation.

### API Database (Optional)

If running the API server for transaction indexing, set up MySQL:

```bash
# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE bridge;

# Create user (optional)
CREATE USER 'bridge_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON bridge.* TO 'bridge_user'@'localhost';
FLUSH PRIVILEGES;
```

Run migrations (from the `api/` directory):

```bash
cd api
export DATABASE_URL="mysql://bridge_user:your_password@localhost:3306/bridge"
npm run migrate
```

## Step 4: Environment Configuration

Create `.env` file in the `cli` directory:

```bash
# Sepolia (Primary)
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
SEPOLIA_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com
SEPOLIA_LOCKER=0x6aaea12cF566C9fddbC7082c15d38F1447a57D10

# Base Sepolia (optional)
BASE_SEPOLIA_RPC_URL=https://base-sepolia.infura.io/v3/YOUR_KEY
BASE_SEPOLIA_LOCKER=0x5208f75aEa0c2AeC5f71494B5f1B7DCF07cC6000

# Casper Testnet
CASPER_NODE_URL=https://node.testnet.casper.network
CASPER_CHAIN_NAME=casper-test
CASPER_ETH_CLIENT=hash-fa183fe46e92b65da88265deb0d48c7ae44bf44d7917f19875f4457321497aa2
CASPER_TOKEN_FACTORY=hash-bf16ba78a7ecfb0e64756aa8468251110f29639f38ccaf9bdb01b6f38a15c2f2

# Relayer Keys
RELAYER_PRIVATE_KEY=0x...  # Your test Ethereum private key
CASPER_SECRET_KEY=path/to/secret_key.pem

# P2P Configuration (local mode)
P2P_ENABLED=false  # Disable for single-relayer testing

# Logging
LOG_LEVEL=debug
```

## Step 5: Generate Test Keys

### Ethereum Relayer Key

```bash
# Generate new key
node -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"

# Or use an existing testnet key
# NEVER use mainnet keys for testing!
```

### Casper Relayer Key

```bash
# Generate ED25519 key
casper-client keygen /path/to/keys

# Or use existing testnet key
# Keys are stored as secret_key.pem
```

## Step 6: Fund Test Accounts

### Sepolia ETH

Get Sepolia ETH for gas:

1. [Alchemy Faucet](https://www.alchemy.com/faucets/ethereum-sepolia)
2. [Infura Faucet](https://www.infura.io/faucet/sepolia)

### Casper CSPR

Get Testnet CSPR:

1. [CSPR.live Faucet](https://testnet.cspr.live/tools/faucet)

Required amounts:

* ETH: \~0.1 ETH for relayer operations
* CSPR: \~1000 CSPR for mint/submit operations

## Step 7: Start the Relayer

### Development Mode

```bash
# Start with hot reloading
npm run dev
```

### Production Mode

```bash
# Build
npm run build

# Start
npm start
```

### Verify Startup

Check logs for successful startup:

```
[2024-01-15 12:00:00] INFO: Loaded persistence state
[2024-01-15 12:00:01] INFO: EVM→Casper worker started
[2024-01-15 12:00:01] INFO: Casper→EVM worker started
[2024-01-15 12:00:02] INFO: Listening for events on Sepolia (11155111)
[2024-01-15 12:00:02] INFO: Listening for events on Casper Testnet
```

## Step 8: Test the Bridge

### Lock Tokens (EVM → Casper)

Using the CLI:

```bash
# Check token balance
bridge-cli evm balance USDC --network sepolia

# Lock tokens
bridge-cli evm lock USDC 10 01abc...def --network sepolia
```

### Verify Processing

Watch logs for:

```
[INFO] Lock event detected: tx=0xabc... amount=10 USDC
[INFO] Waiting for finality: block 1000000, current 999940
[INFO] Finality reached, generating proof
[INFO] Submitting block header to Casper
[INFO] Submitting mint attestation
[INFO] Mint successful: deploy=abc123...
```

## Troubleshooting

### Persistence Issues

```bash
# Check data directory exists and is writable
ls -la data/

# View persistence files
cat data/evm2casper-*.json | jq .
```

### RPC Connection Failed

```bash
# Test Sepolia RPC
curl -X POST $SEPOLIA_RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Test Casper RPC
curl "$CASPER_NODE_URL/rpc" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"info_get_status","params":[],"id":1}'
```

## Next Steps

* [Docker Deployment](https://github.com/make-software/cspr-bridge/tree/master/gitbook/operator-guide/docker-deployment.md) - Multi-container setup
* [AWS Deployment](https://github.com/make-software/cspr-bridge/tree/master/gitbook/operator-guide/aws-deployment.md) - Production deployment
* [Monitoring Setup](/operators/monitoring.md) - Prometheus and Grafana


---

# 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/operators/local-setup.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.