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
/**
* One-call provably-fair vanity client: request → open the seal → verify.
*
* `grindVerifiedVanity` drives the full trustless flow against three.ws's
* `/api/x402/vanity-verifiable` endpoint:
* 1. generate a fresh X25519 recipient keypair (so the secret is ECIES-sealed
* and never travels in plaintext) and a fresh clientSeed (your entropy in
* the mix);
* 2. pay-per-call with your x402-capable fetch and pull back the signed receipt;
* 3. open the sealed envelope locally with the X25519 secret;
* 4. independently verify every protocol claim — including that the key you
* just opened IS the ground key — before handing you the secret.
*
* If verification fails, it THROWS rather than return an unverified key: the
* whole point is that you never accept a key you couldn't prove was honest.
*
* Bring your own x402 fetch (e.g. `wrapFetchWithPayment` from @x402/fetch, or
* the SDK's payExact-driven fetch). This module stays payment-rail-agnostic.
*/
import bs58 from "bs58";
import {
verifyVanityReceipt,
fetchServiceKey,
THREE_VANITY_ENDPOINT,
THREE_VANITY_WELL_KNOWN,
type VanityReceipt,
type VerifyResult,
} from "./verify.js";
import { openSealedJson, generateRecipientKeypair, type SealedEnvelope } from "./sealed.js";
export interface SealedBundle {
format: string;
secretKeyBase58: string;
secretKey: number[];
seed: string;
}
export interface GrindVerifiedResult {
/** Base58 Solana address. */
address: string;
/** 64-byte secret key (Solana / Phantom import format). */
secretKey: Uint8Array;
/** Base58 secret key. */
secretKeyBase58: string;
/** The full signed receipt — keep it; anyone can re-verify it later. */
receipt: VanityReceipt;
/** The per-check verification audit (all passed, or this would have thrown). */
verification: VerifyResult;
}
export interface GrindVerifiedOptions {
prefix?: string;
suffix?: string;
ignoreCase?: boolean;
/** Your own entropy (hex/Base58). A fresh random one is used when omitted. */
clientSeed?: string;
/** x402-capable fetch (paywall-aware). Defaults to global fetch. */
fetchImpl?: typeof fetch;
/** Override the endpoint (e.g. devnet/staging). */
endpoint?: string;
/** Override the pinned service key. By default the live key is fetched from
* the well-known document and pinned, so verification never depends on a
* possibly-stale SDK constant. Pass `false` to skip the fetch and use the
* built-in pin, or a string to pin an explicit key. */
servicePublicKey?: string | false;
/** Well-known URL to resolve the live service key from (default three.ws). */
wellKnownUrl?: string;
}
function randomClientSeedHex(): string {
const b = new Uint8Array(32);
(globalThis.crypto as Crypto).getRandomValues(b);
return bs58.encode(b); // Base58 — the endpoint accepts hex or Base58.
}
/**
* Request a provably-fair vanity wallet, open the seal locally, and verify it.
* Throws if the receipt does not verify against the pinned service key.
*/
export async function grindVerifiedVanity(
opts: GrindVerifiedOptions = {},
): Promise<GrindVerifiedResult> {
const doFetch = opts.fetchImpl ?? fetch;
const endpoint = opts.endpoint ?? THREE_VANITY_ENDPOINT;
// 1. Fresh X25519 recipient + clientSeed — the buyer contributes entropy and
// the secret is sealed to a key only the buyer holds.
const recipient = generateRecipientKeypair();
const clientSeed = opts.clientSeed ?? randomClientSeedHex();
const url = new URL(endpoint);
if (opts.prefix) url.searchParams.set("prefix", opts.prefix);
if (opts.suffix) url.searchParams.set("suffix", opts.suffix);
if (opts.ignoreCase) url.searchParams.set("ignoreCase", "1");
url.searchParams.set("clientSeed", clientSeed);
url.searchParams.set("sealTo", recipient.publicKey);
// 2. Pay + fetch the signed receipt.
const res = await doFetch(url.toString(), { headers: { accept: "application/json" } });
if (!res.ok) {
const text = await res.text().catch(() => "");
throw new Error(`vanity-verifiable request failed: ${res.status} ${text.slice(0, 300)}`);
}
const receipt = (await res.json()) as VanityReceipt & {
sealedSecret?: SealedEnvelope;
secretKeyBase58?: string;
secretKey?: number[];
seed?: string;
};
// 3. Open the sealed envelope locally (or read the plaintext if unsealed).
let secretKeyBase58: string;
let secretKey: Uint8Array;
let openedSeed: Uint8Array | undefined;
if (receipt.sealed && receipt.sealedSecret) {
const bundle = openSealedJson<SealedBundle>(receipt.sealedSecret, recipient.secretKey);
secretKeyBase58 = bundle.secretKeyBase58;
secretKey = Uint8Array.from(bundle.secretKey);
openedSeed = secretKey.slice(0, 32);
} else if (receipt.secretKeyBase58) {
secretKeyBase58 = receipt.secretKeyBase58;
secretKey = Uint8Array.from(receipt.secretKey ?? bs58.decode(receipt.secretKeyBase58));
openedSeed = secretKey.slice(0, 32);
} else {
throw new Error("receipt carried neither a sealed envelope nor a plaintext secret");
}
// 4. Independently verify EVERY claim — including custody of THIS key.
// Pin against the LIVE well-known key by default (so a stale SDK constant
// never causes a false negative or a false positive); callers can override
// with an explicit key or `false` to use the built-in pin.
let servicePublicKey: string | undefined;
if (opts.servicePublicKey === false) {
servicePublicKey = undefined; // fall back to the SDK's built-in pin
} else if (typeof opts.servicePublicKey === "string") {
servicePublicKey = opts.servicePublicKey;
} else {
servicePublicKey = await fetchServiceKey(opts.wellKnownUrl ?? THREE_VANITY_WELL_KNOWN);
}
const verification = verifyVanityReceipt(receipt, {
servicePublicKey,
openedSecretSeed: openedSeed,
});
if (!verification.valid) {
const failed = verification.checks.filter((c) => !c.pass).map((c) => `${c.id}: ${c.detail}`);
throw new Error(`receipt failed verification — ${failed.join("; ")}`);
}
return {
address: receipt.address,
secretKey,
secretKeyBase58,
receipt,
verification,
};
}