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
/**
* On-chain agent-to-agent invocation receipts (the `agent_invocation` Anchor
* program — see contracts/agent-invocation/).
* ---------------------------------------------------------------------------
* When one agent hires and pays another for a skill, we record a verifiable
* receipt on Solana by invoking the program's `invoke_skill` instruction. The
* program is intentionally non-trust-bearing: it moves no funds and grants no
* capability — it validates the caller and emits a `SkillInvoked` event so the
* invocation is permanently auditable on-chain with an explorer link on both
* sides. The USDC payment itself already settled over the x402 rails; this is the
* tamper-proof record THAT it happened.
*
* The instruction is built by hand (Anchor discriminator + Borsh-encoded string
* args) so the API runtime doesn't have to load @coral-xyz/anchor — the same
* dependency-light approach as skill-license-onchain.js. PDA derivation and
* instruction encoding are pure and unit-tested; only `recordInvocationReceipt`
* touches the chain.
*/
import { createHash } from 'node:crypto';
import {
PublicKey,
SystemProgram,
Transaction,
TransactionInstruction,
} from '@solana/web3.js';
import { sendAndConfirm } from './solana/confirm.js';
import { solanaConnection } from './solana/connection.js';
/** Program id baked into the on-chain program's `declare_id!`. Override per
* deployment (e.g. a devnet build) with AGENT_INVOCATION_PROGRAM_ID. */
export const AGENT_INVOCATION_PROGRAM_ID =
process.env.AGENT_INVOCATION_PROGRAM_ID || 'AgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo';
// On-chain limits enforced by the program; validated here too so a caller gets a
// clear error instead of a failed simulation. Must match contracts/agent-invocation.
export const MAX_SKILL_NAME_LEN = 64;
export const MAX_PARAMETERS_LEN = 512;
// Seed prefix — must byte-match `AGENT_SEED` in contracts/agent-invocation/src/lib.rs.
const AGENT_SEED = Buffer.from('agent');
// Anchor instruction discriminator: sha256("global:invoke_skill")[..8].
const INVOKE_SKILL_DISCRIMINATOR = createHash('sha256')
.update('global:invoke_skill')
.digest()
.subarray(0, 8);
function programPk(programId) {
return programId instanceof PublicKey ? programId : new PublicKey(programId);
}
/** Derive an agent's program identity PDA from its authority — matches the Rust
* `seeds = [AGENT_SEED, authority]`. */
export function deriveAgentPda(authority, programId = AGENT_INVOCATION_PROGRAM_ID) {
return PublicKey.findProgramAddressSync(
[AGENT_SEED, new PublicKey(authority).toBuffer()],
programPk(programId),
);
}
// Borsh string: 4-byte little-endian length prefix + UTF-8 bytes.
function encodeBorshString(value) {
const bytes = Buffer.from(String(value), 'utf8');
const len = Buffer.alloc(4);
len.writeUInt32LE(bytes.length, 0);
return Buffer.concat([len, bytes]);
}
/**
* Build the unsigned `invoke_skill` instruction. Pure — no chain access — so the
* encoding and account ordering can be asserted directly in tests.
*
* @param {{ invokerAuthority: string|PublicKey, targetAuthority: string|PublicKey,
* skillName: string, parameters: string, programId?: string|PublicKey }} args
*/
export function buildInvokeSkillIx({ invokerAuthority, targetAuthority, skillName, parameters, programId = AGENT_INVOCATION_PROGRAM_ID }) {
if (!skillName || String(skillName).length === 0) {
throw new Error('skillName must not be empty');
}
if (Buffer.byteLength(String(skillName), 'utf8') > MAX_SKILL_NAME_LEN) {
throw new Error(`skillName exceeds ${MAX_SKILL_NAME_LEN} bytes`);
}
if (Buffer.byteLength(String(parameters ?? ''), 'utf8') > MAX_PARAMETERS_LEN) {
throw new Error(`parameters exceed ${MAX_PARAMETERS_LEN} bytes`);
}
const pid = programPk(programId);
const invokerAuth = new PublicKey(invokerAuthority);
const targetAuth = new PublicKey(targetAuthority);
const [invokerAgent] = deriveAgentPda(invokerAuth, pid);
const [targetAgent] = deriveAgentPda(targetAuth, pid);
const data = Buffer.concat([
INVOKE_SKILL_DISCRIMINATOR,
encodeBorshString(skillName),
encodeBorshString(parameters ?? ''),
]);
// Account order must match the Rust `InvokeSkill` accounts struct exactly.
const keys = [
{ pubkey: invokerAgent, isSigner: false, isWritable: false },
{ pubkey: invokerAuth, isSigner: true, isWritable: true },
{ pubkey: targetAuth, isSigner: false, isWritable: false },
{ pubkey: targetAgent, isSigner: false, isWritable: false },
{ pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
];
return {
instruction: new TransactionInstruction({ programId: pid, keys, data }),
invokerAgent: invokerAgent.toBase58(),
targetAgent: targetAgent.toBase58(),
};
}
/**
* Write a real on-chain invocation receipt. The invoking agent's keypair signs
* and pays the (tiny) transaction fee; the target agent's authority is supplied
* so its agent PDA can be re-derived and recorded. Truncates oversized parameters
* to the program limit rather than failing the receipt.
*
* @param {{ invokerKeypair: import('@solana/web3.js').Keypair,
* targetAuthority: string|PublicKey, skillName: string, parameters?: string,
* network?: 'mainnet'|'devnet', programId?: string,
* connection?: import('@solana/web3.js').Connection }} args
* @returns {Promise<{ signature: string, programId: string, network: string,
* invokerAgent: string, targetAgent: string, explorer: string }>}
*/
export async function recordInvocationReceipt({
invokerKeypair,
targetAuthority,
skillName,
parameters = '',
network = process.env.AGENT_INVOCATION_NETWORK || 'mainnet',
programId = AGENT_INVOCATION_PROGRAM_ID,
connection,
}) {
if (!invokerKeypair?.publicKey) throw new Error('invokerKeypair is required');
if (!targetAuthority) throw new Error('targetAuthority is required');
// Skill name capped to fit on-chain; long params trimmed to the byte limit.
const name = String(skillName || 'skill').slice(0, MAX_SKILL_NAME_LEN);
let params = String(parameters ?? '');
while (Buffer.byteLength(params, 'utf8') > MAX_PARAMETERS_LEN) {
params = params.slice(0, Math.floor(params.length * 0.9));
}
const { instruction, invokerAgent, targetAgent } = buildInvokeSkillIx({
invokerAuthority: invokerKeypair.publicKey,
targetAuthority,
skillName: name,
parameters: params,
programId,
});
const conn = connection || solanaConnection({ network, commitment: 'confirmed' });
const tx = new Transaction().add(instruction);
const signature = await sendAndConfirm(conn, tx, [invokerKeypair], {
commitment: 'confirmed',
});
const cluster = network === 'devnet' ? '?cluster=devnet' : '';
return {
signature,
programId: programPk(programId).toBase58(),
network,
invokerAgent,
targetAgent,
explorer: `https://solscan.io/tx/${signature}${cluster}`,
};
}