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
// Landing race: send one signed transaction through several providers at once,
// resolve on the first real confirmation, and remember who lands.
//
// Three parts, all provider-agnostic:
//
// raceLanes runs a list of lanes concurrently with the SAME signature.
// Solana dedupes by signature, so the lanes are one transaction
// with several doors: the first lane to report a confirmed
// landing wins, the rest are aborted and counted as outpaced,
// and exactly one result is returned. A hard on-chain revert
// reported by any lane is terminal for all of them.
//
// LandingStats per provider landed / lost / outpaced counters, a latency
// average and a failure streak. The race orders lanes by recent
// success. A provider on a failure streak is skipped until a
// cheap health probe passes (the same lane-health pattern the
// generation lanes use), so a dead endpoint costs no latency.
// Counters persist through an optional store (landing_provider_stats).
//
// rpcLane a JSON-RPC provider lane: sendTransaction to the provider,
// then poll the provider's own getSignatureStatuses, so a slow
// provider genuinely loses instead of borrowing another's answer.
const FAIL_STREAK_LIMIT = 3;
const PROBE_INTERVAL_MS = 30_000;
const STATS_TTL_MS = 60_000;
const LATENCY_ALPHA = 0.3;
const RPC_POLL_MS = 400;
const RPC_REQUEST_TIMEOUT_MS = 8_000;
const COMMITMENT_OK = new Set(['confirmed', 'finalized']);
// ── stats ─────────────────────────────────────────────────────────────────────
/**
* @typedef {object} StatsRow
* @property {number} landed
* @property {number} lost errored, or finished without landing
* @property {number} outpaced was still racing when another lane landed
* @property {number} streak consecutive losses since the last landing or passed probe
* @property {number|null} latencyMs moving average send-to-landing latency
* @property {string|null} lastError
* @property {number} lastProbeAt
*/
export class LandingStats {
/**
* @param {object} o
* @param {'mainnet'|'devnet'} o.network
* @param {{ load: (network:string)=>Promise<Record<string,StatsRow>>,
* flush: (network:string, deltas:Record<string,object>)=>Promise<void> } | null} [o.store]
* @param {() => number} [o.now]
*/
constructor({ network, store = null, now = Date.now }) {
this.network = network;
this.store = store;
this.now = now;
/** @type {Map<string, StatsRow>} */
this.rows = new Map();
/** @type {Map<string, {landed:number,lost:number,outpaced:number}>} */
this.pending = new Map();
this.hydratedAt = 0;
}
row(name) {
let r = this.rows.get(name);
if (!r) {
r = { landed: 0, lost: 0, outpaced: 0, streak: 0, latencyMs: null, lastError: null, lastProbeAt: 0 };
this.rows.set(name, r);
}
return r;
}
delta(name) {
let d = this.pending.get(name);
if (!d) {
d = { landed: 0, lost: 0, outpaced: 0 };
this.pending.set(name, d);
}
return d;
}
/** Load persisted counters once per TTL. A store failure leaves in-memory stats in force. */
async hydrate() {
if (!this.store || this.now() - this.hydratedAt < STATS_TTL_MS) return;
this.hydratedAt = this.now();
try {
const loaded = await this.store.load(this.network);
for (const [name, persisted] of Object.entries(loaded || {})) {
const local = this.row(name);
const pending = this.pending.get(name) || { landed: 0, lost: 0, outpaced: 0 };
local.landed = persisted.landed + pending.landed;
local.lost = persisted.lost + pending.lost;
local.outpaced = persisted.outpaced + pending.outpaced;
if (!this.pending.has(name)) {
local.streak = persisted.streak;
local.latencyMs = persisted.latencyMs;
local.lastError = persisted.lastError;
}
}
} catch {
// best effort: the race still runs on in-memory stats
}
}
/** Landing score in (0,1): Laplace-smoothed success rate. Unknown providers start at 0.5. */
score(name) {
const r = this.rows.get(name);
if (!r) return 0.5;
return (r.landed + 1) / (r.landed + r.lost + 2);
}
/** Names sorted best-first: higher success, then lower latency. */
rank(names) {
return [...names].sort((a, b) => {
const d = this.score(b) - this.score(a);
if (Math.abs(d) > 1e-9) return d;
return (this.rows.get(a)?.latencyMs ?? Infinity) - (this.rows.get(b)?.latencyMs ?? Infinity);
});
}
/** True while a provider is on a failure streak and has not passed a probe since. */
isSkipped(name) {
const r = this.rows.get(name);
return !!r && r.streak >= FAIL_STREAK_LIMIT;
}
/** A skipped provider is probed at most once per interval. */
probeDue(name) {
const r = this.rows.get(name);
return !!r && r.streak >= FAIL_STREAK_LIMIT && this.now() - r.lastProbeAt >= PROBE_INTERVAL_MS;
}
recordLanded(name, latencyMs) {
const r = this.row(name);
r.landed += 1;
r.streak = 0;
r.lastError = null;
r.latencyMs = r.latencyMs == null ? latencyMs : Math.round(r.latencyMs * (1 - LATENCY_ALPHA) + latencyMs * LATENCY_ALPHA);
this.delta(name).landed += 1;
}
recordLost(name, err) {
const r = this.row(name);
r.lost += 1;
r.streak += 1;
r.lastError = String(err?.code || err?.message || err || 'not_landed').slice(0, 200);
this.delta(name).lost += 1;
}
recordOutpaced(name) {
this.row(name).outpaced += 1;
this.delta(name).outpaced += 1;
}
/**
* Run a provider's probe. A pass clears the streak so the provider rejoins the
* race on the next trade; a fail restarts the probe interval.
*/
async probe(name, probeFn) {
const r = this.row(name);
r.lastProbeAt = this.now();
try {
await probeFn();
r.streak = 0;
r.lastError = null;
this.delta(name);
return true;
} catch (e) {
r.lastError = `probe: ${String(e?.code || e?.message || e).slice(0, 180)}`;
return false;
}
}
/** Persist accumulated deltas. Best effort; a failed flush keeps the deltas for the next one. */
flush() {
// Serialize: a caller awaiting flush() also waits for any flush already in flight.
this.flushing = (this.flushing || Promise.resolve()).then(() => this.#flushNow());
return this.flushing;
}
async #flushNow() {
if (!this.store || this.pending.size === 0) return;
// Take the deltas before awaiting: flushes overlap (the engine flushes
// fire-and-forget after every race), and a delta left in place while an
// earlier flush is in flight would be written twice.
const taken = this.pending;
this.pending = new Map();
const batch = {};
for (const [name, d] of taken) {
const r = this.rows.get(name);
batch[name] = { ...d, streak: r?.streak ?? 0, latencyMs: r?.latencyMs ?? null, lastError: r?.lastError ?? null };
}
try {
await this.store.flush(this.network, batch);
} catch {
// keep the deltas; the next flush retries them
for (const [name, d] of taken) {
const back = this.delta(name);
back.landed += d.landed;
back.lost += d.lost;
back.outpaced += d.outpaced;
}
}
}
/** Serializable view for the stats table and the endpoint. */
snapshot() {
return [...this.rows.entries()].map(([name, r]) => ({
provider: name,
landed: r.landed,
lost: r.lost,
outpaced: r.outpaced,
streak: r.streak,
skipped: r.streak >= FAIL_STREAK_LIMIT,
successRate: Number(this.score(name).toFixed(3)),
latencyMs: r.latencyMs,
lastError: r.lastError,
}));
}
}
/**
* Postgres store for the stats. `run(text, params)` resolves to an array of rows,
* so it works with the Neon client (`sql.query`) and with an in-process Postgres.
*/
export function createSqlStatsStore(run) {
return {
async load(network) {
const rows = await run(
`select provider, landed, lost, outpaced, streak, latency_ms, last_error
from landing_provider_stats where network = $1`,
[network],
);
const out = {};
for (const r of rows) {
out[r.provider] = {
landed: Number(r.landed),
lost: Number(r.lost),
outpaced: Number(r.outpaced),
streak: Number(r.streak),
latencyMs: r.latency_ms == null ? null : Number(r.latency_ms),
lastError: r.last_error,
lastProbeAt: 0,
};
}
return out;
},
async flush(network, deltas) {
for (const [provider, d] of Object.entries(deltas)) {
await run(
`insert into landing_provider_stats
(provider, network, landed, lost, outpaced, streak, latency_ms, last_error, last_landed_at, updated_at)
values ($1, $2, $3::bigint, $4::bigint, $5::bigint, $6::integer, $7::integer, $8, case when $3::bigint > 0 then now() end, now())
on conflict (provider, network) do update set
landed = landing_provider_stats.landed + excluded.landed,
lost = landing_provider_stats.lost + excluded.lost,
outpaced = landing_provider_stats.outpaced + excluded.outpaced,
streak = excluded.streak,
latency_ms = coalesce(excluded.latency_ms, landing_provider_stats.latency_ms),
last_error = excluded.last_error,
last_landed_at = coalesce(excluded.last_landed_at, landing_provider_stats.last_landed_at),
updated_at = now()`,
[provider, network, d.landed, d.lost, d.outpaced, d.streak, d.latencyMs, d.lastError],
);
}
},
};
}
// ── race ──────────────────────────────────────────────────────────────────────
/**
* Race lanes carrying the same signed transaction.
*
* A lane is `{ name, run(signal) }` and resolves `{ landed, slot }`. It may throw:
* an error with `code: 'TX_ERR'` is an on-chain revert and ends the race for
* everyone; any other error is that lane's loss only.
*
* @returns {Promise<{ winner: {name:string, slot:number|null, ms:number}|null,
* lanes: Array<{name:string, outcome:'landed'|'lost'|'outpaced', ms:number, error:string|null}> }>}
*/
export async function raceLanes({ lanes, stats = null, now = Date.now }) {
const startedAt = now();
const controller = new AbortController();
const report = lanes.map((l) => ({ name: l.name, outcome: /** @type {'landed'|'lost'|'outpaced'|null} */ (null), ms: 0, error: null }));
let winner = null;
let revert = null;
await new Promise((resolve) => {
let open = lanes.length;
if (open === 0) return resolve();
const finish = () => {
open -= 1;
if (open === 0) resolve();
};
lanes.forEach((lane, i) => {
const settled = () => report[i].outcome !== null;
Promise.resolve()
.then(() => lane.run(controller.signal))
.then((res) => {
if (settled()) return;
report[i].ms = now() - startedAt;
if (res?.landed && !winner && !revert) {
winner = { name: lane.name, slot: res.slot ?? null, ms: report[i].ms };
report[i].outcome = 'landed';
stats?.recordLanded(lane.name, report[i].ms);
controller.abort();
resolve();
} else if (res?.landed) {
report[i].outcome = 'outpaced';
stats?.recordOutpaced(lane.name);
} else {
report[i].outcome = 'lost';
report[i].error = 'not_landed';
stats?.recordLost(lane.name, 'not_landed');
}
})
.catch((err) => {
if (settled()) return;
report[i].ms = now() - startedAt;
if (winner) {
report[i].outcome = 'outpaced';
stats?.recordOutpaced(lane.name);
return;
}
report[i].outcome = 'lost';
report[i].error = String(err?.code || err?.message || err).slice(0, 200);
if (err?.code === 'TX_ERR') {
revert = err;
controller.abort();
resolve();
return;
}
stats?.recordLost(lane.name, err);
})
.finally(finish);
});
});
// Lanes still in flight when the race ended were outpaced, not failures.
report.forEach((r, i) => {
if (r.outcome === null) {
r.outcome = 'outpaced';
r.ms = now() - startedAt;
stats?.recordOutpaced(lanes[i].name);
}
});
if (revert) throw revert;
return { winner, lanes: report };
}
// ── JSON-RPC provider lane ────────────────────────────────────────────────────
async function rpcCall(url, method, params, signal, timeoutMs = RPC_REQUEST_TIMEOUT_MS) {
const timeout = AbortSignal.timeout(timeoutMs);
const resp = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
});
if (!resp.ok) {
const err = new Error(`${method} http ${resp.status}`);
err.code = 'LANDING_HTTP';
throw err;
}
const body = await resp.json();
if (body.error) {
const err = new Error(`${method}: ${body.error.message || JSON.stringify(body.error)}`);
err.code = 'LANDING_RPC';
throw err;
}
return body.result;
}
function sleepAbortable(ms, signal) {
return new Promise((resolve) => {
const t = setTimeout(resolve, ms);
signal?.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
});
}
/**
* A lane that submits through a JSON-RPC endpoint and confirms against that same
* endpoint. `rawTx` is the serialized signed transaction.
*/
export function rpcLane({ name, url, rawTx, signature, confirmTimeoutMs = 45_000 }) {
const b64 = Buffer.from(rawTx).toString('base64');
return {
name,
async run(signal) {
await rpcCall(url, 'sendTransaction', [b64, { encoding: 'base64', skipPreflight: true, maxRetries: 0 }], signal);
const deadline = Date.now() + confirmTimeoutMs;
while (Date.now() < deadline && !signal?.aborted) {
const result = await rpcCall(url, 'getSignatureStatuses', [[signature], { searchTransactionHistory: false }], signal);
const st = result?.value?.[0];
if (st?.err) {
const e = new Error(`tx failed on-chain: ${JSON.stringify(st.err)}`);
e.code = 'TX_ERR';
throw e;
}
if (st && COMMITMENT_OK.has(st.confirmationStatus)) return { landed: true, slot: st.slot ?? null };
await sleepAbortable(RPC_POLL_MS, signal);
}
return { landed: false, slot: null };
},
};
}
/** Cheap liveness check for an rpc provider. Throws when the endpoint is not healthy. */
export function rpcProbe(url) {
return async () => {
const r = await rpcCall(url, 'getLatestBlockhash', [{ commitment: 'confirmed' }], null, 3_000);
if (!r?.value?.blockhash) throw Object.assign(new Error('no blockhash'), { code: 'LANDING_PROBE' });
};
}
// ── per-network singleton stats ───────────────────────────────────────────────
const _stats = new Map();
/** Shared stats for a network, persisted to Postgres when a database is configured. */
export function getLandingStats(network, store = defaultStore()) {
let s = _stats.get(network);
if (!s) {
s = new LandingStats({ network, store });
_stats.set(network, s);
}
return s;
}
/** Drop the shared stats (tests, and a manual reset after a provider is repaired). */
export function resetLandingStats() {
_stats.clear();
}
let _defaultStore;
function defaultStore() {
if (_defaultStore !== undefined) return _defaultStore;
_defaultStore = null;
if (process.env.DATABASE_URL) {
_defaultStore = {
async load(network) {
const { sql } = await import('./db.js');
return createSqlStatsStore((t, p) => sql(t, p)).load(network);
},
async flush(network, deltas) {
const { sql } = await import('./db.js');
return createSqlStatsStore((t, p) => sql(t, p)).flush(network, deltas);
},
};
}
return _defaultStore;
}
export const LANDING_TUNING = { FAIL_STREAK_LIMIT, PROBE_INTERVAL_MS };