Boundless Localnet

Guide the user through starting and using the docker compose-based localnet.

Prerequisites

Before starting, ensure:

• Docker is running
• Contracts and guest binaries are built: forge build && cargo check
• Guest ELF binaries exist at target/riscv-guest/ (built by cargo check)

Choose Mode

Ask the user which mode they want (default to dev mode):

Dev Mode (default, fast — fake proofs)

Uses RISC0_DEV_MODE=1. Proofs are faked so everything is instant. The broker runs as part of the docker compose cluster — no separate terminal needed. Best for testing request flow, contract interactions, and integration.

Full Proving Mode (real proofs, requires GPU or Bento cluster)

Uses RISC0_DEV_MODE=false. The broker is NOT included in the localnet cluster. Start it separately with just prover (Bento + broker). Requires a proving backend (local GPU or Bento cluster).

Starting Localnet

Dev Mode

Run just localnet in the foreground (not as a background task). It handles deploying contracts and starting all services — wait for it to complete before submitting requests. This avoids needing to poll container status while the deployer runs.

Explicitly set RISC0_DEV_MODE on the just localnet command to avoid inheriting a stale value from the terminal environment. Other commands don't need it — source .env.localnet sets it.

# Start the full localnet (anvil + postgres + minio + order-stream + broker)
# Run in foreground — wait for it to finish before proceeding
RISC0_DEV_MODE=1 just localnet

Submitting a test request

Submit in a background task, then monitor status through order-stream, on-chain, and broker logs while it waits for fulfillment.

For immediate broker acceptance, the offer's min-price must exceed the broker's minimum profitable price (gas costs + min_mcycle_price). On anvil, gas costs are ~0.00003 ETH, so 0.0001 ETH is safely above the threshold. The price starts at min-price before rampUpStart (defaults to now() + 30s), so setting min-price high enough means the broker accepts before the ramp even begins.

source .env.localnet && cargo run --example submit_echo -- \
  --bidding-start "$(date +%s)" \
  --min-price "0.0001 ETH" \
  --max-price "0.0004 ETH"

Why these values:

• --bidding-start "$(date +%s)": Sets rampUpStart to now. Without this, the default is now() + 30s (DEFAULT_BASE_RAMP_UP_DELAY), which delays when the auction begins.
• --min-price "0.0001 ETH": Above broker's minimum profitable price (~0.00003 ETH gas on anvil). If min-price is too low, the broker schedules a delayed lock attempt and waits for the auction price to ramp up past its threshold.
• --max-price "0.0004 ETH": ~4x min-price, reasonable ceiling

Full Proving Mode

Explicitly set RISC0_DEV_MODE=false on the just localnet command to avoid inheriting a stale value from the terminal environment. Other commands don't need it — source .env.localnet sets it.

# Terminal 1: Start the localnet (anvil + postgres + minio + order-stream, NO broker)
RISC0_DEV_MODE=false just localnet

# Terminal 2: Start the prover cluster (Bento + broker)
source .env.localnet && just prover

# Terminal 3: Submit a test request
source .env.localnet && cargo run --example submit_echo -- \
  --bidding-start "$(date +%s)" \
  --min-price "0.0001 ETH" \
  --max-price "0.0004 ETH"

Checking Order Status

After submitting a request, you'll see a request ID like:

Submitted request: 90f79bf6eb2c4f870365e785982e1f101e93b9061d289271

Query the order-stream

Note: the limit query parameter is required.

# List recent orders
curl -s "http://localhost:8585/api/v1/orders?limit=10" | jq .

# Query a specific order by request ID
curl -s "http://localhost:8585/api/v1/orders?request_id=<REQUEST_ID>&limit=10" | jq .

Check request status from broker logs

Use broker logs to extract the requestor-relevant milestones. The user cares about when the request was submitted, locked, and fulfilled, plus the fulfilled price — not the internal proving pipeline steps.

# Dev mode: broker runs in compose
docker compose -f dockerfiles/compose.localnet.yml --profile dev-broker logs broker 2>&1 | grep <REQUEST_ID>

Key log lines to look for:

• Locked request <ID> — when the broker locked it
• Completed order: <ID> eth_reward: <PRICE> — when it was fulfilled and at what price
• The order's created_at field from the order-stream query shows submission time

Present status to the user as:

Fulfilled price: (from eth_reward in the "Completed order" log line)

Check order-stream logs

docker compose -f dockerfiles/compose.localnet.yml logs order-stream

# Watch live
docker compose -f dockerfiles/compose.localnet.yml logs -f order-stream

Stopping

# Stop localnet (preserves anvil state for restart)
just localnet down

# Stop and wipe all state (fresh start)
just localnet clean

Troubleshooting

Request stuck at "Unknown"

• Check order-stream logs — did it receive the order?
• If Broadcasted order ... to 0 clients, the broker isn't connected to the WebSocket
• In dev mode, check broker container is running: docker compose -f dockerfiles/compose.localnet.yml --profile dev-broker ps

Broker delays lock ("scheduled for lock attempt in Ns")

The broker waits until the auction price exceeds its minimum profitable price (gas costs + min_mcycle_price). To avoid this delay, set --min-price above the broker's gas cost threshold (~0.0001 ETH on anvil). The price sits at min-price before rampUpStart (default now() + 30s), so a sufficiently high min-price means instant acceptance.

Broker not picking up orders

• Check that --min-price is high enough to cover gas + min_mcycle_price
• Check broker's min_mcycle_price in broker.toml vs the offer price

Price oracle errors on anvil

• Ensure broker.toml has the [price_oracle] section with static prices and chainlink disabled. just localnet adds this automatically.

Port conflicts

• Localnet uses ports: 8545 (anvil), 8585 (order-stream), 5435 (postgres), 9100/9101 (minio)
• Check for conflicts: ss -tlnp | grep -E '8545|8585|5435|9100'

Source: boundless-xyz/boundless — distributed by TomeVault.