Skip to content

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.

18.0 KB
Raw Blame
#!/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}`);