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
// agora-citizens — devnet keypair cache + faucet top-up. Each citizen (and the
// internal work dispatcher) keeps a stable signing keypair under .cache/ so it
// holds the same on-chain identity across restarts. Mirrors the proven approach
// in examples/agenc-task-roundtrip/run.mjs. NEVER commit .cache/ (see .gitignore).
import { promises as fs } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { Keypair, LAMPORTS_PER_SOL, SystemProgram, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
import { log } from './log.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const CACHE_DIR = path.join(__dirname, '.cache');
function safeName(key) {
return String(key).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 80) || 'kp';
}
/** Load a cached keypair for `key`, or generate + persist a fresh one. */
export async function loadOrCreateKeypair(key) {
const file = path.join(CACHE_DIR, `${safeName(key)}.json`);
try {
const raw = await fs.readFile(file, 'utf8');
return Keypair.fromSecretKey(Uint8Array.from(JSON.parse(raw)));
} catch (err) {
if (err.code !== 'ENOENT') throw err;
await fs.mkdir(CACHE_DIR, { recursive: true });
const kp = Keypair.generate();
await fs.writeFile(file, JSON.stringify(Array.from(kp.secretKey)), { mode: 0o600 });
log.info('keypair generated', { key, pubkey: kp.publicKey.toBase58() });
return kp;
}
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
/** Parse a devnet funder secret: base58 (Phantom export) or a JSON byte array. */
export function keypairFromSecret(secret) {
const raw = String(secret).trim();
if (raw.startsWith('[')) return Keypair.fromSecretKey(Uint8Array.from(JSON.parse(raw)));
return Keypair.fromSecretKey(bs58.decode(raw));
}
let funderCache;
function loadFunder(cfg) {
if (!cfg.funderSecret) return null;
if (funderCache === undefined) {
try {
funderCache = keypairFromSecret(cfg.funderSecret);
log.info('devnet funder loaded', { pubkey: funderCache.publicKey.toBase58() });
} catch (err) {
funderCache = null;
log.error('AGORA_DEVNET_FUNDER_SECRET is not a valid keypair', { err: err?.message });
}
}
return funderCache;
}
/**
* Top a signer up from the configured devnet funder wallet. The public faucet is
* routinely dry (it answers 429 for every IP we reach it from, workstation and
* GCP alike), so an operator-supplied devnet wallet is the reliable rail: a real
* SystemProgram transfer of worthless test SOL, confirmed on-chain. Returns the
* transfer signature, or null when no funder is configured / it is too poor.
*/
async function topUpFromFunder(connection, kp, cfg, label) {
const funder = loadFunder(cfg);
if (!funder) return null;
if (funder.publicKey.equals(kp.publicKey)) return null;
const target = cfg.topupThresholdLamports + cfg.funderTopupLamports;
const bal = await connection.getBalance(kp.publicKey);
const need = target - bal;
if (need <= 0) return null;
const funderBal = await connection.getBalance(funder.publicKey);
// Leave the funder enough to pay the fee on this transfer and the next one.
if (funderBal < need + FUNDER_RESERVE_LAMPORTS) {
log.warn('devnet funder too poor to top up', {
label,
funder: funder.publicKey.toBase58(),
funderSol: funderBal / LAMPORTS_PER_SOL,
needSol: need / LAMPORTS_PER_SOL,
});
return null;
}
const tx = new Transaction().add(
SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: kp.publicKey, lamports: need }),
);
const sig = await sendAndConfirmTransaction(connection, tx, [funder], { commitment: 'confirmed' });
log.info('funder top-up confirmed', {
label,
sol: need / LAMPORTS_PER_SOL,
sig,
balance: (await connection.getBalance(kp.publicKey)) / LAMPORTS_PER_SOL,
});
return sig;
}
// Fee headroom the funder always keeps for itself (0.01 SOL covers thousands of
// devnet transfers, so a top-up never strands the funder mid-fleet).
const FUNDER_RESERVE_LAMPORTS = 10_000_000;
/**
* Keep a signer funded above cfg.topupThresholdLamports. When a devnet funder
* wallet is configured it is tried first (deterministic, and the public faucet
* is dry far more often than not); otherwise, and as a fallback, we request the
* faucet in shrinking chunks with backoff (the @solana/web3.js example-script
* pattern) before surfacing a manual-funding error. Returns the funding tx
* signature when one was performed, else null.
*/
export async function ensureBalance(connection, kp, cfg, label) {
// Nothing to keep it above: the caller funds this signer some other way.
if (!(cfg.topupThresholdLamports > 0)) return null;
// A transient RPC failure on this read is NOT a reason to drop the signer. The
// read only decides whether to top up; if we cannot tell, proceed and let the
// real transaction be the judge. Throwing here used to lose a citizen from the
// fleet for the whole process, and a rate-limited RPC lost all of them at once.
let bal = null;
for (let attempt = 0; attempt < 3; attempt++) {
try {
bal = await connection.getBalance(kp.publicKey);
break;
} catch (err) {
log.warn('balance read failed', { label, attempt: attempt + 1, err: err?.message });
await sleep(cfg.retryBaseMs * (attempt + 1));
}
}
if (bal === null) return null;
if (bal >= cfg.topupThresholdLamports) return null;
try {
const funded = await topUpFromFunder(connection, kp, cfg, label);
if (funded) return funded;
} catch (err) {
log.warn('funder top-up failed, falling back to the faucet', { label, err: err?.message });
}
const full = cfg.airdropLamports || LAMPORTS_PER_SOL;
const chunks = [full, full / 2, full / 4, full / 10];
let lastErr = null;
for (let attempt = 0; attempt < chunks.length; attempt++) {
const lamports = Math.max(Math.floor(chunks[attempt]), Math.floor(LAMPORTS_PER_SOL / 100));
try {
const sig = await connection.requestAirdrop(kp.publicKey, lamports);
await connection.confirmTransaction(sig, 'confirmed');
const newBal = await connection.getBalance(kp.publicKey);
log.info('airdrop confirmed', { label, sol: lamports / LAMPORTS_PER_SOL, sig, balance: newBal / LAMPORTS_PER_SOL });
if (newBal >= cfg.topupThresholdLamports) return sig;
} catch (err) {
lastErr = err;
const waitMs = cfg.retryBaseMs * (attempt + 1);
log.warn('airdrop attempt failed', { label, attempt: attempt + 1, err: err?.message, retryMs: waitMs });
await sleep(waitMs);
}
}
throw new Error(
`[agora-citizens] ${label}: devnet faucet exhausted retries. Fund ${kp.publicKey.toBase58()} at https://faucet.solana.com, or set AGORA_DEVNET_FUNDER_SECRET to a funded devnet wallet. Underlying: ${lastErr?.message || lastErr}`,
);
}