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
// Patronage — relationships derived from real on-chain support
// =============================================================
// The single source of truth for patron levels, perk entitlement, seasons, and
// the relationship-memory pipeline. Every number it returns is DERIVED LIVE from
// the real custody ledger (agent_custody_events) — there is no stored balance,
// level, or count anywhere. A patron's identity is their on-chain wallet: the
// verified `from` of their tips/streams (api/agents/solana-wallet.js records it
// only after independently re-verifying the transfer on-chain).
//
// Consumed by:
// api/agents/patronage.js — the Support surface, owner CRM, unlock gating
// api/agents/solana-wallet.js — writes a relationship memory on a level-up
// api/agents/talk.js — greets recognized patrons; frees patron-perk skills
import { sql } from './db.js';
import { reverseLookupAddress } from '../../src/solana/sns.js';
// ── Levels (documented thresholds) ──────────────────────────────────────────────
// Cumulative lifetime support in USD, normalized at the moment of each transfer
// (SOL priced to USD, USDC 1:1). Thresholds are intentionally public and stable so
// the ladder a visitor sees is the ladder that gates real perks. `minUsd` is the
// INCLUSIVE floor; `supporter` is anyone who has given more than $0.
export const PATRON_LEVELS = Object.freeze([
{ key: 'supporter', label: 'Supporter', minUsd: 0, glyph: '◔', accent: '#c4b5fd' },
{ key: 'patron', label: 'Patron', minUsd: 10, glyph: '◑', accent: '#a78bfa' },
{ key: 'champion', label: 'Champion', minUsd: 50, glyph: '◕', accent: '#8b5cf6' },
{ key: 'benefactor', label: 'Benefactor', minUsd: 250, glyph: '●', accent: '#7c3aed' },
]);
/** The level for a cumulative USD figure, or null when there is no support yet. */
export function levelForUsd(usd) {
const n = Number(usd) || 0;
if (n <= 0) return null;
let cur = PATRON_LEVELS[0];
for (const lvl of PATRON_LEVELS) if (n >= lvl.minUsd) cur = lvl;
return cur;
}
export function levelIndex(key) {
return PATRON_LEVELS.findIndex((l) => l.key === key);
}
/**
* The next level the viewer has NOT yet reached — their goal. A wallet with $0
* support hasn't even reached Supporter (which needs any positive support), so its
* goal is Supporter; once benefactor is reached this returns null.
*/
export function nextLevelForUsd(usd) {
const n = Number(usd) || 0;
for (const lvl of PATRON_LEVELS) {
const reached = n > 0 && n >= lvl.minUsd;
if (!reached) return lvl;
}
return null;
}
/** Progress toward the next level: { current, next, pct, remainingUsd }. */
export function progressForUsd(usd) {
const n = Number(usd) || 0;
const current = levelForUsd(n);
const next = nextLevelForUsd(n);
if (!next) return { current, next: null, pct: 1, remainingUsd: 0 };
const floor = current ? current.minUsd : 0;
const span = next.minUsd - floor || next.minUsd || 1;
const pct = Math.max(0, Math.min(1, (n - floor) / span));
return { current, next, pct, remainingUsd: Math.max(0, next.minUsd - n) };
}
// ── Seasons / epochs (monthly) ──────────────────────────────────────────────────
// A live competitive window computed purely from the calendar in UTC — no stored
// season rows, so rollover is automatic and historical aggregation just changes
// the `since` bound. There is always a season in flight to compete for.
export function currentSeason(now = new Date()) {
const y = now.getUTCFullYear();
const m = now.getUTCMonth();
const startsAt = new Date(Date.UTC(y, m, 1));
const endsAt = new Date(Date.UTC(y, m + 1, 1));
const key = `${y}-${String(m + 1).padStart(2, '0')}`;
const label = startsAt.toLocaleString('en-US', { month: 'long', year: 'numeric', timeZone: 'UTC' });
return { key, label, startsAt: startsAt.toISOString(), endsAt: endsAt.toISOString() };
}
// ── Patron ledger (derived from the real custody ledger) ─────────────────────────
// Group every verified inbound transfer to this agent by its on-chain payer and
// sum the normalized USD. Tips and stream settlements are the inbound events that
// carry a verified `from` (api/agents/solana-wallet.js). Unpriceable rows count as
// $0 toward the total but still as a support event, so the count never lies.
/**
* Aggregate an agent's supporters from chain truth.
* @param {string} agentId
* @param {{ network?:string, since?:string|null, limit?:number|null, offset?:number }} [opts]
* @returns {Promise<Array<{wallet:string, usd:number, supportCount:number, firstAt:string, lastAt:string}>>}
*/
export async function aggregatePatrons(agentId, opts = {}) {
const { network = 'mainnet', since = null, limit = null, offset = 0 } = opts;
const rows = await sql`
SELECT meta->>'from' AS wallet,
COALESCE(SUM(usd), 0)::float8 AS usd,
COUNT(*)::int AS support_count,
MIN(created_at) AS first_at,
MAX(created_at) AS last_at
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type IN ('tip', 'stream')
AND meta->>'from' IS NOT NULL
AND meta->>'from' <> ''
AND (${since}::timestamptz IS NULL OR created_at >= ${since})
GROUP BY meta->>'from'
ORDER BY usd DESC, support_count DESC, MIN(created_at) ASC
${limit != null ? sql`LIMIT ${Number(limit)} OFFSET ${Number(offset) || 0}` : sql``}
`;
return rows.map((r) => ({
wallet: r.wallet,
usd: Number(r.usd) || 0,
supportCount: r.support_count,
firstAt: r.first_at ? new Date(r.first_at).toISOString() : null,
lastAt: r.last_at ? new Date(r.last_at).toISOString() : null,
}));
}
/** Total distinct patrons + total normalized USD supported (lifetime or season). */
export async function patronTotals(agentId, { network = 'mainnet', since = null } = {}) {
const [row] = await sql`
SELECT COUNT(DISTINCT meta->>'from')::int AS patrons,
COALESCE(SUM(usd), 0)::float8 AS usd,
COUNT(*)::int AS supports
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type IN ('tip', 'stream')
AND meta->>'from' IS NOT NULL
AND meta->>'from' <> ''
AND (${since}::timestamptz IS NULL OR created_at >= ${since})
`;
return { patrons: row?.patrons || 0, usd: Number(row?.usd) || 0, supports: row?.supports || 0 };
}
/** One wallet's standing on one agent, fully derived. usd=0 when not a patron. */
export async function patronStanding(agentId, wallet, { network = 'mainnet' } = {}) {
if (!wallet) return { wallet: null, usd: 0, supportCount: 0, firstAt: null, lastAt: null, level: null, progress: progressForUsd(0) };
const [row] = await sql`
SELECT COALESCE(SUM(usd), 0)::float8 AS usd,
COUNT(*)::int AS support_count,
MIN(created_at) AS first_at,
MAX(created_at) AS last_at
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type IN ('tip', 'stream')
AND meta->>'from' = ${wallet}
`;
const usd = Number(row?.usd) || 0;
return {
wallet,
usd,
supportCount: row?.support_count || 0,
firstAt: row?.first_at ? new Date(row.first_at).toISOString() : null,
lastAt: row?.last_at ? new Date(row.last_at).toISOString() : null,
level: levelForUsd(usd),
progress: progressForUsd(usd),
};
}
// ── Perk ladder config ──────────────────────────────────────────────────────────
export const PERK_TYPES = Object.freeze(['greeting', 'lore', 'skill', 'launch_access', 'badge']);
export async function listPerks(agentId, { activeOnly = false } = {}) {
const rows = await sql`
SELECT id, perk_type, threshold_usd, title, description, payload, is_active, created_at, updated_at
FROM agent_patron_perks
WHERE agent_id = ${agentId}
${activeOnly ? sql`AND is_active = true` : sql``}
ORDER BY threshold_usd ASC, created_at ASC
`;
return rows.map((r) => ({
id: r.id,
perkType: r.perk_type,
thresholdUsd: Number(r.threshold_usd) || 0,
title: r.title,
description: r.description || '',
payload: r.payload || {},
isActive: r.is_active,
}));
}
/**
* Perks a given USD level has earned. A perk is earned only by REAL support: a
* wallet with $0 support is not a patron and unlocks nothing, even a $0-threshold
* rung (which means "any supporter", not "everyone"). Used for display flags and
* for the signature-gated unlock alike.
*/
export function entitledPerks(perks, usd) {
const n = Number(usd) || 0;
if (n <= 0) return [];
return perks.filter((p) => p.isActive && n >= p.thresholdUsd);
}
// ── Display name (SNS reverse with a per-agent cache) ────────────────────────────
// reverseLookupAddress hits Bonfida; we cache the resolution on agent_patron_prefs
// so a busy wall doesn't re-resolve every wallet on every read.
export async function resolvePatronName(agentId, wallet) {
if (!wallet) return null;
try {
const [pref] = await sql`
SELECT display_name FROM agent_patron_prefs
WHERE agent_id = ${agentId} AND patron_wallet = ${wallet}
`;
if (pref && pref.display_name) return pref.display_name;
} catch { /* fall through to live lookup */ }
let name = null;
try { name = await reverseLookupAddress(wallet); } catch { name = null; }
if (name) {
await sql`
INSERT INTO agent_patron_prefs (agent_id, patron_wallet, display_name, updated_at)
VALUES (${agentId}, ${wallet}, ${name}, now())
ON CONFLICT (agent_id, patron_wallet)
DO UPDATE SET display_name = EXCLUDED.display_name, updated_at = now()
`.catch(() => {});
}
return name;
}
/** The set of wallets that opted out of the public wall for this agent. */
export async function hiddenWallets(agentId) {
const rows = await sql`
SELECT patron_wallet FROM agent_patron_prefs
WHERE agent_id = ${agentId} AND hidden = true
`;
return new Set(rows.map((r) => r.patron_wallet));
}
// ── Relationship memory on a level-up (the magic) ────────────────────────────────
// When a patron crosses into a NEW level, write a real agent memory through the
// same store the chat reads, so the agent naturally references the relationship.
// Idempotent per level via agent_patron_prefs.milestone_level — a re-tip at the
// same level writes nothing. Best-effort: a failure never blocks tip recording.
const SHORT = (w) => (w && w.length > 9 ? `${w.slice(0, 4)}…${w.slice(-4)}` : w || 'someone');
/**
* Recompute a patron's standing and, if they just reached a higher level than the
* last one we recorded a memory for, write a relationship memory + update state.
* @returns {Promise<{wrote:boolean, level:string|null}>}
*/
export async function maybeWritePatronMemory({ agentId, wallet, network = 'mainnet' }) {
if (!agentId || !wallet) return { wrote: false, level: null };
let standing;
try {
standing = await patronStanding(agentId, wallet, { network });
} catch {
return { wrote: false, level: null };
}
if (!standing.level) return { wrote: false, level: null };
const [pref] = await sql`
SELECT milestone_level FROM agent_patron_prefs
WHERE agent_id = ${agentId} AND patron_wallet = ${wallet}
`.catch(() => [null]);
const prevIdx = pref?.milestone_level ? levelIndex(pref.milestone_level) : -1;
const nowIdx = levelIndex(standing.level.key);
if (nowIdx <= prevIdx) return { wrote: false, level: standing.level.key };
const name = await resolvePatronName(agentId, wallet);
const who = name ? `${name} (${SHORT(wallet)})` : SHORT(wallet);
const usdStr = standing.usd >= 1 ? `$${standing.usd.toFixed(2)}` : `$${standing.usd.toFixed(4)}`;
const content =
`Patron ${who} has supported me with ${usdStr} in total across ${standing.supportCount} ` +
`${standing.supportCount === 1 ? 'gift' : 'gifts'} and is now a ${standing.level.label}. ` +
`When ${name || 'this supporter'} talks to me, greet them warmly by name and thank them ` +
`sincerely for their support — they are one of my real patrons.`;
try {
await sql`
INSERT INTO agent_memories (agent_id, type, content, tags, context, salience, tier, pinned, updated_at)
VALUES (
${agentId}, 'user', ${content},
${['patron', 'relationship', standing.level.key]},
${JSON.stringify({ kind: 'patron_milestone', patron_wallet: wallet, level: standing.level.key, usd: standing.usd, name: name || null })}::jsonb,
0.85, 'working', false, now()
)
`;
await sql`
INSERT INTO agent_patron_prefs (agent_id, patron_wallet, milestone_level, display_name, updated_at)
VALUES (${agentId}, ${wallet}, ${standing.level.key}, ${name || null}, now())
ON CONFLICT (agent_id, patron_wallet)
DO UPDATE SET milestone_level = EXCLUDED.milestone_level,
display_name = COALESCE(EXCLUDED.display_name, agent_patron_prefs.display_name),
updated_at = now()
`;
return { wrote: true, level: standing.level.key };
} catch {
return { wrote: false, level: standing.level.key };
}
}
/**
* The agent's patron-relationship context for the chat system prompt: the recent
* milestone memories (so the agent can greet any recognized patron by name), plus
* — when the caller's own wallet is known — an explicit "this user is patron X"
* line. Pure read; safe for the public talk endpoint.
*/
export async function patronChatContext(agentId, callerWallet, { network = 'mainnet' } = {}) {
let memories = [];
try {
memories = await sql`
SELECT content, context FROM agent_memories
WHERE agent_id = ${agentId}
AND tags @> ARRAY['patron']::text[]
AND (expires_at IS NULL OR expires_at > now())
ORDER BY salience DESC, created_at DESC
LIMIT 8
`;
} catch { memories = []; }
let caller = null;
if (callerWallet) {
try {
const standing = await patronStanding(agentId, callerWallet, { network });
if (standing.level) {
const name = await resolvePatronName(agentId, callerWallet).catch(() => null);
caller = { ...standing, name };
}
} catch { caller = null; }
}
if (!memories.length && !caller) return null;
const lines = ['## Your patrons (real on-chain supporters)'];
if (memories.length) {
lines.push('You remember these relationships — reference them naturally, never invent one:');
for (const m of memories) lines.push(`- ${m.content}`);
}
if (caller) {
const usdStr = caller.usd >= 1 ? `$${caller.usd.toFixed(2)}` : `$${caller.usd.toFixed(4)}`;
const who = caller.name ? `${caller.name} (${SHORT(caller.wallet)})` : SHORT(caller.wallet);
lines.push(
`The user talking to you RIGHT NOW is ${who}, a ${caller.level.label} who has supported you with ` +
`${usdStr}. Open by greeting them warmly by name and thanking them for their support.`,
);
}
lines.push('Never fabricate a patron relationship that is not listed above.');
return lines.join('\n');
}