Skip to content

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.

37.2 KB
Raw Blame
// GET /api/x402/vanity?prefix=<base58>&suffix=<base58>&ignoreCase=<0|1>
//
// Paid endpoint cataloged by the CDP x402 Bazaar (agentic.market) and the
// pay-skills registry. The server grinds a brand-new Solana Ed25519 keypair
// whose Base58 address starts with `prefix` and/or ends with `suffix`, then
// returns the address plus its secret key (Base58 and 64-byte array forms).
// Buyers pay programmatically with @x402/fetch — no API keys, no accounts.
//
// Pricing is difficulty-tiered: a 1-char pattern is $0.01, 2 chars $0.05,
// 3 chars $0.25 — reflecting the ~58× jump in expected work per character.
// The 402 challenge quotes the price for the exact pattern requested. The
// combined pattern is capped at 3 characters server-side; the grind runs
// single-threaded in a Rust/WASM ed25519 engine (~25k keypairs/sec) under a
// 45-second budget. Longer patterns belong in the browser grinder at /vanity.
//
// The keypair is generated fresh per request and never persisted — the secret
// key exists only in the response body, served once over TLS. Settlement runs
// only after a successful grind, so an exhausted budget (rare, <1% at 3 chars)
// costs the buyer nothing and can be retried.
//
// Networks: Base mainnet (EIP-3009 + Permit2 sibling) and Solana mainnet
// (USDC). verifyPayment / settlePayment in x402-spec.js route per network. The
// Solana entry is omitted when X402_PAY_TO_SOLANA is unset so the 402 stays valid.

import { wrap, cors, error, rateLimited } from '../_lib/http.js';
import {
	send402,
	verifyPayment,
	settlePayment,
	encodePaymentResponseHeader,
	buildExactRequirements,
	resolveResourceUrl,
	buildBazaarSchema,
} from '../_lib/x402-spec.js';
import { env } from '../_lib/env.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import {
	PAYMENT_IDENTIFIER,
	checkCache,
	claimSlotOrRespond,
	extractIdFromHeader,
	hashPaymentProof,
	hashRequestPayload,
	paymentIdentifierExtension,
	releaseSlot,
	storeResponse,
	writeCachedResponse,
	writeConflict,
} from '../_lib/x402/payment-identifier-server.js';
import { installAccessControl } from '../_lib/x402/access-control.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import {
	grindVanityNode,
	validatePattern,
	expectedAttemptsFor,
	MAX_SERVER_PATTERN_LENGTH,
} from '../../src/solana/vanity/grinder-node.js';
import {
	grindVanityMnemonic,
	expectedMnemonicAttempts,
	MAX_MNEMONIC_PATTERN_LENGTH,
} from '../../src/solana/vanity/mnemonic-grinder.js';
import { STRENGTH_WORD_COUNTS, DEFAULT_STRENGTH } from '../../src/solana/vanity/mnemonic.js';
import {
	sealToRecipient,
	parseX25519Key,
	SEALED_ENVELOPE_SCHEME,
} from '../../src/solana/vanity/sealed-envelope.js';
import { buildCertificateCore, signCertificate } from '../../src/solana/vanity/proof-of-grind.js';
import { getServiceIdentity } from '../_lib/vanity-service-key.js';
import { registerCert } from '../_lib/vanity-cert-store.js';
import {
	claimMatchingPattern,
	hasAvailableMatch,
	peekReservedSecret,
	reserveAndReveal,
	releaseReservation,
	isDbUnavailableError,
} from '../_lib/vanity-inventory-store.js';
import { openSecret } from '../_lib/vanity-vault.js';
import { priceFor } from '../_lib/x402-prices.js';
import bs58 from 'bs58';

const ROUTE = '/api/x402/vanity';
const REQUIRED_SCOPE = 'x402:bypass';
const accessControl = installAccessControl({ requiredScope: REQUIRED_SCOPE });
const routeConfig = { path: ROUTE, method: 'GET', requiredScope: REQUIRED_SCOPE };

// Wall-clock budget for the grind. Kept under the route's 60s maxDuration with
// headroom for facilitator verify + settle round-trips.
const GRIND_TIME_BUDGET_MS = 45_000;

// Output formats. `keypair` (default) returns a raw Ed25519 secret key ground in
// the WASM engine. `mnemonic` returns a BIP-39 seed phrase whose derived key
// (m/44'/501'/0'/0', Phantom's default) lands on the vanity address — importable
// as a recovery phrase into any wallet.
const FORMAT_KEYPAIR = 'keypair';
const FORMAT_MNEMONIC = 'mnemonic';
const FORMATS = new Set([FORMAT_KEYPAIR, FORMAT_MNEMONIC]);

// Difficulty-tiered price in USDC atomic units (6 decimals). Indexed by the
// combined prefix+suffix length. Each character multiplies expected work by 58,
// so the price climbs to track compute cost. Length 0 (discovery probe with no
// pattern) quotes the 1-char base price.
const PRICE_BY_LENGTH = {
	0: 10_000, //  $0.01 — base / probe
	1: 10_000, //  $0.01
	2: 50_000, //  $0.05
	3: 250_000, // $0.25
};

