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 core for emitting on-chain threews.* memo attestations.
//
// Used by the production webhook (api/agents/solana-attest-event.js) and the
// in-house pumpfun monitor cron (api/cron/pumpfun-monitor.js). The two share
// the same exactly-once primitive: a claim row in solana_attest_event_claims
// is the lock; the SPL Memo tx is the on-chain artifact; a row in
// solana_attestations mirrors it for the reputation reads.
//
// All callers must provide a deterministic event_id so a retry never produces
// a second on-chain tx for the same logical event.
import crypto from 'node:crypto';
import { solanaConnection } from './solana/connection.js';
import {
Connection,
Keypair,
PublicKey,
Transaction,
TransactionInstruction,
} from '@solana/web3.js';
import { sendAndConfirm } from './solana/confirm.js';
import bs58 from 'bs58';
import { sql } from './db.js';
import { RPC, KIND_MAP } from './solana-attestations.js';
const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');
const TX_TIMEOUT_MS = 12_000;
export function taskHash(task_id, token_mint) {
return crypto.createHash('sha256').update(`${task_id}:${token_mint}`).digest('hex');
}
/**
* Build a threews.* attestation payload for a known event type.
* Recognised sources: pumpkit.graduation|fee_claim|whale|cto, and the
* in-house equivalents pumpfun.graduation|fee_claim|whale|cto.
*/
export function buildPayload({
event_id, event_type, agent_asset, token_mint, task_id, detail,
source = null,
}) {
const ts = Math.floor(Date.now() / 1000);
const base = { v: 1, agent: agent_asset, ts, event_id };
const src = (s) => source ?? s;
switch (event_type) {
case 'graduation':
return { ...base, kind: KIND_MAP.validation,
task_hash: taskHash(task_id, token_mint), passed: true,
source: src('pumpkit.graduation'), token: token_mint };
case 'fee_claim':
return { ...base, kind: KIND_MAP.feedback,
score: 5, source: src('pumpkit.fee_claim'),
token: token_mint, detail: detail ?? null };
case 'whale_trade':
return { ...base, kind: KIND_MAP.task,
task_id, scope_hash: taskHash(task_id, token_mint),
source: src('pumpkit.whale') };
case 'cto_detected':
return { ...base, kind: KIND_MAP.validation,
task_hash: taskHash(task_id, token_mint), passed: false,
source: src('pumpkit.cto'), token: token_mint };
default:
throw new Error(`unknown event_type: ${event_type}`);
}
}
/**
* Decode a Solana secret key from any encoding used across the three.ws env,
* synchronously (bs58 is statically imported here). Mirrors the async
* decodeSecretKey() in solana-signers.js so the attester key works whether it
* was provisioned as a Solana CLI JSON byte array, base64, or base58.
* - JSON array of 64 (or 32) ints — `solana-keygen` keypair file contents
* - base64 of the raw secret-key bytes
* - base58 of the raw secret-key bytes
* @param {string} secret
* @returns {Uint8Array|null} 64/32-byte key, or null if it can't be decoded.
*/
export function decodeAttesterSecret(secret) {
const raw = (secret || '').trim();
if (!raw) return null;
// JSON array form (Solana CLI keypair file contents).
if (raw.startsWith('[')) {
try {
const arr = JSON.parse(raw);
if (Array.isArray(arr) && (arr.length === 64 || arr.length === 32)) {
return Uint8Array.from(arr);
}
} catch {
/* fall through */
}
}
// hex form (128 chars = 64 bytes, or 64 chars = 32 bytes). Checked before
// base58 because hex's '0' is not a base58 character — an all-hex key would
// otherwise throw "Non-base58 character" out of bs58.decode and fail to load.
if (/^[0-9a-fA-F]+$/.test(raw) && (raw.length === 128 || raw.length === 64)) {
const buf = Buffer.from(raw, 'hex');
if (buf.length === 64 || buf.length === 32) return new Uint8Array(buf);
}
// base64 / base64url form. Buffer.from is lenient, so validate the byte length
// and require a clean round-trip to reject base58 strings that happen to
// base64-decode to 64 bytes. base64url (with - and _) is normalized to base64
// first so url-safe-provisioned keys decode instead of falling through to the
// base58 lane and throwing on the '-'/'_'.
try {
const normalized = raw.replace(/-/g, '+').replace(/_/g, '/');
const buf = Buffer.from(normalized, 'base64');
if (
(buf.length === 64 || buf.length === 32) &&
buf.toString('base64').replace(/=+$/, '') ===
normalized.replace(/=+$/, '')
) {
return new Uint8Array(buf);
}
} catch {
/* fall through */
}
// base58 form.
try {
const bytes = bs58.decode(raw);
if (bytes.length === 64 || bytes.length === 32) return Uint8Array.from(bytes);
} catch {
/* fall through */
}
return null;
}
export function loadAttesterKeypair() {
const k = process.env.ATTEST_AGENT_SECRET_KEY;
if (!k) throw Object.assign(new Error('ATTEST_AGENT_SECRET_KEY not configured'), { status: 500 });
const bytes = decodeAttesterSecret(k);
if (!bytes) {
throw Object.assign(
new Error(
'ATTEST_AGENT_SECRET_KEY is set but could not be decoded — expected a 64-byte ' +
'ed25519 secret key as a JSON byte array, base64, or base58 string.',
),
{ status: 500, code: 'attester_key_undecodable' },
);
}
return Keypair.fromSecretKey(bytes);
}
function withTimeout(promise, ms, onTimeout) {
let timer;
const timeout = new Promise((_, reject) => {
timer = setTimeout(() => {
onTimeout?.();
reject(Object.assign(new Error(`rpc timeout after ${ms}ms`), { code: 'RPC_TIMEOUT' }));
}, ms);
});
return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}
/**
* Mint a single attestation, exactly-once.
*
* @param {object} input
* @param {string} input.event_id Deterministic id; collision = idempotent dedupe.
* @param {string} input.event_type 'graduation'|'fee_claim'|'whale_trade'|'cto_detected'
* @param {string} input.source e.g. 'pumpfun.graduation' (in-house) or 'pumpkit.graduation'.
* @param {string} input.agent_asset Metaplex Core asset pubkey.
* @param {'mainnet'|'devnet'} input.network
* @param {string} input.token_mint
* @param {string} input.task_id
* @param {object} [input.detail]
* @param {Keypair} [input.attester] Defaults to loadAttesterKeypair().
*
* @returns {Promise<{ status: 'minted'|'deduped'|'in_progress', signature: string|null, kind: string|null }>}
*/
export async function mintAttestation(input) {
const {
event_id, event_type, source,
agent_asset, network, token_mint, task_id, detail,
attester = loadAttesterKeypair(),
} = input;
if (!event_id || !event_type || !agent_asset || !network || !token_mint || !task_id) {
throw new Error('mintAttestation: missing required fields');
}
const attesterPubkey = attester.publicKey.toBase58();
// Pre-tx claim — the lock that prevents duplicate on-chain txs.
const claim = await sql`
insert into solana_attest_event_claims (agent_asset, network, event_id, attester)
values (${agent_asset}, ${network}, ${event_id}, ${attesterPubkey})
on conflict (agent_asset, network, event_id) do nothing
returning claimed_at
`;
if (claim.length === 0) {
const [winner] = await sql`
select signature from solana_attest_event_claims
where agent_asset = ${agent_asset}
and network = ${network}
and event_id = ${event_id}
`;
return winner?.signature
? { status: 'deduped', signature: winner.signature, kind: null }
: { status: 'in_progress', signature: null, kind: null };
}
const payload = buildPayload({
event_id, event_type, agent_asset, token_mint, task_id, detail, source,
});
const memo = JSON.stringify(payload);
const conn = solanaConnection({ url: RPC[network] || RPC.devnet, commitment: 'confirmed' });
const ix = new TransactionInstruction({
programId: MEMO_PROGRAM_ID,
keys: [
{ pubkey: attester.publicKey, isSigner: true, isWritable: false },
{ pubkey: new PublicKey(agent_asset), isSigner: false, isWritable: false },
],
data: Buffer.from(memo, 'utf8'),
});
const tx = new Transaction().add(ix);
let signature;
try {
signature = await withTimeout(
sendAndConfirm(conn, tx, [attester], { commitment: 'confirmed' }),
TX_TIMEOUT_MS,
);
} catch (e) {
// Release the claim so a future retry can try again.
await sql`
delete from solana_attest_event_claims
where agent_asset = ${agent_asset}
and network = ${network}
and event_id = ${event_id}
and signature is null
`;
throw e;
}
await sql`
update solana_attest_event_claims
set signature = ${signature}, completed_at = now()
where agent_asset = ${agent_asset}
and network = ${network}
and event_id = ${event_id}
`;
try {
await sql`
insert into solana_attestations (
signature, network, slot, block_time, agent_asset, attester,
kind, payload, task_id, target_signature, verified
)
values (
${signature}, ${network}, null, now(),
${agent_asset}, ${attesterPubkey},
${payload.kind}, ${JSON.stringify(payload)}::jsonb,
${payload.task_id ?? null}, null, true
)
on conflict (signature) do nothing
`;
} catch (e) {
if (e?.code !== '23505') throw e;
// Lost race against the unique partial index — claim row already won
// the serialization, so signature above is canonical.
}
return { status: 'minted', signature, kind: payload.kind };
}
/** Deterministic event id for a logical pumpfun event. */
export function deriveEventId({ event_type, mint, slot_or_ts }) {
return crypto.createHash('sha256')
.update(`${event_type}:${mint}:${slot_or_ts}`)
.digest('hex')
.slice(0, 32);
}