Skip to content

TESTNET-RPC-INFRA.md

Latest commit

 

History

History
170 lines (122 loc) · 14.1 KB

TESTNET-RPC-INFRA.md

File metadata and controls

170 lines (122 loc) · 14.1 KB
Raw

Testnet operations, public RPC, and infrastructure

👋 Everyday users: public RPC is https://testnet-rpc.boing.network/. Faucet and portal live on boing.network.
🛠️ Developers: this is the operator hub — bootnodes, env matrix, QA apply, monitoring.
🛰️ Operators: start here before specialist VM/RPC specs.

Audience: Operators and integrators who need bootnodes, public JSON-RPC, website env, canonical native AMM, QA policy, and monitoring in one place. Canonical public RPC is the Cloudflare Worker → Fly path — not a home tunnel.

Specialist guides (RPC methods, VM calldata, security) stay in their own files; this page is the operator hub.

flowchart TB
  Hub[TESTNET-RPC-INFRA] --> Boots[Bootnodes]
  Hub --> RPC[Public RPC gateway]
  Hub --> QA[QA policy apply]
  Hub --> AMM[Canonical native AMM env]
  Hub --> Mon[Monitoring]
Loading

1. Pick your doc (routing)

You need… Start here
User-facing testnet (join, faucet, bootnodes) TESTNET.md
Copy-paste commands (cargo, boing-node, tutorial npm run) NODE-OPERATOR-COMMANDS.md
Home-lab bootnode + tunnel + website secrets INFRASTRUCTURE-SETUP.md (lab appendix; not production RPC)
Hosted testnet on Fly.io FLY-IO.md (./scripts/fly-deploy-testnet.sh)
Beta readiness / six pillars TESTNET.md Part 3.1 · SIX-PILLARS.md
Upgrade / restart the node behind public RPC FLY-IO.md
JSON-RPC methods, errors, canonical pool hex RPC-API-SPEC.md
Canonical native CP pool (OPS-1) + rotations OPS-CANONICAL-TESTNET-NATIVE-AMM-POOL.md § Published
Self-hosted RPC + deploy pool DEVNET-OPERATOR-NATIVE-AMM.md
Node listing API + two-node Windows layout NETWORKS-API.md, TESTNET.md
Node flags, tunnel 530/1033, incidents RUNBOOK.md
QA protocol + content blocklist QUALITY-ASSURANCE-NETWORK.md; apply policy: npm run apply-public-testnet-qa-policy
Feature timeline (when shipped) FEATURES.md
Backlog / future work index NEXT-STEPS-FUTURE-WORK.md

2. Current status snapshot (2026-10-25)

Surface Status Verify
Public testnet RPC Hosted — Cloudflare Worker → Fly boing-testnet-1 only at https://testnet-rpc.boing.network/ (boing-testnet-2 retired 2026-10-24) npm run preflight-rpc; GET /__gateway/health (single backend)
QA transparency RPC Live — registry + pool config npm run verify-public-testnet-rpc
QA content policy 132-term content_blocklist on public RPC (when applied) boing_getQaRegistry; npm run apply-public-testnet-qa-policy after edits
Media blobs Phases 1–33 live; PHASE7 256 MiB active at H≥1306; Phase 34 download ACL shipped BOING-L1-MEDIA-BLOBS.md
Block JSON Byte fields as 0x hex; optional include_code: false slim stubs for explorers RPC-API-SPEC.md
SDK @boing-network/boing-sdk@^0.5.39 on npm npm view @boing-network/boing-sdk version
Canonical CP / DEX Treat live boing_getNetworkInfo.end_user as source of truth (factory/pool may be published after full-stack + register_pair) boing_getNetworkInfo; npm run check-canonical-pool
QA registry vs docs Baseline in docs/config/; live may differ after operator apply npm run verify-qa-alignment
Explorer Live — boing.observer /qa, /tokens, /dex/pools
Chain tip Fly boing-testnet-1 (resets if the volume is wiped) npm run observer-chain-tip-poll

boing.finance Deploy submitted is mempool accept, not explorer listing. /tokens indexes included ContractDeploy* txs; /dex/tokens needs a published factory (end_user.canonical_native_dex_factory). With a single Fly backend, the gateway proxies (and fans out submit) to boing-testnet-1 only.

