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
// Draft agent mint - roadmap Phase 1 deliverable: every successful
// reconstruction output is not only persisted to durable storage (R2, done by
// reconstruct-finalize.js) but also minted as a DRAFT on-chain agent identity.
//
// Solana leads: the draft identity is a Metaplex Core asset minted into the
// three.ws Agent Collection, reusing the exact machinery of the batch deployer
// (api/_lib/onchain-deploy.js) so a draft mint is indistinguishable in shape
// from any other platform mint - collection membership, brand attributes,
// royalties, and Metaplex Agent Registry enrolment included.
//
// Network policy (the spend gate):
// • DRAFT_AGENT_MINT_NETWORK = devnet (default) | mainnet | off
// Devnet is the automated proof path: it runs whenever an authority secret
// is configured and costs nothing real. MAINNET IS NEVER IMPLICIT - it
// activates only when an operator explicitly sets
// DRAFT_AGENT_MINT_NETWORK=mainnet AND funds
// SOLANA_AGENT_COLLECTION_AUTHORITY_KEY on mainnet. That single flag is the
// documented mainnet switch.
// • Without an authority secret the leg reports 'skipped' - a no-op, so a
// deployment without mint credentials behaves exactly as before.
//
// EVM leg (ERC-8004): behind DRAFT_AGENT_MINT_EVM_ENABLED=1 with
// DRAFT_AGENT_MINT_EVM_CHAIN_ID (default 84532, Base Sepolia). It registers the
// agent's card URI through the canonical Identity Registry from the agent's own
// custodial EVM wallet, gas topped up from EVM_TREASURY_PRIVATE_KEY. With no
// treasury key configured the leg is fully dry-run: it builds the real
// register(string) calldata and estimates it against the chain's public RPC,
// proving the wiring without broadcasting.
//
// The whole orchestration is best-effort by contract: callers (the
// reconstruction finalize path) must treat a throw as non-fatal. Idempotent:
// an agent already minted on a network short-circuits to 'already'.
import { sql } from './db.js';
import { env } from './env.js';
import { resolveOrCreateAgentForAvatar } from './agent-identity.js';
export const DRAFT_MINT_NETWORKS = /** @type {const} */ (['devnet', 'mainnet']);
/**
* Resolve the Solana draft-mint network. Devnet is the default automated path;
* mainnet requires an explicit opt-in; 'off' disables the leg entirely.
* @param {NodeJS.ProcessEnv} [e]
* @returns {'devnet'|'mainnet'|'off'}
*/
export function resolveDraftMintNetwork(e = process.env) {
const v = String(e.DRAFT_AGENT_MINT_NETWORK || 'devnet').trim().toLowerCase();
if (v === 'off' || v === 'disabled' || v === '0') return 'off';
if (v === 'mainnet') return 'mainnet';
return 'devnet';
}
/**
* Resolve the EVM (ERC-8004) leg configuration. Off unless explicitly enabled.
* @param {NodeJS.ProcessEnv} [e]
* @returns {{ enabled: boolean, chainId: number }}
*/
export function resolveDraftMintEvm(e = process.env) {
const enabled = ['1', 'true', 'yes', 'on'].includes(
String(e.DRAFT_AGENT_MINT_EVM_ENABLED || '').trim().toLowerCase(),
);
const chainId = Number.parseInt(e.DRAFT_AGENT_MINT_EVM_CHAIN_ID || '84532', 10);
return { enabled, chainId: Number.isFinite(chainId) ? chainId : 84532 };
}
// ── Context loading ──────────────────────────────────────────────────────────
/**
* Load the agent row joined with its avatar's storage keys - the exact shape
* deployAgentOnce() (onchain-deploy.js) consumes.
*/
async function loadAgentContext(agentId) {
const [row] = await sql`
SELECT ai.id, ai.user_id, ai.name, ai.description, ai.meta, ai.avatar_id,
av.thumbnail_key, av.storage_key
FROM agent_identities ai
LEFT JOIN avatars av ON av.id = ai.avatar_id AND av.deleted_at IS NULL
WHERE ai.id = ${agentId} AND ai.deleted_at IS NULL
LIMIT 1
`;
return row || null;
}
// ── Solana leg (Metaplex Core) ───────────────────────────────────────────────
/** True when the agent already carries a minted identity on this network. */
function alreadyMintedOn(meta, network) {
if (network === 'mainnet') return !!meta?.sol_mint_address;
return !!meta?.devnet?.sol_mint_address;
}
export async function solanaDraftMint({ agent, network }) {
if (alreadyMintedOn(agent.meta, network)) {
const asset =
network === 'mainnet' ? agent.meta.sol_mint_address : agent.meta.devnet.sol_mint_address;
return { status: 'already', network, asset };
}
// Late import: the Umi/mpl-core stack is heavy and only needed on the mint
// path, never for flag parsing or the EVM leg.
const {
authoritySecret,
buildAuthorityUmi,
resolveAgentCollection,
loadCollectionAsset,
deployAgentOnce,
explorerUrl,
} = await import('./onchain-deploy.js');
if (!authoritySecret()) {
return { status: 'skipped', reason: 'authority_unconfigured', network };
}
const { umi, authoritySigner } = buildAuthorityUmi(network);
const collectionAddr = await resolveAgentCollection({ umi, authoritySigner, network });
const collectionAsset = await loadCollectionAsset(umi, collectionAddr);
const result = await deployAgentOnce({
umi,
authoritySigner,
collectionAddr,
collectionAsset,
agent,
network,
});
return {
status: 'minted',
network,
asset: result.asset,
signature: result.signature,
collection: collectionAddr,
owner: result.ownerAddress,
explorer: explorerUrl(result.asset, network),
registry: result.registry
? { identity_pda: result.registry.identityPda, signature: result.registry.signature }
: null,
};
}
// ── EVM leg (ERC-8004 Identity Registry) ─────────────────────────────────────
const ERC8004_REGISTER_ABI = [
'function register(string) returns (uint256)',
'event Registered(uint256 indexed agentId, string metadataURI, address indexed owner)',
];
/** Gas floor for the agent's custodial EVM wallet before it can self-sign. */
const EVM_GAS_FLOOR_WEI = 250_000_000_000_000n; // 0.00025 native
function evmExplorerTx(chain, txHash) {
return chain.explorer ? `${chain.explorer}/tx/${txHash}` : null;
}
/** Build the agent card the registry URI resolves to (three.ws Card v1 shape). */
function buildDraftAgentCard({ agent, origin, publicUrl, thumbnailUrl }) {
const image = thumbnailUrl(agent.thumbnail_key) || `${origin}/og.png`;
const glb = agent.storage_key ? publicUrl(agent.storage_key) : null;
return {
name: agent.name || 'Agent',
description: agent.description || `${agent.name || 'Agent'}, an autonomous agent on three.ws`,
image,
url: `${origin}/agents/${agent.id}`,
active: false, // draft identity: registered on-chain, not yet live
x402Support: true,
services: glb ? [{ name: 'avatar', endpoint: glb, type: 'model/gltf-binary' }] : [],
};
}
/**
* Pin the draft card: real IPFS when a provider is configured, else the R2
* manifest fallback (same policy as onchain-deploy's pinManifest).
*/
async function pinDraftCard(card, agentId) {
const bytes = Buffer.from(JSON.stringify(card, null, 2), 'utf-8');
const { pinToIPFS } = await import('./ipfs-pin.js');
const pinned = await pinToIPFS(bytes, `agent-${agentId}.json`).catch(() => null);
if (pinned?.uri) return pinned.uri;
const { putObject, publicUrl } = await import('./r2.js');
const key = `agent-manifests/draft-evm/${agentId}.json`;
await putObject({ key, body: bytes, contentType: 'application/json' });
return publicUrl(key);
}
export async function evmDraftMint({ agent, userId, chainId }) {
const { CHAIN_BY_ID } = await import('./erc8004-chains.js');
const chain = CHAIN_BY_ID[chainId];
if (!chain) return { status: 'skipped', reason: 'unsupported_chain', chainId };
if (agent.meta?.onchain?.chain === `eip155:${chainId}` && agent.meta.onchain.onchain_id) {
return {
status: 'already',
chainId,
onchainId: agent.meta.onchain.onchain_id,
txHash: agent.meta.onchain.tx_hash || null,
};
}
const { evmFallbackProvider } = await import('./evm/rpc.js');
const { getOrCreateAgentEvmWallet, recoverAgentKey } = await import('./agent-wallet.js');
const { address: evmAddress } = await getOrCreateAgentEvmWallet(agent.id, { chainId });
const provider = await evmFallbackProvider(chainId);
const { publicUrl, thumbnailUrl } = await import('./r2.js');
const card = buildDraftAgentCard({ agent, origin: env.APP_ORIGIN, publicUrl, thumbnailUrl });
const metadataUri = await pinDraftCard(card, agent.id);
const { Contract, Wallet, Interface, parseEther, formatEther } = await import('ethers');
const iface = new Interface(ERC8004_REGISTER_ABI);
const data = iface.encodeFunctionData('register(string)', [metadataUri]);
const treasurySecret = (process.env.EVM_TREASURY_PRIVATE_KEY || '').trim();
if (!treasurySecret) {
// Dry-run proof path: the calldata is real, the chain is reachable, and
// the estimate is produced by the chain itself. Nothing is broadcast.
let estimatedGas = null;
try {
estimatedGas = (
await provider.estimateGas({ from: evmAddress, to: chain.registry, data, gasPrice: 0 })
).toString();
} catch (err) {
estimatedGas = `unavailable: ${err?.shortMessage || err?.message || 'estimate failed'}`;
}
return {
status: 'dry_run',
chainId,
chain: chain.name,
registry: chain.registry,
from: evmAddress,
to: chain.registry,
data,
metadataUri,
estimatedGas,
missing: 'EVM_TREASURY_PRIVATE_KEY',
};
}
// Fund the agent wallet for gas from the EVM treasury when it is light.
const treasury = new Wallet(treasurySecret, provider);
const bal = await provider.getBalance(evmAddress);
if (bal < EVM_GAS_FLOOR_WEI) {
const topUp = EVM_GAS_FLOOR_WEI - bal;
const tbal = await provider.getBalance(treasury.address);
if (tbal < topUp + parseEther('0.0001')) {
return {
status: 'skipped',
reason: `treasury_low:${formatEther(tbal)}`,
chainId,
};
}
const fundTx = await treasury.sendTransaction({ to: evmAddress, value: topUp });
await fundTx.wait();
}
const full = await loadAgentContext(agent.id);
const encKey = full?.meta?.encrypted_wallet_key;
if (!encKey) return { status: 'skipped', reason: 'no_evm_key', chainId };
const pkHex = await recoverAgentKey(encKey, {
agentId: agent.id,
userId,
reason: 'draft_agent_mint',
});
const signer = new Wallet(pkHex, provider);
const registry = new Contract(chain.registry, ERC8004_REGISTER_ABI, signer);
const tx = await registry['register(string)'](metadataUri);
const receipt = await tx.wait();
let onChainId = null;
for (const lg of receipt.logs || []) {
try {
const parsed = registry.interface.parseLog(lg);
if (parsed?.name === 'Registered') {
onChainId = parsed.args[0].toString();
break;
}
} catch { /* not our event */ }
}
if (!onChainId) throw new Error('Registered event not found in draft-mint receipt');
// Persist exactly what register-confirm.js persists after verifying a mint:
// the crawler index row plus the unified meta.onchain block on the agent.
await sql`
INSERT INTO erc8004_agents_index
(chain_id, agent_id, owner, registry, agent_uri,
registered_block, registered_tx, registered_at, last_seen_at)
VALUES
(${chainId}, ${onChainId}, ${evmAddress.toLowerCase()}, ${chain.registry.toLowerCase()},
${metadataUri}, ${Number(receipt.blockNumber)}, ${receipt.hash}, now(), now())
ON CONFLICT (chain_id, agent_id) DO NOTHING
`;
const [cur] = await sql`SELECT meta FROM agent_identities WHERE id = ${agent.id}`;
const onchain = {
chain: `eip155:${chainId}`,
family: 'evm',
tx_hash: receipt.hash,
onchain_id: onChainId,
contract_or_mint: chain.registry,
wallet: evmAddress.toLowerCase(),
metadata_uri: metadataUri,
draft: true,
confirmed_at: new Date().toISOString(),
};
await sql`
UPDATE agent_identities
SET meta = ${JSON.stringify({ ...(cur?.meta || {}), onchain })}::jsonb, updated_at = NOW()
WHERE id = ${agent.id}
`;
return {
status: 'minted',
chainId,
chain: chain.name,
registry: chain.registry,
onchainId: onChainId,
owner: evmAddress,
txHash: receipt.hash,
metadataUri,
explorer: evmExplorerTx(chain, receipt.hash),
};
}
// ── Avatar traceability ──────────────────────────────────────────────────────
/** Stamp the draft-mint outcome onto the avatar's source_meta for audit. */
async function persistAvatarDraft({ avatarId, jobId, solana, evm }) {
const stamp = {
draft_mint: {
job_id: jobId,
solana: solana
? { status: solana.status, network: solana.network, asset: solana.asset || null, signature: solana.signature || null }
: null,
evm: evm
? { status: evm.status, chain_id: evm.chainId ?? null, onchain_id: evm.onchainId || null, tx_hash: evm.txHash || null }
: null,
minted_at: new Date().toISOString(),
},
};
await sql`
UPDATE avatars
SET source_meta = coalesce(source_meta, '{}'::jsonb) || ${JSON.stringify(stamp)}::jsonb
WHERE id = ${avatarId}
`;
}
// ── Orchestration ────────────────────────────────────────────────────────────
function defaultDeps() {
return {
resolveAgent: resolveOrCreateAgentForAvatar,
loadAgentContext,
solanaMint: solanaDraftMint,
evmMint: evmDraftMint,
persistAvatarDraft,
network: resolveDraftMintNetwork(),
evm: resolveDraftMintEvm(),
};
}
/**
* Mint the draft on-chain identity for a freshly reconstructed avatar.
*
* @param {object} input
* @param {string} input.userId owner of the avatar
* @param {string} input.avatarId the materialized reconstruction avatar
* @param {string} [input.jobId] originating regen job (traceability only)
* @param {object} [deps] injected dependencies (testing)
* @returns {Promise<{ status: string, agentId?: string, solana?: object|null, evm?: object|null }>}
*/
export async function mintDraftAgentIdentity({ userId, avatarId, jobId = null }, deps = defaultDeps()) {
const agent = await deps.resolveAgent({ userId, avatarId });
if (!agent) return { status: 'no_agent' };
let solana = null;
let evm = null;
if (deps.network !== 'off') {
const ctx = await deps.loadAgentContext(agent.id);
if (ctx) {
solana = await deps.solanaMint({ agent: ctx, network: deps.network });
}
}
if (deps.evm?.enabled) {
const ctx = await deps.loadAgentContext(agent.id);
if (ctx) {
evm = await deps.evmMint({ agent: ctx, userId, chainId: deps.evm.chainId });
}
}
if ((solana && solana.status !== 'skipped') || evm) {
await deps.persistAvatarDraft({ avatarId, jobId, solana, evm }).catch((err) => {
console.warn('[draft-mint] avatar stamp failed:', err?.message);
});
}
return { status: 'ok', agentId: agent.id, solana, evm };
}