// Mnemonic mode grinds ~100× slower (PBKDF2-HMAC-SHA512 per attempt) and ships a
// full importable seed phrase, so it is priced as a premium tier and capped at
// 2 characters server-side.
const PRICE_BY_LENGTH_MNEMONIC = {
	0: 50_000, //  $0.05 — base / probe
	1: 50_000, //  $0.05
	2: 500_000, // $0.50
};

// 4–5 Base58 chars is past what a single 45s server grind can reach (58^4 ≈
// 11.3M attempts ≈ 7.5 min at the WASM engine's ~25k/s; 58^5 ≈ 656M ≈ 7+
// hours) — those lengths are ONLY ever fulfilled from the pre-ground premium
// inventory (workers/vanity-grinder, api/x402/vanity-premium.js), never
// ground live. Priced well above the flat per-length grind tiers to reflect
// the batch-CPU cost of stocking them ahead of time; env-overridable per
// api/_lib/x402-prices.js so ops can retune without a redeploy. `format=
// mnemonic` is NOT extended here — the batch grinder only stocks raw
// keypairs (mnemonic grinding is itself ~100× slower to produce ahead of
// time), so mnemonic stays capped at MAX_MNEMONIC_PATTERN_LENGTH.
const PREMIUM_PRICE_BY_LENGTH = {
	4: () => Number(priceFor('vanity-4', '2500000')), // $2.50 default
	5: () => Number(priceFor('vanity-5', '10000000')), // $10 default
};

// Keypair patterns up to this length are OFFERED (priced + quoted), but only
// ever served from inventory (see hasAvailableMatch gate below) — never
// ground live. Patterns longer than MAX_SERVER_PATTERN_LENGTH and up to this
// ceiling are the "premium" band.
export const INVENTORY_MAX_PATTERN_LENGTH = 5;

export function priceAtomicsFor(format, combinedLength) {
	if (format === FORMAT_MNEMONIC) {
		return PRICE_BY_LENGTH_MNEMONIC[combinedLength] ?? PRICE_BY_LENGTH_MNEMONIC[MAX_MNEMONIC_PATTERN_LENGTH];
	}
	if (combinedLength > MAX_SERVER_PATTERN_LENGTH) {
		const premium = PREMIUM_PRICE_BY_LENGTH[Math.min(combinedLength, INVENTORY_MAX_PATTERN_LENGTH)];
		if (premium) return premium();
	}
	return PRICE_BY_LENGTH[combinedLength] ?? PRICE_BY_LENGTH[MAX_SERVER_PATTERN_LENGTH];
}

const ROUTE_DESCRIPTION =
	'three.ws Solana Vanity Grinder — put your brand on-chain: get a Solana address ' +
	'that starts with your ticker/prefix and/or ends with a chosen suffix. Use it as a ' +
	'branded token MINT address, a recognizable agent or treasury wallet, or any wallet ' +
	'you want identifiable at a glance. The server grinds a brand-new keypair to match — ' +
	'no wallet, account, or SOL required. Two output formats: format=keypair (default) ' +
	'returns the public address and its secret key (Base58 + 64-byte array), ground in a ' +
	'Rust/WASM ed25519 engine — live-ground up to 3 Base58 chars, priced $0.01 (1 char) / ' +
	'$0.05 (2) / $0.25 (3). Longer 4–5 char patterns are offered too, priced $2.50 (4) / ' +
	'$10 (5), but ONLY ever served from the pre-ground premium inventory (never ground ' +
	'live) — a pattern with no inventory match 404s as not_in_stock instead of quoting a ' +
	'price you could never redeem; browse stock at GET /api/x402/vanity-premium. ' +
	'format=mnemonic returns a BIP-39 seed phrase (12 or 24 words) whose ' +
	"derived key at m/44'/501'/0'/0' lands on the vanity address, importable as a recovery " +
	'phrase into Phantom / Solflare / the Solana CLI — capped at 2 chars (~100× slower to ' +
	'grind), priced $0.05 (1 char) / $0.50 (2). Security model: nothing is ever stored — ' +
	'the secret exists only in the response, served once over TLS, and is stripped from the ' +
	'replay/idempotency cache. Optional sealTo=<X25519 public key> seals the secret to you ' +
	'(ECIES; x25519-hkdf-sha256-aes256gcm) so the plaintext never appears in the response ' +
	'or any log — open it client-side with the matching private key. Keyless and ' +
	'account-free: pay-per-call in USDC on Base or Solana mainnet — no API keys, no signup. ' +
	'A matching pre-ground address in the premium inventory is delivered instantly instead ' +
	"of grinding one — response.source is 'inventory' (pre-generated server-side, never " +
	"re-served — same one-time delivery guarantee as vanity-premium) or 'ground' (freshly " +
	'mined this request), and pricing is identical either way.';

