Setup & Installation

This guide will help you download, build, and run The Beaconator REST API service.

Install Rust

If you don't have Rust installed:

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

Install the nightly toolchain:

rustup toolchain install nightly
rustup default nightly

Verify installation:

rustc --version
cargo --version

Download The Beaconator

Clone the repository:

git clone https://github.com/StrobeLabs/the-beaconator
cd the-beaconator

Configure Environment

Copy the example environment file:

cp env.example .env

Edit .env with your settings. See the Environment Variables section below for the full reference.

Minimum required variables:

# RPC endpoint
RPC_URL=https://mainnet.base.org

# Funding wallet private key (without 0x prefix)
# Used for guest wallet funding and ECDSA signing
PRIVATE_KEY=your_private_key_here

# Wallet pool private keys (comma-separated, without 0x prefix)
# These wallets are used for sending transactions
WALLET_PRIVATE_KEYS=key1,key2,key3

# Environment type
ENV=mainnet  # or testnet/localnet

# API authentication
BEACONATOR_ACCESS_TOKEN=your_secret_token

# Redis URL for wallet pool coordination
REDIS_URL=redis://127.0.0.1:6379

# Contract addresses (Base mainnet)
BEACON_FACTORY_ADDRESS=0x...
PERPCITY_REGISTRY_ADDRESS=0x...
PERP_MANAGER_ADDRESS=0x...
USDC_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
MULTICALL3_ADDRESS=0xcA11bde05977b3631167028862bE2a173976CA11

# Perp module addresses
FEES_MODULE_ADDRESS=0x...
MARGIN_RATIOS_MODULE_ADDRESS=0x...
LOCKUP_PERIOD_MODULE_ADDRESS=0x...
SQRT_PRICE_IMPACT_LIMIT_MODULE_ADDRESS=0x...

Build The Project

Build in development mode:

make build

For optimized production build:

make build-release

Build times:

• First build: 5-10 minutes (downloads dependencies)
• Subsequent builds: 1-2 minutes (with caching)

Run The Server

Start the development server:

make dev

The server will start on http://localhost:8000

You should see output like:

🚀 Rocket has launched from http://0.0.0.0:8000

Verify Installation

Test the API is running:

curl http://localhost:8000/

You should see the welcome page with API documentation.

Run Tests

Run unit tests:

make test-unit

Run integration tests (requires Anvil):

# Install Foundry first
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Run integration tests
make test-integration

Run all tests:

make test

Available Make Commands

View all available commands:

make help

Common commands:

• make build - Build in development mode
• make build-release - Build optimized release
• make dev - Run development server
• make test - Run all tests
• make test-unit - Run unit tests only
• make test-integration - Run integration tests
• make quality - Run quality checks
• make lint - Run linter

Docker Deployment

Build Docker image:

docker build -t beaconator .

Run with Docker:

docker run -p 8000:8000 --env-file .env beaconator

The Dockerfile is optimized for Railway deployment with:

• Cargo build caching
• Dependency caching
• Optimized build times

Troubleshooting

Build Errors

If you encounter build errors:

1. Update Rust: rustup update nightly
2. Clean build: cargo clean && make build
3. Check Rust version: Ensure you're on nightly

Anvil Issues (Integration Tests)

If integration tests fail:

# Kill any existing Anvil instances
pkill -9 anvil

# Run cleanup script
./scripts/cleanup_anvil.sh

# Try tests again
make test-integration

RPC Connection Errors

If you see RPC errors:

1. Check RPC_URL: Ensure it's a valid Base RPC endpoint
2. Test connection: curl $RPC_URL -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
3. Try alternative RPC: Use Alchemy, Infura, or QuickNode

Port Already in Use

If port 8000 is already in use:

# Find and kill process on port 8000
lsof -ti:8000 | xargs kill -9

# Or change port in Rocket.toml

Environment Variables

Complete reference for all configuration options.

Required Variables

Optional Variables

Next Steps

• Create your first beacon
• Update beacon data