Testnet Deployment

Deploy the full Cortex stack (contracts + offchain services) to a public testnet.

Live Contract Addresses

Recommended testnet: Base Sepolia — an OP Stack L2 with fast blocks (~2s), free faucets, and a good block explorer.

Prerequisites

• Foundry — forge, cast
• Node.js >= 18
• PostgreSQL client tools — psql
• Three wallets — deployer, solver, agent (each needs testnet ETH)

1. Get Testnet ETH

Fund your deployer wallet with Base Sepolia ETH from any of these faucets:

• Alchemy Faucet — requires free Alchemy account
• Coinbase Developer Platform — requires Coinbase account
• thirdweb Faucet — no account required

2. Configure Environment

cp ops/.env.testnet.example ops/.env.testnet

Edit ops/.env.testnet with your values:

RPC_URL=https://sepolia.base.org
DATABASE_URL=postgres://user:pass@host:5432/cortex
DEPLOYER_KEY=0x<your-deployer-private-key>
SOLVER_PRIVATE_KEY=0x<your-solver-private-key>
AGENT_PRIVATE_KEY=0x<your-agent-private-key>

Never commit private keys. The .env.testnet file is gitignored.

3. Deploy Contracts

source ops/.env.testnet
./ops/deploy-testnet.sh

Deploys AgentRegistry, IntentBook, PolicyModule, AttestationRegistry, SolverRegistry, AttestorRegistry, and CommerceRegistry to Base Sepolia. Contract addresses are written to ops/.env.testnet.

4. Set Up Postgres

You need a Postgres instance accessible from wherever you run the services.

• Railway — simplest option, supports Node.js + Postgres in one platform
• Neon — serverless Postgres with a free tier
• Supabase — managed Postgres with a generous free tier

Copy the connection string and update DATABASE_URL in ops/.env.testnet.

5. Start Services Locally

source ops/.env.testnet
ENV_FILE=ops/.env.testnet ./ops/start-services.sh

Builds services, runs idempotent migrations, and starts the indexer, solver, and API.

6. Manual Service Commands

Source the testnet env and start each service:

source ops/.env.testnet

# Indexer — polls Base Sepolia for events, writes to Postgres
cd indexer && npm run build && node dist/src/index.js

# Solver — watches IntentSubmitted, simulates, fills
cd solver && npm run build && node dist/src/index.js

# API — REST server on port 3001
cd api && npm run build && node dist/src/index.js

Or as background processes:

source ops/.env.testnet

cd indexer && npm run build && nohup node dist/src/index.js > ../ops/indexer.log 2>&1 &
cd ../solver && npm run build && nohup node dist/src/index.js > ../ops/solver.log 2>&1 &
cd ../api && npm run build && nohup node dist/src/index.js > ../ops/api.log 2>&1 &

7. Verify

Check the block explorer

Visit https://sepolia.basescan.org/address/<AGENT_REGISTRY_ADDRESS> to confirm the contract is deployed.

Hit the API

# Health check
curl http://localhost:3001/health
curl http://localhost:3001/analytics/commerce

# List agents
curl http://localhost:3001/agents?owner=0x0000000000000000000000000000000000000000

# List open intents
curl http://localhost:3001/intents?status=open

Hosted API checks:

curl https://api.cortex.wallyweb.com/health
curl https://api.cortex.wallyweb.com/analytics/commerce

Start the dashboard

cd web
NEXT_PUBLIC_API_URL=http://localhost:3001 npm run dev

Open http://localhost:3000/dashboard. Protocol fees should show 0until a future fee switch is intentionally added.

Hosted dashboard: https://cortex.wallyweb.com/dashboard.

8. AWS Deployment

The production-shaped testnet deployment uses S3 + CloudFront for the frontend, ECS Fargate for the API and indexer, RDS Postgres, Route53 DNS, ACM certificates, and ECR repositories for images.

ENV_FILE=ops/.env.testnet ./ops/write-aws-tfvars-from-testnet-env.sh

cd infra/aws
terraform init
terraform apply

cd ../..
AWS_PROFILE=wallyweb AWS_REGION=us-east-1 ./ops/deploy-aws-images.sh
AWS_PROFILE=wallyweb AWS_REGION=us-east-1 NEXT_PUBLIC_API_URL=https://api.cortex.wallyweb.com ./ops/deploy-aws-web.sh

If your Terraform binary architecture does not match provider plugins, set TERRAFORM_BINwhen running the deployment scripts.

Register a test agent

source ops/.env.testnet

cast send "$AGENT_REGISTRY_ADDRESS" \
  "registerAgent(string,bytes,bytes32)" \
  "ipfs://test-agent" \
  "0xaabb" \
  "0x0000000000000000000000000000000000000000000000000000000000000001" \
  --rpc-url "$RPC_URL" \
  --private-key "$AGENT_PRIVATE_KEY"

Wait a few seconds for the indexer, then query curl http://localhost:3001/agents/1.

Alternative: OP Sepolia

The same steps apply to OP Sepolia. Change:

RPC_URL=https://sepolia.optimism.io

The deploy script auto-detects the chain ID. Use the OP Sepolia explorer at sepolia-optimistic.etherscan.io.

Troubleshooting

• Deploy fails with “insufficient funds”: Get more testnet ETH from a faucet. Deployment costs ~0.01 ETH.
• Indexer not picking up events: Check that RPC_URL and contract addresses match. The indexer may take 5-10 seconds.
• Solver not filling intents: Verify SOLVER_PRIVATE_KEY has testnet ETH. Check ops/solver.log.
• Database connection refused: Ensure Postgres is accessible and DATABASE_URL is correct. Test with psql "$DATABASE_URL" -c "SELECT 1".