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
// Shared server-side Metaplex Core agent deploy.
// ---------------------------------------------------------------------------
// Single source of truth for turning an agent into its on-chain identity — a
// Metaplex Core asset minted into the three.ws Agent Collection. Used by
// scripts/deploy-agents-onchain.mjs, the CLI batch/canary runner.
//
// Custody model: one funded wallet (the collection authority) is the mint fee
// payer and — on first run — deploys the Collection account. Each agent is
// owned by its own custodial Solana wallet (generated on demand); the owner does
// NOT sign the mint, so agent wallets never need SOL.
import { Keypair, LAMPORTS_PER_SOL } from '@solana/web3.js';
import bs58 from 'bs58';
import { CID } from 'multiformats/cid';
import * as raw from 'multiformats/codecs/raw';
import { sha256 } from 'multiformats/hashes/sha2';
import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { mplCore, create, createCollection, fetchCollection, ruleSet } from '@metaplex-foundation/mpl-core';
import {
generateSigner,
publicKey as umiPublicKey,
createSignerFromKeypair,
signerIdentity,
} from '@metaplex-foundation/umi';
import { sql } from './db.js';
import { env } from './env.js';
import { putObject, publicUrl as r2PublicUrl, thumbnailUrl } from './r2.js';
import {
buildAgentManifest,
buildAgentOnchainAttributes,
agentRoyaltyConfig,
agentHomeUrl,
} from './three-brand.js';
import { registerAgentIdentity, MPL_AGENT_IDENTITY_PROGRAM_ID } from './agent-registry.js';
import { getAgentCollection } from './solana-collection.js';
import { solanaConnection } from './solana/connection.js';
import { generateSolanaAgentWallet } from './agent-wallet.js';
import { publishFeedEvent } from './feed.js';
import { pinToIPFS } from './ipfs-pin.js';
import { register8004Agent, registrationEnabled as registry8004Enabled } from './solana-8004.js';
// Genesis-hash chain refs (CAIP-2), mirroring api/agents/onchain/[action].js.
export const SOLANA_REFS = {
mainnet: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
devnet: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
};
// A Core asset minted into a collection costs ~0.0037 SOL rent + fee; deploying
// the Collection account on first run costs ~0.003 SOL rent + fee.
export const EST_MINT_LAMPORTS = Math.floor(0.004 * LAMPORTS_PER_SOL);
export const EST_COLLECTION_LAMPORTS = Math.floor(0.005 * LAMPORTS_PER_SOL);
// Registering an asset's Agent Identity PDA costs ~0.0025 SOL rent + fee.
export const EST_REGISTER_LAMPORTS = Math.floor(0.003 * LAMPORTS_PER_SOL);
export function explorerUrl(asset, network) {
const suffix = network === 'devnet' ? '?cluster=devnet' : '';
return `https://solscan.io/account/${asset}${suffix}`;
}
/** Resolve the funded authority secret (collection authority == mint fee payer). */
export function authoritySecret() {
return process.env.SOLANA_AGENT_COLLECTION_AUTHORITY_KEY || process.env.LAUNCH_FUNDER_SECRET || null;
}
/** Build a Umi instance whose identity (payer) + signer is the funded authority. */
export function buildAuthorityUmi(network, secret = authoritySecret()) {
if (!secret) {
throw new Error('Set SOLANA_AGENT_COLLECTION_AUTHORITY_KEY (or LAUNCH_FUNDER_SECRET) to the funded authority wallet secret.');
}
let authorityKeypair;
try {
authorityKeypair = Keypair.fromSecretKey(bs58.decode(secret));
} catch {
throw new Error('authority/funder secret is not a valid base58 keypair');
}
// Route umi through the multi-endpoint failover Connection (not a bare URL) so
// every RPC the build needs — chiefly getLatestBlockhash — rotates across the
// endpoint chain. A bare URL gives umi a single node whose malformed/empty 200
// body surfaces as the `StructError: … but received:` crash instead of failing
// over to a healthy provider.
const umi = createUmi(solanaConnection({ network })).use(mplCore());
const authoritySigner = createSignerFromKeypair(
umi,
umi.eddsa.createKeypairFromSecretKey(authorityKeypair.secretKey),
);
umi.use(signerIdentity(authoritySigner));
return { umi, authoritySigner, authorityKeypair };
}
/** Current authority/funder balance, in lamports (0 on RPC error). */
export async function funderLamports(umi, pubkey) {
try {
const bal = await umi.rpc.getBalance(pubkey);
return Number(bal.basisPoints);
} catch {
return 0;
}
}
// Pin the manifest. Prefer real IPFS pinning (Pinata → web3.storage, via the
// shared ipfs-pin helper); otherwise fall back to R2 while computing the real
// CIDv1 (raw codec, sha2-256) from the bytes, so the content is verifiable
// content-addressing and the returned HTTPS URL is real and resolvable — never a
// stub. Mirrors api/agents/onchain/[action].js.
export async function pinManifest(manifest, agentId) {
const bytes = Buffer.from(JSON.stringify(manifest), 'utf-8');
const pinned = await pinToIPFS(bytes, `agent-${agentId}.json`).catch(() => null);
if (pinned?.cid) return { cid: pinned.cid, uri: pinned.uri };
const digest = await sha256.digest(bytes);
const cid = CID.create(1, raw.code, digest).toString();
const key = `agent-manifests/bulk/${agentId}.json`;
await putObject({ key, body: bytes, contentType: 'application/json' });
return { cid, uri: r2PublicUrl(key) };
}
/**
* Agents that are minted as Core assets on this network but are NOT yet in the
* Metaplex Agent Registry (no `agent_registry.identity_pda`). This is the
* back-fill set — the already-minted agents Metaplex asks us to register.
*/
export async function fetchUnregisteredAgents(network, limit) {
return network === 'mainnet'
? sql`
SELECT ai.id, ai.user_id, ai.name, ai.description, ai.meta, ai.avatar_id
FROM agent_identities ai
WHERE ai.deleted_at IS NULL
AND ai.meta->>'sol_mint_address' IS NOT NULL
AND ai.meta->'agent_registry'->>'identity_pda' IS NULL
ORDER BY ai.created_at ASC
LIMIT ${limit}
`
: sql`
SELECT ai.id, ai.user_id, ai.name, ai.description, ai.meta, ai.avatar_id
FROM agent_identities ai
WHERE ai.deleted_at IS NULL
AND ai.meta->'devnet'->>'sol_mint_address' IS NOT NULL
AND ai.meta->'devnet'->'agent_registry'->>'identity_pda' IS NULL
ORDER BY ai.created_at ASC
LIMIT ${limit}
`;
}
/** Agents still missing an on-chain identity on this network. */
export async function fetchUndeployedAgents(network, limit) {
return network === 'mainnet'
? 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.deleted_at IS NULL
AND ai.meta->>'sol_mint_address' IS NULL
ORDER BY ai.created_at ASC
LIMIT ${limit}
`
: 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.deleted_at IS NULL
AND ai.meta->'devnet'->>'sol_mint_address' IS NULL
ORDER BY ai.created_at ASC
LIMIT ${limit}
`;
}
// Resolve the three.ws Agent Collection for this network: prefer the env var
// (keeps the interactive deploy + edit paths aligned), then a persisted setting,
// then deploy the Collection account on first run and persist its address.
// `onEvent(type, data)` receives a 'collection' event; pass a logger or SSE emitter.
export async function resolveAgentCollection({ umi, authoritySigner, network, onEvent }) {
const authority = authoritySigner.publicKey.toString();
const envAddr = getAgentCollection(network);
if (envAddr) {
onEvent?.('collection', { address: envAddr, source: 'env', authority });
return envAddr;
}
await sql`
CREATE TABLE IF NOT EXISTS app_settings (
key text PRIMARY KEY,
value jsonb NOT NULL,
updated_at timestamptz NOT NULL DEFAULT now()
)
`;
const settingKey = `solana_agent_collection_${network}`;
const [row] = await sql`SELECT value FROM app_settings WHERE key = ${settingKey}`;
if (row?.value?.address) {
onEvent?.('collection', { address: row.value.address, source: 'db', authority });
return row.value.address;
}
// First run for this network: deploy the Collection account, funded +
// authority-signed by the funder.
const bal = await funderLamports(umi, authoritySigner.publicKey);
if (bal < EST_COLLECTION_LAMPORTS) {
throw new Error(
`funder needs ~${(EST_COLLECTION_LAMPORTS / LAMPORTS_PER_SOL).toFixed(3)} SOL to deploy the three.ws Agents collection — top up ${authority} and re-run`,
);
}
const collectionSigner = generateSigner(umi);
const collectionUri = `${env.APP_ORIGIN}/api/agents/solana-collection-metadata?network=${network}`;
const result = await createCollection(umi, {
collection: collectionSigner,
name: 'three.ws Agents',
uri: collectionUri,
plugins: [
{
type: 'Attributes',
attributeList: [
{ key: 'platform', value: 'three.ws' },
{ key: 'url', value: env.APP_ORIGIN },
{ key: 'standard', value: 'metaplex-core' },
{ key: 'schema', value: 'agent-manifest/0.1' },
{ key: 'chain', value: `solana:${SOLANA_REFS[network]}` },
],
},
],
}).sendAndConfirm(umi, { confirm: { commitment: 'confirmed' } });
const address = collectionSigner.publicKey.toString();
const signature = bs58.encode(result.signature);
await sql`
INSERT INTO app_settings (key, value)
VALUES (${settingKey}, ${JSON.stringify({ address, authority, signature, deployed_at: new Date().toISOString() })}::jsonb)
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()
`;
onEvent?.('collection', { address, source: 'deployed', authority, signature });
return address;
}
/**
* Fetch the on-chain CollectionV1 once per run. The Core `create` helper reads
* `collection.publicKey` (and oracles/lifecycleHooks) off this object — passing a
* bare publicKey silently mints a STANDALONE asset, so the real object is required
* to actually bind the asset into the collection. Returns null for no collection.
*/
export async function loadCollectionAsset(umi, collectionAddr) {
if (!collectionAddr) return null;
return fetchCollection(umi, umiPublicKey(collectionAddr));
}
/**
* Deploy a single agent on-chain: ensure its owner wallet, pin its manifest,
* mint the Core asset into the collection, and persist the result. Returns
* { asset, signature, metadataUri, ownerAddress, image }. Pure of UI concerns —
* pass `onEvent` to receive a 'wallet' event when a custodial wallet is created.
* `collectionAsset` is the fetched CollectionV1 (from loadCollectionAsset).
*/
export async function deployAgentOnce({ umi, authoritySigner, collectionAddr, collectionAsset, agent, network, onEvent }) {
const agentName = agent.name || 'Agent';
// 1. Resolve the owner. Prefer the agent's existing Solana wallet. If it has
// none: give it its own custodial wallet when the platform key is present
// (so the secret can be encrypted at rest and recovered later); otherwise
// custody the asset under the collection authority — transferable to the
// agent/user on claim. The owner never signs the mint, so it needs no SOL.
const authorityAddress = authoritySigner.publicKey.toString();
let meta = { ...(agent.meta || {}) };
let ownerAddress = meta.solana_address;
if (!ownerAddress) {
if (process.env.JWT_SECRET) {
const wallet = await generateSolanaAgentWallet();
meta = {
...meta,
solana_address: wallet.address,
encrypted_solana_secret: wallet.encrypted_secret,
solana_wallet_source: 'bulk_onchain',
};
ownerAddress = wallet.address;
await sql`
UPDATE agent_identities
SET meta = ${JSON.stringify(meta)}::jsonb, updated_at = NOW()
WHERE id = ${agent.id}
`;
onEvent?.('wallet', { agent_id: agent.id, name: agentName, owner: ownerAddress });
} else {
ownerAddress = authorityAddress;
}
}
const custody = ownerAddress === authorityAddress;
// 2. Media + manifest.
// thumbnailUrl(), not a bare publicUrl: this image is baked into the token's
// on-chain metadata, so a legacy origin-pointing `*_og.png` key would mint a
// permanently dead image URL. Dropping it leaves the field empty instead.
const image = thumbnailUrl(agent.thumbnail_key) || '';
const animationUrl = agent.storage_key ? r2PublicUrl(agent.storage_key) : '';
const createdAt = new Date().toISOString();
const manifest = buildAgentManifest({
name: agentName,
description: agent.description || '',
avatarId: agent.avatar_id || null,
image,
animationUrl,
externalUrl: agentHomeUrl(agent.id),
ownerAddress,
createdAt,
});
const { uri: metadataUri } = await pinManifest(manifest, agent.id);
// 3. Mint the Core asset into the collection.
const attributes = buildAgentOnchainAttributes({
name: agentName,
agentUrl: agentHomeUrl(agent.id),
createdAt,
});
const royalty = agentRoyaltyConfig(ownerAddress);
const ownerPk = umiPublicKey(ownerAddress);
const assetSigner = generateSigner(umi);
const createArgs = {
asset: assetSigner,
owner: ownerPk,
name: agentName.slice(0, 32) || 'Agent',
uri: metadataUri,
plugins: [
...(attributes.length ? [{ type: 'Attributes', attributeList: attributes }] : []),
...(royalty
? [{
type: 'Royalties',
basisPoints: royalty.basisPoints,
creators: royalty.creators.map((c) => ({ address: umiPublicKey(c.address), percentage: c.percentage })),
ruleSet: ruleSet('None'),
}]
: []),
],
};
if (collectionAsset) {
createArgs.collection = collectionAsset;
createArgs.authority = authoritySigner;
}
const result = await create(umi, createArgs).sendAndConfirm(umi, {
confirm: { commitment: 'confirmed' },
});
const asset = assetSigner.publicKey.toString();
const signature = bs58.encode(result.signature);
// 4. Persist. Mainnet writes the canonical fields every read path keys on;
// devnet is isolated under meta.devnet so it never blocks a mainnet mint.
const onchain = {
chain: `solana:${SOLANA_REFS[network]}`,
family: 'solana',
cluster: network,
onchain_id: asset,
sol_asset: asset,
contract_or_mint: asset,
metadata_uri: metadataUri,
owner: ownerAddress,
custody,
tx_hash: signature,
...(collectionAddr ? { collection: collectionAddr } : {}),
confirmed_at: new Date().toISOString(),
};
const merged =
network === 'mainnet'
? {
...meta,
chain_type: 'solana',
network,
sol_mint_address: asset,
...(collectionAddr ? { collection: collectionAddr, update_authority: 'threews' } : {}),
onchain,
}
: { ...meta, devnet: { sol_mint_address: asset, collection: collectionAddr || null, onchain } };
await sql`
UPDATE agent_identities
SET meta = ${JSON.stringify(merged)}::jsonb, updated_at = NOW()
WHERE id = ${agent.id}
`;
await sql`
INSERT INTO agent_actions (agent_id, type, payload, source_skill)
VALUES (
${agent.id},
${'solana.deploy'},
${JSON.stringify({ asset, network, signature, collection: collectionAddr || null, owner: ownerAddress, source: 'bulk_onchain' })}::jsonb,
${'bulk_onchain'}
)
`.catch(() => {});
// Truthful on-chain feed event — fired only after the tx confirms (mainnet).
if (network === 'mainnet') {
publishFeedEvent({
type: 'agent-onchain',
ts: Date.now(),
actor: agentName,
agentId: agent.id,
name: agentName,
chain: 'Solana',
}).catch(() => {});
}
// 5. Enrol the freshly-minted asset in the Metaplex Agent Registry. The mint
// already succeeded and is persisted, so a transient registry failure must
// not unwind it — record the error and let the back-fill retry. The owner
// never signs (the collection authority is the asset's update authority).
let registry = null;
try {
registry = await registerAgentOnce({
umi,
authoritySigner,
agent: { ...agent, meta: merged },
asset,
collectionAddr,
network,
onEvent,
});
} catch (err) {
onEvent?.('registry_error', { agent_id: agent.id, name: agentName, error: err.message });
}
return { asset, signature, metadataUri, ownerAddress, image, registry };
}
/**
* Enrol a Core-minted agent in the Metaplex Agent Registry (Agent Identity PDA).
* Shared by the post-mint step above and the back-fill of already-minted agents.
* Resolves the asset/collection from explicit args or the agent's persisted meta,
* pins the registration document, sends `registerIdentityV1` (authority-signed,
* no owner signature), and persists an `agent_registry` block. Idempotent:
* already-registered assets short-circuit without a tx.
*
* @returns {Promise<{ asset, identityPda, registrationUri, signature, alreadyRegistered }>}
*/
export async function registerAgentOnce({ umi, authoritySigner, agent, asset, collectionAddr, network, onEvent }) {
const agentName = agent.name || 'Agent';
const meta = agent.meta || {};
const isMainnet = network === 'mainnet';
const net = isMainnet ? meta : meta.devnet || {};
const resolvedAsset = asset || net.sol_mint_address;
if (!resolvedAsset) {
throw new Error('agent has no Core asset on this network — mint it before registering');
}
const resolvedCollection = collectionAddr || net.collection || null;
// The Agent Identity PDA stores this URI permanently — the registry program has
// no instruction to change it later. So point it at the agent's live, MUTABLE
// registration endpoint (served by api/agents/[id]/registration.js from current
// data) rather than an immutable pinned snapshot: that keeps `active`, services,
// the 3D model, and any future token link accurate without re-registering.
const registrationUri = `${env.APP_ORIGIN}/api/agents/${agent.id}/registration`;
const { identityPda, signature, alreadyRegistered } = await registerAgentIdentity({
umi,
authoritySigner,
asset: resolvedAsset,
collectionAddr: resolvedCollection,
registrationUri,
});
const registryBlock = {
standard: 'metaplex-agent-registry',
program: MPL_AGENT_IDENTITY_PROGRAM_ID.toString(),
identity_pda: identityPda,
asset: resolvedAsset,
...(resolvedCollection ? { collection: resolvedCollection } : {}),
authority: authoritySigner.publicKey.toString(),
registration_uri: registrationUri,
network,
...(signature ? { tx_hash: signature } : {}),
registered_at: new Date().toISOString(),
};
// Merge only the registry block — read current meta so we never clobber a
// concurrent mint/edit, then write back the canonical (mainnet) or devnet path.
const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${agent.id}`;
const current = row?.meta || meta;
const nextMeta = isMainnet
? { ...current, agent_registry: registryBlock }
: { ...current, devnet: { ...(current.devnet || {}), agent_registry: registryBlock } };
await sql`
UPDATE agent_identities
SET meta = ${JSON.stringify(nextMeta)}::jsonb, updated_at = NOW()
WHERE id = ${agent.id}
`;
await sql`
INSERT INTO agent_actions (agent_id, type, payload, source_skill)
VALUES (
${agent.id},
${'solana.register'},
${JSON.stringify({ asset: resolvedAsset, network, identity_pda: identityPda, signature, collection: resolvedCollection, already: alreadyRegistered, source: 'agent_registry' })}::jsonb,
${'agent_registry'}
)
`.catch(() => {});
// Enrol in the open 8004 registry too, on the same authority-managed path. The
// Metaplex identity above is already persisted, so a failure here is reported
// and left for the back-fill rather than unwinding it.
let registry8004 = null;
if (registry8004Enabled(network)) {
try {
const r = await register8004Agent({ agent: { ...agent, meta: { ...current, ...(isMainnet ? {} : { devnet: current.devnet }) } }, network });
registry8004 = { asset: r.asset, signature: r.signature, alreadyRegistered: r.alreadyRegistered };
onEvent?.('registry_8004', { agent_id: agent.id, asset: r.asset, signature: r.signature, already_registered: r.alreadyRegistered });
} catch (err) {
onEvent?.('registry_8004_error', { agent_id: agent.id, name: agentName, error: err.message });
}
}
onEvent?.('registered', {
agent_id: agent.id,
name: agentName,
asset: resolvedAsset,
identity_pda: identityPda,
signature,
already_registered: alreadyRegistered,
explorer_url: explorerUrl(identityPda, network),
});
return { asset: resolvedAsset, identityPda, registrationUri, signature, alreadyRegistered, registry8004 };
}