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
/**
* ERC-8004 ValidationRegistry attestor (server-side).
*
* Turns an agent's GLB into a signed, on-chain validation attestation:
*
* 1. Fetch the GLB (SSRF-guarded) and run it through the platform's one glTF
* validator — the same inspector behind /api/x402/model-check. Parse-success
* ⇒ structurally valid; parse-failure ⇒ a hard error in the report.
* 2. Independently sha256 the exact bytes (byte-check, surfaced separately —
* a passing schema validation never overrides byte identity, per spec).
* 3. Build the canonical report and pin it to R2. `hashReport()` keccaks the
* report's compact JSON, so a verifier fetches the pinned file, re-stringifies
* it without indentation, re-hashes, and compares against the chain.
* 4. Answer the agent's on-chain validation request from the platform validator
* key with validationResponse(requestHash, score, proofURI, proofHash, kind),
* opening the request first when the platform is allowed to.
*
* Best-effort by contract: callers wrap this in try/catch — a validation failure
* (or missing key / undeployed registry / no open request) must never block or
* revert the registration itself. Errors carry a machine-readable `.code` so the
* caller can surface a clear ops state instead of a silent skip.
*/
import { createHash } from 'node:crypto';
import { Contract, Wallet } from 'ethers';
import { env } from './env.js';
import { CHAIN_BY_ID, VALIDATION_REGISTRY_ABI, validationRegistryFor } from './erc8004-chains.js';
import { evmFallbackProvider } from './evm/rpc.js';
import { putObject, publicUrl } from './r2.js';
import {
assertSafePublicUrl,
fetchSafePublicUrlPinned,
MaxBytesExceededError,
SsrfBlockedError,
} from './ssrf-guard.js';
import { inspectModel, suggestOptimizations } from './model-inspect.js';
import {
buildGlbReport,
hashReport,
reportPassed,
responseForPassed,
validationRequestHash,
KIND_GLB_SCHEMA,
} from '../../src/erc8004/validation-report.js';
// Just the ERC-721 authority reads the registry itself checks before accepting a
// validationRequest: enough to tell "we can open this request" from "the owner
// has to".
const IDENTITY_AUTH_ABI = [
'function ownerOf(uint256 tokenId) external view returns (address)',
'function getApproved(uint256 tokenId) external view returns (address)',
'function isApprovedForAll(address owner, address operator) external view returns (bool)',
];
const MAX_FETCH_BYTES = 16 * 1024 * 1024;
const FETCH_TIMEOUT_MS = 20_000;
class AttestError extends Error {
constructor(code, message) {
super(message);
this.name = 'AttestError';
this.code = code;
}
}
/**
* Fetch + validate a GLB. Never throws on an *invalid model* — an unparseable
* GLB is a valid outcome (a failing report). Only throws on transport/SSRF
* problems the caller can't attribute to the model.
*
* @param {string} glbUrl
* @param {string} validatedAt ISO timestamp (caller-supplied).
* @returns {Promise<{ report: object, passed: boolean, sha256: string, byteLength: number }>}
*/
export async function validateGlb(glbUrl, validatedAt) {
let parsed;
try {
parsed = await assertSafePublicUrl(glbUrl, { allowHttp: true });
} catch (err) {
if (err instanceof SsrfBlockedError) throw new AttestError('invalid_glb_url', err.message);
throw err;
}
// Pinned fetch: every redirect hop is re-validated and the socket connects
// to the address that was checked, so a public host answering 302 to the
// metadata server (or rebinding its DNS) cannot pull internal bytes into a
// report that is then pinned publicly. The byte cap is enforced while
// streaming, before the body is buffered.
let upstream;
try {
upstream = await fetchSafePublicUrlPinned(
parsed.toString(),
{
headers: { accept: 'model/gltf-binary,model/gltf+json,application/octet-stream' },
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
},
{ allowHttp: true, maxBytes: MAX_FETCH_BYTES },
);
} catch (err) {
if (err instanceof SsrfBlockedError) throw new AttestError('invalid_glb_url', err.message);
if (err instanceof MaxBytesExceededError) {
throw new AttestError('glb_too_large', `GLB is ${err.observed} bytes; max ${MAX_FETCH_BYTES}`);
}
throw new AttestError('glb_fetch_failed', `could not fetch GLB: ${err.message}`);
}
if (!upstream.ok) {
throw new AttestError('glb_fetch_failed', `GLB fetch returned ${upstream.status}`);
}
const contentLength = Number(upstream.headers.get('content-length') || 0);
if (contentLength && contentLength > MAX_FETCH_BYTES) {
throw new AttestError('glb_too_large', `GLB is ${contentLength} bytes; max ${MAX_FETCH_BYTES}`);
}
const bytes = new Uint8Array(await upstream.arrayBuffer());
if (bytes.byteLength > MAX_FETCH_BYTES) {
throw new AttestError('glb_too_large', `GLB is ${bytes.byteLength} bytes; max ${MAX_FETCH_BYTES}`);
}
const sha256 = createHash('sha256').update(bytes).digest('hex');
let inspect = null;
let suggestions = [];
let error = null;
try {
inspect = await inspectModel(bytes, { fileSize: bytes.byteLength });
suggestions = suggestOptimizations(inspect);
} catch (err) {
// Unparseable model → a failing report, not a thrown attestation.
error = err?.message || 'model failed to parse';
}
const report = buildGlbReport({
url: parsed.toString(),
sha256,
byteLength: bytes.byteLength,
inspect,
suggestions,
error,
validatedAt,
});
return { report, passed: reportPassed(report), sha256, byteLength: bytes.byteLength };
}
/**
* Pin the report JSON to R2 and return its public URL.
* @param {object} report
* @param {number} chainId
* @param {string|number} agentId
* @returns {Promise<string>}
*/
async function pinReport(report, chainId, agentId) {
const body = Buffer.from(JSON.stringify(report, null, 2));
const key = `erc8004/validation/${chainId}/${agentId}/${report.byteCheck?.sha256 || 'report'}.json`;
await putObject({ key, body, contentType: 'application/json' });
return publicUrl(key);
}
/** Read a request's on-chain status. Returns null when no such request exists. */
async function readRequest(registry, requestHash) {
try {
const s = await registry.getValidationStatus(requestHash);
return {
validator: s[0],
agentId: s[1],
response: Number(s[2]),
responseHash: s[3],
tag: s[4],
lastUpdate: Number(s[5]),
};
} catch (err) {
// The registry reverts require("unknown") for a hash it has never seen.
if (err?.code === 'CALL_EXCEPTION' || /unknown/i.test(String(err?.shortMessage || err?.message))) {
return null;
}
throw new AttestError('registry_read_failed', `could not read validation status: ${err.message}`);
}
}
/**
* Can `validator` open a validation request for this agent? The registry allows
* the agent's ERC-721 owner, a per-token approved operator, or an operator
* approved for all of the owner's tokens.
*/
async function canOpenRequest({ identityAddr, provider, agentId, validator }) {
if (!identityAddr) return false;
const identity = new Contract(identityAddr, IDENTITY_AUTH_ABI, provider);
const id = BigInt(agentId);
let owner;
try {
owner = await identity.ownerOf(id);
} catch {
return false;
}
if (owner.toLowerCase() === validator.toLowerCase()) return true;
const [approved, forAll] = await Promise.all([
identity.getApproved(id).catch(() => null),
identity.isApprovedForAll(owner, validator).catch(() => false),
]);
return Boolean(forAll) || (approved && approved.toLowerCase() === validator.toLowerCase());
}
/**
* Full attestation: validate the GLB, pin the report, answer on-chain.
*
* The deployed ValidationRegistry is two-legged: the agent's owner (or an
* approved operator) opens a request naming a validator, and only that validator
* may answer it. So this runs one of three ways:
*
* - a request for our validator already exists → answer it (this is also the
* re-validation path: answering again updates the record in place);
* - no request, but the platform validator is the owner/an approved operator
* → open the request itself, then answer it;
* - no request and no authority → throw `validation_request_required` carrying
* the exact call the owner's wallet must submit, so the UI can prompt for it.
*
* Best-effort by contract: callers wrap this in try/catch and registration is
* never blocked by the outcome.
*
* @param {object} p
* @param {number} p.chainId
* @param {string|number} p.agentId
* @param {string} p.glbUrl
* @param {string} p.validatedAt ISO timestamp (caller-supplied; deterministic hashing).
* @param {string} [p.requestHash] Answer this exact request (the owner just opened it).
* @returns {Promise<{
* passed: boolean, proofHash: string, proofURI: string, txHash: string,
* requestHash: string, requestTxHash: string|null, score: number,
* sha256: string, validatedAt: string, kind: string, chainId: number,
* agentId: string, validator: string, report: object,
* }>}
*/
export async function attestValidation({ chainId, agentId, glbUrl, validatedAt, requestHash: pinnedHash }) {
const chain = CHAIN_BY_ID[chainId];
if (!chain) throw new AttestError('unsupported_chain', `unsupported chain ${chainId}`);
const registryAddr = validationRegistryFor(chainId);
if (!registryAddr) {
throw new AttestError(
'validation_registry_not_deployed',
`ValidationRegistry is not deployed on ${chain.name} (chain ${chainId}).`,
);
}
const pk = env.VALIDATOR_PRIVATE_KEY;
if (!pk) {
throw new AttestError(
'validator_key_not_configured',
'VALIDATOR_PRIVATE_KEY is not set, so no attestation can be signed.',
);
}
// 1. Validate the GLB (this part never throws on an invalid model).
const { report, passed, sha256 } = await validateGlb(glbUrl, validatedAt);
// 2. Provider + wallet. The quorum-1 FallbackProvider tries the chain's
// endpoints in priority order for reads and broadcasts the signed write
// through whichever answers, so one dead RPC never blocks an attestation.
const provider = await evmFallbackProvider(chainId);
const wallet = new Wallet(pk, provider);
const registry = new Contract(registryAddr, VALIDATION_REGISTRY_ABI, wallet);
// 3. Find (or open) the request this attestation answers.
const requestHash = pinnedHash || validationRequestHash({ chainId, agentId, seed: `0x${sha256}` });
const existing = await readRequest(registry, requestHash);
if (existing && existing.validator.toLowerCase() !== wallet.address.toLowerCase()) {
throw new AttestError(
'request_not_for_validator',
`Request ${requestHash} names validator ${existing.validator}, not the platform validator ${wallet.address}.`,
);
}
if (existing && String(existing.agentId) !== String(agentId)) {
throw new AttestError(
'request_agent_mismatch',
`Request ${requestHash} belongs to agent ${existing.agentId}, not ${agentId}.`,
);
}
let requestTxHash = null;
if (!existing) {
const authorized = await canOpenRequest({
identityAddr: chain.registry,
provider,
agentId,
validator: wallet.address,
});
if (!authorized) {
const err = new AttestError(
'validation_request_required',
`Agent ${agentId} has no open validation request for ${wallet.address}. The agent owner must call ` +
`validationRequest(${wallet.address}, ${agentId}, <glbUrl>, ${requestHash}) on ${registryAddr}, then retry.`,
);
err.request = {
chainId,
agentId: String(agentId),
registry: registryAddr,
validatorAddress: wallet.address,
requestURI: glbUrl,
requestHash,
};
throw err;
}
let reqTx;
try {
reqTx = await registry.validationRequest(wallet.address, BigInt(agentId), glbUrl, requestHash);
} catch (err) {
throw new AttestError('request_failed', `validationRequest reverted: ${err.shortMessage || err.message}`);
}
await reqTx.wait();
requestTxHash = reqTx.hash;
}
// 4. Pin the report, then answer the request. `responseURI` is emitted but not
// stored by the registry, so the pinned URL is recovered from the event (or
// our index cache); `responseHash` is the integrity check that binds them.
const proofURI = await pinReport(report, chainId, agentId);
const proofHash = hashReport(report);
const score = responseForPassed(passed);
let tx;
try {
tx = await registry.validationResponse(requestHash, score, proofURI, proofHash, KIND_GLB_SCHEMA);
} catch (err) {
throw new AttestError('response_failed', `validationResponse reverted: ${err.shortMessage || err.message}`);
}
await tx.wait();
return {
passed,
score,
proofHash,
proofURI,
txHash: tx.hash,
requestHash,
requestTxHash,
sha256,
validatedAt,
kind: KIND_GLB_SCHEMA,
chainId,
agentId: String(agentId),
validator: wallet.address,
report,
};
}
export { AttestError };