// Base58 excludes 0/O/I/l. Note also that an address is 32 random bytes
// Base58-encoded, so its LEADING characters are not uniformly distributed —
// a given prefix can be markedly harder than the naive 58^n estimate, while
// suffix characters are uniform. The example uses a reliable 2-char prefix.
const DISCOVERY_INPUT_EXAMPLE = { prefix: 'So', suffix: '', ignoreCase: '0' };

const DISCOVERY_INPUT_SCHEMA = {
	$schema: 'https://json-schema.org/draft/2020-12/schema',
	type: 'object',
	properties: {
		prefix: {
			type: 'string',
			description:
				'Base58 characters the address must start with. Base58 excludes 0, O, I, l. ' +
				'Combined with suffix, max 3 characters.',
		},
		suffix: {
			type: 'string',
			description:
				'Base58 characters the address must end with. Combined with prefix, max 3 characters.',
		},
		ignoreCase: {
			type: 'string',
			enum: ['0', '1', 'true', 'false'],
			description:
				'When 1/true, match the pattern case-insensitively (faster, less specific).',
		},
		format: {
			type: 'string',
			enum: ['keypair', 'mnemonic'],
			description:
				'keypair (default): return a raw 64-byte Ed25519 secret key, up to 3 chars. ' +
				'mnemonic: return a BIP-39 seed phrase importable into any wallet, up to 2 chars.',
		},
		strength: {
			type: 'string',
			enum: ['128', '256'],
			description:
				'Mnemonic mode only. 128 → 12 words (default), 256 → 24 words. Ignored for keypair format.',
		},
		sealTo: {
			type: 'string',
			description:
				'Optional. Your 32-byte X25519 public key (Base58, Base64url, or hex). When set, ' +
				'the secret is sealed to it (x25519-hkdf-sha256-aes256gcm) and the plaintext secret ' +
				'is omitted from the response — open it client-side with the matching private key.',
		},
	},
};

// SECURITY: this is a discovery-schema EXAMPLE only — it documents the response
// shape, it is NOT a real key. The secretKey/secretKeyBase58 below are synthetic
// placeholders (all-zero bytes), never a funded keypair. The live endpoint grinds
// and returns a fresh keypair per request; never paste a real secret key here.
const DISCOVERY_OUTPUT_EXAMPLE = {
	address: 'SoEXAMPLEdoNotUse1111111111111111111111111111',
	prefix: 'So',
	suffix: null,
	ignoreCase: false,
	format: 'keypair',
	secretKeyBase58: '<example-only — the live endpoint returns the ground secret key here>',
	secretKey: [
		0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
		0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
		0, 0,
	],
	mnemonic: null,
	wordCount: null,
	derivationPath: null,
	attempts: 160000,
	durationMs: 6030,
	expectedAttempts: 57960,
	network: 'solana',
	explorerUrl: 'https://solscan.io/account/SoEXAMPLEdoNotUse1111111111111111111111111111',
	source: 'ground',
};

const DISCOVERY_OUTPUT_SCHEMA = {
	$schema: 'https://json-schema.org/draft/2020-12/schema',
	type: 'object',
	required: ['address', 'secretKeyBase58', 'secretKey', 'attempts'],
	properties: {
		address: { type: 'string', description: 'Base58 Solana public key.' },
		prefix: { type: ['string', 'null'] },
		suffix: { type: ['string', 'null'] },
		ignoreCase: { type: 'boolean' },
		format: { type: 'string', enum: ['keypair', 'mnemonic'] },
		secretKeyBase58: {
			type: 'string',
			description:
				'Base58-encoded 64-byte Ed25519 secret key (import into Phantom/Solflare). ' +
				'Present in both formats — in mnemonic mode it is the key derived from the phrase.',
		},
		secretKey: {
			type: 'array',
			items: { type: 'integer', minimum: 0, maximum: 255 },
			minItems: 64,
			maxItems: 64,
			description: '64-byte secret key as an int array — save as a Solana CLI keypair JSON.',
		},
		mnemonic: {
			type: ['string', 'null'],
			description:
				'mnemonic format only: BIP-39 seed phrase (12/24 words). Type it into any wallet ' +
				'to recover this address. null in keypair format.',
		},
		wordCount: { type: ['integer', 'null'], description: 'mnemonic format only: 12 or 24.' },
		derivationPath: {
			type: ['string', 'null'],
			description: "mnemonic format only: BIP-44 path, e.g. m/44'/501'/0'/0'.",
		},
		sealed: {
			type: 'boolean',
			description:
				'Present and true only when sealTo was supplied. The plaintext secret fields ' +
				'(secretKeyBase58/secretKey/mnemonic) are then omitted in favor of sealedSecret.',
		},
		sealedSecret: {
			type: 'object',
			description:
				'sealTo only: ECIES envelope { scheme, epk, nonce, ciphertext, recipient }. Open it ' +
				'with the X25519 private key matching sealTo to recover a JSON bundle of the secret.',
		},
		sealedFields: {
			type: 'array',
			items: { type: 'string' },
			description: 'sealTo only: the field names contained in the decrypted JSON bundle.',
		},
		attempts: { type: 'integer', description: 'Keypairs tried before the match.' },
		durationMs: { type: 'number' },
		expectedAttempts: {
			type: 'integer',
			description: 'Naive 58^n expectation (prefix bias can make the real figure higher).',
		},
		network: { type: 'string' },
		explorerUrl: { type: 'string', format: 'uri' },
		source: {
			type: 'string',
			enum: ['inventory', 'ground'],
			description:
				"'inventory': served instantly from a pre-ground address in the premium inventory " +
				"(delivered once, then destroyed server-side — never re-served). 'ground': mined " +
				'fresh for this request. Price is the same either way.',
		},
		certificate: {
			type: 'object',
			description:
				'Proof-of-grind certificate (three-pog/v1): a public, signed attestation of the ' +
				'pattern, address, difficulty, rarity, and a freshness nonce — verifiable offline ' +
				'with verifyProofOfGrind() or at /vanity/verify. Contains no secret. The attestation ' +
				'public key is published at /.well-known/three-vanity.json.',
		},
		verifyUrl: { type: 'string', format: 'uri', description: 'Public verifier page for the certificate.' },
		serviceKeyUrl: { type: 'string', format: 'uri', description: 'Published attestation key (.well-known).' },
	},
};

