Local Development Setup

Configuration values prefixed YOUR_ are placeholders for your own deployment. For the public testnet use the contract reference; never mix networks or environments.

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

Prerequisites

Required Software

# 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

git clone https://github.com/make-software/astralbeam-core.git
cd astralbeam-core

Step 2: Install Dependencies

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:

# 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). BRIDGE_NETWORK selects which network-specific migration folder applies (schema/general/ always runs, plus schema/testnet/ or schema/mainnet/):

cd api
export DB_HOST=localhost DB_PORT=3306 DB_USER=bridge_user \
  DB_PASSWORD=your_password DB_NAME=bridge
BRIDGE_NETWORK=testnet npm run db:migrate

Step 4: Environment Configuration

Create .env file in the cli directory:

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

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

# Casper Testnet
CASPER_NODE_URL=https://node.testnet.casper.network
CASPER_CHAIN_NAME=casper-test
CASPER_ETH_CLIENT=YOUR_ETH_CLIENT_PACKAGE_HASH
CASPER_TOKEN_FACTORY=YOUR_TOKEN_FACTORY_PACKAGE_HASH

# 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

# 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

# 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:

Casper CSPR

Get Testnet CSPR:

CSPR.live Faucet

Required amounts:

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

Step 7: Start the Relayer

Development Mode

# Start with hot reloading
npm run dev

Production Mode

# 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:

# 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

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

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

RPC Connection Failed

# 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

Operator Configuration - Deployment settings
Monitoring - Health and alerts
Monitoring Setup - Prometheus and Grafana

Local Setup