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
/**
* Persistence + atomic claim ledger for sealed wallet drops.
*
* A drop is a pre-funded Solana wallet sealed (ECIES) to a recipient and handed
* out by link / QR / 3D agent. This store holds the drop record and runs the
* single, atomic state machine that makes a drop claimable EXACTLY ONCE, by the
* holder of the claim secret, or reclaimable by the sender after expiry, never
* both. Mirrors vanity-bounty-store.js: Upstash Redis when configured, an
* in-process Map fallback otherwise (local/CI works; a Redis outage degrades).
*
* ── Operator-blind by construction ───────────────────────────────────────────
* A stored drop NEVER holds a plaintext private key or seed. It holds only:
* • the public funded `address`,
* • the SEALED envelope (opaque ECIES ciphertext addressed to the recipient),
* • the recipient's PUBLIC X25519 key (direct mode) or the claim PUBLIC key
* + the one-way `claimTokenHash` (claim-time mode).
* The operator therefore cannot open any wallet it stores or brokers. The public
* projection (`toPublicDrop`) additionally strips the sealed envelope so it is
* only ever released through the gated claim/reveal path.
*
* ── The create fee lands before the drop does ────────────────────────────────
* A drop is born `escrow_pending`: recorded, but in NO index, and refused by the
* claim, reveal and reclaim paths. Only `activateDrop` (called once the x402
* create fee has really settled) flips it to `funded` and indexes it. A fee that
* fails to settle voids the drop (`voidDrop`) after its on-chain funding is swept
* back, so nobody can walk away with a wallet the platform funded for free.
*
* ── Atomic single-claim state machine ────────────────────────────────────────
* escrow_pending ─fee settled─▶ funded (activateDrop; void otherwise)
* funded ──claim(token)──▶ claimed (compare-and-set, idempotent on token)
* └─expiry+reclaim─▶ reclaimed (compare-and-set, sender-only, mutex)
* A Lua compare-and-set flips status and records the claimer/reclaimer, and
* returns "won" ONLY to the first caller. A claimed drop can never be reclaimed
* and vice versa. Idempotency: re-presenting the SAME claim token after a claim
* returns "won" again (so a retried release isn't a re-race); reclaim after a
* reclaim returns "reclaimable" again.
*
* Layout (Redis):
* HASH vanity:drop:rec field=id → JSON(drop record)
* ZSET vanity:drop:by-recency member=id score=createdAt(ms)
* ZSET vanity:drop:funded member=id score=expiresAt(ms) (live, reclaim sweep)
* ZSET vanity:drop:by-sender member=id score=createdAt(ms) (sender index, per senderTag)
*/
import { getRedis } from './redis.js';
const NS = 'vanity:drop';
const K = {
rec: `${NS}:rec`,
byRecency: `${NS}:by-recency`,
funded: `${NS}:funded`,
sender: (tag) => `${NS}:by-sender:${tag}`,
};
const MAX_SCAN = 500;
// Statuses a drop holds before (or instead of) becoming a real, claimable gift.
const TRANSIENT_STATUSES = Object.freeze(['escrow_pending', 'void']);
/** True for a drop that has not (or will never) go live. */
export function isTransientDrop(rec) {
return !!rec && TRANSIENT_STATUSES.includes(rec.status);
}
// Public projection: the sealed envelope + claim-token hash + funding tx detail
// stay private. The privacy boundary: the envelope is released only by the gated
// claim/reveal path, never on a list or status read.
const PUBLIC_FIELDS = Object.freeze([
'id', 'protocol', 'address', 'asset', 'amount', 'amountAtomics', 'network',
'sealMode', 'status', 'message', 'theme', 'senderLabel', 'vanity',
'createdAt', 'expiresAt', 'claimedAt', 'reclaimedAt', 'fundingConfirmed',
'recipient', 'irlPinId', 'roomId',
]);
const mem = new Map(); // id → record (fallback store)
/** Project a record to its public shape (no sealed envelope, no token hash, no tx). */
export function toPublicDrop(rec) {
if (!rec || typeof rec !== 'object') return null;
const out = {};
for (const k of PUBLIC_FIELDS) if (rec[k] !== undefined) out[k] = rec[k];
if (!out.id) return null;
return out;
}
function parse(raw) {
if (!raw) return null;
if (typeof raw === 'object') return raw; // Upstash auto-deserializes JSON
try { return JSON.parse(raw); } catch { return null; }
}
/**
* Record a drop, claiming the id atomically (hsetnx) so a collision can't repoint
* the indexes at an existing record.
*
* Pass `status: 'escrow_pending'` (what api/vanity/drops.js does) to record it
* WITHOUT indexing: the drop is invisible to the sender list and the reclaim
* sweep, and the claim/reveal/reclaim paths refuse it, until `activateDrop`
* confirms the create fee settled. `funded` indexes immediately, which is only
* correct once the fee is collected.
*
* @param {object} rec - fully-formed drop record (see api/vanity/drops.js).
* @returns {Promise<object>} the stored record.
*/
export async function createDrop(rec) {
const record = { ...rec, status: rec.status || 'funded' };
const redis = getRedis();
if (redis) {
const created = await redis.hsetnx(K.rec, record.id, JSON.stringify(record));
if (created === 0 || created === false) {
throw Object.assign(new Error('drop id collision'), { status: 409, code: 'duplicate_drop' });
}
if (record.status === 'funded') await indexDrop(redis, record);
} else {
if (mem.has(record.id)) {
throw Object.assign(new Error('drop id collision'), { status: 409, code: 'duplicate_drop' });
}
mem.set(record.id, record);
}
return record;
}
/** Add a live drop to the recency / reclaim-sweep / sender indexes. */
async function indexDrop(redis, record) {
const pipe = redis.multi();
pipe.zadd(K.byRecency, { score: record.createdAt, member: record.id });
pipe.zadd(K.funded, { score: record.expiresAt, member: record.id });
if (record.senderTag) pipe.zadd(K.sender(record.senderTag), { score: record.createdAt, member: record.id });
await pipe.exec();
}
/**
* Flip a pending drop live now that its x402 create fee settled, recording the
* settlement tx as the audit trail and indexing it in the same step. Idempotent:
* re-activating an already-funded drop is a no-op that still reports 'live'.
*
* Read-modify-write is safe here (no compare-and-set Lua needed): a pending drop's
* id exists only inside the one create request that minted it, so this transition
* has exactly one writer. Every LATER transition (claim, reclaim) is contended and
* does use an atomic compare-and-set.
*
* @param {object} p
* @param {string} p.id
* @param {string} [p.escrowTx] - the x402 settlement transaction.
* @returns {Promise<'live'|'ineligible'|'missing'>}
*/
export async function activateDrop({ id, escrowTx }) {
const rec = await getDropRecord(id);
if (!rec) return 'missing';
if (rec.status === 'funded') return 'live';
if (rec.status !== 'escrow_pending') return 'ineligible';
const next = { ...rec, status: 'funded', escrowTx: escrowTx || '', escrowSettledAt: Date.now() };
const redis = getRedis();
if (redis) {
// Status first, then the indexes: a reader that races us either misses the
// drop entirely or finds one already marked funded, never a pending record
// sitting in the claim/sweep indexes.
await redis.hset(K.rec, { [next.id]: JSON.stringify(next) });
await indexDrop(redis, next);
} else {
mem.set(String(id), next);
}
return 'live';
}
/**
* Void a pending drop whose create fee never settled, so it can never be claimed,
* revealed, or swept as a live drop. Idempotent.
*
* @param {object} p
* @param {string} p.id
* @param {string} [p.reason] - why the fee never landed (audit trail).
* @returns {Promise<'void'|'ineligible'|'missing'>}
*/
export async function voidDrop({ id, reason }) {
const rec = await getDropRecord(id);
if (!rec) return 'missing';
if (rec.status === 'void') return 'void';
if (rec.status !== 'escrow_pending') return 'ineligible';
const next = { ...rec, status: 'void', voidedAt: Date.now(), voidReason: reason || '' };
const redis = getRedis();
if (redis) await redis.hset(K.rec, { [next.id]: JSON.stringify(next) });
else mem.set(String(id), next);
return 'void';
}
/** Full internal record by id (includes sealed envelope + token hash). */
export async function getDropRecord(id) {
const key = String(id || '');
if (!key) return null;
const redis = getRedis();
if (redis) return parse(await redis.hget(K.rec, key));
return mem.get(key) || null;
}
/** Public view by id. */
export async function getDrop(id) {
return toPublicDrop(await getDropRecord(id));
}
// Atomic funded→claimed compare-and-set. Idempotent on claimerTag (the digest of
// the presented claim token): re-presenting the SAME token after a claim returns
// 1 again (so a retried envelope release doesn't re-race). A claim on an already-
// reclaimed/expired drop returns -1. Returns 1=won, 0=lost(claimed by other),
// -1=not-claimable(reclaimed/expired), -2=missing.
const CLAIM_LUA = `
local raw = redis.call('HGET', KEYS[1], ARGV[1])
if not raw then return -2 end
local rec = cjson.decode(raw)
if rec.status == 'claimed' then
if rec.claimerTag == ARGV[2] then return 1 else return 0 end
end
if rec.status ~= 'funded' then return -1 end
local now = tonumber(ARGV[4])
if rec.expiresAt and now > tonumber(rec.expiresAt) then return -1 end
rec.status = 'claimed'
rec.claimerTag = ARGV[2]
rec.claimedAt = now
rec.claimRecipient = ARGV[3]
redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(rec))
redis.call('ZREM', KEYS[2], ARGV[1])
return 1
`;
/**
* Atomically claim a drop. The FIRST valid claim (proven possession of the claim
* token) wins; later ones lose. Idempotent on claimerTag. Does NOT release the
* envelope itself: the caller reads the record after a `won` and returns the
* sealed envelope, so a release error can be retried without re-racing.
*
* @param {object} p
* @param {string} p.id
* @param {string} p.claimerTag - one-way digest tying this claim to its token.
* @param {string} [p.claimRecipient] - optional recipient pubkey the holder re-sealed to (audit).
* @returns {Promise<'won'|'lost'|'closed'|'missing'>}
*/
export async function claimDrop({ id, claimerTag, claimRecipient }) {
const now = Date.now();
const redis = getRedis();
if (redis) {
const r = await redis.eval(
CLAIM_LUA,
[K.rec, K.funded],
[String(id), String(claimerTag), String(claimRecipient || ''), String(now)],
);
return claimCode(Number(r));
}
const rec = mem.get(String(id));
if (!rec) return 'missing';
if (rec.status === 'claimed') return rec.claimerTag === claimerTag ? 'won' : 'lost';
if (rec.status !== 'funded') return 'closed';
if (rec.expiresAt && now > rec.expiresAt) return 'closed';
rec.status = 'claimed';
rec.claimerTag = claimerTag;
rec.claimedAt = now;
rec.claimRecipient = claimRecipient || '';
mem.set(String(id), rec);
return 'won';
}
function claimCode(n) {
if (n === 1) return 'won';
if (n === 0) return 'lost';
if (n === -2) return 'missing';
return 'closed';
}
// Atomic funded→reclaimed compare-and-set, only for EXPIRED drops. Mutually
// exclusive with claim: a claimed drop can never be reclaimed and vice versa.
// Idempotent: re-running on an already-reclaimed drop returns 1. Returns
// 1=reclaimable(now reclaimed), 0=not-eligible, -2=missing.
const RECLAIM_LUA = `
local raw = redis.call('HGET', KEYS[1], ARGV[1])
if not raw then return -2 end
local rec = cjson.decode(raw)
if rec.status == 'reclaimed' then return 1 end
if rec.status ~= 'funded' then return 0 end
local now = tonumber(ARGV[2])
if not rec.expiresAt or now <= tonumber(rec.expiresAt) then return 0 end
rec.status = 'reclaimed'
rec.reclaimedAt = now
redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(rec))
redis.call('ZREM', KEYS[2], ARGV[1])
return 1
`;
/**
* Atomically mark an EXPIRED, unclaimed drop as reclaimed so its funds can be
* swept back to the sender exactly once. Mutually exclusive with claimDrop.
* @param {string} id
* @returns {Promise<'reclaimable'|'ineligible'|'missing'>}
*/
export async function markReclaimable(id) {
const now = Date.now();
const redis = getRedis();
if (redis) {
const r = Number(await redis.eval(RECLAIM_LUA, [K.rec, K.funded], [String(id), String(now)]));
if (r === 1) return 'reclaimable';
if (r === -2) return 'missing';
return 'ineligible';
}
const rec = mem.get(String(id));
if (!rec) return 'missing';
if (rec.status === 'reclaimed') return 'reclaimable';
if (rec.status !== 'funded') return 'ineligible';
if (!rec.expiresAt || now <= rec.expiresAt) return 'ineligible';
rec.status = 'reclaimed';
rec.reclaimedAt = now;
mem.set(String(id), rec);
return 'reclaimable';
}
/** Record the on-chain reclaim sweep tx after a successful reclaim (idempotent set). */
export async function recordReclaim({ id, reclaimTx }) {
const rec = await getDropRecord(id);
if (!rec) return null;
rec.reclaimTx = reclaimTx;
rec.reclaimAt = Date.now();
const redis = getRedis();
if (redis) await redis.hset(K.rec, { [id]: JSON.stringify(rec) });
else mem.set(id, rec);
return rec;
}
/** Record the claimer's re-seal recipient + a delivery note after the envelope is released (audit). */
export async function recordClaimDelivery({ id, claimRecipient }) {
const rec = await getDropRecord(id);
if (!rec) return null;
if (claimRecipient) rec.claimRecipient = claimRecipient;
rec.deliveredAt = Date.now();
const redis = getRedis();
if (redis) await redis.hset(K.rec, { [id]: JSON.stringify(rec) });
else mem.set(id, rec);
return rec;
}
/**
* List a sender's drops (newest first), public projection. `senderTag` is an
* opaque, non-PII tag the creator chooses (e.g. a hash of their session) so they
* can find their drops to reclaim: it is never required and never exposed.
* @param {string} senderTag
* @param {number} [limit=50]
*/
export async function listBySender(senderTag, limit = 50) {
const tag = String(senderTag || '').trim();
if (!tag) return [];
const n = Math.max(1, Math.min(100, Number(limit) || 50));
const redis = getRedis();
if (redis) {
const members = await redis.zrange(K.sender(tag), 0, n - 1, { rev: true });
if (!members.length) return [];
const raw = await redis.hmget(K.rec, ...members);
return members.map((_, i) => parse(raw?.[i])).filter(Boolean).map(toPublicDrop);
}
return [...mem.values()]
.filter((r) => r.senderTag === tag && !isTransientDrop(r))
.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0))
.slice(0, n)
.map(toPublicDrop);
}
/** Expired, still-funded drops (oldest expiry first), the reclaim sweep queue. */
export async function listReclaimable(limit = 50) {
const now = Date.now();
const n = Math.max(1, Math.min(100, Number(limit) || 50));
const redis = getRedis();
if (redis) {
// Score is expiresAt; everything below `now` is expired and still funded.
const members = await redis.zrange(K.funded, 0, now, { byScore: true });
const slice = members.slice(0, n);
if (!slice.length) return [];
const raw = await redis.hmget(K.rec, ...slice);
return slice.map((_, i) => parse(raw?.[i])).filter((r) => r && r.status === 'funded' && r.expiresAt <= now);
}
return [...mem.values()]
.filter((r) => r.status === 'funded' && r.expiresAt && r.expiresAt <= now)
.sort((a, b) => a.expiresAt - b.expiresAt)
.slice(0, n);
}
/** Aggregate stats for the landing/explore surface. */
export async function dropStats() {
const redis = getRedis();
let recs;
if (redis) {
const all = await redis.hgetall(K.rec);
recs = all ? Object.values(all).map(parse).filter(Boolean) : [];
} else {
recs = [...mem.values()];
}
const now = Date.now();
// Pending/void drops never became gifts, so they count toward nothing, `total`
// included, which is the number of drops the platform actually issued.
const real = recs.filter((r) => !isTransientDrop(r));
let funded = 0, claimed = 0, reclaimed = 0;
for (const r of real) {
if (r.status === 'claimed') claimed++;
else if (r.status === 'reclaimed') reclaimed++;
else if (r.status === 'funded' && (!r.expiresAt || r.expiresAt > now)) funded++;
}
return { funded, claimed, reclaimed, total: real.length };
}
// Test-only: reset the in-memory fallback between specs.
export function __resetMemoryStore() {
mem.clear();
}
export { PUBLIC_FIELDS };