Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
The on-chain world — real-time presence on BNB Chain
/agora's Play mode ("Enter the Commons") has an opt-in toggle — "Record
on-chain (BNB testnet)" — that writes your walk to a real BNB Chain smart
contract, gaslessly, and shows you every other on-chain player as a live
ghost marker. This page explains what it is, exactly why BNB Chain is the
only chain where this is practical today, how it's built, and how to
reproduce the proof yourself. Everything here is real code against real
endpoints; nothing is mocked.
1. Why this only works on BNB Chain
A real-time on-chain presence layer needs two things at once, and BNB Chain
is the only EVM chain (verified 2026-07-07, see
prompts/bnb-chain/00-CONTEXT.md) that has shipped both:
- Blocks fast enough that "on-chain" can mean "this frame." BSC's Fermi hardfork (BEP-619/590, live 2026-01-14) produces a block roughly every 0.45 seconds — live-measured via public RPC, not a roadmap number. Ethereum L1 is 12s, Base is 2s. At 0.45s, an on-chain move commits and becomes visible to every other client at a cadence a walking avatar actually needs — waiting 2-12 seconds to see someone else's step would make "on-chain presence" feel broken, not real-time.
- Gasless sends from a plain private-key wallet, with no smart-account
setup. BEP-414's paymaster API (
pm_isSponsorable+eth_sendRawTransaction) lets an unmodified EOA sign agasPrice: 0transaction that a sponsor pays for atomically (BEP-322 bundles). Production implementation: MegaFuel (NodeReal). This is mechanically impossible on Ethereum L1/Base today — EIP-1559 rejects a zero-fee tx outright, ERC-4337 needs a smart-contract account, EIP-7702 needs a delegation step. A visitor with a brand-new, empty wallet can start walking on-chain immediately; nobody has to fund gas first.
Neither fact alone is enough — a fast chain with normal gas costs still asks every walking player to hold and spend real funds every ~0.45s; a gasless chain with 12s blocks still feels laggy. BNB Chain is the only place we've verified both are live simultaneously.
What this is not: a claim of "20,000 TPS" or an on-chain game engine — those are refuted/roadmap claims (00-CONTEXT). This is one, specific, verifiable mechanism: an event-only move-commit contract, read back over a public RPC, at a real sub-second cadence.
2. Architecture
Browser (src/agora/onchain-presence.js)
│
├─ position/heading every frame ──► src/bnb/move-sender.js (MoveCoalescer)
│ │
│ ▼
│ api/_lib/bnb/world-moves.js (sendMove)
│ │
│ ▼
│ api/_lib/bnb/megafuel.js (sendGasless)
│ ── try pm_isSponsorable ──► MegaFuel paymaster
│ ── declined/failed ──► self-pay walletClient
│ │
│ ▼
│ WorldMoves.sol on BSC (move() emits Moved)
│ │
└─ src/bnb/world-presence-reader.js ◄───┘ (watchContractEvent / bounded backfill)
│
▼
src/bnb/onchain-ghosts.js (interpolate, drop on staleness)
│
▼
ghost octahedron markers rendered in the live THREE.js scene
WorldMoves.sol (contracts/src/WorldMoves.sol) is the whole on-chain
surface: join(worldId), leave(worldId), move(worldId,x,y,z,facing), and
checkpoint(worldId,x,y,z,facing). move() is event-only — zero SSTORE
(~4,800 gas of internal execution, forge test-measured), so a player
walking at the chain's own block cadence never accumulates state or rent;
checkpoint() is the one opt-in storage-writing call, for anything that
wants a queryable "last known position" instead of just the event log.
Coordinates are signed 24-bit integers in millimeters (an ~8.39km cube);
out-of-range coordinates revert rather than silently clamp, so a client
never drifts out of sync with what's actually on-chain.
src/bnb/move-sender.js's MoveCoalescer is the client-side throttle: it
only launches a new move() send once the previous one's round trip has
resolved, so a 60fps position stream still produces roughly one on-chain move
per block, not one per frame, with zero timer/interval logic — congestion
control falls out of the "wait for the last one" rule alone.
api/_lib/bnb/megafuel.js's sendGasless() always tries the sponsored
path first (pm_isSponsorable) and falls back to a normal gas-paying send if
MegaFuel declines, times out, or is down — the mandatory self-pay fallback
00-CONTEXT requires for every MegaFuel-dependent feature. The toggle labels
this honestly in the UI (on = sponsored, on-selfpay = self-pay with the
decline reason as a tooltip) rather than pretending every send is free.
src/bnb/world-presence-reader.js's watchWorldPresence() does a bounded
backfill (~1,200 blocks ≈ ~9 minutes at 0.45s/block) on join so a new visitor
immediately sees players who were already there, then polls
watchContractEvent for live Moved/Joined/Left events — reads need no
API key or wallet, straight from the browser to a public RPC.
api/bnb/world-config.js exposes { address, deployed, chainId, explorer, rpcs, worldId } — a tiny public, non-secret GET — so the browser never needs
its own build-time copy of the deployed address, and flipping the
server-side env var the moment a public deploy lands activates every open
tab with zero rebuild.
3. Reproducible walkthrough
Try it (once a public address exists): open /agora → Enter the
Commons → click Record on-chain (BNB testnet) → confirm the one-time
local session-key prompt (a BSC-testnet-only key generated in your browser
and kept in localStorage; never sent anywhere, never funded, sponsored
sends need no balance) → walk with WASD. You'll see your own send status in
the toggle's label, and every other on-chain player nearby as a glowing
ghost marker with a nameplate.
Reproduce the two-wallet proof locally (the exact steps this doc's own
verification used — see prompts/bnb-chain/PROGRESS.md's prompt 18 entry for
full output):
# 1. A local chain that reproduces BSC's live measured cadence exactly
anvil --chain-id 97 --block-time 0.45 --port 8555
# 2. Deploy the real, unmodified script (see contracts/DEPLOYMENTS.md)
cd contracts && forge script script/DeployWorldMoves.s.sol:DeployWorldMoves \
--rpc-url http://127.0.0.1:8555 \
--private-key <anvil-account-0-private-key> \
--broadcast
# 3. Point a browser session at it without a public deploy or env change —
# the same dev-override onchain-presence.js's turnOn() already supports:
# http://localhost:PORT/agora?play=1
# &bnbDevAddress=<deployed WorldMoves address>
# &bnbDevRpc=http://127.0.0.1:8555
Open that URL in two separate browser profiles (or two Playwright contexts,
each with a different funded local test key seeded into
localStorage['three.ws:bnb-presence-key']), turn the toggle on in both,
and walk. Each browser's console logs [onchain-presence] move sent hash=... mode=... for its own sends and [onchain-presence] ghost joined player=... the moment it picks up the other's.
4. Real proof (2026-07-08)
Deployed WorldMoves (anvil-local, --block-time 0.45, per the "not yet a
public deploy" state below): 0x5FbDB2315678afecb367f032d93F642f64180aa3.
Deploy tx 0xab86fb5937e655dd1e64d8e45118ca5624d20f9b4bd213704067f5dc7ae8b65a,
block 18, status success.
Two real, independent headless-Chromium sessions (Playwright), each with a distinct funded wallet, drove real WASD movement concurrently for 60 seconds against the on-chain toggle described above:
| wallet | tx hash | block | status | mode |
|---|---|---|---|---|
A (0x7099…dc79C8) |
0xd1b5188c…9d7 |
1849 | success | self-pay |
| A | 0xb63fdb5b…997 |
1880 | success | self-pay |
| A | 0x5f772762…f61 |
1927 | success | self-pay |
| A | 0x11dd19f4…b32 |
1986 | success | self-pay |
B (0x3C44…4293BC) |
0x945ce448…715 |
1863 | success | self-pay |
| B | 0x317554f6…b20 |
1916 | success | self-pay |
| B | 0x3d378b15…c78 |
1963 | success | self-pay |
Block cadence: block 1849 → block 1986 is 137 blocks across 61 real
seconds — a 0.445s average inter-block time, matching the live BSC
testnet's measured ~0.45s Fermi cadence to within 1% (anvil's --block-time 0.45 deliberately reproduces the live-measured rate, rather than the
wall-clock-paced local blocks earlier prompts in this campaign used).
Cross-visibility, both directions, live: wallet A's browser logged
ghost joined player=0x3C44…4293BC the moment wallet B's first move landed;
wallet B's browser independently logged ghost joined player=0x7099…dc79C8
for wallet A — two fully separate browser processes, no shared state beyond
the chain itself.
Mode: every send resolved self-pay — MegaFuel's real testnet
pm_isSponsorable was probed for real on every send (no mock); it declined
because no NodeReal sponsor policy has been provisioned for these throwaway
addresses. This is the expected, documented outcome (see §5) and the
self-pay fallback is proven working, not a no-op — every tx above actually
landed and paid its own gas.
Full receipts, the finer-grained per-block timestamp sampling, and the exact
reproduction commands are recorded in contracts/DEPLOYMENTS.md's "Prompt
18" subsection and prompts/bnb-chain/PROGRESS.md.
5. Honest caveats
- Not yet on the public BSC testnet. Every proof above (this doc and
prompts 14/15/16/18) ran against a local
anvilinstance because a real public deploy needs a funded deployer key (BNB_TESTNET_DEPLOYER_KEY/DEPLOYER_PK) that this environment doesn't have, and the public tBNB faucet is reCAPTCHA-gated with no programmatic path. The deploy script, bytecode, and dry-run against the live public RPC are all already verified (contracts/DEPLOYMENTS.md) — the only missing piece is a funded owner-controlled key. The momentWORLD_MOVES_ADDRESS_TESTNETis set,/api/bnb/world-configstarts returning a real address for every visitor with zero further code changes. - MegaFuel is one operator. NodeReal runs the only production MegaFuel
paymaster today; BEP-414 itself is still a Draft BSC Improvement Proposal.
Sponsor policies are allowlisted per address/contract — a policy has to be
explicitly provisioned (dashboard.nodereal.io) before sends from a given
address are ever sponsored. That's why every real run in this doc shows
self-pay, notsponsored— it's a policy-provisioning gap, not a code gap;sendGasless()'s branch on the probe result is already correct and tested either way. - Self-pay always works, and is the honest default. The toggle never
hides which mode a send used —
on(sponsored) vs.on-selfpay(self-pay, tooltip shows the decline reason) are both real, both wired, both tested. move()'s coordinates are not the same as your world position. The contract's 24-bit millimeter space (±8,388.6mper axis) is far larger than any three.ws scene needs;toContractPos/fromContractPos(src/bnb/move-sender.js,src/agora/onchain-presence.js) do the unit conversion. Coordinates outside that range simply never fire an on-chain write (checked client-side before the call, so no doomed on-chain revert).
Related
- BNB Chain payments — the MPP/x402 payment rail this
campaign also shipped, same
api/_lib/bnb/namespace. contracts/src/WorldMoves.sol— the contract itself, full NatSpec.contracts/DEPLOYMENTS.md— deploy status, bytecode, and every real broadcast proof for every BNB Chain contract in this repo.STRUCTURE.md's Agora row — the full on-chain-presence file map.prompts/bnb-chain/PROGRESS.md— the full campaign trail, prompts 14 through 18.