const ROUTE_BAZAAR = {
	discoverable: true,
	info: {
		input: { type: 'http', method: 'GET', queryParams: DISCOVERY_INPUT_EXAMPLE },
		output: { type: 'json', example: DISCOVERY_OUTPUT_EXAMPLE },
	},
	schema: buildBazaarSchema({
		method: 'GET',
		queryParamsSchema: DISCOVERY_INPUT_SCHEMA,
		outputSchema: DISCOVERY_OUTPUT_SCHEMA,
	}),
};

function buildRequirements(resourceUrl, priceAtomics) {
	// Solana-first accepts, Base gated on baseSettleable() (CDP or opt-in) plus its
	// gasless Permit2 sibling under CDP — see buildExactRequirements.
	return buildExactRequirements(resourceUrl, priceAtomics);
}

// Parse + validate the requested pattern. Returns { prefix, suffix, ignoreCase,
// combinedLength } or throws an Error with .status/.code for a clean 4xx. A
// request with NO pattern (the Bazaar discovery probe) is allowed through with
// combinedLength 0 so the 402 challenge can still be emitted for indexing.
function parsePattern(req) {
	const q = req.query || {};
	const prefix = typeof q.prefix === 'string' ? q.prefix.trim() : '';
	const suffix = typeof q.suffix === 'string' ? q.suffix.trim() : '';
	const ignoreCase = q.ignoreCase === '1' || q.ignoreCase === 'true';

	const format = typeof q.format === 'string' ? q.format.trim().toLowerCase() : FORMAT_KEYPAIR;
	if (!FORMATS.has(format)) {
		throw Object.assign(new Error(`invalid format '${format}' — use keypair or mnemonic`), {
			status: 400,
			code: 'validation_error',
		});
	}

	let strength = DEFAULT_STRENGTH;
	if (q.strength != null && q.strength !== '') {
		strength = Number(q.strength);
		if (!STRENGTH_WORD_COUNTS[strength]) {
			throw Object.assign(
				new Error(`invalid strength '${q.strength}' — use 128 (12 words) or 256 (24 words)`),
				{ status: 400, code: 'validation_error' },
			);
		}
	}

	for (const [label, pattern] of [
		['prefix', prefix],
		['suffix', suffix],
	]) {
		if (!pattern) continue;
		const v = validatePattern(pattern);
		if (!v.valid) {
			throw Object.assign(new Error(`invalid ${label}: ${v.errors.join('; ')}`), {
				status: 400,
				code: 'validation_error',
			});
		}
	}

	// Keypair patterns get a second, wider ceiling: MAX_SERVER_PATTERN_LENGTH is
	// what the live WASM grinder can reach in the 45s budget; anything up to
	// INVENTORY_MAX_PATTERN_LENGTH is OFFERED but only ever fulfilled from the
	// premium inventory (checked below, before any 402 is quoted — see
	// hasAvailableMatch in the handler). Mnemonic format has no inventory
	// backing, so its ceiling stays the live-grind cap.
	const maxLength =
		format === FORMAT_MNEMONIC ? MAX_MNEMONIC_PATTERN_LENGTH : INVENTORY_MAX_PATTERN_LENGTH;
	const combinedLength = prefix.length + suffix.length;
	if (combinedLength > maxLength) {
		const reason =
			format === FORMAT_MNEMONIC
				? `seed-phrase grinding is ~100× slower; drop format=mnemonic for up to ${MAX_SERVER_PATTERN_LENGTH} chars, ` +
					`or grind longer mnemonic patterns on your own machine`
				: 'grind longer patterns in the browser at /vanity, or check /api/x402/vanity-premium for pre-ground stock';
		throw Object.assign(
			new Error(
				`combined pattern length ${combinedLength} exceeds the ${format} server limit of ` +
					`${maxLength} characters — ${reason}`,
			),
			{ status: 400, code: 'pattern_too_long' },
		);
	}
	// 4–5 chars (keypair only) is the premium, inventory-only band — never
	// ground live. See hasAvailableMatch gate in the handler and the "not in
	// stock" 404 it returns for a pattern inventory doesn't hold.
	const premiumOnly = format !== FORMAT_MNEMONIC && combinedLength > MAX_SERVER_PATTERN_LENGTH;

	// Optional confidential delivery: an X25519 public key the secret is sealed
	// to. Validate the key shape up front so a malformed key is a clean 400
	// before the buyer ever pays. parseX25519Key throws status/code on bad input.
	let sealTo = null;
	if (typeof q.sealTo === 'string' && q.sealTo.trim()) {
		sealTo = q.sealTo.trim();
		parseX25519Key(sealTo, 'sealTo');
	}

	return { prefix, suffix, ignoreCase, combinedLength, format, strength, sealTo, premiumOnly };
}

