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 complete local development environment for AstralBeam.

Prerequisites

Required Software

Note: Relayers use file-based JSON persistence. No database is required for relayer development.

Installation

Node.js:

# Using nvm (recommended)
nvm install 18
nvm use 18

Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

Foundry:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Repository Setup

Clone and Install

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

# Install CLI dependencies
cd cli
npm install
npm run build

# Install EVM contract dependencies
cd ../contracts/eth
forge install

# Build Casper contracts
cd ../casper
cargo odra build

Protocol library candidate

The protocol/ directory contains the producer for @astralbeam-io/protocol, a private npm library of deterministic event codecs, schemas and hashes. Registry installation requires authorized npm access. It is developed independently of the API and relayer; neither application adopts it automatically. With Node 20 or 22, run from the repository root:

npm ci --prefix protocol --ignore-scripts
npm run build --prefix protocol
npm test --prefix protocol

Decoded data is not verified chain evidence. Factory attribution, finality, authorization and signing remain consumer responsibilities. See protocol/README.md for the candidate API. Publication and production adoption are separate reviewed steps.

Environment Configuration

Copy the CLI's .env.example and use the variable names documented in Operator Configuration. For local chains, deploy your own contracts and use only their addresses. For public-testnet integration, use the public-testnet RPC/network identity and the contract reference. Never point a local Casper node at public-testnet package hashes.

Private keys are needed only for signing/operator workflows. Read-only API examples do not require a key.

Local Networks

EVM: Anvil

Start a local EVM chain using Anvil:

# Basic start
anvil

# With specific chain ID
anvil --chain-id 31337

# Fork Sepolia for testing
anvil --fork-url https://sepolia.infura.io/v3/YOUR_KEY

Deploy contracts locally:

cd contracts/eth

# Deploy to local Anvil
forge script script/DeployMultiSigLocker.s.sol \
  --rpc-url http://localhost:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --broadcast

Casper: NCTL

NCTL provides a local Casper network for testing.

Install NCTL:

# Clone casper-node
git clone https://github.com/casper-network/casper-node.git
cd casper-node

# Build NCTL
make setup-rs
make build-system-contracts

# Add to PATH
export PATH=$PATH:$(pwd)/utils/nctl

Start NCTL:

# Start network with 5 validators
nctl-start

# Check status
nctl-status

# View node URLs
nctl-view-node-ports
# Node 1: http://localhost:11101/rpc

Deploy Casper contracts:

cd contracts/casper

# Deploy to NCTL
casper-client put-deploy \
  --node-address http://localhost:11101/rpc \
  --chain-name casper-net-1 \
  --secret-key ~/.nctl/assets/users/user-1/secret_key.pem \
  --payment-amount 200000000000 \
  --session-path target/wasm32-unknown-unknown/release/token_factory.wasm

Development Workflow

Project Structure

bridge/
├── cli/                    # TypeScript CLI and workers
│   ├── src/
│   │   ├── index.ts       # CLI entry point
│   │   ├── commands/      # CLI commands
│   │   ├── workers/       # Bridge workers
│   │   └── shared/        # Shared utilities
│   └── tests/
├── contracts/
│   ├── eth/               # EVM contracts (Foundry)
│   │   ├── erc20locker/
│   │   └── casperbridge/
│   └── casper/            # Casper contracts (Odra)
│       └── src/
├── api/                   # REST API server
└── monitoring/            # Grafana dashboards

Running Components

Start the CLI in development:

cd cli
npm run dev

Start a single worker:

# EVM to Casper worker
npm run start -- --worker evm2casper

# Casper to EVM worker
npm run start -- --worker casper2evm

Run API server:

cd api
npm run dev

Hot Reloading

For TypeScript development with hot reloading:

cd cli
npm run watch

In another terminal:

npm run dev

Debugging

Logging

Set log level in environment:

LOG_LEVEL=debug npm run start

Log levels: error, warn, info, debug, trace

VS Code Debug Configuration

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug CLI",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "${workspaceFolder}/cli",
      "env": {
        "LOG_LEVEL": "debug"
      }
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "cwd": "${workspaceFolder}/cli"
    }
  ]
}

Contract Debugging

EVM with Foundry:

# Run with verbose output
forge test -vvvv

# Debug specific test
forge test --match-test testLockTokens -vvvv

# Gas report
forge test --gas-report

Casper with Odra:

# Run tests with output
cargo odra test -- --nocapture

# Specific test
cargo odra test test_mint_tokens

Common Tasks

Generate TypeScript Types from ABI

cd cli

# For EVM contracts
npx typechain --target ethers-v6 \
  --out-dir src/types \
  '../contracts/eth/out/**/*.json'

Database Operations

cd cli

# Create new migration
npm run migrate:create -- add_new_table

# Run migrations
npm run migrate

# Rollback
npm run migrate:rollback

# Reset database
npm run migrate:reset

Linting and Formatting

# TypeScript
cd cli
npm run lint
npm run format

# Rust
cd contracts/casper
cargo fmt
cargo clippy

# Solidity
cd contracts/eth
forge fmt

Troubleshooting

Common Issues

"State file corrupted or missing"

# Check data directory
ls -la data/

# Clear persistence and restart fresh
rm -rf data/*.json
npm run dev

"NCTL not starting"

# Clean and restart
nctl-stop
nctl-clean
nctl-start

"Forge build fails"

# Update dependencies
forge update

# Clean and rebuild
forge clean
forge build

"Casper contract deployment fails"

# Check payment amount
# Minimum is usually 100 CSPR for deployment
--payment-amount 200000000000  # 200 CSPR

Getting Help

• GitHub Issues: make-software/astralbeam-core/issues