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
// @ts-check
// Materialize certificates: the on-chain proof a physical print carries.
//
// When an order ships, three things are frozen together and never move again:
//
// 1. the SHA-256 of the exact bytes that were printed (and of the prepared
// GLB the certificate page renders),
// 2. the edition number claimed out of that model's series, claimed
// atomically so two simultaneous shipments cannot both be "number 7",
// 3. a Solana memo transaction carrying both, signed by the platform.
//
// The QR on the package resolves to /cert/<id>, which renders the original
// model, the lineage, the edition, and the RAW memo payload. That last part is
// the point: a buyer verifies a print by hashing the file and comparing it to
// the string in the transaction, with no dependency on this database, this
// company, or any block explorer staying online.
//
// Cluster policy. Devnet is the default and needs no approval: it proves the
// pipeline end to end. Mainnet is gated twice on purpose (CLAUDE.md gate 1
// covers irreversible on-chain actions): PRINT_CERT_CLUSTER must say mainnet
// AND PRINT_CERT_MAINNET_APPROVAL must carry the owner's recorded approval. A
// missing approval does not silently downgrade to devnet, because a devnet
// signature printed on a mainnet certificate would be a lie; it leaves the
// certificate unattested, records why, and lets the sweep retry once the
// approval lands.
//
// Failure policy. Issuance never blocks a shipment. The row is written first;
// the QR and the memo are best-effort and retried by the print reconciliation
// sweep (api/cron/print-orders-sync.js). A certificate with a null signature is
// a real certificate whose proof is still in flight, and the page says so.
import crypto from 'node:crypto';
import { Buffer } from 'node:buffer';
import QRCode from 'qrcode';
import { Keypair, PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
import { sql } from '../db.js';
import { getObjectBuffer, keyFromPublicUrl, putObject, publicUrl, objectStorageConfigured } from '../r2.js';
import { solanaConnection } from '../solana/connection.js';
import { sendAndConfirm } from '../solana/confirm.js';
import { decodeAttesterSecret } from '../attest-event.js';
import { RPC } from '../solana-attestations.js';
import { seriesKeyFor, editionLimitFor, PrintEditionError } from './editions.js';
/** SPL Memo v2. Same program the agent attestations use. */
const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');
const TX_TIMEOUT_MS = 20_000;
/** The memo schema version. Bumping it is a wire-format change, not a tweak. */
export const CERT_MEMO_KIND = 'threews.print.v1';
/** Bounded so a claim race cannot spin: 12 shipments of one model at once. */
const EDITION_CLAIM_ATTEMPTS = 12;
export const CERT_ID_RE = /^[0-9a-f]{24}$/;
/** Typed failure so handlers map a cause to a status code, never a bare 500. */
export class PrintCertificateError extends Error {
/**
* @param {string} code
* @param {string} message
* @param {Record<string, unknown>} [extra]
*/
constructor(code, message, extra = {}) {
super(message);
this.name = 'PrintCertificateError';
this.code = code;
Object.assign(this, extra);
}
}
/** 24 lowercase hex characters: short enough to print, wide enough to be unguessable. */
export function newCertificateId() {
return crypto.randomBytes(12).toString('hex');
}
/** @param {Buffer|Uint8Array} bytes */
export function sha256Hex(bytes) {
return crypto.createHash('sha256').update(bytes).digest('hex');
}
export function siteOrigin() {
return (process.env.PUBLIC_BASE_URL || 'https://three.ws').replace(/\/$/, '');
}
/** @param {string} certId */
export function certificateUrl(certId) {
return `${siteOrigin()}/cert/${certId}`;
}
/**
* Which cluster certificates attest on. Devnet unless the deployment says
* otherwise; anything unrecognised is devnet, never a silent mainnet spend.
* @returns {'mainnet'|'devnet'}
*/
export function certCluster() {
return String(process.env.PRINT_CERT_CLUSTER || '').trim().toLowerCase() === 'mainnet'
? 'mainnet'
: 'devnet';
}
/**
* The owner gate on real-money attestation. Mainnet sends are irreversible
* on-chain actions, so they require an explicit recorded approval on top of
* the cluster flag.
* @returns {{ allowed: boolean, reason: string }}
*/
export function mainnetAttestationAllowed() {
const approval = String(process.env.PRINT_CERT_MAINNET_APPROVAL || '').trim();
if (!approval) {
return {
allowed: false,
reason:
'mainnet attestation is owner-gated: set PRINT_CERT_MAINNET_APPROVAL to the recorded approval before certificates attest on mainnet',
};
}
return { allowed: true, reason: '' };
}
/** The keypair that signs certificate memos. */
export function loadCertAttester() {
const raw = process.env.PRINT_CERT_ATTESTER_SECRET || process.env.ATTEST_AGENT_SECRET_KEY;
if (!raw) {
throw new PrintCertificateError(
'attester_unconfigured',
'no certificate attester key: set PRINT_CERT_ATTESTER_SECRET (or ATTEST_AGENT_SECRET_KEY)',
);
}
const bytes = decodeAttesterSecret(raw);
if (!bytes) {
throw new PrintCertificateError(
'attester_key_undecodable',
'the certificate attester key is set but is not a decodable ed25519 secret key',
);
}
return Keypair.fromSecretKey(bytes);
}
/**
* The exact JSON a certificate's memo transaction carries. Compact on purpose:
* SPL Memo is capped per transaction, and every byte here is printed on the
* certificate page for a human to compare against the chain.
*
* @param {{ id: string, glb_sha256: string, print_asset_sha256?: string|null, print_asset_kind?: string|null,
* edition_no: number, edition_of?: number|null, creation_id?: string|null, printed_at?: Date|string|null }} cert
* @returns {string}
*/
export function buildCertificateMemo(cert) {
/** @type {Record<string, unknown>} */
const payload = {
v: 1,
kind: CERT_MEMO_KIND,
cert: cert.id,
sha256: cert.glb_sha256,
ed: cert.edition_no,
of: cert.edition_of ?? null,
ts: Math.floor(new Date(cert.printed_at || Date.now()).getTime() / 1000),
};
if (cert.creation_id) payload.creation = cert.creation_id;
if (cert.print_asset_sha256 && cert.print_asset_kind) {
payload.print = `${cert.print_asset_kind}:${cert.print_asset_sha256}`;
}
return JSON.stringify(payload);
}
/**
* Pick the manufacturing asset an order was actually printed from. STL and 3MF
* are what a bureau loads; the GLB is the viewable original and is hashed
* separately. Returns null when the order carries neither.
* @param {Record<string, string>} assets
*/
export function pickPrintAsset(assets) {
for (const kind of ['3mf', 'stl', 'glb']) {
const url = assets?.[kind];
if (typeof url === 'string' && url) return { kind, url };
}
return null;
}
/**
* Read an asset by its public URL and return its bytes plus the storage key.
* @param {string} url
*/
async function readAsset(url) {
const key = keyFromPublicUrl(url);
if (!key) {
throw new PrintCertificateError(
'asset_not_in_bucket',
`prepared asset ${url} does not live in this deployment's object storage, so its bytes cannot be hashed`,
);
}
const bytes = await getObjectBuffer(key);
return { key, bytes };
}
/**
* Claim the next edition number for a series and insert the certificate in one
* statement, retrying the collision a concurrent claim produces.
*
* Two things make this atomic without a transaction, which matters because the
* serverless driver has none: the unique index on (series_key, edition_no)
* means only one of two simultaneous "max + 1" writers can win, and the HAVING
* clause means a full series selects zero rows rather than writing an
* over-numbered certificate. The loser recomputes and takes the next number, or
* is told the edition is sold out. Exported because it is the primitive the
* concurrency test exercises directly.
*
* @param {object} row
* @returns {Promise<any>} the inserted certificate, or the one that already
* existed for this order.
*/
export async function claimEdition(row) {
for (let attempt = 1; attempt <= EDITION_CLAIM_ATTEMPTS; attempt++) {
try {
const inserted = await sql`
insert into print_certificates (
id, order_id, creation_id, series_key, edition_no, edition_of,
glb_sha256, glb_bytes, print_asset_kind, print_asset_key, print_asset_sha256,
material_id, material_label, network, memo
)
select
${row.id}, ${row.order_id}, ${row.creation_id}, ${row.series_key},
coalesce(max(edition_no), 0) + 1, ${row.edition_of},
${row.glb_sha256}, ${row.glb_bytes}, ${row.print_asset_kind},
${row.print_asset_key}, ${row.print_asset_sha256},
${row.material_id}, ${row.material_label}, ${row.network}, ''
from print_certificates
where series_key = ${row.series_key}
having ${row.edition_of}::int is null
or coalesce(max(edition_no), 0) + 1 <= ${row.edition_of}::int
returning *
`;
if (inserted.length === 0) {
throw new PrintEditionError(
'edition_sold_out',
`this edition is capped at ${row.edition_of} and every copy has already been certified`,
{ limit: row.edition_of },
);
}
return inserted[0];
} catch (err) {
if (err?.code !== '23505') throw err;
// A unique violation is one of two things, and the row tells us which:
// this order was already certified (the idempotent answer), or a
// concurrent claim took the number we computed (recompute and retry).
const [existing] = await sql`select * from print_certificates where order_id = ${row.order_id} limit 1`;
if (existing) return existing;
if (attempt >= EDITION_CLAIM_ATTEMPTS) throw err;
}
}
throw new PrintCertificateError(
'edition_claim_contended',
'could not claim an edition number after repeated concurrent collisions',
);
}
/**
* Render the certificate's QR as a PNG and store it beside the prepared assets.
* Best-effort: a certificate without its QR is still a valid certificate, and
* the sweep regenerates it.
* @param {{ id: string }} cert
* @returns {Promise<{ qr_key: string, qr_url: string }|null>}
*/
export async function generateCertificateQr(cert) {
if (!objectStorageConfigured()) return null;
const png = await QRCode.toBuffer(certificateUrl(cert.id), {
type: 'png',
errorCorrectionLevel: 'Q',
margin: 2,
width: 720,
color: { dark: '#000000ff', light: '#ffffffff' },
});
const key = `print/certs/${cert.id}/qr.png`;
await putObject({ key, body: png, contentType: 'image/png' });
const url = publicUrl(key);
await sql`update print_certificates set qr_key = ${key}, qr_url = ${url} where id = ${cert.id}`;
return { qr_key: key, qr_url: url };
}
/**
* Send the certificate's memo transaction and record its signature.
*
* @param {any} cert a print_certificates row
* @returns {Promise<{ status: 'attested'|'already'|'refused', signature: string|null, reason?: string }>}
*/
export async function attestCertificate(cert) {
if (cert.solana_signature) {
return { status: 'already', signature: cert.solana_signature };
}
const network = cert.network === 'mainnet' ? 'mainnet' : 'devnet';
if (network === 'mainnet') {
const gate = mainnetAttestationAllowed();
if (!gate.allowed) {
await sql`
update print_certificates
set attest_error = ${gate.reason}, attest_attempts = attest_attempts + 1
where id = ${cert.id}
`;
return { status: 'refused', signature: null, reason: gate.reason };
}
}
const memo = cert.memo && cert.memo !== '' ? cert.memo : buildCertificateMemo(cert);
const attester = loadCertAttester();
const conn = solanaConnection({ url: RPC[network], commitment: 'confirmed' });
const ix = new TransactionInstruction({
programId: MEMO_PROGRAM_ID,
keys: [{ pubkey: attester.publicKey, isSigner: true, isWritable: true }],
data: Buffer.from(memo, 'utf8'),
});
let signature;
try {
signature = await withTimeout(
sendAndConfirm(conn, new Transaction().add(ix), [attester], { commitment: 'confirmed' }),
TX_TIMEOUT_MS,
);
} catch (err) {
await sql`
update print_certificates
set attest_error = ${String(err?.message || err).slice(0, 500)},
attest_attempts = attest_attempts + 1
where id = ${cert.id}
`;
throw err;
}
await sql`
update print_certificates
set solana_signature = ${signature}, attested_at = now(), attest_error = null,
memo = ${memo}, attest_attempts = attest_attempts + 1
where id = ${cert.id}
`;
return { status: 'attested', signature };
}
/**
* @template T
* @param {Promise<T>} promise
* @param {number} ms
* @returns {Promise<T>}
*/
function withTimeout(promise, ms) {
let timer;
const timeout = new Promise((_, reject) => {
timer = setTimeout(
() => reject(Object.assign(new Error(`solana rpc timeout after ${ms}ms`), { code: 'RPC_TIMEOUT' })),
ms,
);
});
return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}
/**
* Issue the certificate for a shipped order. Idempotent: a second call returns
* the certificate the first one wrote.
*
* @param {{ orderId: string, attest?: boolean, qr?: boolean }} input
* @returns {Promise<{ certificate: any, created: boolean, attestation: { status: string, signature: string|null, reason?: string }|null }>}
*/
export async function issueCertificateForOrder({ orderId, attest = true, qr = true }) {
const [existing] = await sql`select * from print_certificates where order_id = ${orderId} limit 1`;
if (existing) {
return { certificate: existing, created: false, attestation: null };
}
const [order] = await sql`
select id, creation_id, source_glb_url, prepared_asset_urls, material_id, quote, user_id
from print_orders where id = ${orderId} limit 1
`;
if (!order) throw new PrintCertificateError('order_not_found', `no print order ${orderId}`);
const assets = order.prepared_asset_urls || {};
const glbUrl = assets.glb || order.source_glb_url;
if (!glbUrl) {
throw new PrintCertificateError(
'order_has_no_asset',
'this order carries neither a prepared GLB nor a source GLB, so there are no bytes to certify',
);
}
const glb = await readAsset(glbUrl);
const glbSha256 = sha256Hex(glb.bytes);
// The manufacturing file, when the prepare step produced one distinct from
// the GLB. Hashing it is what makes "these exact bytes were printed"
// checkable, rather than only "this model was printed".
let printAsset = null;
const picked = pickPrintAsset(assets);
if (picked && picked.url !== glbUrl) {
const read = await readAsset(picked.url);
printAsset = { kind: picked.kind, key: read.key, sha256: sha256Hex(read.bytes) };
}
const seriesKey = seriesKeyFor({ creationId: order.creation_id, glbSha256 });
const editionOf = await editionLimitFor(order.creation_id);
const materialLabel = order.quote?.material?.label || order.quote?.material_label || null;
const claimed = await claimEdition({
id: newCertificateId(),
order_id: order.id,
creation_id: order.creation_id ?? null,
series_key: seriesKey,
edition_of: editionOf,
glb_sha256: glbSha256,
glb_bytes: glb.bytes.length,
print_asset_kind: printAsset?.kind ?? null,
print_asset_key: printAsset?.key ?? null,
print_asset_sha256: printAsset?.sha256 ?? null,
material_id: order.material_id ?? null,
material_label: materialLabel,
network: certCluster(),
});
// A claim that resolved to an existing row (the order unique index won a
// race) is already complete; do not re-run its side effects.
if (claimed.memo) {
return { certificate: claimed, created: false, attestation: null };
}
const memo = buildCertificateMemo(claimed);
await sql`update print_certificates set memo = ${memo} where id = ${claimed.id}`;
let certificate = { ...claimed, memo };
if (qr) {
try {
const stored = await generateCertificateQr(certificate);
if (stored) certificate = { ...certificate, ...stored };
} catch (err) {
console.error('[print-certificate] qr generation failed:', err?.message);
}
}
let attestation = null;
if (attest) {
try {
attestation = await attestCertificate(certificate);
if (attestation.signature) {
certificate = { ...certificate, solana_signature: attestation.signature, attested_at: new Date() };
}
} catch (err) {
console.error('[print-certificate] attestation failed:', err?.message);
attestation = { status: 'failed', signature: null, reason: String(err?.message || err) };
}
}
return { certificate, created: true, attestation };
}
/**
* The retry path the print reconciliation sweep runs: certificates whose memo
* never landed, oldest first, with their QR backfilled on the way past.
*
* @param {{ limit?: number, maxAttempts?: number }} [opts]
*/
export async function retryPendingAttestations({ limit = 10, maxAttempts = 8 } = {}) {
const pending = await sql`
select * from print_certificates
where solana_signature is null and attest_attempts < ${maxAttempts}
order by created_at asc
limit ${limit}
`;
const result = { scanned: pending.length, attested: 0, refused: 0, failed: 0, qrBackfilled: 0 };
for (const cert of pending) {
if (!cert.qr_url) {
try {
if (await generateCertificateQr(cert)) result.qrBackfilled += 1;
} catch (err) {
console.error('[print-certificate] qr backfill failed:', err?.message);
}
}
try {
const out = await attestCertificate(cert);
if (out.status === 'attested') result.attested += 1;
else if (out.status === 'refused') result.refused += 1;
} catch {
result.failed += 1;
}
}
return result;
}
/**
* Public read shape. `prompt` is withheld for a private creation: the
* certificate always renders (the buyer holds the object and the proof), but a
* private model's lineage stays private.
*
* @param {string} certId
* @returns {Promise<object|null>}
*/
export async function getPublicCertificate(certId) {
if (!CERT_ID_RE.test(String(certId || ''))) return null;
const [row] = await sql`
select c.*,
o.material_id as order_material_id,
o.quantity as order_quantity,
fc.prompt as creation_prompt,
fc.visibility as creation_visibility,
fc.glb_url as creation_glb_url,
fc.preview_image_url as creation_preview_url,
fc.model_category as creation_category,
fc.parent_creation_id as creation_parent_id,
fc.refine_instruction as creation_refine_instruction,
fc.created_at as creation_created_at,
fc.print_edition_limit as creation_edition_limit,
u.username as creator_username,
u.display_name as creator_display_name
from print_certificates c
join print_orders o on o.id = c.order_id
left join forge_creations fc on fc.id = c.creation_id
left join users u on u.id = fc.user_id and u.deleted_at is null
where c.id = ${certId}
limit 1
`;
if (!row) return null;
const isPrivate = row.creation_visibility === 'private';
const [issued] = await sql`
select count(*)::int as n from print_certificates where series_key = ${row.series_key}
`;
return {
id: row.id,
edition_no: row.edition_no,
edition_of: row.edition_of ?? null,
edition_issued: issued?.n ?? row.edition_no,
printed_at: row.printed_at,
material_id: row.material_id ?? row.order_material_id ?? null,
material_label: row.material_label ?? null,
glb_sha256: row.glb_sha256,
glb_bytes: row.glb_bytes ?? null,
print_asset_kind: row.print_asset_kind ?? null,
print_asset_sha256: row.print_asset_sha256 ?? null,
network: row.network,
memo: row.memo,
solana_signature: row.solana_signature ?? null,
attested_at: row.attested_at ?? null,
explorer_url: row.solana_signature ? explorerTxUrl(row.solana_signature, row.network) : null,
qr_url: row.qr_url ?? null,
certificate_url: certificateUrl(row.id),
creation: row.creation_id
? {
id: row.creation_id,
// A private model still shows its object: the holder of the print
// owns that. Its prompt is the creator's, and stays theirs.
prompt: isPrivate ? null : (row.creation_prompt ?? null),
prompt_withheld: isPrivate,
glb_url: row.creation_glb_url ?? null,
preview_image_url: row.creation_preview_url ?? null,
category: row.creation_category ?? null,
parent_creation_id: isPrivate ? null : (row.creation_parent_id ?? null),
refine_instruction: isPrivate ? null : (row.creation_refine_instruction ?? null),
created_at: row.creation_created_at ?? null,
visibility: row.creation_visibility ?? null,
model_url: isPrivate ? null : `/m/${row.creation_id}`,
creator_username: isPrivate ? null : (row.creator_username ?? null),
creator_display_name: isPrivate ? null : (row.creator_display_name ?? null),
}
: null,
};
}
/**
* A public explorer link for a signature. The certificate page renders the raw
* memo beside it, so the page keeps working when the explorer does not.
* @param {string} signature
* @param {string} network
*/
export function explorerTxUrl(signature, network) {
const cluster = network === 'mainnet' ? '' : '?cluster=devnet';
return `https://explorer.solana.com/tx/${signature}${cluster}`;
}