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
/**
* Gasless ERC-8004 agent registration relay for BNB Chain (prompt 03).
*
* The campaign's headline demo: a brand-new, zero-balance wallet mints its
* ERC-8004 on-chain identity from the first click — no faucet, no funding.
* The client (a browser wallet or an in-page ephemeral key — either way the
* private key never leaves the browser) signs a *legacy* `register()` /
* `register(string)` transaction against the Identity Registry and hands us
* only the raw signed bytes. This module never sees a key, only bytes that
* are already fully signed — it parses them, decides sponsored vs. self-pay
* vs. decline, and relays.
*
* Two real broadcast paths, chosen by the `gasPrice` already baked into the
* signature the client sent:
*
* - `gasPrice === 0n` → "gasless attempt". Probe MegaFuel's
* `pm_isSponsorable` with the parsed tx; if sponsorable, relay the EXACT
* client bytes via MegaFuel's `eth_sendRawTransaction`
* (api/_lib/bnb/megafuel.js `submitRawTx`) — the sponsor tx pairs with it
* atomically at the block-builder layer. mode: 'sponsored'.
* If MegaFuel declines, we do NOT try to self-pay a zero-gasPrice
* transaction — every BSC node rejects a gasPrice-underpriced tx outside
* the paymaster path, so broadcasting it would just be a guaranteed
* revert-before-inclusion. That's mechanically impossible, not a bug. We
* return `{ mode: 'declined', reason, hint }` so the caller can show
* "you'll pay ~$0.001 gas" and resubmit a *newly signed*, real-gasPrice
* transaction — which lands in the branch below.
* - `gasPrice > 0n` → "self-pay attempt". The client already re-signed with
* real gas (after a decline, or because it knew sponsorship was
* unavailable). We broadcast the bytes as-is via the standard public RPC.
* mode: 'self-pay'.
*
* `sendGasless()` in megafuel.js is deliberately NOT reused here: it signs
* internally via a server-held viem `Account` (the right shape for a demo/ops
* account, e.g. the anvil-fork proof in prompt 02's PROGRESS entry) — not
* this endpoint's "client always signs, server never holds a key" model. This
* module only ever relays bytes it was handed.
*/
import { parseTransaction, recoverTransactionAddress, keccak256, toBytes, parseAbi } from 'viem';
import { getPublicClient, BNB_CHAINS } from './chains.js';
import { isSponsorable, submitRawTx as megafuelSubmitRawTx } from './megafuel.js';
import { IDENTITY_REGISTRY_ABI, REGISTRY_DEPLOYMENTS } from '../../../src/erc8004/abi.js';
/** Typed error for every failure path — `status` maps straight to the HTTP response. */
export class RegisterRelayError extends Error {
/** @param {string} message @param {{ code?: string, status?: number, cause?: unknown }} [info] */
constructor(message, info = {}) {
super(message);
this.name = 'RegisterRelayError';
this.code = info.code || 'bad_request';
this.status = info.status || 400;
if (info.cause) this.cause = info.cause;
}
}
// viem's parseAbi rejects the one `register(string,tuple[])` overload (inline
// anonymous tuple param syntax it doesn't parse) — filtering that single
// signature out (not rewriting any signature text) keeps every other entry
// byte-identical to src/erc8004/abi.js, per the prompt's "do NOT redefine the
// ABI" instruction. Only used for the two read calls below (balanceOf /
// tokenOfOwnerByIndex); event decoding uses raw topic matching instead (see
// api/erc8004/register-confirm.js for the same proven pattern).
const READ_ABI = parseAbi(IDENTITY_REGISTRY_ABI.filter((sig) => !sig.includes('tuple')));
const REGISTERED_TOPIC = keccak256(toBytes('Registered(uint256,string,address)'));
const TRANSFER_TOPIC = keccak256(toBytes('Transfer(address,address,uint256)'));
function normalizeNetwork(network) {
if (network === 56 || network === '56' || network === 'bsc' || network === 'mainnet' || network === 'bscMainnet') return 'bscMainnet';
return 'bscTestnet';
}
function registryAddressFor(network) {
const chainId = BNB_CHAINS[network].id;
const dep = REGISTRY_DEPLOYMENTS[chainId];
if (!dep?.identityRegistry) {
throw new RegisterRelayError(`no ERC-8004 Identity Registry deployment known for chain ${chainId}`, {
code: 'unknown_registry',
status: 500,
});
}
return dep.identityRegistry.toLowerCase();
}
/**
* Whether `address` already holds an agent on `registry`, and its id when
* resolvable.
*
* `balanceOf` is the reliable signal (standard ERC-721, confirmed live
* against the real BSC testnet Identity Registry 2026-07-08). `tokenId` is a
* best-effort enrichment: `tokenOfOwnerByIndex` requires ERC721Enumerable
* storage, and the live testnet deployment declares the function in its ABI
* but REVERTS on it (confirmed live, same date — no enumerable mapping
* wired). A registry that doesn't support enumeration must not be treated as
* "not registered" — that would let a held address slip through into a
* duplicate mint attempt — so a revert here still reports `registered: true`,
* just with `agentId: null`.
*
* @returns {Promise<{ registered: boolean, agentId: string|null }>}
*/
async function alreadyRegisteredAgentId(publicClient, registry, address) {
const balance = await publicClient.readContract({
address: registry,
abi: READ_ABI,
functionName: 'balanceOf',
args: [address],
});
if (!balance || balance === 0n) return { registered: false, agentId: null };
try {
const tokenId = await publicClient.readContract({
address: registry,
abi: READ_ABI,
functionName: 'tokenOfOwnerByIndex',
args: [address, 0n],
});
return { registered: true, agentId: tokenId.toString() };
} catch {
return { registered: true, agentId: null };
}
}
/**
* Wait (bounded) for the receipt and pull `agentId` out of the `Registered`
* (preferred) or `Transfer` (ERC-721 mint fallback) log via raw topic
* matching — sidesteps ABI-decode ambiguity entirely, same technique already
* proven in api/erc8004/register-confirm.js. On a revert, best-effort replay
* the call at the failing block to surface the actual revert reason instead
* of a bare "reverted".
*/
async function waitAndDecode(publicClient, { hash, registry, from, to, data, value }) {
let receipt;
try {
receipt = await publicClient.waitForTransactionReceipt({ hash, timeout: 25_000 });
} catch (err) {
// Real BSC block times are sub-second (00-CONTEXT verified fact #3), but a
// congested public RPC can still miss the window — surface honestly as
// pending rather than failing outright; the hash is still real and
// resolvable via any explorer/RPC once it lands.
return { pending: true, agentId: null, hash };
}
if (receipt.status === 'reverted') {
let reason = 'transaction reverted';
try {
await publicClient.call({ account: from, to, data, value: value ?? 0n, blockNumber: receipt.blockNumber });
} catch (simErr) {
reason = simErr.shortMessage || simErr.message || reason;
}
throw new RegisterRelayError(reason, { code: 'tx_reverted', status: 422 });
}
// `Registered(uint256 indexed agentId, string agentURI, address indexed owner)`
// puts agentId at topics[1] — preferred, and what the live registry always
// emits alongside Transfer on a mint. `Transfer(address indexed from,
// address indexed to, uint256 indexed tokenId)` puts tokenId at topics[3],
// NOT topics[1] (that's `from`) — a real mint emits both events in the same
// receipt with Transfer logged first, so blindly taking the first
// Registered-or-Transfer match and reading topics[1] silently decodes
// Transfer's `from` (0x0 on every mint) as the agentId. Caught live against
// the real BSC testnet registry 2026-07-08 (see PROGRESS.md) — matching
// each topic layout to its own event is load-bearing, not cosmetic.
const registeredLog = receipt.logs.find((l) => l.address?.toLowerCase() === registry && l.topics?.[0] === REGISTERED_TOPIC);
const transferLog = receipt.logs.find((l) => l.address?.toLowerCase() === registry && l.topics?.[0] === TRANSFER_TOPIC);
const agentId = registeredLog
? BigInt(registeredLog.topics[1]).toString()
: transferLog?.topics?.[3]
? BigInt(transferLog.topics[3]).toString()
: null;
return { pending: false, agentId, hash, blockNumber: Number(receipt.blockNumber) };
}
/**
* Relay a client-signed ERC-8004 `register` transaction, gaslessly when
* possible. Never signs, never touches a key — only parses and relays bytes
* it was handed.
*
* @param {object} params
* @param {string} params.signedRegisterTx 0x-prefixed, fully signed legacy raw tx
* @param {'bscMainnet'|'bscTestnet'|56|97} [params.network]
* @param {import('viem').PublicClient} [params.publicClient] injectable for tests
* @param {object} [params.megafuelOpts] forwarded to isSponsorable/submitRawTx (tests)
* @returns {Promise<object>}
*/
export async function relayGaslessRegistration({ signedRegisterTx, network, publicClient: injectedClient, megafuelOpts = {} }) {
if (typeof signedRegisterTx !== 'string' || !/^0x[0-9a-fA-F]+$/.test(signedRegisterTx)) {
throw new RegisterRelayError('signedRegisterTx must be a 0x-prefixed signed raw transaction hex', { code: 'bad_tx' });
}
const net = normalizeNetwork(network);
const registry = registryAddressFor(net);
let parsed;
try {
parsed = parseTransaction(signedRegisterTx);
} catch (err) {
throw new RegisterRelayError('could not parse the signed transaction', { code: 'bad_tx', cause: err });
}
if (!parsed.to || parsed.to.toLowerCase() !== registry) {
throw new RegisterRelayError(`transaction must call the ERC-8004 Identity Registry (${registry}) on ${net}`, { code: 'wrong_target' });
}
if (parsed.type !== 'legacy') {
throw new RegisterRelayError('sign a legacy (type 0) transaction — MegaFuel gasless relies on gasPrice, not EIP-1559 fee fields', {
code: 'bad_tx_type',
});
}
let from;
try {
from = await recoverTransactionAddress({ serializedTransaction: signedRegisterTx });
} catch (err) {
throw new RegisterRelayError('could not recover a valid signature from the transaction', { code: 'bad_signature', cause: err });
}
const publicClient = injectedClient || getPublicClient(net);
// Never double-mint — an address that already owns an agent gets its
// existing agentId back (when resolvable) instead of a broadcast attempt.
// A failed *read* (RPC hiccup) must not block a legitimate first mint, so
// only a successful `registered: true` short-circuits.
const existing = await alreadyRegisteredAgentId(publicClient, registry, from).catch(() => ({ registered: false, agentId: null }));
if (existing.registered) {
return { alreadyRegistered: true, agentId: existing.agentId, address: from, network: net };
}
const gasPrice = parsed.gasPrice ?? 0n;
const value = parsed.value ?? 0n;
if (gasPrice === 0n) {
const probe = await isSponsorable(net, { to: parsed.to, from, value, gas: parsed.gas, data: parsed.data }, megafuelOpts);
if (!probe.sponsorable) {
return {
mode: 'declined',
reason: probe.reason,
address: from,
network: net,
hint: 'MegaFuel declined to sponsor this address right now — fund it with a small amount of tBNB (~0.001) and resubmit a transaction signed with a real gasPrice to self-pay.',
};
}
let hash;
try {
const submit = megafuelOpts.submitRawTx || megafuelSubmitRawTx;
hash = await submit(net, signedRegisterTx, megafuelOpts);
} catch (err) {
throw new RegisterRelayError(`MegaFuel accepted the sponsorship probe but the sponsored send failed: ${err.message}`, {
code: 'sponsored_send_failed',
status: 502,
cause: err,
});
}
const decoded = await waitAndDecode(publicClient, { hash, registry, from, to: parsed.to, data: parsed.data, value });
return { mode: 'sponsored', address: from, network: net, sponsor: probe.sponsorInfo, ...decoded };
}
// Self-pay: the caller already re-signed with real gas — broadcast as-is.
let hash;
try {
hash = await publicClient.sendRawTransaction({ serializedTransaction: signedRegisterTx });
} catch (err) {
const msg = err.shortMessage || err.message || String(err);
const code = /insufficient funds/i.test(msg) ? 'insufficient_funds' : /nonce/i.test(msg) ? 'bad_nonce' : /already known|replacement/i.test(msg) ? 'duplicate_tx' : 'broadcast_failed';
throw new RegisterRelayError(msg, { code, status: 400, cause: err });
}
const decoded = await waitAndDecode(publicClient, { hash, registry, from, to: parsed.to, data: parsed.data, value });
return { mode: 'self-pay', address: from, network: net, ...decoded };
}