Native token deploys still meter ~200k–400k gas, but the fee is fee market v1: at full schedule a ~200k–400k gas deploy is about 0.2–0.4 BOING (micro ≈ 0.002–0.004 BOING), not one BOING per 21k gas. The faucet dispenses 20 BOING per request (FAUCET_DISPENSE_AMOUNT; may need a second request for a large deploy; not enough for min validator stake). Underfunded deploys fail that tx (nonce consumed) without aborting the block; a retry of the identical signed payload still returns Duplicate transaction while it sits in the mempool.

After a chain reset, head_height may be 0 while prior bootstrap contracts remain readable. Treat boing_getNetworkInfo.end_user as the live contract hint source.

Public RPC HTTP 403 (Bot Fight / WAF)

Cloudflare Bot Fight Mode (fight_mode) on zone boing.network returns HTTP 403 with cf-mitigated: challenge (“Just a moment…”) for automated clients (curl, SDKs, explorer /api/rpc). That blocks JSON-RPC even when the Worker and Fly backends are healthy.

  • Operators: Keep Bot Fight Mode off for this zone (or skip SBFM for http.host eq "testnet-rpc.boing.network"). DNS for testnet-rpc must CNAME to the Worker (boing-public-rpc-gateway.*.workers.dev), not a retired *.cfargotunnel.com origin.
  • Integrators: boing-sdk sets User-Agent: boing-sdk/json-rpc in Node/CLI; UA alone does not bypass Bot Fight Mode.
  • Symptom check: 403 + cf-mitigated: challenge on every UA ⇒ Bot Fight, not a downed origin. workers.dev / *.fly.dev still 200 while the custom hostname challenges.

3. Go-live sequence (order matters)

Prerequisite: Workspace builds and tests clean — TESTNET.md (cargo test, boing-sdk npm test).

  1. Same genesis everywhere — All validators and full nodes share one genesis (faucet account, chain id, etc.).

  2. Bootnodes — At least two stable P2P listeners (or one host today); publish multiaddrs on the website and in TESTNET.md §6. See INFRASTRUCTURE-SETUP.md.

  3. Validators / block production — Enough stake and connectivity that height advances.

  4. Public RPC — Fly boing-testnet-1 + Cloudflare Worker at https://testnet-rpc.boing.network/ (FLY-IO.md). DNS for testnet-rpc must CNAME to the Worker — not *.cfargotunnel.com. Set BOING_CHAIN_ID=6913, BOING_CHAIN_NAME=Boing Testnet, and optional BOING_CANONICAL_NATIVE_* from tools/boing-node-public-testnet.env.example. See RUNBOOK.md §8.

  5. Verify RPC from the internet — Before announcing “testnet is up”:

    cd examples/native-boing-tutorial && npm install
export BOING_RPC_URL=https://testnet-rpc.boing.network/
npm run preflight-rpc

    Or npm run check-testnet-rpc only; optional BOING_PROBE_FULL=1. See NODE-OPERATOR-COMMANDS.md.

  6. Faucet — Node behind the public URL runs with --faucet-enable; confirm via boing.network/faucet.

  7. Website / portal env — TESTNET.md / WEBSITE-AND-DEPLOYMENT.md, WEBSITE-AND-DEPLOYMENT.md: PUBLIC_BOOTNODES, PUBLIC_TESTNET_RPC_URL.

  8. Node listing API — NETWORKS-API.md; clients read GET https://boing.network/api/networks.

  9. Optional: native DEX full stack — npm run deploy-native-dex-full-stack from examples/native-boing-tutorial after boing-sdk build. For public testnet, publish canonical pool id per OPS-CANONICAL-TESTNET-NATIVE-AMM-POOL.md (OPS-1).

  10. Optional: QA content policy — Edit docs/config/qa_content_blocklist.en.json, then npm run apply-public-testnet-qa-policy (requires BOING_OPERATOR_RPC_TOKEN on the node and the matching X-Boing-Operator header; operator methods are rejected with -32057 when the token is unset). Restart nodes after upgrading boing-node so boing_qaCheck uses the live registry.

  11. Micro fee market (recommended) — Product target is Solana-like micro fees, not gasless. Set BOING_MICRO_FEES_ACTIVATION_HEIGHT on public nodes (current tip or tip+1), then npm run apply-micro-fee-policy (loads docs/config/network_fee_config.canonical.json via boing_operatorApplyFeePolicy). Confirm with boing_getNetworkFeePolicy. Details: OPTIONAL-PRIORITY-FEES.md, FLY-IO.md.

Later upgrades to the RPC binary: FLY-IO.md.