// Confidential delivery: when the caller supplies an X25519 public key, encrypt
// the secret material to it (ECIES sealed envelope) so the plaintext secret
// never appears in the response body, a proxy log, or the idempotency cache.
// The address + grind metadata stay in the clear; only the secret is sealed.
async function sealSecret(result, sealTo) {
	const bundle =
		result.format === FORMAT_MNEMONIC
			? {
					format: FORMAT_MNEMONIC,
					mnemonic: result.mnemonic,
					wordCount: result.wordCount,
					derivationPath: result.derivationPath,
					secretKeyBase58: result.secretKeyBase58,
					secretKey: result.secretKey,
				}
			: {
					format: FORMAT_KEYPAIR,
					secretKeyBase58: result.secretKeyBase58,
					secretKey: result.secretKey,
				};
	const sealedSecret = await sealToRecipient(JSON.stringify(bundle), sealTo);
	// Strip every plaintext secret field; keep public metadata.
	const { secretKeyBase58, secretKey, mnemonic, ...clear } = result;
	return {
		...clear,
		sealed: true,
		sealedScheme: SEALED_ENVELOPE_SCHEME,
		sealedContentType: 'application/json',
		sealedFields: Object.keys(bundle),
		sealedSecret,
	};
}

const PUBLIC_ORIGIN = env.APP_ORIGIN || 'https://three.ws';

// Attach a public, offline-verifiable proof-of-grind certificate to a grind
// result. The certificate attests the pattern, address, difficulty, rarity,
// freshness nonce, and (when sealed) the delivery envelope — signed by the
// long-lived three.ws attestation key. It contains NO secret, so it is safe in
// the response, the idempotency cache, and at rest. The certificate is also
// registered (first-write-wins) so a buyer/marketplace can later confirm this is
// the single canonical "freshly ground" proof for the address. Registry/signing
// failures must never break delivery — the buyer paid for a key, and the
// certificate is additive — so issuance degrades gracefully on error.
async function attachCertificate(result, pattern) {
	let identity;
	try {
		identity = await getServiceIdentity();
	} catch (err) {
		console.error('[vanity/cert] attestation key unavailable; delivering without certificate', err?.message || err);
		return result;
	}
	const delivery = result.sealed
		? { sealed: true, sealedScheme: result.sealedScheme || SEALED_ENVELOPE_SCHEME, sealedRecipient: result.sealedSecret?.recipient || null }
		: { sealed: false };
	let certificate;
	try {
		const core = buildCertificateCore({
			address: result.address,
			pattern: { prefix: pattern.prefix || null, suffix: pattern.suffix || null, ignoreCase: !!pattern.ignoreCase },
			format: result.format,
			attempts: result.attempts,
			delivery,
			network: 'solana',
			keyId: identity.keyId,
		});
		certificate = signCertificate({ core, signingSeed: identity.seed, keyId: identity.keyId });
	} catch (err) {
		console.error('[vanity/cert] failed to sign certificate; delivering without it', err?.message || err);
		return result;
	}
	try {
		await registerCert(certificate);
	} catch (err) {
		// A registry outage degrades to "offline-verifiable only" — the certificate
		// still verifies cryptographically; only the single-issuance check is skipped.
		console.warn('[vanity/cert] registry unavailable; certificate is offline-verifiable only', err?.message || err);
	}
	return {
		...result,
		certificate,
		verifyUrl: `${PUBLIC_ORIGIN}/vanity/verify`,
		certVerifyUrl: `${PUBLIC_ORIGIN}/vanity/verify?cert=${encodeURIComponent(certificate.certId)}`,
		serviceKeyUrl: `${PUBLIC_ORIGIN}/.well-known/three-vanity.json`,
	};
}

