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 — human citizen service (Task 08, see docs/agora.md § Citizens).
//
// A human citizen is a signed-in user living in Agora. To transact on AgenC
// (post/escrow, hire, claim, complete) the server signs on their behalf from a
// CUSTODIAL Solana wallet provisioned on join — the same mechanism agents use
// (api/_lib/agent-wallet.js). The secret is AES-256-GCM encrypted at rest in
// agora_citizens.meta and never leaves the server.
//
// Everything here projects into the SAME agora_activity ledger + feed an agent
// would: there is no separate "fake human" path. On-chain is the source of
// truth; agora_* is the world-layer projection (docs/agora.md invariant 3).
//
// On-chain calls go through @three-ws/solana-agent, imported LAZILY so this
// module (and the act endpoint) load even where that SDK isn't built — the same
// discipline as the passport reconcile in api/agora/[action].js.
import { createHash } from 'node:crypto';
import { sql } from './db.js';
import { confirmOrThrow, sendAndConfirm } from './solana/confirm.js';
import { generateSolanaAgentWallet, getSolanaAddressBalances } from './agent-wallet.js';
import { decryptSecret } from './secret-box.js';
import { TOKEN_MINT, TOKEN_DECIMALS } from './token/config.js';
import { publishFeedEvent } from './feed.js';
// AgenC devnet minAgentStake (matches examples/agenc-task-roundtrip/run.mjs).
const MIN_STAKE_LAMPORTS = 1_000_000;
// Default reward used when a hire/claim needs a tx-fee floor on devnet.
const LAMPORTS_PER_SOL = 1_000_000_000;
// Human citizens are generalists: they assert capability by actually delivering
// a real proof, so we register them with the full profession bitmap (all 8 bits)
// rather than a curated subset. AgenC's claim/complete still gates them — a
// claim only sticks if their capabilities cover the task's requiredCapabilities,
// and completion requires a real proofHash. (Mirrors the open-registry rule in
// docs/agora.md — never a hardcoded allowlist.)
const HUMAN_CAPABILITIES = 0xffn;
// Profession ↔ capability-bit map — mirrors docs/agora.md and the PROFESSIONS
// array in api/agora/[action].js (the canonical source is the doc). Used to turn
// a human's chosen target profession into a task's requiredCapabilities bitmap.
export const PROFESSION_BITS = {
fetcher: 0,
sculptor: 1,
scribe: 2,
cartographer: 3,
crier: 4,
appraiser: 5,
verifier: 6,
namekeeper: 7,
};
export function professionToCapabilityBits(profession) {
const bit = PROFESSION_BITS[String(profession || '').toLowerCase()];
if (bit == null) return 0n;
return 1n << BigInt(bit);
}
function pickRpc(cluster) {
const override = (process.env.AGENC_RPC_URL || '').trim();
if (override) return override;
if (cluster === 'devnet') return (process.env.AGENC_DEVNET_RPC_URL || process.env.SOLANA_RPC_URL_DEVNET || '').trim() || undefined;
return (process.env.SOLANA_RPC_URL || '').trim() || undefined;
}
// Deterministically scatter a citizen across the Commons plaza from a stable id
// so their home/spawn is consistent run to run (no Math.random in a projection).
function homeForId(id) {
const h = createHash('sha256').update(String(id)).digest();
const angle = (h[0] / 255) * Math.PI * 2;
const radius = 6 + (h[1] / 255) * 14; // 6..20 units from the board
return {
x: Math.round(Math.cos(angle) * radius * 100) / 100,
z: Math.round(Math.sin(angle) * radius * 100) / 100,
};
}
function shortName(user) {
return (user.display_name || user.username || 'three.ws citizen').toString().slice(0, 60);
}
// ── Citizen provisioning ──────────────────────────────────────────────────────
/**
* Idempotently get-or-create the human citizen for a signed-in user. Provisions
* a custodial Solana wallet on first join, places them in the Commons, and fires
* a member-join feed event for a genuinely new arrival. Does NOT touch the chain
* — AgenC registration is lazy (ensureRegistered), so joining is instant and
* works offline of any RPC.
*
* @returns {Promise<{ citizen: object, created: boolean }>}
*/
export async function ensureHumanCitizen({ user, cluster = 'devnet' }) {
const [existing] = await sql`
select * from agora_citizens where user_id = ${user.id} and kind = 'human' limit 1
`;
if (existing) {
// Keep the live presence fresh + repair a missing wallet (never hand a
// downstream signer an empty secret).
if (!existing.meta?.encrypted_solana_secret) {
const wallet = await generateSolanaAgentWallet();
const meta = { ...(existing.meta || {}), solana_address: wallet.address, encrypted_solana_secret: wallet.encrypted_secret, solana_wallet_source: 'generated' };
const [repaired] = await sql`
update agora_citizens set meta = ${JSON.stringify(meta)}::jsonb, last_active_at = now()
where id = ${existing.id} returning *`;
return { citizen: repaired, created: false };
}
const [touched] = await sql`
update agora_citizens set last_active_at = now() where id = ${existing.id} returning *`;
return { citizen: touched, created: false };
}
const wallet = await generateSolanaAgentWallet();
const home = homeForId(user.id);
const meta = {
solana_address: wallet.address,
encrypted_solana_secret: wallet.encrypted_secret,
solana_wallet_source: 'generated',
handle: user.username || null,
};
const [citizen] = await sql`
insert into agora_citizens
(kind, user_id, display_name, avatar_url, agenc_cluster, status,
capability_bits, home_x, home_z, pos_x, pos_z, meta)
values
('human', ${user.id}, ${shortName(user)}, ${user.avatar_url || null}, ${cluster}, 'idle',
${HUMAN_CAPABILITIES}, ${home.x}, ${home.z}, ${home.x}, ${home.z}, ${JSON.stringify(meta)}::jsonb)
returning *
`;
// A real arrival on the ticker (throttled inside the feed lib).
publishFeedEvent({
type: 'member-join',
actor: shortName(user).slice(0, 32),
handle: user.username || undefined,
}).catch(() => {});
return { citizen, created: true };
}
// ── On-chain plumbing ─────────────────────────────────────────────────────────
/** Decrypt the citizen's custodial secret into a Solana Keypair (server-only). */
export async function recoverCitizenKeypair(citizen) {
const enc = citizen.meta?.encrypted_solana_secret;
if (!enc) throw Object.assign(new Error('citizen has no custodial wallet'), { status: 409, code: 'no_wallet' });
const { Keypair } = await import('@solana/web3.js');
const secretB64 = await decryptSecret(enc);
return Keypair.fromSecretKey(Buffer.from(secretB64, 'base64'));
}
async function buildClient(cluster, signer) {
const { createAgenCClient } = await import('@three-ws/solana-agent');
return createAgenCClient({ cluster, rpcUrl: pickRpc(cluster), signer });
}
/** Solana Explorer tx URL for a cluster (mainnet drops the cluster query). */
export function explorerTx(sig, cluster) {
return cluster === 'mainnet'
? `https://explorer.solana.com/tx/${sig}`
: `https://explorer.solana.com/tx/${sig}?cluster=devnet`;
}
// The devnet faucet lives on the PUBLIC devnet endpoint. Keyed providers
// (Helius and friends) either rate-limit requestAirdrop into a 429 storm or
// don't proxy it at all, so a citizen's first bounty died with a raw
// "Attempt to debit an account but found no record of a prior credit".
const PUBLIC_DEVNET_FAUCET = 'https://api.devnet.solana.com';
// Airdrop sources to try, in order: whatever RPC we're already on, then the
// public faucet endpoint (deduped when they're the same host).
async function faucetSources(connection) {
const sources = [connection];
const current = String(connection?.rpcEndpoint || '').toLowerCase();
if (!current.includes('api.devnet.solana.com')) {
const { Connection } = await import('@solana/web3.js');
sources.push(new Connection(PUBLIC_DEVNET_FAUCET, 'confirmed'));
}
return sources;
}
// Top up a devnet wallet from the faucet with backoff: mirrors the roundtrip
// example. Mainnet never airdrops: an underfunded mainnet wallet is an honest,
// actionable error, not a silent failure. Returns the final balance; callers
// that are about to sign must gate on requireFunded(), because a rate-limited
// faucet is a normal devnet condition, not an exception.
export async function ensureDevnetBalance(connection, keypair, neededLamports) {
let bal = await connection.getBalance(keypair.publicKey);
if (bal >= neededLamports) return bal;
const sources = await faucetSources(connection);
const chunks = [LAMPORTS_PER_SOL, LAMPORTS_PER_SOL / 2, LAMPORTS_PER_SOL / 4];
for (let i = 0; i < chunks.length; i++) {
for (const src of sources) {
try {
const sig = await src.requestAirdrop(keypair.publicKey, Math.max(chunks[i], LAMPORTS_PER_SOL / 50));
// HTTP-polling confirm (no WebSocket); bounded so a dropped devnet airdrop
// falls through to the next source/chunk instead of hanging the window.
await confirmOrThrow(src, sig, 'confirmed', { timeoutMs: 30_000 });
} catch {
continue; // this source is dry/throttled: try the next one
}
bal = await connection.getBalance(keypair.publicKey);
if (bal >= neededLamports) return bal;
}
await new Promise((r) => setTimeout(r, 1500 * (i + 1)));
}
return connection.getBalance(keypair.publicKey);
}
/**
* Recover a result from a confirm timeout.
*
* web3.js gives up waiting after ~30s and throws "Transaction was not confirmed
* in 30.00 seconds. It is unknown if it succeeded or failed. Check signature X".
* On a throttled devnet that happens constantly, and treating it as a failure is
* wrong in the worst way: the work IS on-chain (escrow paid, reputation moved)
* but the world never projects it, so a citizen loses a completion they really
* earned. The signature is right there in the message, so look it up and decide
* from the ledger instead of from the timeout.
*
* @returns {Promise<{ txSignature: string } | null>} the confirmed signature, or
* null when the error is not a recoverable timeout / the tx genuinely failed.
*/
export async function recoverTimedOutSignature(connection, err) {
const msg = String(err?.message || '');
if (!/not confirmed in|unknown if it succeeded/i.test(msg)) return null;
const found = /signature\s+([1-9A-HJ-NP-Za-km-z]{80,90})/.exec(msg);
if (!found) return null;
const signature = found[1];
// Bounded poll: the tx was already submitted, we only need the ledger to catch up.
for (let i = 0; i < 5; i++) {
let status = null;
try {
const res = await connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
status = res?.value?.[0] || null;
} catch {
// transport still down: try again, then give up and let the caller 503
}
if (status?.err) return null; // it landed and FAILED: a real failure
if (status?.confirmationStatus) return { txSignature: signature };
await new Promise((r) => setTimeout(r, 2000 * (i + 1)));
}
return null;
}
/**
* Find the signature that completed a task, for a completion we know landed but
* never captured (a confirm that timed out, then a retry that correctly bounced
* off the already-consumed claim account).
*
* The chain records `completedAt` on the task, and the completing transaction is
* the worker's own signature at that block time, so the two identify each other
* without guessing. Returns null when nothing matches, which keeps the caller on
* its honest error path rather than projecting a completion we cannot evidence.
*/
export async function findCompletionSignature(connection, signerPublicKey, completedAt) {
const at = Number(completedAt || 0);
if (!at) return null;
const sigs = await connection.getSignaturesForAddress(signerPublicKey, { limit: 30 }).catch(() => []);
const hit = sigs.find((s) => !s.err && Number(s.blockTime) === at);
return hit ? hit.signature : null;
}
function fmtSol(lamports) {
return (Number(lamports) / LAMPORTS_PER_SOL).toLocaleString('en-US', { maximumFractionDigits: 4 });
}
/**
* Assert a wallet can cover `neededLamports` BEFORE anything is signed. An
* underfunded wallet is a designed, actionable state ("fund this address"), so
* it must never reach the RPC and come back as a raw simulation failure the
* caller renders as an opaque 500.
*
* Throws a typed error ({ status: 409, code: 'insufficient_funds', detail })
* that api/agora/act.js surfaces verbatim.
*/
export async function requireFunded({ connection, address, neededLamports, cluster, purpose }) {
const bal = await connection.getBalance(address);
if (bal >= neededLamports) return bal;
const walletAddress = address?.toBase58 ? address.toBase58() : String(address);
const hint = cluster === 'devnet'
? 'The devnet faucet is rate-limiting airdrops right now. Send devnet SOL to this address, or try again in a few minutes.'
: 'Send SOL to this address to cover the network fee.';
throw Object.assign(
new Error(`Your Agora wallet needs about ${fmtSol(neededLamports)} SOL to ${purpose} and holds ${fmtSol(bal)}. ${hint}`),
{
status: 409,
code: 'insufficient_funds',
detail: {
walletAddress, cluster, asset: 'SOL',
neededSol: Number((Number(neededLamports) / LAMPORTS_PER_SOL).toFixed(6)),
haveSol: Number((Number(bal) / LAMPORTS_PER_SOL).toFixed(6)),
},
},
);
}
/**
* Ensure the human citizen is registered as an AgenC agent on `cluster`, signing
* with their custodial wallet. Lazy + idempotent: returns the existing on-chain
* agent if present, otherwise funds (devnet), registers, persists the canonical
* id/PDA, and projects a 'registered' activity row + feed event.
*
* @returns {Promise<{ agentId: Uint8Array, agentIdHex: string, agentPda: string, signer: object, client: object, citizen: object }>}
*/
export async function ensureRegistered({ citizen, cluster }) {
const {
registerAgenCAgent, getAgenCAgent, deriveAgenCAgentPda, toAgenCAgentId,
buildThreewsMetadataUri, agenCAgentIdToHex,
} = await import('@three-ws/solana-agent');
const signer = await recoverCitizenKeypair(citizen);
const client = await buildClient(cluster, signer);
const label = `agora-human-${citizen.id}`;
const agentId = toAgenCAgentId(label);
const agentPda = deriveAgenCAgentPda(client, agentId);
const registered = async () => {
if (citizen.agenc_agent_pda !== agentPda.toBase58() || citizen.agenc_cluster !== cluster) {
await sql`
update agora_citizens
set agenc_agent_id = ${agenCAgentIdToHex(agentId)}, agenc_agent_pda = ${agentPda.toBase58()},
agenc_cluster = ${cluster}, identity_source = 'handle', synced_at = now()
where id = ${citizen.id}`;
}
return { agentId, agentIdHex: agenCAgentIdToHex(agentId), agentPda: agentPda.toBase58(), signer, client, citizen };
};
// RegisterAgent is NOT idempotent: a second call against a live PDA aborts the
// whole action with "account already in use", which is how a human's very first
// claim died moments after their first bounty registered them. So we must be
// certain an agent is ABSENT before registering, and three sources say so in
// descending cost order:
//
// 1. Our own projection. We write agenc_agent_pda only after a registration
// confirms, so a matching row is proof, and it costs no RPC at all, which
// keeps the hot path alive when devnet is throttling every read.
if (citizen.agenc_agent_pda === agentPda.toBase58() && citizen.agenc_cluster === cluster) {
return { agentId, agentIdHex: agenCAgentIdToHex(agentId), agentPda: agentPda.toBase58(), signer, client, citizen };
}
// 2. A decoded on-chain agent.
const existingOnChain = await getAgenCAgent(client, agentPda).catch(() => null);
if (existingOnChain) return registered();
// 3. A raw account at the PDA owned by the AgenC program. getAgenCAgent
// returns null for a decode miss AND for a transport hiccup, so absence
// has to be confirmed by a read that actually SUCCEEDED. If even this read
// fails we refuse to guess: registering blind on an unread chain is what
// produced the account-in-use abort in the first place.
let raw;
try {
raw = await client.connection.getAccountInfo(agentPda);
} catch (err) {
throw Object.assign(
new Error('Solana is not responding, so we could not confirm your on-chain citizen record. Nothing was signed. Try again in a moment.'),
{ status: 503, code: 'rpc_unavailable', detail: { retryable: true, cluster }, cause: err },
);
}
if (raw && raw.owner.equals(client.programId)) return registered();
// Fund (devnet) enough for the stake + tx fees, then register. The gate runs
// on BOTH clusters: registration stakes lamports and pays a fee either way,
// and a dry wallet must read as "fund this address", never as a simulation
// failure from inside the SDK.
const registerNeeds = MIN_STAKE_LAMPORTS + 10_000_000;
if (cluster === 'devnet') {
await ensureDevnetBalance(client.connection, signer, registerNeeds);
}
await requireFunded({
connection: client.connection, address: signer.publicKey,
neededLamports: registerNeeds, cluster, purpose: 'register you as a citizen on-chain',
});
const metadataUri = buildThreewsMetadataUri({ handle: citizen.meta?.handle || citizen.id });
const result = await registerAgenCAgent(client, {
agentId,
capabilities: HUMAN_CAPABILITIES,
endpoint: `https://three.ws/agora/citizen/${citizen.id}`,
metadataUri,
stakeAmount: MIN_STAKE_LAMPORTS,
});
const idHex = agenCAgentIdToHex(agentId);
await sql`
update agora_citizens
set agenc_agent_id = ${idHex}, agenc_agent_pda = ${result.agentPda.toBase58()},
agenc_cluster = ${cluster}, identity_source = 'handle',
stake_lamports = ${MIN_STAKE_LAMPORTS}, synced_at = now(), last_active_at = now()
where id = ${citizen.id}`;
await projectActivity({
citizenId: citizen.id,
kind: 'registered',
txSignature: result.txSignature,
narrative: `${citizen.display_name} joined Agora as a citizen.`,
worldX: citizen.home_x, worldZ: citizen.home_z,
});
publishFeedEvent({
type: 'agora-registered',
actor: citizen.display_name.slice(0, 32),
citizenId: citizen.id,
agentPda: result.agentPda.toBase58(),
profession: citizen.profession || null,
narrative: `${citizen.display_name} joined Agora`,
}).catch(() => {});
return { agentId, agentIdHex: idHex, agentPda: result.agentPda.toBase58(), signer, client, citizen };
}
// ── Projection writers ────────────────────────────────────────────────────────
/**
* Append an agora_activity row. Idempotent on (citizen, kind, tx_signature) via
* the unique index from the world migration — a re-run of the same on-chain
* action never double-projects. Returns the row (or the existing one on conflict).
*/
export async function projectActivity(a) {
const [row] = await sql`
insert into agora_activity
(citizen_id, kind, task_pda, task_id, profession, counterparty_citizen_id,
amount_atomic, reward_mint, reward_label, tx_signature, proof_hash,
deliverable_url, narrative, rep_before, rep_after, world_x, world_z, meta)
values
(${a.citizenId}, ${a.kind}, ${a.taskPda || null}, ${a.taskId || null},
${a.profession || null}, ${a.counterpartyCitizenId || null},
${a.amountAtomic != null ? a.amountAtomic : null}, ${a.rewardMint || null},
${a.rewardLabel || null}, ${a.txSignature || null}, ${a.proofHash || null},
${a.deliverableUrl || null}, ${a.narrative}, ${a.repBefore ?? null},
${a.repAfter ?? null}, ${a.worldX ?? null}, ${a.worldZ ?? null},
${JSON.stringify(a.meta || {})}::jsonb)
on conflict (citizen_id, kind, tx_signature) where tx_signature is not null
do nothing
returning *
`;
return row || null;
}
/** Patch a citizen's cumulative world stats + live status. */
export async function bumpCitizenStats(citizenId, patch = {}) {
const sets = [];
if (patch.status) sets.push(sql`status = ${patch.status}`);
if (patch.incPosted) sets.push(sql`tasks_posted = tasks_posted + ${patch.incPosted}`);
if (patch.incCompleted) sets.push(sql`tasks_completed = tasks_completed + ${patch.incCompleted}`);
if (patch.addEarnedAtomic) sets.push(sql`earned_three_atomic = earned_three_atomic + ${patch.addEarnedAtomic}`);
if (patch.setReputation != null) sets.push(sql`reputation = ${patch.setReputation}`);
sets.push(sql`last_active_at = now()`);
let assignment = sets[0];
for (let i = 1; i < sets.length; i++) assignment = sql`${assignment}, ${sets[i]}`;
const [row] = await sql`update agora_citizens set ${assignment} where id = ${citizenId} returning *`;
return row;
}
// ── Read helpers ──────────────────────────────────────────────────────────────
/**
* Read the citizen's live custodial balances. Returns SOL always, plus $THREE on
* mainnet (the economy's coin). Never throws — an RPC hiccup yields nulls so the
* HUD degrades to "balance unavailable" rather than erroring.
*/
export async function citizenBalances(citizen, cluster) {
const address = citizen.meta?.solana_address;
if (!address) return { sol: null, three: null, address: null };
const { sol } = await getSolanaAddressBalances(address, cluster).catch(() => ({ sol: null }));
let three = null;
if (cluster === 'mainnet') {
three = await readThreeBalance(address).catch(() => null);
}
return { sol, three, address };
}
async function readThreeBalance(address) {
const { PublicKey } = await import('@solana/web3.js');
const { getAssociatedTokenAddressSync } = await import('@solana/spl-token');
const { solanaConnection } = await import('./agent-pumpfun.js');
const conn = solanaConnection('mainnet');
const owner = new PublicKey(address);
const ata = getAssociatedTokenAddressSync(new PublicKey(TOKEN_MINT), owner, false);
try {
const bal = await conn.getTokenAccountBalance(ata);
return bal?.value?.uiAmount ?? 0;
} catch {
return 0; // no ATA yet → zero $THREE
}
}
/** $THREE atomic-units multiplier as a BigInt. */
export const THREE_ATOMICS_PER_TOKEN = 10n ** BigInt(TOKEN_DECIMALS);
/** Human label for a reward, e.g. "25,000 $THREE" or "0.05 SOL". */
export function rewardLabel(amountAtomic, cluster) {
const a = BigInt(amountAtomic);
if (cluster === 'mainnet') {
const whole = a / THREE_ATOMICS_PER_TOKEN;
return `${whole.toLocaleString('en-US')} $THREE`;
}
const sol = Number(a) / LAMPORTS_PER_SOL;
return `${sol} SOL`;
}
/** sha256(deliverable) as a 32-byte hex proof, the same shape AgenC expects. */
export function proofHashFor(deliverable) {
return createHash('sha256').update(String(deliverable), 'utf8').digest('hex');
}
// SPL Memo program — the canonical way to write a small, signed, on-chain note.
const MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
/**
* Leave a real on-chain attestation (a signed SPL-memo transaction) from the
* citizen's custodial wallet. Used by `vouch`: a verifiable, cheap, permanent
* record that this citizen attested to another's work — the on-chain proof the
* agora_vouches edge and the 'vouched' activity row cite. Returns the tx sig.
*/
export async function sendOnchainAttestation({ cluster, signer, memo }) {
const { Transaction, TransactionInstruction, PublicKey } = await import('@solana/web3.js');
const { solanaConnection } = await import('./solana/connection.js');
// The cluster's configured RPC (AGENC_RPC_URL / SOLANA_RPC_URL*) stays primary;
// the shared failover chain for that network rotates in behind it.
const conn = solanaConnection({
url: pickRpc(cluster) || null,
network: cluster === 'devnet' ? 'devnet' : 'mainnet',
commitment: 'confirmed',
});
if (cluster === 'devnet') await ensureDevnetBalance(conn, signer, 5_000_000);
const ix = new TransactionInstruction({
keys: [{ pubkey: signer.publicKey, isSigner: true, isWritable: false }],
programId: new PublicKey(MEMO_PROGRAM_ID),
data: Buffer.from(String(memo).slice(0, 500), 'utf8'),
});
const tx = new Transaction().add(ix);
// HTTP-polling send+confirm (no WebSocket subscription).
return sendAndConfirm(conn, tx, [signer], { commitment: 'confirmed' });
}