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.
ERC-8004 Validation Attestation
three.ws runs an agent's GLB through the platform's glTF validator and records the
verdict on the ERC-8004 ValidationRegistry. This is what makes
supportedTrust: ["validation"] in the 3D Agent Card real: the agent carries an
on-chain, independently verifiable proof that its model passed validation.
The registry is request/response, and that shapes everything
The deployed registry is the ERC-8004 reference ValidationRegistryUpgradeable
(the same 0x8004-vanity address family as the Identity Registry). It has no
validator allow-list and no single-call "record". It has two legs:
| Call | Who may send it | What it does |
|---|---|---|
validationRequest(validator, agentId, requestURI, requestHash) |
the agent's ERC-721 owner, a per-token approved operator, or an operator approved for all | opens a request under an id the caller chooses, addressed to one validator |
validationResponse(requestHash, response, responseURI, responseHash, tag) |
only the validator named in that request | answers it with a 0..100 score, a proof hash, and a tag |
Consequences worth knowing before reading the code:
- A validator cannot attest unilaterally. The platform validator can only answer a request that exists and names it. When it holds no operator authority over the agent, the owner has to open the request first.
responseURIis emitted, never stored. The pinned report URL cannot be read back from registry storage, so the badge takes it from the platform index and only trusts it when its hash matches the on-chainresponseHash.- Score, not a boolean. A glTF check is binary, so we write 100 for a pass and
0 for a fail and read back through a midpoint threshold
(
src/erc8004/validation-report.js). - An unanswered request is visible on-chain. Its
tagis empty until the validator answers, which is how "pending" is distinguished from "no verdict".
Flow
register/bind ──▶ POST /api/erc8004/validate ──▶ api/_lib/validation-attest.js
│
1. fetch GLB (pinned SSRF guard)│ reuses the ONE glTF validator
2. sha256 the bytes (byte-check) │ (src/gltf-inspect.js, the same
3. inspectModel() -> report │ code behind /api/x402/model-check)
4. find or open the request │
5. pin report JSON -> R2 │
6. validationResponse(...) signed▼
by VALIDATOR_PRIVATE_KEY ──▶ ValidationRegistry (on-chain)
profile badge ◀── GET /api/erc8004/validation ◀── resolveLatestValidation()
(walletless) getAgentValidations(agentId)
+ getValidationStatus(hash)
Step 4 resolves one of three ways:
- A request for the platform validator already exists (same GLB re-validated, or the owner just opened one): answer it. Answering again updates that record in place, so re-validation never piles up duplicates.
- No request, but the platform validator is the owner or an approved operator: open the request, then answer it. Two transactions, one call.
- No request and no authority: return
409 validation_request_requiredwith the exact call the owner must sign (registry,validatorAddress,agentId,requestURI,requestHash). The badge prompts for it viasrc/erc8004/validation-request.js, then retriesPOST /api/erc8004/validatewith thatrequestHashso the platform answers it. Registration is never blocked either way.
The requestHash is derived, not random:
keccak256(abi.encode(chainId, agentId, kind, glbSha256)). The same model always
maps to the same request, and a new model always gets its own.
- The GLB fetch is pinned. It goes through
fetchSafePublicUrlPinned(api/_lib/ssrf-guard.js): every redirect hop is re-validated, the socket connects to the address that was checked, and the byte cap is enforced while streaming. A blocked host returnsinvalid_glb_url, an oversized modelglb_too_large, so a public URL answering 302 to an internal address cannot leak bytes into the publicly pinned report. - Pass/fail = zero parse/schema errors. Optimization suggestions are recorded
as warnings/infos and never fail a model. See
src/erc8004/validation-report.js. - Byte-check vs schema-check are independent. A passing schema validation
never overrides the sha256 byte identity; both are surfaced in the report
(
byteCheck.sha256andissues). - Best-effort. A validation failure, a missing validator key, an undeployed registry, or a missing request never blocks or reverts the registration. The agent is registered; it is just unvalidated, and the badge says so.
- Verifying a proof.
hashReport()keccaks the report's compact JSON. Fetch the pinned file,JSON.stringify(JSON.parse(bytes)), keccak it, and compare against the chain'sresponseHash. - One dead RPC never blocks an attestation. The attestor signs against
evmFallbackProvider(chainId)fromapi/_lib/evm/rpc.js, a quorum-1 fallback over the chain's endpoint list in priority order, so both the reads in step 4 and the broadcast in step 6 go through whichever endpoint answers. On BSC Testnet that list leads with PublicNode, because the bnbchain data-seed nodes refuse everyeth_getLogscall outright. - The
/validationdashboard resolvesipfs://report links through the shared gateway list insrc/ipfs.js(resolveURI), the same rotation the rest of the platform uses, rather than one hardcoded gateway.
Badge states
src/shared/validation-badge.js renders five designed states from the on-chain
read: validated (green, links to the proof report + validator), validation
failed (red, shows the failure reason from the pinned report), validation
pending (a request is open, no verdict yet), not validated (registry
deployed, nothing requested, and owners get a Validate action), and pending
(while fetching / attesting). When the ValidationRegistry is not deployed on the
agent's chain the badge renders nothing.
Operating the platform validator
The validator is a dedicated EVM key. It is not in the repo.
- Provision (already done, address below):
Address:node scripts/erc8004/provision-validator-key.mjs0x93Bc7EfB0059B784465619FC73C2db8D01b1CD04(provisioned 2026-06-15). - Store the secret: set
VALIDATOR_PRIVATE_KEYon the Cloud Run service (three-ws-api) for production and.env.localfor local runs. Never commit it. - Fund the address with gas on each ValidationRegistry chain. It pays for the response transaction (and the request too, on agents where it is an operator).
- Nothing to allow-list. The registry has no validator list; authority comes
from the request. To let the platform attest without prompting the owner, the
owner approves the validator as an operator on the Identity Registry
(
approve(validator, agentId)orsetApprovalForAll(validator, true)).
Until the key is configured on a chain whose ValidationRegistry is deployed,
/api/erc8004/validate returns a clear ops error (validator_key_not_configured,
validation_registry_not_deployed, or validation_request_required), never a
silent skip. Testnet (Base Sepolia 84532 and six sibling testnets) has the
registry deployed and is the first end-to-end target; mainnet has no reference
deployment yet, so VALIDATION_REGISTRY_MAINNET stays empty and the badge renders
nothing there.
Before trusting any address in that table, run:
npm run verify:erc8004-validation
It follows each configured registry to its implementation, asserts every selector
in VALIDATION_REGISTRY_ABI is present in the bytecode, and exercises the reads
the badge depends on. This check exists because "there is bytecode at the address"
was once mistaken for "the address implements our interface": the platform pointed
at the reference registry while calling functions from
contracts/src/ValidationRegistry.sol, every call reverted, and the read path
reported the reverts as "no attestation yet".
Surfaces
| Piece | File |
|---|---|
| Pure report + score/request-id helpers | src/erc8004/validation-report.js |
| Server attestor | api/_lib/validation-attest.js |
Endpoints (validate POST, validation GET) |
api/erc8004/[action].js |
| Walletless on-chain read | api/_lib/onchain.js -> resolveLatestValidation |
| Owner request leg (browser) | src/erc8004/validation-request.js |
| Registry address + ABI | api/_lib/erc8004-chains.js |
| Interface verifier | scripts/erc8004/verify-validation-registry.mjs |
| Badge component | src/shared/validation-badge.js |
| Profile render | src/agent-detail.js |
| Public dashboard | src/validation-ui.js, /validation |
| DB cache (list views / ops) | migrations 20260615000000_erc8004_validation.sql, 20260806120000_erc8004_validation_request_hash.sql |