EVM Contracts Deployment

Deploy GoldClob and perps contracts to BSC and Base

Overview

The EVM contracts package provides betting infrastructure for BSC and Base networks:

• GoldClob - Central Limit Order Book for duel outcome betting
• AgentPerpEngine - Perpetual futures for agent skill ratings (ERC20 margin)
• AgentPerpEngineNative - Perpetual futures with native token margin
• SkillOracle - Oracle for agent skill updates
• MockERC20 - Test token for local development

Deployment Metadata System

All contract addresses are managed in a centralized deployment manifest:

• packages/gold-betting-demo/deployments/contracts.json - Single source of truth
• packages/gold-betting-demo/deployments/index.ts - Typed configuration with runtime validation

Benefits:

• Eliminates hardcoded addresses scattered across codebase
• Type-safe access to deployment metadata
• Automatic validation of manifest structure
• Shared across frontend, keeper, deployment scripts, and tests

Preflight Validation

Before deploying to any network, run preflight checks:

cd packages/gold-betting-demo
bun run deploy:preflight:testnet    # Validate testnet deployment
bun run deploy:preflight:mainnet    # Validate mainnet deployment

Validation checks:

• ✅ Solana program keypairs match deployment manifest
• ✅ Anchor IDL files match deployment manifest
• ✅ App and keeper IDL files are in sync
• ✅ EVM deployment environment variables are configured
• ✅ EVM RPC URLs are available (configured or using Hardhat fallbacks)
• ✅ Contract addresses are present in deployment manifest

Warnings vs Failures:

• Warnings: Missing RPC URLs (will use fallbacks), pending contract addresses
• Failures: Mismatched program IDs, missing required env vars, invalid addresses

Deploy to Testnet

Deploy GoldClob contracts to testnet networks:

cd packages/evm-contracts

# BSC Testnet
bun run deploy:bsc-testnet

# Base Sepolia
bun run deploy:base-sepolia

Environment variables:

• PRIVATE_KEY - Deployer private key (required)
• BSC_RPC_URL - BSC RPC endpoint (optional, uses Hardhat fallback if not set)
• BASE_RPC_URL - Base RPC endpoint (optional, uses Hardhat fallback if not set)
• GOLD_TOKEN_ADDRESS - GOLD token address (optional, recorded in deployment receipt)

Deployment process:

1. Validates treasury and market maker addresses (uses deployer address for testnet)
2. Deploys GoldClob contract
3. Writes deployment receipt to deployments/<network>.json
4. Updates central manifest at ../gold-betting-demo/deployments/contracts.json

Deploy to Mainnet

Deploy GoldClob contracts to mainnet networks:

cd packages/evm-contracts

# BSC Mainnet
TREASURY_ADDRESS=0x... MARKET_MAKER_ADDRESS=0x... bun run deploy:bsc

# Base Mainnet
TREASURY_ADDRESS=0x... MARKET_MAKER_ADDRESS=0x... bun run deploy:base

Environment variables required:

• PRIVATE_KEY - Deployer private key (required)
• TREASURY_ADDRESS - Treasury address for fee collection (required for mainnet)
• MARKET_MAKER_ADDRESS - Market maker address for fee collection (required for mainnet)
• GOLD_TOKEN_ADDRESS - GOLD token address (optional, recorded in deployment receipt)
• BSC_RPC_URL / BASE_RPC_URL - RPC endpoints (optional, uses Hardhat fallbacks if not set)

Mainnet safety:

• Mainnet deployments require explicit TREASURY_ADDRESS and MARKET_MAKER_ADDRESS
• Deployment fails if these are not set (prevents accidental use of deployer address)
• Validates all addresses before deployment

Skip manifest update (for testing):

SKIP_BETTING_MANIFEST_UPDATE=true bun run deploy:bsc-testnet

Deployment Receipts

Each deployment writes a detailed receipt to packages/evm-contracts/deployments/<network>.json:

{
  "network": "bsc",
  "chainId": 56,
  "deployer": "0x...",
  "goldClobAddress": "0x...",
  "treasuryAddress": "0x...",
  "marketMakerAddress": "0x...",
  "goldTokenAddress": "0x...",
  "deploymentTxHash": "0x...",
  "deployedAt": "2026-03-08T12:00:00.000Z"
}

