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
/**
* Verifiable, provably-fair vanity grinding — the protocol primitive.
*
* Every other vanity service asks you to trust the operator: trust that the key
* was generated with real randomness, that no copy was kept, that they didn't
* grind 10,000 candidates and hand you the one whose key they secretly logged.
* This module makes all three claims *provable* after the fact, with nothing but
* the receipt and open-source crypto.
*
* ── Protocol `three-vanity/v1` (commit–reveal seed mixing) ───────────────────
*
* 1. COMMIT. Before grinding, the server draws a uniformly random 32-byte
* `serverSeed` and publishes `commitment = SHA-256("three-vanity/seed-commit/v1"
* ‖ serverSeed)`. The commitment is bound into the signed receipt, so the
* server is locked to that seed *before* it knows which candidate will win —
* it cannot have precomputed a rainbow table keyed to the buyer's pattern.
*
* 2. MIX. Neither party alone may control the output. The two seeds plus the
* request nonce are folded into a single master seed:
*
* masterSeed = HKDF-SHA256(
* ikm = serverSeed ‖ clientSeed ‖ requestNonce,
* salt = SHA-256("three-vanity/mix-salt/v1"),
* info = "three-vanity/master/v1",
* len = 32)
*
* `clientSeed` is buyer-supplied (or a fresh random one we reveal); the buyer
* therefore contributes entropy the server could not predict at commit time.
*
* 3. DERIVE. Candidate `i` (a 0-based counter) has a fully deterministic Ed25519
* secret seed:
*
* seed_i = HMAC-SHA256(key = masterSeed,
* msg = "three-vanity/candidate/v1" ‖ uint64_be(i))
*
* The 32-byte `seed_i` is the Ed25519 private scalar seed; its public key is
* the Solana address. The grinder walks i = 0,1,2,… until the address matches
* the pattern; the winning index is recorded as `winningIndex`.
*
* 4. SEAL + SIGN. The secret is sealed to the buyer (ECIES, sealed-envelope.js)
* so plaintext never touches the wire, and the server signs the receipt with
* its long-lived Ed25519 identity key (published at /.well-known/three-vanity.json).
*
* ── Verification (verifyVanityReceipt) reproduces, never trusts ──────────────
*
* • SHA-256(serverSeed) === commitment (server didn't swap the seed)
* • re-derive masterSeed and seed_{winningIndex} (mixing was honest)
* • that seed's public key === receipt.address (address ↔ key bind)
* • address satisfies the claimed pattern (pattern honesty)
* • Ed25519 verify(signature, receipt, serviceKey) (it's really our service)
* • optionally: opened secret === re-derived secret (the sealed key is THE key)
*
* Determinism is the whole point, so this file hand-derives every candidate in
* JS (noble Ed25519) rather than the WASM grinder — the verifier must reproduce
* the exact stream. It is isomorphic: @noble/curves + @noble/hashes give pure-JS
* Ed25519/HMAC/HKDF/SHA-256 that run identically in Node serverless and the
* browser. Behaviour is pinned by fixed vectors in
* tests/vanity-verifiable-grind.test.js (including a tamper/negative test).
*/
import bs58 from 'bs58';
import { ed25519 } from '@noble/curves/ed25519.js';
import { sha256 } from '@noble/hashes/sha256';
import { hmac } from '@noble/hashes/hmac';
import { hkdf } from '@noble/hashes/hkdf';
import { bytesToHex, hexToBytes, concatBytes } from '@noble/hashes/utils';
import {
validatePattern,
BASE58_ALPHABET,
expectedAttempts,
difficultyModel,
DIFFICULTY_MODEL,
DIFFICULTY_MODEL_V1,
} from './validation.js';
export const PROTOCOL_VERSION = 'three-vanity/v1';
export const RECEIPT_TYPE = 'three-vanity-receipt';
export const SIGNATURE_SCHEME = 'ed25519';
const enc = new TextEncoder();
// Domain-separation tags. Distinct prefixes guarantee a hash computed for one
// purpose can never collide with one computed for another.
const TAG_SEED_COMMIT = enc.encode('three-vanity/seed-commit/v1');
const TAG_MIX_SALT = sha256(enc.encode('three-vanity/mix-salt/v1'));
const TAG_MASTER_INFO = enc.encode('three-vanity/master/v1');
const TAG_CANDIDATE = enc.encode('three-vanity/candidate/v1');
const TAG_RECEIPT = enc.encode('three-vanity/receipt/v1');
const SEED_BYTES = 32;
function asBytes(value, label) {
if (value instanceof Uint8Array) return value;
if (typeof value === 'string') {
const s = value.trim();
if (/^[0-9a-fA-F]+$/.test(s) && s.length % 2 === 0) return hexToBytes(s);
try {
return bs58.decode(s);
} catch {
throw new Error(`${label} is not valid hex or Base58`);
}
}
throw new Error(`${label} must be a Uint8Array, hex, or Base58 string`);
}
/** 32 cryptographically-random bytes (WebCrypto, works in Node + browser). */
export function randomSeed() {
const b = new Uint8Array(SEED_BYTES);
globalThis.crypto.getRandomValues(b);
return b;
}
/** uint64 big-endian encoding of a non-negative integer counter. */
function uint64be(n) {
const out = new Uint8Array(8);
let v = BigInt(n);
for (let i = 7; i >= 0; i--) {
out[i] = Number(v & 0xffn);
v >>= 8n;
}
return out;
}
/**
* Commitment the server publishes before grinding.
* @param {Uint8Array|string} serverSeed - 32-byte seed (hex/Base58 accepted).
* @returns {string} lowercase hex SHA-256 commitment.
*/
export function commitToSeed(serverSeed) {
const seed = asBytes(serverSeed, 'serverSeed');
if (seed.length !== SEED_BYTES) throw new Error('serverSeed must be 32 bytes');
return bytesToHex(sha256(concatBytes(TAG_SEED_COMMIT, seed)));
}
/**
* Fold serverSeed + clientSeed + requestNonce into the 32-byte master seed that
* drives candidate derivation. Order is fixed and domain-separated.
* @param {object} p
* @param {Uint8Array|string} p.serverSeed
* @param {Uint8Array|string} p.clientSeed
* @param {Uint8Array|string} p.requestNonce
* @returns {Uint8Array} 32-byte master seed.
*/
export function deriveMasterSeed({ serverSeed, clientSeed, requestNonce }) {
const ikm = concatBytes(
asBytes(serverSeed, 'serverSeed'),
asBytes(clientSeed, 'clientSeed'),
asBytes(requestNonce, 'requestNonce'),
);
return hkdf(sha256, ikm, TAG_MIX_SALT, TAG_MASTER_INFO, SEED_BYTES);
}
/**
* Deterministic Ed25519 secret seed for candidate `index` under a master seed.
* @param {Uint8Array} masterSeed - 32-byte output of deriveMasterSeed.
* @param {number} index - non-negative candidate counter.
* @returns {Uint8Array} 32-byte Ed25519 private seed.
*/
export function candidateSeed(masterSeed, index) {
return hmac(sha256, masterSeed, concatBytes(TAG_CANDIDATE, uint64be(index)));
}
/**
* Base58 Solana address for a candidate index — the public key of seed_index.
* @param {Uint8Array} masterSeed
* @param {number} index
* @returns {{ address: string, seed: Uint8Array, publicKey: Uint8Array }}
*/
export function candidateAddress(masterSeed, index) {
const seed = candidateSeed(masterSeed, index);
const publicKey = ed25519.getPublicKey(seed);
return { address: bs58.encode(publicKey), seed, publicKey };
}
/**
* Assemble a Solana 64-byte secret key (seed ‖ public key) from a 32-byte seed,
* matching `Keypair.fromSecretKey()` / Phantom import format.
* @param {Uint8Array} seed - 32-byte Ed25519 private seed.
* @returns {Uint8Array} 64-byte secret key.
*/
export function secretKeyFromSeed(seed) {
const pub = ed25519.getPublicKey(seed);
const sk = new Uint8Array(64);
sk.set(seed, 0);
sk.set(pub, 32);
return sk;
}
/**
* Does a Base58 address satisfy a prefix/suffix pattern?
* Mirrors the WASM grinder's matcher exactly so the difficulty model is honest.
* @param {string} address
* @param {object} p
* @param {string} [p.prefix]
* @param {string} [p.suffix]
* @param {boolean} [p.ignoreCase=false]
* @returns {boolean}
*/
export function addressMatchesPattern(address, { prefix = '', suffix = '', ignoreCase = false } = {}) {
let addr = address;
let pre = prefix || '';
let suf = suffix || '';
if (ignoreCase) {
addr = addr.toLowerCase();
pre = pre.toLowerCase();
suf = suf.toLowerCase();
}
if (pre && !addr.startsWith(pre)) return false;
if (suf && !addr.endsWith(suf)) return false;
return true;
}
/**
* Grind deterministically: walk candidate indices until the address matches.
* Bounded by attempt + time budgets. Returns the winning index + key material.
*
* @param {object} opts
* @param {Uint8Array} opts.masterSeed
* @param {string} [opts.prefix]
* @param {string} [opts.suffix]
* @param {boolean} [opts.ignoreCase=false]
* @param {number} [opts.maxAttempts=Infinity]
* @param {number} [opts.timeBudgetMs=Infinity]
* @param {number} [opts.startIndex=0]
* @returns {{ found:boolean, index:number, address:string, seed:Uint8Array,
* secretKey:Uint8Array, attempts:number, durationMs:number }}
*/
export function grindDeterministic({
masterSeed,
prefix = '',
suffix = '',
ignoreCase = false,
maxAttempts = Infinity,
timeBudgetMs = Infinity,
startIndex = 0,
}) {
const startedAt = performance.now();
const pattern = { prefix, suffix, ignoreCase };
let index = startIndex;
let attempts = 0;
for (; attempts < maxAttempts; index++, attempts++) {
if (attempts % 1024 === 0 && performance.now() - startedAt >= timeBudgetMs) break;
const { address, seed } = candidateAddress(masterSeed, index);
if (addressMatchesPattern(address, pattern)) {
return {
found: true,
index,
address,
seed,
secretKey: secretKeyFromSeed(seed),
attempts: attempts + 1,
durationMs: performance.now() - startedAt,
};
}
}
return {
found: false,
index: -1,
address: '',
seed: new Uint8Array(0),
secretKey: new Uint8Array(0),
attempts,
durationMs: performance.now() - startedAt,
};
}
// The EXACT set of fields covered by the service signature, in no particular
// order (canonicalization sorts them). The delivery payload (sealedSecret /
// secretKey / seed) and navigation hints (explorerUrl / verifyUrl) are NOT
// signed — they're derivable or recipient-specific — so the verifier projects a
// receipt down to exactly these keys before hashing. This makes the signature
// stable regardless of what extra fields a response or a UI round-trips.
export const SIGNED_FIELDS = Object.freeze([
'protocol',
'receiptType',
'address',
'pattern',
'commitment',
'serverSeed',
'clientSeed',
'requestNonce',
'winningIndex',
'attempts',
'durationMs',
'difficulty',
'sealed',
'sealedScheme',
'sealedRecipient',
'sealedEpk',
'network',
'ts',
]);
/** Project an object down to exactly the signed fields (present ones only). */
export function projectSignedCore(obj) {
const core = {};
for (const k of SIGNED_FIELDS) {
if (obj[k] !== undefined) core[k] = obj[k];
}
return core;
}
/**
* Canonical byte serialization of a receipt's signable core. Sorting keys and
* fixing the encoding make the signature reproducible on any platform — the
* verifier hashes the exact same bytes. The input is projected to SIGNED_FIELDS
* first, so extra response/UI fields never perturb the signature.
* @param {object} core
* @returns {Uint8Array}
*/
export function canonicalReceiptBytes(core) {
const stable = stableStringify(projectSignedCore(core));
return concatBytes(TAG_RECEIPT, enc.encode(stable));
}
// Deterministic JSON: object keys sorted recursively, no whitespace. Numbers and
// strings serialize as standard JSON. Used only for the signable core, whose
// values are all primitives/strings.
function stableStringify(value) {
if (value === null || typeof value !== 'object') return JSON.stringify(value);
if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
const keys = Object.keys(value).sort();
return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
}
/**
* Build + sign a receipt. The signing key is the service's long-lived Ed25519
* identity secret (32-byte seed). Returns the full receipt object the buyer keeps.
*
* @param {object} p
* @param {object} p.core - signable fields (commitment, clientSeed, requestNonce,
* pattern, address, difficulty, attempts, winningIndex, durationMs,
* sealedRecipient, sealedEpk, serverSeed, ts, …).
* @param {Uint8Array|string} p.signingSeed - 32-byte service Ed25519 secret seed.
* @returns {object} receipt with `signature` (hex) + `servicePublicKey` (Base58).
*/
export function signReceipt({ core, signingSeed }) {
const seed = asBytes(signingSeed, 'signingSeed');
if (seed.length !== SEED_BYTES) throw new Error('signingSeed must be 32 bytes');
const msg = canonicalReceiptBytes(core);
const signature = ed25519.sign(msg, seed);
const publicKey = ed25519.getPublicKey(seed);
return {
...core,
signature: bytesToHex(signature),
servicePublicKey: bs58.encode(publicKey),
signatureScheme: SIGNATURE_SCHEME,
};
}
/**
* Verify a receipt's service signature against a pinned/known public key.
* @param {object} receipt
* @param {Uint8Array|string} servicePublicKey - 32-byte Ed25519 public key.
* @returns {boolean}
*/
export function verifyReceiptSignature(receipt, servicePublicKey) {
if (!receipt?.signature) return false;
const { signature, servicePublicKey: _spk, signatureScheme: _ss, ...core } = receipt;
let sig;
let pub;
try {
sig = hexToBytes(signature);
pub = asBytes(servicePublicKey, 'servicePublicKey');
} catch {
return false;
}
try {
return ed25519.verify(sig, canonicalReceiptBytes(core), pub);
} catch {
return false;
}
}
/**
* @typedef {object} VerifyCheck
* @property {string} id
* @property {string} label
* @property {boolean} pass
* @property {string} detail
*/
/**
* Independently verify a vanity receipt. Runs every protocol check and returns a
* per-check audit so a UI/CLI can render exactly what passed and what failed.
* Trusts nothing in the receipt — it recomputes each claim from first principles.
*
* @param {object} receipt - the signed receipt.
* @param {object} [opts]
* @param {Uint8Array|string} [opts.servicePublicKey] - pinned service key. When
* omitted, the signature is checked against the receipt's own
* `servicePublicKey` and a separate `serviceKeyPinned` check reports that no
* pin was supplied (so an attacker self-signing is caught when a pin IS given).
* @param {Uint8Array} [opts.openedSecretSeed] - the 32-byte Ed25519 seed the
* buyer recovered from the sealed envelope. When present, we confirm it equals
* the seed the protocol re-derives — i.e. the key you hold is THE ground key.
* @returns {{ valid:boolean, checks:VerifyCheck[], address:string }}
*/
export function verifyVanityReceipt(receipt, opts = {}) {
const checks = [];
const add = (id, label, pass, detail) => checks.push({ id, label, pass, detail });
if (!receipt || typeof receipt !== 'object') {
add('shape', 'Receipt is well-formed', false, 'receipt is missing or not an object');
return { valid: false, checks, address: '' };
}
if (receipt.protocol !== PROTOCOL_VERSION) {
add(
'protocol',
'Protocol version is supported',
false,
`receipt protocol "${receipt.protocol}" ≠ "${PROTOCOL_VERSION}"`,
);
return { valid: false, checks, address: receipt.address || '' };
}
add('protocol', 'Protocol version is supported', true, PROTOCOL_VERSION);
// 1. Commitment opens to the revealed serverSeed.
let serverSeed;
let computedCommitment = '';
try {
serverSeed = asBytes(receipt.serverSeed, 'serverSeed');
computedCommitment = commitToSeed(serverSeed);
} catch (e) {
add('commitment', 'serverSeed opens the commitment', false, e.message);
}
if (computedCommitment) {
const ok = timingSafeEqualHex(computedCommitment, String(receipt.commitment || ''));
add(
'commitment',
'serverSeed opens the commitment',
ok,
ok
? 'SHA-256(serverSeed) matches the committed value — the server could not have swapped seeds after seeing the result'
: `SHA-256(serverSeed) = ${computedCommitment} ≠ committed ${receipt.commitment}`,
);
}
// 2. Re-derive the master seed + winning candidate and bind it to the address.
let derivedAddress = '';
let derivedSeed = null;
try {
const masterSeed = deriveMasterSeed({
serverSeed: receipt.serverSeed,
clientSeed: receipt.clientSeed,
requestNonce: receipt.requestNonce,
});
const cand = candidateAddress(masterSeed, receipt.winningIndex);
derivedAddress = cand.address;
derivedSeed = cand.seed;
const ok = derivedAddress === receipt.address;
add(
'derivation',
'Address derives from the mixed seed at the claimed index',
ok,
ok
? `candidate #${receipt.winningIndex} re-derives to ${derivedAddress}`
: `candidate #${receipt.winningIndex} re-derives to ${derivedAddress}, not the claimed ${receipt.address}`,
);
} catch (e) {
add('derivation', 'Address derives from the mixed seed at the claimed index', false, e.message);
}
// 3. The address satisfies the requested pattern.
{
const pat = receipt.pattern || {};
const ok = addressMatchesPattern(receipt.address || '', pat);
const want = [pat.prefix && `prefix "${pat.prefix}"`, pat.suffix && `suffix "${pat.suffix}"`]
.filter(Boolean)
.join(' + ') || '(no pattern)';
add(
'pattern',
'Address satisfies the requested pattern',
ok,
ok ? `${receipt.address} matches ${want}` : `${receipt.address} does NOT match ${want}`,
);
}
// 4. Difficulty claim is the honest probability model, the one the receipt
// was ISSUED under, named in its own signed `difficulty.model`. Receipts
// predating the Base58 leading-character correction declare v1 and must
// keep verifying; an absent field means v1.
{
const pat = receipt.pattern || {};
const model = receipt.difficulty?.model || DIFFICULTY_MODEL_V1;
const expected = Math.round(difficultyModel(model)(pat.prefix || '', pat.suffix || '', !!pat.ignoreCase));
const ok = Number(receipt.difficulty?.expectedAttempts) === expected;
add(
'difficulty',
'Difficulty matches the honest model',
ok,
ok
? `expectedAttempts = ${expected} under ${model}`
: `receipt claims ${receipt.difficulty?.expectedAttempts}, ${model} model = ${expected}`,
);
}
// 5. Service signature.
{
const pin = opts.servicePublicKey;
const keyToCheck = pin ?? receipt.servicePublicKey;
const sigOk = verifyReceiptSignature(receipt, keyToCheck);
add(
'signature',
'Service Ed25519 signature is valid',
sigOk,
sigOk
? `signed by ${receipt.servicePublicKey}`
: 'signature does not verify against the service key',
);
const pinned = pin
? sameKey(pin, receipt.servicePublicKey)
: false;
add(
'serviceKeyPinned',
'Signed by the pinned three.ws service key',
pin ? pinned : false,
pin
? pinned
? `receipt key ${receipt.servicePublicKey} matches the pinned key`
: `receipt key ${receipt.servicePublicKey} ≠ pinned key — possible impostor`
: 'no pinned key supplied — fetch /.well-known/three-vanity.json to pin and prove the signer is three.ws',
);
}
// 6. (Optional) the opened secret is THE ground key.
if (opts.openedSecretSeed) {
let opened;
try {
opened = asBytes(opts.openedSecretSeed, 'openedSecretSeed');
if (opened.length === 64) opened = opened.slice(0, 32);
} catch (e) {
opened = null;
add('custody', 'Your recovered key is the ground key', false, e.message);
}
if (opened) {
const ok =
derivedSeed != null &&
opened.length === 32 &&
constantTimeBytesEqual(opened, derivedSeed);
const pubOk = ok && bs58.encode(ed25519.getPublicKey(opened)) === receipt.address;
add(
'custody',
'Your recovered key is the ground key',
ok && pubOk,
ok && pubOk
? 'the secret you opened re-derives to the receipt address — you hold the one and only key'
: 'the opened secret does NOT match the protocol-derived key for this receipt',
);
}
}
const required = checks.filter((c) => c.id !== 'serviceKeyPinned' || opts.servicePublicKey);
const valid = required.every((c) => c.pass);
return { valid, checks, address: receipt.address || '' };
}
function sameKey(a, b) {
try {
return constantTimeBytesEqual(asBytes(a, 'a'), asBytes(b, 'b'));
} catch {
return false;
}
}
function constantTimeBytesEqual(a, b) {
if (a.length !== b.length) return false;
let diff = 0;
for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
return diff === 0;
}
function timingSafeEqualHex(a, b) {
if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) return false;
let diff = 0;
for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
return diff === 0;
}
export { BASE58_ALPHABET, validatePattern };