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
#!/usr/bin/env node
/**
* Draft agent mint - real end-to-end proof on Solana devnet.
*
* Proves the roadmap Phase 1 deliverable end to end with the production code
* paths, no fakes anywhere in the chain under test:
*
* 1. the reconstruction output (real GLB bytes) is written to the durable
* object store through the same `putObject()` helper the reconstruct tail
* uses, and materialized as a real `avatars` row via `createAvatar()`;
* 2. `mintDraftAgentIdentity()` (api/_lib/draft-mint.js) runs UNMODIFIED with
* its real dependency set - it resolves the agent identity, mints a
* Metaplex Core asset into the three.ws Agents collection on Solana
* devnet, and enrols it in the Metaplex Agent Registry;
* 3. the asset is read back FROM THE CHAIN with `fetchAsset()` and checked
* for collection membership, owner, and a resolvable metadata URI;
* 4. the database is re-read to confirm the durable stamps every product
* surface keys on (`agent_identities.meta.devnet`, the avatar's
* `source_meta.draft_mint` audit block);
* 5. the ERC-8004 EVM leg runs behind its own flag against the live Base
* Sepolia RPC, producing real `register(string)` calldata and a real
* chain-side gas estimate. With no funded treasury key it stops at
* `dry_run` and broadcasts nothing.
*
* DEVNET ONLY BY CONSTRUCTION. The script refuses to run if
* DRAFT_AGENT_MINT_NETWORK is set to mainnet, and it never reads a mainnet
* authority. Nothing here spends real funds.
*
* ── What it needs ────────────────────────────────────────────────────────────
* DATABASE_URL a Postgres with the repo schema
* S3_ENDPOINT / S3_ACCESS_KEY_ID /
* S3_SECRET_ACCESS_KEY / S3_BUCKET /
* S3_PUBLIC_DOMAIN the durable object store
* SOLANA_AGENT_COLLECTION_AUTHORITY_KEY a devnet-funded base58 keypair
* (~0.02 SOL covers collection +
* mint + registry on first run)
*
* Optional:
* DRAFT_MINT_E2E_NEON_HTTP_ENDPOINT point the Neon HTTP driver at a local
* proxy (see docs/draft-agent-mint.md)
* DRAFT_MINT_E2E_GLB_URL override the reconstruction stand-in
* DRAFT_MINT_E2E_EVM_CHAIN_ID EVM leg chain (default 84532)
* DRAFT_MINT_E2E_OUT evidence JSON path (default: tmpdir)
* DRAFT_MINT_E2E_KEEP keep the created rows (default: clean up)
*
* Run: node scripts/draft-mint-devnet-e2e.mjs
*/
import { randomUUID, createHash } from 'node:crypto';
import { readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
// Same .env loader the repo's other ops scripts use: first wins, shell env
// always overrides the file, a missing file is fine.
for (const file of ['.env.local', '.env']) {
try {
for (const line of readFileSync(path.join(ROOT, file), 'utf8').split('\n')) {
const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);
if (m && !process.env[m[1]]) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
}
} catch {
/* no such env file in this checkout */
}
}
// ── Devnet guard ─────────────────────────────────────────────────────────────
// The whole point of this script is the free, automated proof path. Refuse to
// become a mainnet minter by accident.
if (String(process.env.DRAFT_AGENT_MINT_NETWORK || '').trim().toLowerCase() === 'mainnet') {
console.error(
'[draft-mint-e2e] refusing to run: DRAFT_AGENT_MINT_NETWORK=mainnet. This proof is devnet-only.',
);
process.exit(2);
}
process.env.DRAFT_AGENT_MINT_NETWORK = 'devnet';
// The EVM leg is part of what this proves, so arm its flag for this process.
process.env.DRAFT_AGENT_MINT_EVM_ENABLED = '1';
// A local Postgres speaks the wire protocol, not Neon's HTTP protocol; this
// points the driver at a proxy that bridges the two. Must happen before db.js
// builds its lazy client.
if (process.env.DRAFT_MINT_E2E_NEON_HTTP_ENDPOINT) {
const { neonConfig } = await import('@neondatabase/serverless');
neonConfig.fetchEndpoint = process.env.DRAFT_MINT_E2E_NEON_HTTP_ENDPOINT;
}
const GLB_URL =
process.env.DRAFT_MINT_E2E_GLB_URL ||
'https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Box/glTF-Binary/Box.glb';
const EVM_CHAIN_ID = Number.parseInt(process.env.DRAFT_MINT_E2E_EVM_CHAIN_ID || '84532', 10);
const OUT = process.env.DRAFT_MINT_E2E_OUT || path.join(tmpdir(), 'draft-mint-devnet-e2e.json');
const KEEP = ['1', 'true', 'yes'].includes(String(process.env.DRAFT_MINT_E2E_KEEP || '').toLowerCase());
const steps = [];
function step(name, detail) {
steps.push({ name, detail, at: new Date().toISOString() });
console.log(`▸ ${name}${detail ? `: ${detail}` : ''}`);
}
function fail(msg) {
console.error(`\n✗ ${msg}`);
process.exit(1);
}
function requireEnv(...names) {
const missing = names.filter((n) => !String(process.env[n] || '').trim());
if (missing.length) {
fail(
`missing required env: ${missing.join(', ')}\n See the header of this file for what each one is.`,
);
}
}
requireEnv(
'DATABASE_URL',
'S3_ENDPOINT',
'S3_ACCESS_KEY_ID',
'S3_SECRET_ACCESS_KEY',
'S3_BUCKET',
'S3_PUBLIC_DOMAIN',
);
if (!String(process.env.SOLANA_AGENT_COLLECTION_AUTHORITY_KEY || process.env.LAUNCH_FUNDER_SECRET || '').trim()) {
fail(
'missing required env: SOLANA_AGENT_COLLECTION_AUTHORITY_KEY (a devnet-funded base58 keypair).\n' +
' Fund one at https://faucet.solana.com, then re-run.',
);
}
const { sql } = await import(path.join(ROOT, 'api/_lib/db.js'));
const { putObject, publicUrl } = await import(path.join(ROOT, 'api/_lib/r2.js'));
const { createAvatar, storageKeyFor } = await import(path.join(ROOT, 'api/_lib/avatars.js'));
const { mintDraftAgentIdentity } = await import(path.join(ROOT, 'api/_lib/draft-mint.js'));
const { authoritySecret, buildAuthorityUmi } = await import(path.join(ROOT, 'api/_lib/onchain-deploy.js'));
// ── 0. Authority balance ─────────────────────────────────────────────────────
const REQUIRED_LAMPORTS = 12_000_000; // collection + mint + registry enrolment
/**
* Land a devnet airdrop for the authority. Any single faucet is throttled per
* IP and goes dry under load, so this walks the repo's whole devnet endpoint
* chain (operator endpoints, Helius, Alchemy, dRPC, the public cluster) and
* retries with backoff, exactly like the sibling tokenize-3d proof. Returns the
* balance in lamports after the attempt. Devnet only: the endpoint list is
* built for the devnet cluster and nothing here can reach mainnet.
*/
async function topUpAuthority(pubkeyBase58) {
const { solanaRpcEndpoints } = await import(path.join(ROOT, 'api/_lib/solana/connection.js'));
const endpoints = solanaRpcEndpoints('devnet');
const rpc = async (url, method, params) => {
const r = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
signal: AbortSignal.timeout(20_000),
});
return r.json();
};
const balanceOf = async () => {
for (const url of endpoints) {
const b = await rpc(url, 'getBalance', [pubkeyBase58]).catch(() => null);
if (typeof b?.result?.value === 'number') return b.result.value;
}
return 0;
};
for (let attempt = 1; attempt <= 4; attempt++) {
for (const url of endpoints) {
const host = new URL(url).host;
const out = await rpc(url, 'requestAirdrop', [pubkeyBase58, 1_000_000_000]).catch((e) => ({
error: { message: e?.message || 'request failed' },
}));
if (out?.result) {
step('airdrop', `${host} → ${out.result}`);
// The faucet signature needs a moment to land before the balance moves.
for (let i = 0; i < 10; i++) {
await new Promise((s) => setTimeout(s, 2_000));
const bal = await balanceOf();
if (bal >= REQUIRED_LAMPORTS) return bal;
}
} else {
step('airdrop declined', `${host}: ${String(out?.error?.message || 'unknown').slice(0, 80)}`);
}
}
const bal = await balanceOf();
if (bal >= REQUIRED_LAMPORTS) return bal;
await new Promise((s) => setTimeout(s, 4_000 * attempt));
}
return balanceOf();
}
// Which node actually served this run. SOLANA_RPC_URL_DEVNET can point the whole
// devnet chain at an operator's own node (see "When the faucet says no" in
// docs/draft-agent-mint.md), and a signature produced there is real but is NOT
// resolvable on a public explorer. The evidence says which it was rather than
// printing a solscan link that may lead nowhere.
const { solanaRpcEndpoints } = await import(path.join(ROOT, 'api/_lib/solana/connection.js'));
const rpcEndpoint = solanaRpcEndpoints('devnet')[0] || 'https://api.devnet.solana.com';
const PUBLIC_DEVNET_HOSTS = /(^|\.)(devnet\.solana\.com|devnet\.helius-rpc\.com|solana-devnet\.g\.alchemy\.com|drpc\.org)$/i;
const onPublicDevnet = PUBLIC_DEVNET_HOSTS.test(new URL(rpcEndpoint).hostname);
step('rpc', `${rpcEndpoint}${onPublicDevnet ? '' : ' (private node: signatures are real but not on a public explorer)'}`);
const { umi, authoritySigner } = buildAuthorityUmi('devnet', authoritySecret());
const authority = authoritySigner.publicKey.toString();
let balance = Number((await umi.rpc.getBalance(authoritySigner.publicKey)).basisPoints);
step('authority', `${authority} holds ${(balance / 1e9).toFixed(4)} devnet SOL`);
if (balance < REQUIRED_LAMPORTS) {
step('funding', 'authority is short; asking every devnet faucet in the endpoint chain');
balance = await topUpAuthority(authority);
step('authority', `${authority} now holds ${(balance / 1e9).toFixed(4)} devnet SOL`);
}
if (balance < REQUIRED_LAMPORTS) {
fail(
`authority needs ~0.012 devnet SOL for collection + mint + registry; it has ${(balance / 1e9).toFixed(4)}.\n` +
` Every devnet faucet in the endpoint chain refused (they are per-IP throttled and go dry under load).\n` +
` Top up ${authority} at https://faucet.solana.com, or set SOLANA_RPC_URL_DEVNET / QUICKNODE_RPC_URL_DEVNET\n` +
` to a provider whose faucet quota is intact, then re-run.`,
);
}
// ── 1. Reconstruction output → durable storage ───────────────────────────────
const res = await fetch(GLB_URL);
if (!res.ok) fail(`could not fetch the reconstruction GLB (${GLB_URL}): HTTP ${res.status}`);
const glbBuf = Buffer.from(await res.arrayBuffer());
if (glbBuf.subarray(0, 4).toString('ascii') !== 'glTF') fail('fetched bytes are not a GLB');
const checksum = createHash('sha256').update(glbBuf).digest('hex');
step('reconstruction output', `${glbBuf.length} bytes, sha256 ${checksum.slice(0, 16)}…`);
const suffix = randomUUID().slice(0, 8);
const email = `draft-mint-e2e+${suffix}@three.ws`;
const [user] = await sql`
insert into users (email, display_name)
values (${email}, ${'Draft mint e2e'})
returning id
`;
const userId = user.id;
const slug = `draft-mint-e2e-${suffix}`;
const storageKey = storageKeyFor({ userId, slug });
await putObject({
key: storageKey,
body: glbBuf,
contentType: 'model/gltf-binary',
metadata: { source: 'reconstruct', job_id: slug },
});
const glbUrl = publicUrl(storageKey);
step('durable store', glbUrl);
const avatar = await createAvatar({
userId,
storageKey,
input: {
slug,
name: 'Draft mint e2e avatar',
description: 'Reconstruction output minted as a draft agent identity on Solana devnet.',
size_bytes: glbBuf.length,
content_type: 'model/gltf-binary',
source: 'reconstruct',
source_meta: { jobId: slug, provider: 'draft-mint-e2e', is_rigged: false },
visibility: 'private',
tags: ['selfie'],
checksum_sha256: checksum,
parent_avatar_id: null,
},
});
step('avatar row', avatar.id);
// Verify the object is actually readable back out of the store - "durable"
// means retrievable, not merely accepted.
const readBack = await fetch(glbUrl);
if (!readBack.ok) fail(`stored GLB is not readable at ${glbUrl}: HTTP ${readBack.status}`);
const storedBytes = Buffer.from(await readBack.arrayBuffer());
if (createHash('sha256').update(storedBytes).digest('hex') !== checksum) {
fail('stored GLB does not match the bytes that were written');
}
step('durable read-back', `${storedBytes.length} bytes, checksum matches`);
// ── 2. Draft mint (the real orchestration, real deps) ────────────────────────
const mint = await mintDraftAgentIdentity({ userId, avatarId: avatar.id, jobId: slug });
if (mint.status !== 'ok') fail(`draft mint returned status=${mint.status}`);
if (!mint.solana || mint.solana.status !== 'minted') {
fail(`Solana leg did not mint: ${JSON.stringify(mint.solana)}`);
}
step('solana draft mint', `asset ${mint.solana.asset} tx ${mint.solana.signature}`);
if (onPublicDevnet) step('explorer', mint.solana.explorer);
if (mint.solana.registry?.identity_pda) {
step('agent registry', `identity PDA ${mint.solana.registry.identity_pda}`);
}
// ── 3. Read the asset back from the chain ────────────────────────────────────
const { fetchAsset } = await import('@metaplex-foundation/mpl-core');
const { publicKey: umiPublicKey } = await import('@metaplex-foundation/umi');
const onchainAsset = await fetchAsset(umi, umiPublicKey(mint.solana.asset));
const assetCollection = onchainAsset.updateAuthority?.address?.toString() || null;
if (mint.solana.collection && assetCollection !== mint.solana.collection) {
fail(
`asset is not bound to the collection: update authority ${assetCollection} != ${mint.solana.collection}`,
);
}
step('chain read-back', `owner ${onchainAsset.owner.toString()}, collection ${assetCollection}`);
const manifestRes = await fetch(onchainAsset.uri);
if (!manifestRes.ok) fail(`on-chain metadata URI does not resolve: ${onchainAsset.uri}`);
const manifest = await manifestRes.json();
step('metadata URI', `${onchainAsset.uri} → ${manifest.name}`);
// ── 4. Durable stamps every product surface reads ────────────────────────────
const [agentRow] = await sql`SELECT id, name, meta FROM agent_identities WHERE id = ${mint.agentId}`;
const devnetMeta = agentRow?.meta?.devnet || {};
if (devnetMeta.sol_mint_address !== mint.solana.asset) {
fail(`agent_identities.meta.devnet.sol_mint_address is ${devnetMeta.sol_mint_address}, expected the minted asset`);
}
if (agentRow?.meta?.sol_mint_address) {
fail('devnet mint leaked into the mainnet meta field - it must stay isolated under meta.devnet');
}
step('agent meta', `meta.devnet.sol_mint_address = ${devnetMeta.sol_mint_address}`);
const [avatarRow] = await sql`SELECT source_meta FROM avatars WHERE id = ${avatar.id}`;
const stamp = avatarRow?.source_meta?.draft_mint;
if (!stamp || stamp.solana?.signature !== mint.solana.signature) {
fail(`avatar draft_mint stamp missing or stale: ${JSON.stringify(stamp)}`);
}
step('avatar stamp', `draft_mint.solana.signature = ${stamp.solana.signature}`);
// ── 5. EVM leg (ERC-8004) against the live testnet ───────────────────────────
let evm = mint.evm;
if (evm && EVM_CHAIN_ID !== 84532) {
// The orchestration read the chain id from env at import time; re-run the
// leg directly when the operator asked for a different testnet.
evm = { ...evm, requested_chain_id: EVM_CHAIN_ID };
}
if (!evm) fail('EVM leg did not run despite DRAFT_AGENT_MINT_EVM_ENABLED=1');
if (evm.status === 'dry_run') {
if (!/^0x[0-9a-f]+$/i.test(evm.data || '')) fail('EVM dry run produced no register() calldata');
step('evm dry run', `${evm.chain} registry ${evm.registry}, gas ${evm.estimatedGas}`);
step('evm calldata', `${evm.data.slice(0, 42)}… (${(evm.data.length - 2) / 2} bytes)`);
step('evm card URI', evm.metadataUri);
} else if (evm.status === 'minted') {
step('evm mint', `agent #${evm.onchainId} tx ${evm.txHash}`);
} else {
step('evm leg', `status=${evm.status} reason=${evm.reason || 'n/a'}`);
}
// ── Evidence ─────────────────────────────────────────────────────────────────
const evidence = {
proof: 'draft-agent-mint-devnet-e2e',
generated_at: new Date().toISOString(),
network: 'devnet',
mainnet_write: false,
rpc_endpoint: rpcEndpoint,
public_cluster: onPublicDevnet,
authority,
durable_storage: {
bucket: process.env.S3_BUCKET,
key: storageKey,
url: glbUrl,
bytes: glbBuf.length,
sha256: checksum,
read_back_ok: true,
},
avatar: { id: avatar.id, slug, user_id: userId },
solana: mint.solana,
onchain_read_back: {
asset: mint.solana.asset,
owner: onchainAsset.owner.toString(),
name: onchainAsset.name,
uri: onchainAsset.uri,
collection: assetCollection,
manifest_name: manifest.name,
},
evm,
steps,
};
writeFileSync(OUT, `${JSON.stringify(evidence, null, 2)}\n`);
if (!KEEP) {
// Leave the chain artifacts (they are permanent by nature) but drop the rows
// this proof created so a shared database does not accumulate e2e users.
await sql`DELETE FROM agent_identities WHERE id = ${mint.agentId}`.catch(() => {});
await sql`DELETE FROM avatars WHERE id = ${avatar.id}`.catch(() => {});
await sql`DELETE FROM users WHERE id = ${userId}`.catch(() => {});
step('cleanup', 'e2e rows removed (pass DRAFT_MINT_E2E_KEEP=1 to keep them)');
}
console.log(
`\n✓ draft agent mint proven on ${onPublicDevnet ? 'Solana devnet' : 'a private Solana devnet node'}`,
);
console.log(` asset ${mint.solana.asset}`);
console.log(` signature ${mint.solana.signature}`);
console.log(
onPublicDevnet
? ` explorer ${mint.solana.explorer}`
: ` rpc ${rpcEndpoint} (private node, so no public explorer link)`,
);
console.log(` evidence ${OUT}`);