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 Passport Widget — public, read-only on-chain identity card
* rendered alongside the 3D avatar canvas.
*
* Contract reads run in parallel:
* IdentityRegistry.ownerOf(agentId) → wallet
* IdentityRegistry.tokenURI(agentId) → registration JSON URL
* IdentityRegistry.name()/symbol() → collection label
* erc8004/reputation.js getReputation → star average + count, on either registry dialect
* erc8004/reputation.js getRecentReviews → recent feedback (if enabled)
* ValidationRegistry.getLatestValidation → optional proof row
*
* No wallet connection, no writes, no feedback submission. That's a v2 task.
*/
import { Contract, JsonRpcProvider } from 'ethers';
import { IDENTITY_REGISTRY_ABI, REGISTRY_DEPLOYMENTS } from '../erc8004/index.js';
import { getReputation, getRecentReviews } from '../erc8004/reputation.js';
import {
CHAIN_SLUGS,
PUBLIC_RPCS,
EXPLORERS,
resolveChainId,
chainLabel,
} from '../widget-types.js';
import { resolveURI, isDecentralizedURI } from '../ipfs.js';
import { log } from '../shared/log.js';
import { shortAddress } from '../shared/address.js';
const CACHE_PREFIX = 'erc8004-passport:';
const STALE_TTL_MS = 1000 * 60 * 60 * 24; // 24h hard ceiling on stale cache
/**
* Mount the passport widget.
*
* @param {import('../viewer.js').Viewer} viewer The three.js viewer instance.
* @param {object} config Passport config (see widget-types.js passport schema).
* @param {HTMLElement} container Root container. The widget takes this over.
* @param {string} [widgetId] Optional cache-busting key.
* @returns {Promise<{ destroy: () => void }>}
*/
export async function mountPassport(viewer, config, container, widgetId) {
const state = {
config,
widgetId: widgetId || `${config.chain}:${config.agentId}`,
cacheKey: `${CACHE_PREFIX}${config.chain}:${config.agentId}`,
chainId: resolveChainId(config.chain),
data: null,
lastVerifiedAt: null,
destroyed: false,
pollTimer: null,
visibilityHandler: null,
};
_applyTurntable(viewer, config);
_kioskifyCanvas(viewer, container);
const panel = document.createElement('div');
panel.className = `passport-panel passport-layout--${config.layout} passport-badge-size--${config.badgeSize}`;
container.appendChild(panel);
const root = container;
root.classList.add('passport-widget', `passport-root--${config.layout}`);
_renderLoading(panel, config);
// Hydrate from cache immediately so the panel has content before RPC responds.
const cached = _readCache(state.cacheKey);
if (cached && cached.data) {
state.data = cached.data;
state.lastVerifiedAt = cached.savedAt;
_render(panel, state);
}
await _refresh(state, panel);
if (config.refreshIntervalSec > 0) {
const tick = () => {
if (state.destroyed) return;
if (document.hidden) return;
_refresh(state, panel).catch(() => {
/* keep stale */
});
};
state.pollTimer = setInterval(tick, config.refreshIntervalSec * 1000);
state.visibilityHandler = () => {
if (!document.hidden) tick();
};
document.addEventListener('visibilitychange', state.visibilityHandler);
}
return {
destroy() {
state.destroyed = true;
if (state.pollTimer) clearInterval(state.pollTimer);
if (state.visibilityHandler) {
document.removeEventListener('visibilitychange', state.visibilityHandler);
}
panel.remove();
root.classList.remove('passport-widget', `passport-root--${config.layout}`);
},
};
}
// ---------------------------------------------------------------------------
// RPC + contract reads
// ---------------------------------------------------------------------------
function _pickRpc(config, chainId) {
if (config.rpcURL) {
// Require HTTPS per the security spec.
if (!/^https:\/\//i.test(config.rpcURL)) {
log.warn('[passport] ignoring non-HTTPS rpcURL');
} else {
return config.rpcURL;
}
}
return PUBLIC_RPCS[chainId] || null;
}
async function _refresh(state, panel) {
const { config, chainId } = state;
if (!chainId) {
_renderError(panel, `Unknown chain "${config.chain}".`, state);
return;
}
const deployment = REGISTRY_DEPLOYMENTS[chainId];
if (!deployment || !deployment.identityRegistry) {
_renderError(panel, `No ERC-8004 registry deployed on ${chainLabel(chainId)}.`, state);
return;
}
if (!config.agentId) {
_renderError(panel, 'No agent id configured.', state);
return;
}
if (!/^\d+$/.test(String(config.agentId))) {
_renderError(panel, 'Invalid agent id.', state);
return;
}
const rpcURL = _pickRpc(config, chainId);
if (!rpcURL) {
_renderError(panel, `No RPC available for ${chainLabel(chainId)}.`, state);
return;
}
try {
const provider = new JsonRpcProvider(rpcURL, chainId, { staticNetwork: true });
const identity = new Contract(deployment.identityRegistry, IDENTITY_REGISTRY_ABI, provider);
const hasReputation = Boolean(deployment.reputationRegistry);
const agentId = BigInt(config.agentId);
// ownerOf will revert for non-existent tokens; catch that specifically.
const [ownerRes, tokenURIRes, nameRes, symbolRes, repRes] = await Promise.allSettled([
identity.ownerOf(agentId),
identity.tokenURI(agentId),
identity.name(),
identity.symbol(),
hasReputation && config.showReputation
? getReputation({ agentId, runner: provider, chainId })
: Promise.resolve(null),
]);
if (ownerRes.status === 'rejected') {
_renderError(panel, 'Agent not found on this chain.', state);
return;
}
const wallet = ownerRes.value;
const tokenURI = tokenURIRes.status === 'fulfilled' ? tokenURIRes.value : '';
const name = nameRes.status === 'fulfilled' ? nameRes.value : '';
const symbol = symbolRes.status === 'fulfilled' ? symbolRes.value : '';
let reputationData = null;
if (repRes.status === 'fulfilled' && repRes.value) {
reputationData = { count: repRes.value.count, average: repRes.value.average };
}
let feedback = [];
if (hasReputation && config.showRecentFeedback) {
feedback = await _fetchRecentFeedback(agentId, provider, chainId).catch(() => []);
}
let manifest = null;
if (tokenURI) {
manifest = await _fetchManifest(tokenURI).catch(() => null);
}
state.data = {
wallet,
tokenURI,
name,
symbol,
reputation: reputationData,
feedback,
manifest,
};
state.lastVerifiedAt = Date.now();
_writeCache(state.cacheKey, { data: state.data, savedAt: state.lastVerifiedAt });
_render(panel, state);
} catch (err) {
log.warn('[passport] refresh failed:', err.message || err);
// Leave whatever stale data we had; update the status label.
_render(panel, state, { staleReason: 'RPC error' });
}
}
/**
* Query the last N ReputationSubmitted events for this agent.
* Scoped to the recent history to avoid full-log scans.
*/
async function _fetchRecentFeedback(agentId, provider, chainId) {
const reviews = await getRecentReviews({ agentId, runner: provider, chainId });
return reviews
.slice(-5)
.reverse()
.map((r) => ({
from: r.from,
score: r.score,
comment: _sanitizeText(r.comment || ''),
txHash: r.txHash,
}));
}
async function _fetchManifest(tokenURI) {
const resolved = isDecentralizedURI(tokenURI) ? resolveURI(tokenURI) : tokenURI;
if (!/^https?:\/\//i.test(resolved)) return null;
const res = await fetch(resolved, { mode: 'cors' });
if (!res.ok) throw new Error(`manifest fetch ${res.status}`);
const ct = res.headers.get('content-type') || '';
if (!ct.includes('json') && !resolved.endsWith('.json')) {
// Only fetch JSON — never render tokenURI HTML.
return null;
}
const json = await res.json();
return _pickManifestFields(json);
}
/** Allow-list the fields we render. Drop everything else. */
function _pickManifestFields(raw) {
if (!raw || typeof raw !== 'object') return null;
return {
name: typeof raw.name === 'string' ? raw.name.slice(0, 120) : '',
description: typeof raw.description === 'string' ? raw.description.slice(0, 500) : '',
image: typeof raw.image === 'string' ? raw.image : '',
agentRegistry: typeof raw.agentRegistry === 'string' ? raw.agentRegistry.slice(0, 200) : '',
};
}
// ---------------------------------------------------------------------------
// Rendering
// ---------------------------------------------------------------------------
function _renderLoading(panel, config) {
panel.innerHTML = `
<div class="passport-card" role="status">
<div class="passport-skeleton">
<div class="passport-skeleton-row"></div>
<div class="passport-skeleton-row short"></div>
<div class="passport-skeleton-row"></div>
</div>
<span class="passport-loading-label">Loading on-chain identity…</span>
</div>
${config.showPoweredBy ? _poweredByHTML(config) : ''}
`;
}
function _renderError(panel, message, state) {
const { config } = state;
panel.innerHTML = `
<div class="passport-card passport-card--error" role="alert">
<div class="passport-error-icon" aria-hidden="true">!</div>
<div class="passport-error-msg">${_escapeHTML(message)}</div>
</div>
${config.showPoweredBy ? _poweredByHTML(config) : ''}
`;
}
function _render(panel, state, opts = {}) {
const { config, chainId, data, lastVerifiedAt } = state;
if (!data) {
// No data and no error path yet — leave whatever's up.
return;
}
const explorer = EXPLORERS[chainId] || '';
const walletShort = _shortAddr(data.wallet);
const agentName = data.manifest?.name || data.name || `Agent #${config.agentId}`;
const verifiedISO = lastVerifiedAt ? new Date(lastVerifiedAt).toISOString() : '';
const verifiedRel = lastVerifiedAt ? _relativeTime(lastVerifiedAt) : '';
const stale = Boolean(opts.staleReason);
const repBlock =
config.showReputation && data.reputation
? `
<div class="passport-row passport-row--reputation">
<span class="passport-star" aria-hidden="true">★</span>
<span class="passport-rep-avg">${data.reputation.count === 0 ? '—' : data.reputation.average.toFixed(2)}</span>
<span class="passport-rep-count">(${data.reputation.count} ${data.reputation.count === 1 ? 'review' : 'reviews'})</span>
</div>
`
: '';
const feedbackBlock =
config.showRecentFeedback && data.feedback && data.feedback.length
? `
<div class="passport-section passport-section--feedback">
<div class="passport-section-title">Recent feedback</div>
<ul class="passport-feedback-list">
${data.feedback
.map(
(f) => `
<li class="passport-feedback-item">
<span class="passport-feedback-comment">${_escapeHTML(f.comment || '—')}</span>
<span class="passport-feedback-meta">${_shortAddr(f.from)} · ${f.score}★</span>
</li>
`,
)
.join('')}
</ul>
</div>
`
: '';
const jsonBlock =
config.showRegistrationJSON && data.tokenURI
? `
<div class="passport-section passport-section--json">
<a class="passport-json-link" href="${_escapeAttr(_resolveForLink(data.tokenURI))}" target="_blank" rel="noopener noreferrer">
View passport JSON ↗
</a>
</div>
`
: '';
const explorerLink = explorer
? `
<a class="passport-explorer-link" href="${_escapeAttr(`${explorer}/address/${data.wallet}`)}" target="_blank" rel="noopener noreferrer" title="View on explorer">↗</a>
`
: '';
const chainSlug = chainLabel(chainId);
const staleBanner = stale
? `
<div class="passport-stale">Offline · last verified ${_escapeHTML(verifiedRel)}</div>
`
: '';
if (config.layout === 'badge') {
panel.innerHTML = `
<div class="passport-badge" role="group" aria-label="ERC-8004 Passport">
<div class="passport-badge-name" title="${_escapeAttr(agentName)}">${_escapeHTML(agentName)}</div>
<div class="passport-badge-line">
<span class="passport-badge-id">#${_escapeHTML(String(config.agentId))}</span>
<span class="passport-badge-sep">·</span>
<span class="passport-badge-chain">${_escapeHTML(chainSlug)}</span>
<span class="passport-badge-check" aria-label="Registered on-chain">✓</span>
</div>
${
config.showReputation && data.reputation
? `
<div class="passport-badge-rep">
<span class="passport-star" aria-hidden="true">★</span>
${data.reputation.count === 0 ? '—' : data.reputation.average.toFixed(2)}
</div>
`
: ''
}
${staleBanner}
</div>
${config.showPoweredBy ? _poweredByHTML(config) : ''}
`;
return;
}
panel.innerHTML = `
<div class="passport-card">
<div class="passport-header">
<div class="passport-name">${_escapeHTML(agentName)}</div>
<div class="passport-check" aria-label="Registered on-chain" title="Registered on-chain">✓</div>
</div>
<div class="passport-subhead">
<span class="passport-id">Agent #${_escapeHTML(String(config.agentId))}</span>
<span class="passport-sep">·</span>
<span class="passport-chain">${_escapeHTML(chainSlug)}</span>
</div>
<div class="passport-wallet-row">
<button type="button" class="passport-wallet" data-copy="${_escapeAttr(data.wallet)}" title="Copy ${_escapeAttr(data.wallet)}">
${_escapeHTML(walletShort)}
</button>
${explorerLink}
</div>
${repBlock}
${feedbackBlock}
${jsonBlock}
${
lastVerifiedAt
? `
<div class="passport-verified" title="${_escapeAttr(verifiedISO)}">
${stale ? 'Last verified' : 'Verified'} ${_escapeHTML(verifiedRel)}
</div>
`
: ''
}
</div>
${config.showPoweredBy ? _poweredByHTML(config) : ''}
`;
const copyBtn = panel.querySelector('.passport-wallet[data-copy]');
if (copyBtn) {
copyBtn.addEventListener('click', () => {
const addr = copyBtn.dataset.copy;
if (!addr) return;
navigator.clipboard
?.writeText(addr)
.then(() => {
copyBtn.classList.add('passport-wallet--copied');
setTimeout(() => copyBtn.classList.remove('passport-wallet--copied'), 1200);
})
.catch(() => {
/* ignore */
});
});
}
}
function _poweredByHTML(_config) {
return `
<a class="passport-powered-by" href="https://three.ws/" target="_blank" rel="noopener noreferrer">
three.ws
</a>
`;
}
// ---------------------------------------------------------------------------
// Viewer setup
// ---------------------------------------------------------------------------
function _applyTurntable(viewer, config) {
if (!viewer || !viewer.controls) return;
if (config.autoRotate === false) return;
viewer.state.autoRotate = true;
viewer.controls.autoRotate = true;
viewer.controls.autoRotateSpeed = (config.rotationSpeed ?? 0.6) * 4;
viewer.invalidate?.();
}
function _kioskifyCanvas(_viewer, container) {
// Reduce viewer chrome for embed contexts.
const validator = document.querySelector('.validator-toggle');
if (validator) validator.style.display = 'none';
const header = document.querySelector('header');
if (header) header.style.display = 'none';
container.classList.add('passport-canvas-host');
}
// ---------------------------------------------------------------------------
// Cache
// ---------------------------------------------------------------------------
function _readCache(key) {
try {
const raw = localStorage.getItem(key);
if (!raw) return null;
const parsed = JSON.parse(raw);
if (!parsed?.savedAt) return null;
if (Date.now() - parsed.savedAt > STALE_TTL_MS) return null;
return parsed;
} catch {
return null;
}
}
function _writeCache(key, payload) {
try {
// Wallet & tokenURI are strings. Only persist serialisable fields.
const safe = {
savedAt: payload.savedAt,
data: {
wallet: payload.data.wallet,
tokenURI: payload.data.tokenURI,
name: payload.data.name,
symbol: payload.data.symbol,
reputation: payload.data.reputation,
feedback: payload.data.feedback,
manifest: payload.data.manifest,
},
};
localStorage.setItem(key, JSON.stringify(safe));
} catch {
/* quota / privacy mode — ignore */
}
}
// ---------------------------------------------------------------------------
// Utilities
// ---------------------------------------------------------------------------
function _shortAddr(addr) { return shortAddress(addr, 6, 4); }
function _escapeHTML(s) {
return String(s ?? '')
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
function _escapeAttr(s) {
return _escapeHTML(s);
}
function _sanitizeText(s) {
// Strip anything that looks like a tag. Feedback is plain text.
return String(s ?? '')
.replace(/<[^>]*>/g, '')
.slice(0, 500);
}
function _relativeTime(ts) {
const diff = Date.now() - ts;
const sec = Math.floor(diff / 1000);
if (sec < 60) return 'just now';
const min = Math.floor(sec / 60);
if (min < 60) return `${min}m ago`;
const hr = Math.floor(min / 60);
if (hr < 24) return `${hr}h ago`;
const day = Math.floor(hr / 24);
return `${day}d ago`;
}
function _resolveForLink(uri) {
return isDecentralizedURI(uri) ? resolveURI(uri) : uri;
}
// Re-export for Studio later.
export { CHAIN_SLUGS };