async function grindAndShape({ prefix, suffix, ignoreCase, format, strength, sealTo }) {
	let shaped;
	if (format === FORMAT_MNEMONIC) {
		const result = grindVanityMnemonic({
			prefix,
			suffix,
			ignoreCase,
			strength,
			timeBudgetMs: GRIND_TIME_BUDGET_MS,
		});
		shaped = {
			address: result.publicKey,
			prefix: prefix || null,
			suffix: suffix || null,
			ignoreCase,
			format: FORMAT_MNEMONIC,
			secretKeyBase58: bs58.encode(result.secretKey),
			secretKey: Array.from(result.secretKey),
			mnemonic: result.mnemonic,
			wordCount: result.wordCount,
			derivationPath: result.derivationPath,
			attempts: result.attempts,
			durationMs: Math.round(result.durationMs),
			expectedAttempts: Math.round(expectedMnemonicAttempts(prefix, suffix, ignoreCase)),
			network: 'solana',
			explorerUrl: `https://solscan.io/account/${result.publicKey}`,
			source: 'ground',
		};
	} else {
		const result = grindVanityNode({
			prefix,
			suffix,
			ignoreCase,
			timeBudgetMs: GRIND_TIME_BUDGET_MS,
		});
		shaped = {
			address: result.publicKey,
			prefix: prefix || null,
			suffix: suffix || null,
			ignoreCase,
			format: FORMAT_KEYPAIR,
			secretKeyBase58: bs58.encode(result.secretKey),
			secretKey: Array.from(result.secretKey),
			mnemonic: null,
			wordCount: null,
			derivationPath: null,
			attempts: result.attempts,
			durationMs: Math.round(result.durationMs),
			expectedAttempts: expectedAttemptsFor(prefix, suffix, ignoreCase),
			network: 'solana',
			explorerUrl: `https://solscan.io/account/${result.publicKey}`,
			source: 'ground',
		};
	}

	const delivered = sealTo ? await sealSecret(shaped, sealTo) : shaped;
	return attachCertificate(delivered, { prefix, suffix, ignoreCase });
}

// ── Instant inventory fast path ──────────────────────────────────────────────
// Before grinding, check whether a pre-ground address from
// api/_lib/vanity-inventory-store.js already satisfies the requested
// prefix/suffix pattern. A hit is claimed atomically (reserve → decrypt →,
// after settle, reveal-and-destroy) and delivered exactly once — the same
// sealing/certificate pipeline as a fresh grind, just without the CPU cost or
// the wait. A miss (no match, or ANY failure along the way — DB down,
// decrypt error) returns null and the caller falls straight through to
// grindAndShape() unchanged. Never throws: an inventory outage must degrade
// to "grind as normal", not break the endpoint.
export async function tryInstantFromInventory(pattern, { paymentId, purchaser }) {
	const { prefix, suffix, ignoreCase, format, combinedLength, sealTo } = pattern;
	if (!paymentId || (!prefix && !suffix) || combinedLength === 0) return null;

	// Guardrail: never hand out an inventory item worth more than the flat
	// price this pattern length already charges — see claimMatchingPattern's
	// maxPriceUsd doc for why. Anything pricier stays reserved for the priced
	// premium tier (/api/x402/vanity-premium).
	const maxPriceUsd = priceAtomicsFor(format, combinedLength) / 1_000_000;

	let claim;
	try {
		claim = await claimMatchingPattern({ prefix, suffix, ignoreCase, format, maxPriceUsd, paymentId, purchaser });
	} catch (err) {
		if (!isDbUnavailableError(err)) {
			console.error('[vanity] inventory claim lookup failed; falling back to grind', err?.message || err);
		}
		return null;
	}
	if (!claim.ok) return null;

	const item = claim.item;
	const startedAt = Date.now();
	let bundle;
	try {
		const peek = await peekReservedSecret(item.address, { paymentId });
		if (!peek.ok) throw new Error(peek.reason);
		bundle = JSON.parse(await openSecret(peek.ciphertext, peek.scheme));
	} catch (err) {
		console.error('[vanity] inventory decrypt failed; releasing + falling back to grind', err?.message || err);
		await releaseReservation(item.address, { paymentId }).catch(() => {});
		return null;
	}

	const shaped = {
		address: item.address,
		prefix: prefix || null,
		suffix: suffix || null,
		ignoreCase,
		format: bundle.format || item.format || FORMAT_KEYPAIR,
		secretKeyBase58: bundle.secretKeyBase58,
		secretKey: bundle.secretKey,
		mnemonic: bundle.mnemonic || null,
		wordCount: bundle.wordCount || null,
		derivationPath: bundle.derivationPath || null,
		attempts: item.difficultyAttempts,
		durationMs: Date.now() - startedAt,
		expectedAttempts: item.difficultyAttempts,
		network: 'solana',
		explorerUrl: `https://solscan.io/account/${item.address}`,
		source: 'inventory',
	};

	const delivered = sealTo ? await sealSecret(shaped, sealTo) : shaped;
	const withCert = await attachCertificate(delivered, { prefix, suffix, ignoreCase });
	return { result: withCert, item };
}

