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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// BNB testnet: preflight, deploy, and live-prove WorldMoves + GreenfieldVault.
// ---------------------------------------------------------------------------
// One command for the whole of backlog work order 07. The two contracts are
// code-complete and dry-run verified; the only thing that has ever been missing
// is a funded deployer key, so this script does everything around that step and
// makes the funded moment a single invocation.
//
// Modes:
// node scripts/bnb-testnet-deploy-prove.mjs
// Preflight only. Resolves the deployer, reads its live tBNB balance,
// simulates BOTH deploy scripts against the public BSC testnet RPC, and
// renders the spend-confirmation table CLAUDE.md's gate 1 requires.
// Never signs anything. Exit 3 when the deployer is unfunded.
//
// node scripts/bnb-testnet-deploy-prove.mjs --broadcast
// Runs the preflight, then broadcasts both deploys with the REAL,
// unmodified contracts/script/Deploy*.s.sol, then runs the live proof
// against the address it just deployed.
//
// node scripts/bnb-testnet-deploy-prove.mjs --prove-only --address 0x...
// Skips deployment and proves the sender / reader / ghost paths against
// an already-deployed WorldMoves.
//
// The proof exercises the real production modules, not reimplementations:
// sender api/_lib/bnb/world-moves.js sendJoin / sendMove / sendLeave
// reader src/bnb/world-presence-reader.js watchWorldPresence
// ghost src/bnb/onchain-ghosts.js createGhostTracker
//
// Flags: --world-id <n> (default 1), --moves <n> (default 3), --out <file.json>
import { readFileSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { formatEther, createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const CONTRACTS_DIR = resolve(REPO_ROOT, 'contracts');
/** Load `contracts/.env` then the repo `.env`, never overriding the shell. */
function loadEnvFiles() {
for (const file of [resolve(CONTRACTS_DIR, '.env'), resolve(REPO_ROOT, '.env')]) {
try {
for (const line of readFileSync(file, 'utf8').split('\n')) {
const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
if (m && !(m[1] in process.env)) process.env[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
}
} catch {
/* absent file is fine; the shell environment may already carry the vars */
}
}
}
loadEnvFiles();
const { BNB_CHAINS, getPublicClient } = await import(`${REPO_ROOT}/api/_lib/bnb/chains.js`);
const TESTNET = BNB_CHAINS.bscTestnet;
function parseArgs(argv) {
const out = { broadcast: false, proveOnly: false, address: null, worldId: 1, moves: 3, outFile: null };
for (let i = 0; i < argv.length; i += 1) {
const a = argv[i];
if (a === '--broadcast') out.broadcast = true;
else if (a === '--prove-only') out.proveOnly = true;
else if (a === '--address') out.address = argv[++i];
else if (a === '--world-id') out.worldId = Number(argv[++i]);
else if (a === '--moves') out.moves = Number(argv[++i]);
else if (a === '--out') out.outFile = argv[++i];
else throw new Error(`unknown flag ${a}; see the header of ${'scripts/bnb-testnet-deploy-prove.mjs'}`);
}
if (!Number.isInteger(out.worldId) || out.worldId < 0) throw new Error('--world-id must be a non-negative integer');
if (!Number.isInteger(out.moves) || out.moves < 1) throw new Error('--moves must be a positive integer');
return out;
}
/** First BSC testnet RPC that answers `eth_chainId` with 97. */
async function pickRpc() {
const candidates = [process.env.BSC_TESTNET_RPC_URL, ...TESTNET.rpcs].filter(Boolean);
const tried = [];
for (const url of candidates) {
try {
const client = createPublicClient({ transport: http(url, { timeout: 8000 }) });
const id = await client.getChainId();
if (id === 97) return url;
tried.push(`${url} (chainId ${id})`);
} catch (err) {
tried.push(`${url} (${err.shortMessage || err.message})`);
}
}
throw new Error(`no reachable BSC testnet RPC. Tried:\n ${tried.join('\n ')}`);
}
function deployerAccount() {
const raw = (process.env.BNB_TESTNET_DEPLOYER_KEY || process.env.DEPLOYER_PK || '').trim();
if (!raw) {
throw new Error(
'BNB_TESTNET_DEPLOYER_KEY is not set. Generate one with `cast wallet new`, write it to contracts/.env ' +
'(gitignored), and fund it at https://www.bnbchain.org/en/testnet-faucet (reCAPTCHA, so a human must do it).',
);
}
const pk = raw.startsWith('0x') ? raw : `0x${raw}`;
if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) throw new Error('BNB_TESTNET_DEPLOYER_KEY must be a 32-byte hex private key');
return privateKeyToAccount(pk);
}
function forgeScript(scriptRef, { rpcUrl, broadcast, privateKey }) {
const args = ['script', scriptRef, '--rpc-url', rpcUrl, '--json'];
if (broadcast) args.push('--broadcast', '--private-key', privateKey, '--slow');
const stdout = execFileSync('forge', args, {
cwd: CONTRACTS_DIR,
encoding: 'utf8',
maxBuffer: 64 * 1024 * 1024,
env: { ...process.env, BSC_TESTNET_RPC_URL: rpcUrl },
});
// `--json` emits one JSON object per line interleaved with plain log lines.
const objects = [];
for (const line of stdout.split('\n')) {
const t = line.trim();
if (!t.startsWith('{')) continue;
try {
objects.push(JSON.parse(t));
} catch {
/* a non-JSON brace line, e.g. a console.log of a struct */
}
}
return { stdout, objects };
}
/** Pull the cost estimate out of a forge `--json` simulation. */
function estimateFrom(objects) {
const est = objects.find((o) => o && o.estimated_total_gas_used !== undefined);
const run = objects.find((o) => o && o.gas_used !== undefined && o.success !== undefined);
if (!est) return null;
return {
simulationSucceeded: run ? !!run.success : null,
constructorGas: run ? Number(run.gas_used) : null,
totalGas: Number(est.estimated_total_gas_used),
gasPriceGwei: Number(est.estimated_gas_price),
amount: `${est.estimated_amount_required} ${est.token_symbol}`,
};
}
/** Deployed address + receipt facts, read from the broadcast artifact forge writes. */
function deployedAddress(scriptFile) {
const artifact = resolve(CONTRACTS_DIR, 'broadcast', scriptFile, '97', 'run-latest.json');
const run = JSON.parse(readFileSync(artifact, 'utf8'));
const create = run.transactions.find((t) => t.transactionType === 'CREATE');
if (!create) throw new Error(`no CREATE transaction in ${artifact}`);
const receipt = (run.receipts || []).find((r) => r.transactionHash === create.hash) || {};
return {
address: create.contractAddress,
txHash: create.hash,
blockNumber: receipt.blockNumber ? Number(BigInt(receipt.blockNumber)) : null,
gasUsed: receipt.gasUsed ? Number(BigInt(receipt.gasUsed)) : null,
status: receipt.status ?? null,
};
}
function bscscan(kind, value) {
return `${TESTNET.explorer}/${kind}/${value}`;
}
/**
* Exercise the three live paths against a real deployment. The reader is
* started BEFORE the sender fires so every event is observed live rather than
* backfilled, and the ghost tracker is driven purely from reader callbacks.
*/
async function proveLivePaths({ address, worldId, moves, account, rpcUrl }) {
const { sendJoin, sendMove, sendLeave } = await import(`${REPO_ROOT}/api/_lib/bnb/world-moves.js`);
const { watchWorldPresence } = await import(`${REPO_ROOT}/src/bnb/world-presence-reader.js`);
const { createGhostTracker } = await import(`${REPO_ROOT}/src/bnb/onchain-ghosts.js`);
const observed = { moved: [], joined: [], left: [], errors: [] };
const ghosts = createGhostTracker();
// Pin reader AND sender to the one RPC that answered the preflight, so the
// proof cannot silently split across endpoints (or, on an anvil fork, leak
// sends onto the public testnet).
const publicClient = getPublicClient('bscTestnet', { rpcs: [rpcUrl], cache: false });
const sendOpts = { address, publicClient };
const watcher = await watchWorldPresence({
worldId,
address,
network: 'bscTestnet',
publicClient,
pollMs: 700,
backfillBlocks: 0n,
onMove: (ev) => {
observed.moved.push({ ...ev, blockNumber: Number(ev.blockNumber), timestamp: Number(ev.timestamp) });
// Wall clock, not the block timestamp: staleness here means "how long
// since we saw this player", and it is what src/agora/onchain-presence.js
// feeds the tracker in production (upsert with no explicit timestamp).
ghosts.upsert(ev.player, { x: ev.x, y: ev.y, z: ev.z, facing: ev.facing });
},
onJoin: (ev) => observed.joined.push({ player: ev.player, timestamp: Number(ev.timestamp) }),
onLeave: (ev) => {
observed.left.push({ player: ev.player, timestamp: Number(ev.timestamp) });
ghosts.remove(ev.player);
},
onError: (err) => observed.errors.push(err.shortMessage || err.message),
});
const sent = [];
try {
const join = await sendJoin({ account, worldId, network: 'bscTestnet' }, sendOpts);
sent.push({ call: 'join', ...join });
console.log(` join ${join.hash} (${join.mode})`);
for (let i = 0; i < moves; i += 1) {
const pos = { x: 1000 + i * 250, y: 0, z: -500 + i * 125 };
const facing = (i * 9000) % 36000;
const res = await sendMove({ account, worldId, pos, facing, network: 'bscTestnet' }, sendOpts);
sent.push({ call: 'move', pos, facing, ...res });
console.log(` move #${i + 1} ${res.hash} (${res.mode}) pos=${JSON.stringify(pos)} facing=${facing}`);
}
// Give the reader's poll loop time to see the last move before `leave`
// removes the ghost, so the ghost path is observed populated then empty.
await waitFor(() => observed.moved.length >= moves, 45_000, 'reader never observed every Moved event');
ghosts.tick(1 / 60, Date.now());
const beforeLeave = [...ghosts.values()].map((g) => ({
player: g.player,
interpolated: { x: round(g.x), y: round(g.y), z: round(g.z), facing: round(g.facing) },
target: { x: round(g.target.x), y: round(g.target.y), z: round(g.target.z), facing: round(g.target.facing) },
moves: g.moves,
}));
const leave = await sendLeave({ account, worldId, network: 'bscTestnet' }, sendOpts);
sent.push({ call: 'leave', ...leave });
console.log(` leave ${leave.hash} (${leave.mode})`);
await waitFor(() => observed.left.length >= 1, 45_000, 'reader never observed the Left event');
return { sent, observed, ghostsBeforeLeave: beforeLeave, ghostsAfterLeave: ghosts.size };
} finally {
watcher.stop();
}
}
const round = (n) => Math.round(n * 100) / 100;
async function waitFor(predicate, timeoutMs, message) {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (predicate()) return;
await new Promise((r) => setTimeout(r, 400));
}
throw new Error(`${message} (waited ${timeoutMs}ms)`);
}
async function main() {
const opts = parseArgs(process.argv.slice(2));
const rpcUrl = await pickRpc();
const account = deployerAccount();
const client = createPublicClient({ transport: http(rpcUrl, { timeout: 15_000 }) });
const balance = await client.getBalance({ address: account.address });
const report = {
network: 'bscTestnet',
chainId: TESTNET.id,
rpcUrl,
deployer: account.address,
deployerBalanceWei: balance.toString(),
deployerBalanceBnb: formatEther(balance),
explorer: TESTNET.explorer,
ranAt: new Date().toISOString(),
};
console.log(`network BNB Smart Chain Testnet (chainId ${TESTNET.id})`);
console.log(`rpc ${rpcUrl}`);
console.log(`deployer ${account.address}`);
console.log(`balance ${formatEther(balance)} tBNB ${bscscan('address', account.address)}`);
console.log('');
if (!opts.proveOnly) {
console.log('simulating both deploy scripts against the live testnet RPC (no broadcast)...');
const sims = {
GreenfieldVault: estimateFrom(
forgeScript('script/DeployGreenfieldVault.s.sol:DeployGreenfieldVault', { rpcUrl, broadcast: false }).objects,
),
WorldMoves: estimateFrom(
forgeScript('script/DeployWorldMoves.s.sol:DeployWorldMoves', { rpcUrl, broadcast: false }).objects,
),
};
report.simulation = sims;
for (const [name, s] of Object.entries(sims)) {
const ok = s?.simulationSucceeded ? 'ok ' : 'FAIL';
console.log(
` ${name.padEnd(16)} ${ok} gas ${String(s?.totalGas ?? 'n/a').padStart(9)} @ ${s?.gasPriceGwei ?? '?'} gwei cost ${s?.amount ?? 'n/a'}`,
);
}
console.log('');
}
if (balance === 0n && !opts.proveOnly) {
console.log('DEPLOYER IS UNFUNDED. Nothing was signed.');
console.log(`Fund ${account.address} with tBNB at https://www.bnbchain.org/en/testnet-faucet`);
console.log('(the faucet is reCAPTCHA-gated, so a human has to complete it), then re-run with --broadcast.');
if (opts.outFile) writeFileSync(opts.outFile, JSON.stringify(report, null, 2));
process.exit(3);
}
if (!opts.broadcast && !opts.proveOnly) {
console.log('Preflight only. Re-run with --broadcast to deploy (this SPENDS testnet funds from the key above).');
if (opts.outFile) writeFileSync(opts.outFile, JSON.stringify(report, null, 2));
return;
}
let worldMoves = opts.address;
if (opts.broadcast) {
console.log('broadcasting GreenfieldVault...');
forgeScript('script/DeployGreenfieldVault.s.sol:DeployGreenfieldVault', {
rpcUrl,
broadcast: true,
privateKey: process.env.BNB_TESTNET_DEPLOYER_KEY,
});
const vault = deployedAddress('DeployGreenfieldVault.s.sol');
report.greenfieldVault = { ...vault, explorer: bscscan('address', vault.address) };
console.log(` GreenfieldVault ${vault.address} tx ${vault.txHash} block ${vault.blockNumber}`);
console.log('broadcasting WorldMoves...');
forgeScript('script/DeployWorldMoves.s.sol:DeployWorldMoves', {
rpcUrl,
broadcast: true,
privateKey: process.env.BNB_TESTNET_DEPLOYER_KEY,
});
const wm = deployedAddress('DeployWorldMoves.s.sol');
report.worldMoves = { ...wm, explorer: bscscan('address', wm.address) };
worldMoves = wm.address;
console.log(` WorldMoves ${wm.address} tx ${wm.txHash} block ${wm.blockNumber}`);
console.log('');
}
if (!worldMoves) throw new Error('--prove-only needs --address <deployed WorldMoves>');
console.log(`proving sender / reader / ghost against ${worldMoves} (worldId ${opts.worldId})...`);
report.proof = await proveLivePaths({
address: worldMoves,
worldId: opts.worldId,
moves: opts.moves,
account,
rpcUrl,
});
console.log('');
console.log(` reader observed ${report.proof.observed.joined.length} Joined, ${report.proof.observed.moved.length} Moved, ${report.proof.observed.left.length} Left`);
console.log(` ghost tracker ${report.proof.ghostsBeforeLeave.length} ghost(s) before leave, ${report.proof.ghostsAfterLeave} after`);
if (report.proof.observed.errors.length) console.log(` reader errors ${report.proof.observed.errors.join('; ')}`);
console.log('');
console.log('Next: set the address on the service, then confirm the public endpoint flips to deployed:true');
console.log(` gcloud run services update three-ws-api --region us-central1 --project aerial-vehicle-466722-p5 \\`);
console.log(` --update-env-vars WORLD_MOVES_ADDRESS_TESTNET=${worldMoves}`);
console.log(' curl -s "https://three.ws/api/bnb/world-config?network=testnet" | python3 -m json.tool');
if (opts.outFile) {
writeFileSync(opts.outFile, JSON.stringify(report, null, 2));
console.log(`\nevidence written to ${opts.outFile}`);
}
}
main().catch((err) => {
console.error(`\n${err.message}`);
process.exit(1);
});