HTTP 530 / Cloudflare error 1033

Cloudflare returns 530 when a Tunnel hostname cannot reach its connector. Public testnet RPC must not depend on a home cloudflared process. Confirm the Worker route is attached (workers/public-rpc-gateway) and Fly /live is 200. Explorer POST /api/rpc failsover to *.fly.dev if the public hostname is still on a dead tunnel. Details: FLY-IO.md, RUNBOOK.md §8.3.

4. Environment variables (integrators)

Consumer Typical vars Where documented
Cloudflare Pages / website PUBLIC_TESTNET_RPC_URL, PUBLIC_BOOTNODES INFRASTRUCTURE-SETUP.md, WEBSITE-AND-DEPLOYMENT.md
boing.finance REACT_APP_BOING_NATIVE_AMM_POOL, REACT_APP_BOING_NATIVE_VM_* OPS-CANONICAL-TESTNET-NATIVE-AMM-POOL.md §3
Tutorial / scripts BOING_RPC_URL, BOING_POOL_HEX examples/native-boing-tutorial/README.md
Public boing-node BOING_CHAIN_ID, BOING_CHAIN_NAME, BOING_CANONICAL_NATIVE_*, BOING_DEX_*, BOING_OPERATOR_RPC_TOKEN (required for operator-only methods; fail-closed when unset), optional BOING_MICRO_FEES_ACTIVATION_HEIGHT tools/boing-node-public-testnet.env.example, RUNBOOK.md §8, OPTIONAL-PRIORITY-FEES.md
Relaxed testnet rate limits BOING_RATE_PROFILE=dev or --dev-rate-limits RUNBOOK.md §2 — not for public RPC

5. Canonical native AMM pool (integration contract)

  1. Source of truth: live boing_getNetworkInfo.end_user on https://testnet-rpc.boing.network/ (FLY-IO.md). Re-check after any volume wipe or full-stack redeploy; historical published hex 0x5b60d6f8… (OPS-CANONICAL-TESTNET-NATIVE-AMM-POOL.md; SDK CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX) is not currently advertised on hosted Fly end_user.
  2. Procedure: OPS-CANONICAL-TESTNET-NATIVE-AMM-POOL.md.
  3. SDK constant: CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX in boing-sdk.

6. After deploy — verification

Layer Check
RPC from internet npm run preflight-rpc or check-testnet-rpc (NODE-OPERATOR-COMMANDS.md)
Canonical pool npm run check-canonical-pool — CI: canonical-pool-public-rpc.yml
QA alignment npm run verify-qa-alignment, npm run verify-public-testnet-rpc
QA vulgarity smoke boing_qaCheck with blocked asset_name → reject / CONTENT_POLICY_VIOLATION (after node binary includes registry fix)
Public RPC edge GET /live and GET /__gateway/health on https://testnet-rpc.boing.network/ — no HTTP 530
Manual dApp smoke NATIVE-AMM-INTEGRATION-CHECKLIST.md § Manual E2E smoke
Playwright (optional CI) PLAYWRIGHT-E2E-CI-OPS.md, examples/native-boing-playwright/README.md

7. Monitoring without a hosted observer

boing.observer is a separate deploy — see BOING-OBSERVER-AND-EXPRESS.md. Until durable indexing is needed:

  1. npm run observer-chain-tip-poll — height + boing_getSyncState; BOING_POLL_ONCE=1 for one sample.
  2. npm run check-testnet-rpc, verify-public-testnet-rpc, npm run probe-rpc.
  3. Indexer scripts — indexer-chain-tips, indexer-ingest-tick (INDEXER-RECEIPT-AND-LOG-INGESTION.md).

Production-grade explorer backend: OBSERVER-HOSTED-SERVICE.md (OBS-1). Deployed D1 worker: GET /api/readiness on examples/observer-d1-worker.

8. Security and incidents

Topic Doc
Disclosure SECURITY-STANDARDS.md §5
Incident steps RUNBOOK.md §6
Public RPC WAF / rate limits PUBLIC-RPC-WAF-GUIDANCE.md
Public RPC operator token BOING_OPERATOR_RPC_TOKEN + header X-Boing-Operator — RPC-API-SPEC.md

9. Line endings (Windows)

Repo .gitattributes enforces eol=lf for *.js / *.mjs. Re-clone or git add --renormalize . once if CRLF diffs appear.

Boing Network — Quality, enforced by the protocol.