The deploy script automatically updates the central contracts.json manifest after successful deployment.

Typed Contract Helpers

The typed-contracts.ts module provides type-safe contract deployment and interaction:

import { 
  deployGoldClob, 
  deploySkillOracle, 
  deployMockErc20,
  deployAgentPerpEngine,
  deployAgentPerpEngineNative 
} from '../typed-contracts';

// Type-safe deployment with IntelliSense
const clob = await deployGoldClob(treasuryAddress, marketMakerAddress, signer);
const oracle = await deploySkillOracle(initialBasePrice, signer);
const mockToken = await deployMockErc20("USDC", "USDC", signer);

// Fully typed contract interfaces
const match: GoldClobMatch = await clob.matches(matchId);
const position: GoldClobPosition = await clob.positions(matchId, trader);
const order: GoldClobOrder = await clob.orders(orderId);

Available contract interfaces:

• GoldClobContract - CLOB market with typed methods
• SkillOracleContract - Oracle with typed skill updates
• MockERC20Contract - Test token with typed mint/approve
• AgentPerpEngineContract - Perps engine with typed position management
• AgentPerpEngineNativeContract - Native token perps engine

Benefits:

• Compile-time type checking for all contract interactions
• IntelliSense support in tests and scripts
• Prevents common errors (wrong parameter types, missing overrides)
• Consistent deployment patterns across test suites

Local Testing

Run the full EVM contract test suite:

cd packages/evm-contracts
bun test

Test coverage:

• GoldClob basic functionality
• GoldClob exploit resistance (post-fix validation)
• GoldClob fuzz testing (randomized invariants)
• GoldClob round 2 security fixes
• AgentPerpEngine security regressions
• AgentPerpEngineNative security regressions

All tests now use typed contract helpers:

// Before
const GoldClob = await ethers.getContractFactory("GoldClob");
const clob = await GoldClob.deploy(treasury.address, marketMaker.address);

// After
const clob = await deployGoldClob(treasury.address, marketMaker.address);

Local Simulation

Run local EVM simulation with PnL reporting:

cd packages/evm-contracts
bun run simulate:localnet

Simulation scenarios:

• Whale round trip (large position open/close)
• Funding rate drift
• Isolated insurance containment
• Positive equity liquidation
• Local insurance shortfall
• Fee recycling into isolated insurance
• Model deprecation lifecycle

Output: simulations/gold-clob-localnet-report.json

Fee Structure

GoldClob fees:

• tradeTreasuryFeeBps - Fee to treasury on every trade (default: 100 BPS = 1%)
• tradeMarketMakerFeeBps - Fee to market maker on every trade (default: 100 BPS = 1%)
• winningsMarketMakerFeeBps - Fee to market maker on claim (default: 200 BPS = 2%)

Fee routing:

• Trade fees: Split between treasury and market maker
• Claim fees: Route to market maker
• Market maker fees can be recycled into liquidity

Configuration:

// During deployment
const clob = await deployGoldClob(
  treasuryAddress,
  marketMakerAddress,
  signer
);

// Fee rates are hardcoded in contract constructor:
// tradeTreasuryFeeBps = 100
// tradeMarketMakerFeeBps = 100
// winningsMarketMakerFeeBps = 200

Troubleshooting

Deployment fails with “Invalid TREASURY_ADDRESS”:

• Ensure TREASURY_ADDRESS is set for mainnet deployments
• Verify address is a valid Ethereum address (checksummed)

Deployment fails with “insufficient funds”:

• Check deployer wallet balance
• Ensure wallet has enough native tokens for gas (BNB for BSC, ETH for Base)

RPC connection errors:

• Verify RPC URL is correct and accessible
• Check RPC provider rate limits
• Try using Hardhat fallback RPC (remove custom RPC_URL env var)

Manifest update fails:

• Verify packages/gold-betting-demo/deployments/contracts.json exists
• Check file permissions (must be writable)
• Ensure network key exists in manifest (bsc, bscTestnet, base, baseSepolia)

Type errors in tests:

• Ensure typed-contracts.ts is up to date with contract ABIs
• Regenerate types if contract interfaces changed
• Check that all tests import from typed-contracts.ts

Related Documentation

• Betting Production Deploy - Full deployment guide
• Gold Betting Demo - Betting stack overview
• Configuration - Environment variables