// Cache-safe copy of a delivered result. Never persist spendable key material at
// rest: the live response delivers the ground secret once over TLS (this
// endpoint's stated contract), and the x402 replay/idempotency cache must NOT
// hold it, or a cache read or compromise would recover spendable keys for the
// cache TTL. The plaintext secret fields are stripped from the STORED copy, so a
// replayed payment receives the public metadata plus an explicit marker rather
// than the key. A sealed response carries only ciphertext (sealedSecret), which
// is safe at rest, so it is cached unchanged.
export function cacheSafeBody(result) {
	if (result?.sealed) return JSON.stringify(result);
	const { secretKeyBase58, secretKey, mnemonic, ...publicMeta } = result;
	void secretKeyBase58; void secretKey; void mnemonic;
	return JSON.stringify({
		...publicMeta,
		secret_omitted_from_cache: true,
		note: 'The ground secret is returned only once in the original response and is never stored. If you did not capture it, grind again.',
	});
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (req.method !== 'GET') {
		res.setHeader('allow', 'GET');
		return error(res, 405, 'method_not_allowed', 'use GET');
	}

	// Light rate limit on the public (pre-payment) path so the 402 challenge
	// and parameter validation can't be hammered. The grind itself is paywalled.
	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	// Validate the pattern up front so a malformed request is rejected before we
	// ever quote a price. A pattern-free probe is allowed (combinedLength 0).
	let pattern;
	try {
		pattern = parsePattern(req);
	} catch (err) {
		return error(res, err.status || 400, err.code || 'validation_error', err.message);
	}

	// Premium 4–5 char band: only ever fulfilled from inventory, so check stock
	// BEFORE quoting a price — a buyer must never be asked to pay for a pattern
	// that isn't sitting in the warehouse. A DB outage here degrades to "not in
	// stock" (honest, refundable-nothing failure) rather than a false quote.
	if (pattern.premiumOnly) {
		let inStock = false;
		try {
			inStock = await hasAvailableMatch({
				prefix: pattern.prefix,
				suffix: pattern.suffix,
				ignoreCase: pattern.ignoreCase,
				format: pattern.format,
			});
		} catch (err) {
			if (!isDbUnavailableError(err)) console.error('[vanity] premium stock check failed', err?.message || err);
		}
		if (!inStock) {
			return error(
				res,
				404,
				'not_in_stock',
				`pattern not in stock — the live grinder's grindable range is 1–${MAX_SERVER_PATTERN_LENGTH} ` +
					`Base58 chars; ${pattern.combinedLength}-char patterns are served only from the premium ` +
					`inventory when a match exists. Browse current stock at GET /api/x402/vanity-premium` +
					`?prefix=${encodeURIComponent(pattern.prefix || '')}.`,
			);
		}
	}

	const resourceUrl = resolveResourceUrl(req, ROUTE);
	const priceAtomics = priceAtomicsFor(pattern.format, pattern.combinedLength);
	const requirements = buildRequirements(resourceUrl, priceAtomics);
	const service = withService({
		serviceName: 'three.ws Solana Vanity Grinder',
		tags: ['solana', 'vanity', 'keypair', 'wallet', 'address', 'mnemonic', 'seed-phrase', 'bip39'],
	});
	const challenge = {
		resourceUrl,
		accepts: requirements,
		description: ROUTE_DESCRIPTION,
		bazaar: ROUTE_BAZAAR,
		extensions: { [PAYMENT_IDENTIFIER]: paymentIdentifierExtension(false) },
		serviceName: service.serviceName,
		tags: service.tags,
		iconUrl: service.iconUrl,
	};

	// USE-23: access-control hook short-circuits payment for internal /
	// subscription / OAuth callers before we read the X-PAYMENT header.
	const acResult = await accessControl(req, routeConfig);
	if (acResult?.abort) {
		if (acResult.headers) {
			for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
		}
		return error(
			res,
			acResult.status || 403,
			acResult.code || 'access_denied',
			acResult.reason || 'access denied',
		);
	}
	if (acResult?.grantAccess) {
		// The premium 4-5 char band is inventory-only. grindAndShape would reject
		// it as pattern_too_long (the live grinder tops out at
		// MAX_SERVER_PATTERN_LENGTH), and an access grant is not a purchase, so it
		// cannot claim stock either. Say that plainly rather than surfacing a
		// length error for a pattern we just confirmed IS in stock.
		if (pattern.premiumOnly) {
			return error(
				res,
				409,
				'purchase_required',
				`${pattern.combinedLength}-char patterns come only from the premium inventory, which is sold per item. ` +
					`An access grant covers the live grind (1-${MAX_SERVER_PATTERN_LENGTH} chars); buy this pattern at ` +
					`GET /api/x402/vanity-premium?prefix=${encodeURIComponent(pattern.prefix || '')}.`,
			);
		}
		let result;
		try {
			result = await grindAndShape(pattern);
		} catch (err) {
			return error(res, err.status || 500, err.code || 'internal_error', err.message);
		}
		if (acResult.headers) {
			for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
		}
		res.setHeader('x-payment-bypass', acResult.reason || 'granted');
		res.setHeader('cache-control', 'no-store');
		res.setHeader('content-type', 'application/json; charset=utf-8');
		res.end(JSON.stringify(result));
		return;
	}

	const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];
	if (!paymentHeader) return send402(res, challenge);

	// USE-15: idempotency cache lookup before paying for /verify. A retried
	// payment (same payment-id, same query) returns the SAME ground keypair
	// instead of grinding a fresh one and double-charging.
	const clientPaymentId = extractIdFromHeader(paymentHeader);
	const payloadHash = hashRequestPayload({ method: req.method, url: req.url, body: null });
	const paymentHash = hashPaymentProof(paymentHeader);
	// Always-on replay guard: the payment-identifier extension is client-opt-in,
	// so when the client omits it we fall back to the proof hash itself as the
	// dedup key (reproducible only by the original payer), making replay
	// protection unconditional. Same idiom as api/_lib/x402-paid-endpoint.js.
	const paymentId = clientPaymentId || (paymentHash ? `proof:${paymentHash}` : null);
	// Close the check-then-act window: N concurrent requests carrying the same
	// payment could all miss the cache, all run the paid work, and all settle
	// before the first response was stored. The NX claim admits exactly one;
	// the rest are answered inside claimSlotOrRespond (replay/conflict/in-flight).
	let ownsReservation = false;
	if (paymentId) {
		const lookup = await checkCache({ route: ROUTE, paymentId, payloadHash, paymentHash });
		if (lookup.kind === 'hit') return writeCachedResponse(res, lookup.entry);
		if (lookup.kind === 'conflict') {
			return writeConflict(res, {
				route: ROUTE,
				attemptedHash: lookup.attemptedHash,
				existingHash: lookup.existingHash,
				reason: lookup.reason,
			});
		}
		ownsReservation = await claimSlotOrRespond({ res, route: ROUTE, paymentId, payloadHash, paymentHash });
		if (!ownsReservation) return;
	}

	let verified;
	try {
		verified = await verifyPayment({ paymentHeader, requirements });
	} catch (err) {
		if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
		if (err.status === 402) return send402(res, { ...challenge, error: err.message });
		return error(res, err.status || 502, err.code || 'verify_failed', err.message);
	}

	// Instant path FIRST: a matching pre-ground address in inventory is
	// claimed and decrypted here (still before settle, so a claim/decrypt
	// failure costs the buyer nothing — see tryInstantFromInventory). No
	// match (or any failure) returns null and falls straight through to the
	// live grind, unchanged from before this endpoint knew inventory existed.
	const purchaser = verified?.payer || verified?.from || clientPaymentId || 'x402';
	let result;
	let inventoryClaim = null;
	try {
		const instant = paymentId ? await tryInstantFromInventory(pattern, { paymentId, purchaser }) : null;
		if (instant) {
			result = instant.result;
			inventoryClaim = instant.item;
		} else if (pattern.premiumOnly) {
			// The pre-payment hasAvailableMatch check above found stock, but
			// between the 402 quote and this settle another buyer won the race for
			// the (possibly only) matching item. This band is NEVER ground live
			// (58^4-58^5 attempts is hours, far past the 45s budget) — fail clean
			// instead of falling through to an infeasible grind. Settlement has not
			// run, so the buyer is charged nothing and can retry.
			throw Object.assign(
				new Error('the matching inventory item was claimed by another buyer between quote and payment — retry'),
				{ status: 409, code: 'sold_out' },
			);
		} else {
			// Grind AFTER verify but BEFORE settle: an invalid pattern or exhausted
			// budget throws here, and settlement never runs, so the buyer isn't
			// charged. grindAndShape is async (it may seal the secret to the
			// buyer's key), so it must be awaited — otherwise the body serializes
			// an unresolved Promise.
			result = await grindAndShape(pattern);
		}
	} catch (err) {
		if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
		return error(res, err.status || 500, err.code || 'grind_failed', err.message);
	}

	let settled;
	try {
		settled = await settlePayment({ verified });
	} catch (err) {
		if (inventoryClaim) {
			// Settlement failed after we reserved (but did not yet reveal/destroy)
			// the inventory item — release it back to available so a transient
			// payment failure never strands sellable stock.
			await releaseReservation(inventoryClaim.address, { paymentId }).catch(() => {});
		}
		if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
		return error(res, err.status || 502, err.code || 'settle_failed', err.message);
	}

	if (inventoryClaim) {
		// One-shot reveal AFTER settle: flips reserved→destroyed and nulls the
		// stored ciphertext atomically, so this address can never be served
		// again. We already hold the plaintext (delivered above), so a hiccup
		// here is logged, not fatal to delivery.
		try {
			await reserveAndReveal(inventoryClaim.address, { paymentId });
		} catch (err) {
			console.error('[vanity] inventory reveal/destroy after settle failed', err?.message || err);
		}
	}

	const paymentResponseHeader = encodePaymentResponseHeader(settled);
	const contentType = 'application/json; charset=utf-8';
	const body = JSON.stringify(result);

	res.setHeader('x-payment-response', paymentResponseHeader);
	res.setHeader('cache-control', 'no-store');
	res.setHeader('content-type', contentType);
	res.end(body);

	if (paymentId) {
		await storeResponse({
			route: ROUTE,
			paymentId,
			payloadHash,
			paymentHash,
			status: 200,
			body: cacheSafeBody(result),
			contentType,
			paymentResponseHeader,
		});
	}
});