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
/**
* MegaFuel gasless-send client for BNB Chain, with a mandatory self-pay fallback.
*
* The crown-jewel BNB capability: a plain private-key EOA can send a transaction
* that pays ZERO gas, sponsored at the block-building layer (BEP-414 paymaster +
* BEP-322 atomic bundles), operated by NodeReal's MegaFuel. No smart account, no
* 7702 delegation — mechanically impossible on Ethereum L1 / Base.
*
* Two RPC methods do the whole job (`pm_isSponsorable`, `eth_sendRawTransaction`
* against the paymaster endpoint), so rather than pull `megafuel-js-sdk` into the
* serverless bundle we call them directly via `fetch` — same rationale as
* `erc8004-chains.js` keeping the bundle lean. If MegaFuel declines or is down we
* self-pay through the prompt-01 public client, so a send NEVER hard-fails on the
* sponsorship path alone (00-CONTEXT: outage → self-pay).
*
* This module never reads a private key. The caller passes a viem account
* (built from its own signer), and signing happens through that account.
*/
import { getPublicClient } from './chains.js';
/** MegaFuel paymaster endpoints (00-CONTEXT). No secret required for reads/self-pay. */
export const MEGAFUEL_ENDPOINTS = {
bscMainnet: 'https://bsc-megafuel.nodereal.io',
bscTestnet: 'https://bsc-megafuel-testnet.nodereal.io',
};
const DEFAULT_TIMEOUT_MS = 8000;
/** Typed error for MegaFuel/self-pay failures. `code` disambiguates the stage. */
export class MegaFuelError extends Error {
/** @param {string} message @param {{ code?: string, cause?: unknown, mode?: string }} [info] */
constructor(message, info = {}) {
super(message);
this.name = 'MegaFuelError';
this.code = info.code || 'megafuel_error';
this.mode = info.mode;
if (info.cause) this.cause = info.cause;
}
}
function normalizeNetwork(network) {
if (network === 56 || network === '56' || network === 'bsc' || network === 'mainnet' || network === 'bscMainnet') return 'bscMainnet';
return 'bscTestnet';
}
/**
* Resolve the MegaFuel endpoint for `pm_isSponsorable` / `eth_sendRawTransaction`.
* Per NodeReal's docs these two RPC methods live at the plain `bsc-megafuel(-testnet)`
* base URL always — there is no API-key path segment for them. `NODEREAL_MEGAFUEL_KEY`
* is only used by the separate policy-*management* endpoint
* (`open-platform-ap.nodereal.io/{apikey}/megafuel(-testnet)`, `pm_createPolicy` /
* `pm_updatePolicy` — a one-time sponsor setup step, not implemented here).
* Sponsorship itself is resolved server-side purely by matching the tx's `from`
* address against an already-provisioned policy, so this send path needs no key.
*/
export function megafuelEndpoint(network) {
const key = normalizeNetwork(network);
return MEGAFUEL_ENDPOINTS[key];
}
/** Low-level JSON-RPC POST with a bounded timeout. Injectable `fetchImpl` for tests. */
async function rpc(url, method, params, { fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetchImpl(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
signal: controller.signal,
});
if (!res.ok) throw new MegaFuelError(`MegaFuel HTTP ${res.status}`, { code: 'http_error' });
const json = await res.json();
if (json.error) throw new MegaFuelError(json.error.message || 'rpc error', { code: 'rpc_error', cause: json.error });
return json.result;
} finally {
clearTimeout(timer);
}
}
/** Shape a viem tx request into the paymaster's expected JSON tx object. */
function toPaymasterTx(tx, from) {
const hex = (v) => (v == null ? undefined : typeof v === 'bigint' ? `0x${v.toString(16)}` : v);
return {
from,
to: tx.to,
value: hex(tx.value ?? 0n) ?? '0x0',
gas: hex(tx.gas),
data: tx.data || '0x',
};
}
/**
* Ask MegaFuel whether it will sponsor a tx. A policy "no" is a NORMAL answer,
* not an error — this never throws on a decline.
*
* @param {'bscMainnet'|'bscTestnet'|56|97} network
* @param {{ to:string, from?:string, value?:bigint|string, gas?:bigint|string, data?:string }} txRequest
* @param {{ fetchImpl?:Function, timeoutMs?:number, megafuelRpc?:Function }} [opts]
* @returns {Promise<{ sponsorable:boolean, sponsorInfo:object|null, reason:string|null }>}
*/
export async function isSponsorable(network, txRequest, opts = {}) {
const key = normalizeNetwork(network);
const call = opts.megafuelRpc
? (method, params) => opts.megafuelRpc(method, params)
: (method, params) => rpc(megafuelEndpoint(key), method, params, opts);
try {
const result = await call('pm_isSponsorable', [toPaymasterTx(txRequest, txRequest.from)]);
const sponsorable = !!(result && result.sponsorable);
return {
sponsorable,
sponsorInfo: sponsorable ? result : null,
reason: sponsorable ? null : result?.reason || result?.message || 'not sponsorable',
};
} catch (err) {
// Wire/endpoint failure is treated as "not sponsorable" so the caller
// silently self-pays. The reason is surfaced for observability.
return { sponsorable: false, sponsorInfo: null, reason: `probe failed: ${err.message}` };
}
}
/**
* Send a transaction gaslessly via MegaFuel when sponsorable, else self-pay.
* The self-pay fallback is mandatory: a policy decline, a MegaFuel 5xx, or a
* timeout all resolve to a normal self-paid send. Only a genuinely failed
* self-pay (no gas / revert) raises a typed error.
*
* @param {'bscMainnet'|'bscTestnet'|56|97} network
* @param {{ account: import('viem').Account, tx: { to:string, value?:bigint, data?:string, gas?:bigint } }} params
* `account` is a viem account (caller-owned signer); no key is read here.
* @param {{
* publicClient?: import('viem').PublicClient,
* walletClient?: import('viem').WalletClient,
* megafuelRpc?: Function, fetchImpl?: Function, timeoutMs?: number,
* }} [opts]
* @returns {Promise<{ hash:`0x${string}`, mode:'sponsored'|'self-pay', sponsor?:object|null, reason?:string|null }>}
*/
export async function sendGasless(network, { account, tx }, opts = {}) {
const key = normalizeNetwork(network);
if (!account || typeof account.signTransaction !== 'function') {
throw new MegaFuelError('sendGasless requires a viem account with signTransaction', { code: 'bad_signer' });
}
if (!tx || !tx.to || !/^0x[0-9a-fA-F]{40}$/.test(tx.to)) {
throw new MegaFuelError('sendGasless requires tx.to to be a valid address', { code: 'bad_tx' });
}
const publicClient = opts.publicClient || getPublicClient(key);
const chainId = BNB_CHAIN_ID[key];
// Try the sponsored path first.
const probe = await isSponsorable(
key,
{ to: tx.to, from: account.address, value: tx.value, gas: tx.gas, data: tx.data },
opts,
);
if (probe.sponsorable) {
try {
const nonce = await publicClient.getTransactionCount({ address: account.address, blockTag: 'pending' });
const gas = tx.gas ?? (await publicClient.estimateGas({ account, to: tx.to, value: tx.value ?? 0n, data: tx.data }));
// gasPrice: 0 is the whole trick — the sponsor tx pays for inclusion.
const signed = await account.signTransaction({
to: tx.to,
value: tx.value ?? 0n,
data: tx.data || '0x',
gas,
gasPrice: 0n,
nonce,
chainId,
});
const call = opts.megafuelRpc
? (m, p) => opts.megafuelRpc(m, p)
: (m, p) => rpc(megafuelEndpoint(key), m, p, opts);
const hash = await call('eth_sendRawTransaction', [signed]);
return { hash, mode: 'sponsored', sponsor: probe.sponsorInfo };
} catch (err) {
// MegaFuel accepted the probe but the raw send failed → fall through
// to self-pay rather than hard-failing.
return selfPay(key, { account, tx }, publicClient, opts, `sponsored send failed: ${err.message}`);
}
}
return selfPay(key, { account, tx }, publicClient, opts, probe.reason);
}
/**
* Relay an ALREADY-SIGNED raw transaction through MegaFuel's paymaster
* `eth_sendRawTransaction`, without touching a private key or building the
* transaction ourselves. `sendGasless()` above signs internally via a
* server-held viem Account — the right shape for a demo/ops account (e.g. the
* anvil-fork proof in the prompt-02 PROGRESS entry), but wrong for a flow
* where the CLIENT signs (browser wallet or an in-page ephemeral key) and the
* server only ever sees bytes it can relay, never a key. That's exactly the
* gasless ERC-8004 registration relay (api/_lib/bnb/erc8004-gasless.js,
* prompt 03) needs: this is the low-level primitive `sendGasless` doesn't
* expose.
*
* @param {'bscMainnet'|'bscTestnet'|56|97} network
* @param {`0x${string}`} signedTx RLP-encoded, fully signed raw transaction hex
* @param {{ megafuelRpc?:Function, fetchImpl?:Function, timeoutMs?:number }} [opts]
* @returns {Promise<`0x${string}`>} transaction hash
*/
export async function submitRawTx(network, signedTx, opts = {}) {
if (typeof signedTx !== 'string' || !/^0x[0-9a-fA-F]+$/.test(signedTx)) {
throw new MegaFuelError('submitRawTx requires a 0x-prefixed signed raw transaction hex', { code: 'bad_raw_tx' });
}
const key = normalizeNetwork(network);
const call = opts.megafuelRpc
? (m, p) => opts.megafuelRpc(m, p)
: (m, p) => rpc(megafuelEndpoint(key), m, p, opts);
return call('eth_sendRawTransaction', [signedTx]);
}
/** Self-pay path: a normal, gas-paying send via the standard public/wallet client. */
async function selfPay(network, { account, tx }, publicClient, opts, reason) {
try {
let walletClient = opts.walletClient;
if (!walletClient) {
const { createWalletClient, http } = await import('viem');
walletClient = createWalletClient({
account,
chain: publicClient.chain,
transport: http(publicClient.bnbRpcs?.[0]),
});
}
const hash = await walletClient.sendTransaction({
account,
to: tx.to,
value: tx.value ?? 0n,
data: tx.data || '0x',
gas: tx.gas,
});
return { hash, mode: 'self-pay', reason };
} catch (err) {
throw new MegaFuelError(`self-pay send failed: ${err.shortMessage || err.message}`, {
code: 'self_pay_failed',
mode: 'self-pay',
cause: err,
});
}
}
const BNB_CHAIN_ID = { bscMainnet: 56, bscTestnet: 97 };