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
// Premium vanity inventory — the Postgres store.
//
// The security-critical surface. Everything that reads or mutates the
// `vanity_inventory` table lives here so the single-use delivery contract is
// enforced in ONE place, as atomic status-guarded UPDATEs the database
// serializes — never as read-then-write logic a race could double-spend.
//
// State machine (see the migration for the CHECK):
// available ──reserve──▶ reserved ──reveal──▶ revealed ──destroy──▶ destroyed
// A reveal is a single atomic UPDATE that flips reserved→revealed and RETURNS the
// ciphertext in the same statement. A second reveal matches zero rows (status is
// no longer 'reserved'/'sold'), so the secret is delivered exactly once. Delete-
// after-reveal (retention_days = 0, the default) nulls the ciphertext in that
// same reveal, so it is gone the instant it is served.
//
// PUBLIC vs SECRET: every public read (listing, item detail) selects an explicit
// column list that OMITS secret_ciphertext. Only reserveAndReveal() ever touches
// the ciphertext, and it returns it to the caller (the delivery endpoint) exactly
// once, then this module never surfaces it again.
import { sql, isDbUnavailableError } from './db.js';
// Columns that are safe to expose publicly (never includes secret_ciphertext).
const PUBLIC_COLS = sql`
id, address, prefix, suffix, ignore_case, pattern_label, format,
difficulty_attempts, rarity_bits, rarity_tier, rarity_score,
status, price_usd, created_at
`;
function shapePublic(row) {
if (!row) return null;
return {
id: row.id,
address: row.address,
prefix: row.prefix,
suffix: row.suffix,
ignoreCase: row.ignore_case,
patternLabel: row.pattern_label,
format: row.format,
difficultyAttempts: Number(row.difficulty_attempts),
rarityBits: Number(row.rarity_bits),
rarityTier: row.rarity_tier,
rarityScore: Number(row.rarity_score),
status: row.status,
priceUsd: Number(row.price_usd),
createdAt: row.created_at,
};
}
/**
* Upsert a freshly-ground inventory item. Idempotent on `address` — a re-run of a
* batch that re-finds an address is a safe no-op (never overwrites a sold row or
* re-exposes a destroyed one). The caller (workers/vanity-grinder) has ALREADY
* sealed the secret via api/_lib/vanity-vault.js; this function only ever sees
* ciphertext.
*
* @param {object} item
* @returns {Promise<{ inserted:boolean, address:string }>}
*/
export async function upsertInventoryItem(item) {
const {
address,
prefix = null,
suffix = null,
ignoreCase = false,
patternLabel,
format = 'keypair',
difficultyAttempts = 0,
rarityBits = 0,
rarityTier = 'common',
rarityScore = 0,
secretCiphertext,
secretScheme = 'aes-256-gcm',
priceUsd = 1,
retentionDays = 0,
batchId = null,
} = item;
if (!address) throw new Error('upsertInventoryItem: address required');
if (!secretCiphertext) throw new Error('upsertInventoryItem: sealed secret required');
if (secretCiphertext.includes('"secretKey"') || /^\[?\s*\d+\s*,\s*\d+/.test(secretCiphertext)) {
// Guard against a caller accidentally passing a plaintext key. The vault
// ciphertext is always a scheme-prefixed opaque blob, never raw JSON/array.
throw new Error('upsertInventoryItem: refusing to store what looks like a plaintext secret');
}
const [row] = await sql`
INSERT INTO vanity_inventory
(address, prefix, suffix, ignore_case, pattern_label, format,
difficulty_attempts, rarity_bits, rarity_tier, rarity_score,
secret_ciphertext, secret_scheme, price_usd, retention_days, batch_id)
VALUES
(${address}, ${prefix}, ${suffix}, ${ignoreCase}, ${patternLabel}, ${format},
${String(difficultyAttempts)}, ${rarityBits}, ${rarityTier}, ${rarityScore},
${secretCiphertext}, ${secretScheme}, ${priceUsd}, ${retentionDays}, ${batchId})
ON CONFLICT (address) DO NOTHING
RETURNING id
`;
return { inserted: Boolean(row), address };
}
/**
* Browse available inventory (public metadata only). Optional pattern filter and
* ordering. Never returns ciphertext.
*
* @param {object} [opts]
* @param {string} [opts.prefix] case-insensitive prefix filter
* @param {string} [opts.tier] rarity tier filter
* @param {'rarity'|'price'|'new'} [opts.sort]
* @param {number} [opts.limit]
* @param {number} [opts.offset]
* @returns {Promise<object[]>}
*/
function availableWhere({ prefix, tier } = {}) {
let where = sql`status = 'available'`;
if (prefix) where = sql`${where} AND lower(prefix) LIKE ${String(prefix).toLowerCase() + '%'}`;
if (tier) where = sql`${where} AND rarity_tier = ${String(tier)}`;
return where;
}
export async function listAvailable(opts = {}) {
const { prefix, tier, sort = 'rarity', limit = 60, offset = 0 } = opts;
const lim = Math.min(Math.max(1, Number(limit) || 60), 200);
const off = Math.max(0, Number(offset) || 0);
const where = availableWhere({ prefix, tier });
let order;
if (sort === 'price') order = sql`price_usd ASC, rarity_score DESC`;
else if (sort === 'new') order = sql`created_at DESC`;
else order = sql`rarity_score DESC, price_usd DESC`;
const rows = await sql`
SELECT ${PUBLIC_COLS} FROM vanity_inventory
WHERE ${where}
ORDER BY ${order}
LIMIT ${lim} OFFSET ${off}
`;
return rows.map(shapePublic);
}
/**
* How many available rows match the same filter listAvailable() would page over.
* The listing needs this to tell a browser "showing 100 of 385" and to know when
* a "load more" page exists, instead of silently capping the shelf at one page.
*
* @param {object} [opts]
* @param {string} [opts.prefix]
* @param {string} [opts.tier]
* @returns {Promise<number>}
*/
export async function countAvailable(opts = {}) {
const where = availableWhere(opts);
const [row] = await sql`SELECT count(*) AS n FROM vanity_inventory WHERE ${where}`;
return Number(row?.n || 0);
}
/** Public detail for one address (metadata only, any status). */
export async function getPublicItem(address) {
const [row] = await sql`
SELECT ${PUBLIC_COLS} FROM vanity_inventory WHERE address = ${address} LIMIT 1
`;
return shapePublic(row);
}
/** Aggregate counts + price range for the listing header / stats strip. */
export async function inventoryStats() {
const [row] = await sql`
SELECT
count(*) FILTER (WHERE status = 'available') AS available,
count(*) FILTER (WHERE status IN ('revealed','sold','destroyed')) AS sold,
count(*) AS total,
coalesce(min(price_usd) FILTER (WHERE status = 'available'), 0) AS min_price,
coalesce(max(price_usd) FILTER (WHERE status = 'available'), 0) AS max_price,
count(DISTINCT rarity_tier) FILTER (WHERE status = 'available') AS tiers
FROM vanity_inventory
`;
return {
available: Number(row?.available || 0),
sold: Number(row?.sold || 0),
total: Number(row?.total || 0),
minPrice: Number(row?.min_price || 0),
maxPrice: Number(row?.max_price || 0),
tiers: Number(row?.tiers || 0),
};
}
/**
* Every distinct target pattern that still has stock ON THE SHELF.
*
* The batch grinder (workers/vanity-grinder) runs on ephemeral spot tasks whose
* local checkpoint file dies with the container, so a restart used to re-grind
* patterns that were already sitting in this table. This is the durable resume
* signal: the grinder seeds its completed-set from here and skips those targets.
*
* Deliberately filtered to `available` rather than "ever ground": a pattern that
* sold out is exactly what the replenish cron wants ground again.
*
* @returns {Promise<Array<{prefix:string|null, suffix:string|null, ignoreCase:boolean, count:number}>>}
*/
export async function availableTargetPatterns() {
const rows = await sql`
SELECT prefix, suffix, ignore_case, count(*) AS n
FROM vanity_inventory
WHERE status = 'available'
GROUP BY prefix, suffix, ignore_case
`;
return rows.map((row) => ({
prefix: row.prefix,
suffix: row.suffix,
ignoreCase: Boolean(row.ignore_case),
count: Number(row.n || 0),
}));
}
/**
* Atomically reserve an available item for a paying buyer. This is the FIRST half
* of purchase: it flips available→reserved only if the row is still available, so
* two concurrent buyers of the same address can never both win. Idempotent per
* payment_id: if the SAME payment already reserved this address, it re-selects
* that reservation instead of failing (a retried/settled payment is not a
* conflict).
*
* @returns {Promise<{ ok:true, item:object } | { ok:false, reason:string }>}
*/
export async function reserveForPurchase(address, { paymentId, purchaser }) {
if (!address) return { ok: false, reason: 'address required' };
const [row] = await sql`
UPDATE vanity_inventory
SET status = 'reserved',
payment_id = ${paymentId || null},
purchaser = ${purchaser || null},
reserved_at = now(),
updated_at = now()
WHERE address = ${address} AND status = 'available'
RETURNING ${PUBLIC_COLS}
`;
if (row) return { ok: true, item: shapePublic(row) };
// Not available — either already reserved by THIS payment (idempotent retry),
// already revealed/sold, or gone. Distinguish so the caller returns the right
// state instead of a blanket conflict.
const [existing] = await sql`
SELECT ${PUBLIC_COLS}, payment_id FROM vanity_inventory WHERE address = ${address} LIMIT 1
`;
if (!existing) return { ok: false, reason: 'not_found' };
if (paymentId && existing.payment_id === paymentId && ['reserved', 'sold'].includes(existing.status)) {
return { ok: true, item: shapePublic(existing) };
}
return { ok: false, reason: existing.status === 'available' ? 'race' : 'unavailable', status: existing.status };
}
/**
* The one-shot reveal — the function the delivery endpoint calls.
*
* Postgres cannot both null a column AND return its pre-null value in one plain
* UPDATE … RETURNING, so this is an atomic CTE: `moved` captures the row (FOR
* UPDATE), `revealed` flips its status and nulls the ciphertext per retention,
* and the final SELECT returns the ciphertext captured in `moved` BEFORE the
* null-out. The `secret_ciphertext IS NOT NULL` + status guard in `moved` makes
* the whole thing single-use: a second call captures zero rows and returns
* `already_revealed`. On retention_days = 0 (delete-after-reveal, the default)
* the ciphertext is destroyed in the same statement that serves it.
*
* Guarded by payment_id: only the payment that reserved the row can reveal it.
*
* @returns {Promise<{ ok:true, ciphertext:string, scheme:string, item:object, destroyed:boolean }
* | { ok:false, reason:string, status?:string }>}
*/
export async function reserveAndReveal(address, { paymentId }) {
if (!address) return { ok: false, reason: 'address required' };
if (!paymentId) return { ok: false, reason: 'payment_id required' };
const rows = await sql`
WITH moved AS (
SELECT id, secret_ciphertext, secret_scheme, retention_days
FROM vanity_inventory
WHERE address = ${address}
AND payment_id = ${paymentId}
AND status IN ('reserved', 'sold')
AND secret_ciphertext IS NOT NULL
FOR UPDATE
),
revealed AS (
UPDATE vanity_inventory v
SET status = CASE WHEN v.retention_days = 0 THEN 'destroyed' ELSE 'revealed' END,
revealed_at = now(),
sold_at = coalesce(v.sold_at, now()),
secret_ciphertext = CASE WHEN v.retention_days = 0 THEN NULL ELSE v.secret_ciphertext END,
destroyed_at = CASE WHEN v.retention_days = 0 THEN now() ELSE v.destroyed_at END,
updated_at = now()
FROM moved
WHERE v.id = moved.id
RETURNING v.address, v.prefix, v.suffix, v.ignore_case, v.pattern_label, v.format,
v.difficulty_attempts, v.rarity_bits, v.rarity_tier, v.rarity_score,
v.status, v.price_usd, v.created_at, v.id
)
SELECT
moved.secret_ciphertext AS ciphertext,
moved.secret_scheme AS scheme,
moved.retention_days AS retention_days,
revealed.*
FROM moved JOIN revealed ON revealed.id = moved.id
`;
const row = rows[0];
if (!row) {
const [cur] = await sql`SELECT status, payment_id FROM vanity_inventory WHERE address = ${address} LIMIT 1`;
if (!cur) return { ok: false, reason: 'not_found' };
if (['revealed', 'destroyed'].includes(cur.status)) return { ok: false, reason: 'already_revealed' };
if (paymentId && cur.payment_id && cur.payment_id !== paymentId) return { ok: false, reason: 'wrong_payment' };
return { ok: false, reason: 'not_reserved', status: cur.status };
}
return {
ok: true,
ciphertext: row.ciphertext,
scheme: row.scheme,
destroyed: Number(row.retention_days) === 0,
item: shapePublic(row),
};
}
/**
* Instant-inventory fast path: atomically find AND claim one available item
* whose actual `address` satisfies a requested prefix/suffix pattern, so the
* live-grind endpoints (api/x402/vanity.js, api/x402/pump-launch.js) can
* serve a pre-ground key instead of grinding one. Matching runs against the
* real address text (case-folded per `ignoreCase`), not the item's own
* stored prefix/suffix label — a longer pre-ground item ("Solana…") also
* satisfies a shorter request ("So"), which is the whole point of turning
* spare inventory into instant delivery for the cheap live-grind tier.
*
* `maxPriceUsd` is the economics guardrail: the live grinder charges a flat
* per-length fee (a few cents), while inventory items can be worth up to $50.
* Without this cap, a $0.05 request could accidentally match — and give
* away — a rare item that should only ever sell through the priced premium
* tier (api/x402/vanity-premium.js). Passing `maxPriceUsd` restricts the
* candidate set to items worth no more than what the buyer is already
* paying, so instant delivery is strictly a latency win, never a discount.
* Omit it (pump-launch's flat-fee upsell) to allow any matching item.
*
* `FOR UPDATE SKIP LOCKED` inside the id subquery is the same idiom used by
* claimRegenJobs() (api/_lib/x402/thumbnail-regen.js): it makes the claim
* safe under concurrent callers racing for the same last matching row — one
* wins the row, the other's subquery skips the locked row and (if no other
* candidate exists) claims nothing, so the same address is never reserved
* twice.
*
* @param {object} opts
* @param {string} [opts.prefix]
* @param {string} [opts.suffix]
* @param {boolean} [opts.ignoreCase]
* @param {string} [opts.format='keypair']
* @param {number} [opts.maxPriceUsd] optional price ceiling in USD
* @param {string} opts.paymentId
* @param {string} [opts.purchaser]
* @returns {Promise<{ ok:true, item:object } | { ok:false, reason:string }>}
*/
export async function claimMatchingPattern({
prefix = '',
suffix = '',
ignoreCase = false,
format = 'keypair',
maxPriceUsd,
paymentId,
purchaser,
}) {
if (!paymentId) return { ok: false, reason: 'payment_id_required' };
const pfx = String(prefix || '');
const sfx = String(suffix || '');
if (!pfx && !sfx) return { ok: false, reason: 'no_pattern' };
let where = sql`status = 'available' AND format = ${format}`;
if (pfx) {
where = ignoreCase
? sql`${where} AND lower(left(address, ${pfx.length})) = ${pfx.toLowerCase()}`
: sql`${where} AND left(address, ${pfx.length}) = ${pfx}`;
}
if (sfx) {
where = ignoreCase
? sql`${where} AND lower(right(address, ${sfx.length})) = ${sfx.toLowerCase()}`
: sql`${where} AND right(address, ${sfx.length}) = ${sfx}`;
}
if (maxPriceUsd != null) where = sql`${where} AND price_usd <= ${maxPriceUsd}`;
const rows = await sql`
UPDATE vanity_inventory
SET status = 'reserved', payment_id = ${paymentId}, purchaser = ${purchaser || null},
reserved_at = now(), updated_at = now()
WHERE id IN (
SELECT id FROM vanity_inventory
WHERE ${where}
ORDER BY created_at ASC
LIMIT 1
FOR UPDATE SKIP LOCKED
)
RETURNING ${PUBLIC_COLS}
`;
const row = rows[0];
if (!row) return { ok: false, reason: 'no_match' };
return { ok: true, item: shapePublic(row) };
}
/**
* Read-only stock check: does an AVAILABLE item exist whose real address
* satisfies this prefix/suffix pattern? Never reserves — used to quote the
* premium long-pattern tier in api/x402/vanity.js honestly BEFORE issuing a
* 402 (so a buyer is never asked to pay for a pattern that isn't in stock).
* The actual claim (with claimMatchingPattern's FOR UPDATE SKIP LOCKED race
* safety) only happens after payment verifies.
*
* @param {object} opts
* @param {string} [opts.prefix]
* @param {string} [opts.suffix]
* @param {boolean} [opts.ignoreCase]
* @param {string} [opts.format='keypair']
* @returns {Promise<boolean>}
*/
export async function hasAvailableMatch({ prefix = '', suffix = '', ignoreCase = false, format = 'keypair' }) {
const pfx = String(prefix || '');
const sfx = String(suffix || '');
if (!pfx && !sfx) return false;
let where = sql`status = 'available' AND format = ${format}`;
if (pfx) {
where = ignoreCase
? sql`${where} AND lower(left(address, ${pfx.length})) = ${pfx.toLowerCase()}`
: sql`${where} AND left(address, ${pfx.length}) = ${pfx}`;
}
if (sfx) {
where = ignoreCase
? sql`${where} AND lower(right(address, ${sfx.length})) = ${sfx.toLowerCase()}`
: sql`${where} AND right(address, ${sfx.length}) = ${sfx}`;
}
const [row] = await sql`SELECT 1 FROM vanity_inventory WHERE ${where} LIMIT 1`;
return Boolean(row);
}
/**
* Non-destructive read of the sealed ciphertext for a row reserved by THIS
* payment. The delivery endpoint calls this AFTER reserve but BEFORE settle to
* prove it can actually decrypt (e.g. KMS reachable) before charging the buyer —
* so a decrypt outage fails the purchase cleanly instead of settling and then
* being unable to deliver. Only ever returns ciphertext for a row this payment
* already reserved (so it's already unavailable to anyone else); does not change
* state, so single-use delivery is still enforced solely by reserveAndReveal().
*
* @returns {Promise<{ ok:true, ciphertext:string, scheme:string }
* | { ok:false, reason:string }>}
*/
export async function peekReservedSecret(address, { paymentId }) {
if (!address || !paymentId) return { ok: false, reason: 'address + payment_id required' };
const [row] = await sql`
SELECT secret_ciphertext, secret_scheme FROM vanity_inventory
WHERE address = ${address} AND payment_id = ${paymentId}
AND status IN ('reserved', 'sold') AND secret_ciphertext IS NOT NULL
LIMIT 1
`;
if (!row) return { ok: false, reason: 'not_reserved_or_gone' };
return { ok: true, ciphertext: row.secret_ciphertext, scheme: row.secret_scheme };
}
/**
* Sweep: destroy ciphertext for revealed items whose retention window has passed.
* Run from scripts/vanity-inventory-load.mjs --sweep (or a cron). Idempotent.
* @returns {Promise<{ destroyed:number }>}
*/
export async function sweepExpiredSecrets() {
const rows = await sql`
UPDATE vanity_inventory
SET secret_ciphertext = NULL,
status = 'destroyed',
destroyed_at = now(),
updated_at = now()
WHERE status = 'revealed'
AND retention_days > 0
AND secret_ciphertext IS NOT NULL
AND revealed_at < now() - (retention_days * interval '1 day')
RETURNING id
`;
return { destroyed: rows.length };
}
/**
* Release a reservation back to available. Called if payment settlement fails
* AFTER a reserve but BEFORE reveal, so a stuck reservation doesn't strand
* sellable stock. Guarded by payment_id so only the reserving payment can release.
*/
export async function releaseReservation(address, { paymentId }) {
const [row] = await sql`
UPDATE vanity_inventory
SET status = 'available', payment_id = NULL, purchaser = NULL,
reserved_at = NULL, updated_at = now()
WHERE address = ${address} AND status = 'reserved' AND payment_id = ${paymentId}
RETURNING id
`;
return { released: Boolean(row) };
}
export { isDbUnavailableError };