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.

28.4 KB
Raw Blame
// Fork Royalty Streams — provenance income for avatar creators.
//
// WHY ONLY three.ws CAN DO THIS: the platform already welds a verifiable fork
// lineage (avatars.parent_avatar_id + source_meta.forked_from) to a real,
// funded, self-custodial wallet on every agent. So when you make a great avatar
// and others fork it, and THEIR forks earn, a creator-set slice of that real
// income can stream back up the lineage to your wallet — automatically, on-chain,
// transparently.
//
// THE OWNERSHIP INVARIANT (never violated): a fork solely owns its wallet and its
// funds. A royalty is an OPT-IN split on the fork's DEFINED NEW INCOME at the
// moment it is earned — never a claim on the fork's existing balance, never key
// access for the ancestor. The forker consents to the exact terms at fork time
// and always keeps the clear majority. The payout is a normal outbound transfer
// the fork's own custodial signer authorizes (the same signer the owner already
// trusts for withdraws/trades), gated to a hard-capped, decaying slice.
//
// SAFETY: opt-in · per-creator + total caps · depth decay · majority-to-forker ·
// idempotent (one obligation per income event per ancestor) · audited on both
// sides · $THREE-rule clean (payout rail is native SOL; no other mint named).
//
// This module is split into PURE math (testable without a DB or chain) and the
// DB/chain-touching engine. The cron-free trigger is fire-and-forget from the
// real income paths (tip + money-stream settlement) in api/agents/solana-wallet.js.

import { sql } from './db.js';
import { insertNotification } from './notify.js';

// ── Platform policy constants (the fairness guardrails) ──────────────────────

// The most a single creator may set as their fork royalty (10%). A creator
// configuring a higher number is clamped to this — the UI shows the cap.
export const ROYALTY_PER_CREATOR_CAP_BPS = 1000;

// The hard ceiling on TOTAL upstream take across the whole lineage (20%). After
// decay, if the summed schedule still exceeds this, every share is scaled down
// proportionally so the forker keeps at least 10000 - this.
export const ROYALTY_TOTAL_CAP_BPS = 2000;

// The forker can never keep less than this share of their own eligible income
// (80%). Equals 10000 - ROYALTY_TOTAL_CAP_BPS; asserted by resolveSchedule.
export const MIN_FORKER_KEEP_BPS = 10000 - ROYALTY_TOTAL_CAP_BPS;

// Geometric depth decay: the immediate parent earns its set rate; each further
// generation earns half of the previous, so deep ancestors fade rather than
// stack. depth 1 → 1×, depth 2 → 0.5×, depth 3 → 0.25× …
export const ROYALTY_DEPTH_DECAY = 0.5;

// Royalties pay on native SOL income only — the rail we can split and settle
// atomically. SPL/USDC income is honestly out of scope (no fake "pending"
// obligation we never pay). Surfaced in the config copy.
export const ROYALTY_ELIGIBLE_ASSET = 'SOL';

// Skip dust: a per-ancestor share below this (0.00002 SOL) is recorded 'skipped'
// rather than paid — a sub-dust transfer would cost more in fees than it moves.
export const ROYALTY_MIN_PAYOUT_LAMPORTS = 20_000n;

// Lamports kept back when sizing a payout against the fork's live balance, so a
// royalty transfer can never push the wallet below fee budget.
const ROYALTY_FEE_RESERVE_LAMPORTS = 15_000n;

// ── Config (the rate a creator sets, stored on the agent record) ─────────────

const DEFAULT_ELIGIBLE = { tips: true, stream: true };

/**
 * Read & normalize an agent's fork-royalty config from its meta. Defaults to
 * "no royalty" (forks are fully free — the platform default). Always returns a
 * sane shape so callers never branch on undefined.
 * @returns {{ bps:number, eligible:{tips:boolean,stream:boolean}, set_at:string|null }}
 */
export function getRoyaltyConfig(meta) {
	const raw = meta?.fork_royalty;
	if (!raw || typeof raw !== 'object') {
		return { bps: 0, eligible: { ...DEFAULT_ELIGIBLE }, set_at: null };
	}
	const bps = clampCreatorBps(raw.bps);
	const eligible = {
		tips: raw.eligible?.tips !== false,
		stream: raw.eligible?.stream !== false,
	};
	return { bps, eligible, set_at: raw.set_at || null };
}

/** Clamp a creator-supplied royalty to [0, ROYALTY_PER_CREATOR_CAP_BPS]. */
export function clampCreatorBps(bps) {
	const n = Math.round(Number(bps) || 0);
	if (!Number.isFinite(n) || n <= 0) return 0;
	return Math.min(n, ROYALTY_PER_CREATOR_CAP_BPS);
}

// ── PURE: schedule resolution (decay + cap) ──────────────────────────────────

/**
 * Resolve the effective upstream royalty schedule for a fork from its ordered
 * ancestor chain. Pure — no DB, no chain — so the fairness math is unit-tested
 * in isolation.
 *
 * @param {Array<{ depth:number, ancestor_agent_id:string, ancestor_avatar_id?:string,
 *                 ancestor_owner_id?:string, ancestor_owner_name?:string,
 *                 ancestor_wallet?:string|null, set_bps:number,
 *                 eligible?:{tips:boolean,stream:boolean} }>} ancestors
 *        depth 1 = immediate parent. set_bps = that ancestor's configured rate.
 * @returns {{ total_bps:number, keep_bps:number, entries:Array }}
 */
export function resolveSchedule(ancestors) {
	const decayed = [];
	for (const a of ancestors || []) {
		const setBps = clampCreatorBps(a.set_bps);
		if (setBps <= 0) continue; // ancestor opted out — contributes nothing
		const depth = Math.max(1, Math.round(a.depth || 1));
		const factor = Math.pow(ROYALTY_DEPTH_DECAY, depth - 1);
		const bps = Math.round(setBps * factor);
		if (bps <= 0) continue; // decayed below a whole bp — drop
		decayed.push({
			depth,
			ancestor_agent_id: a.ancestor_agent_id,
			ancestor_avatar_id: a.ancestor_avatar_id ?? null,
			ancestor_owner_id: a.ancestor_owner_id ?? null,
			ancestor_owner_name: a.ancestor_owner_name ?? null,
			ancestor_wallet: a.ancestor_wallet ?? null,
			set_bps: setBps,
			bps,
			eligible: {
				tips: a.eligible?.tips !== false,
				stream: a.eligible?.stream !== false,
			},
		});
	}

	let total = decayed.reduce((s, e) => s + e.bps, 0);

	// Enforce the absolute total cap by scaling every share down proportionally.
	// Largest-remainder rounding keeps the scaled sum exactly at the cap.
	if (total > ROYALTY_TOTAL_CAP_BPS && total > 0) {
		const scale = ROYALTY_TOTAL_CAP_BPS / total;
		let running = 0;
		const withRemainder = decayed.map((e) => {
			const exact = e.bps * scale;
			const floor = Math.floor(exact);
			running += floor;
			return { e, floor, frac: exact - floor };
		});
		let leftover = ROYALTY_TOTAL_CAP_BPS - running;
		withRemainder.sort((a, b) => b.frac - a.frac);
		for (const item of withRemainder) {
			item.e.bps = item.floor + (leftover > 0 ? 1 : 0);
			if (leftover > 0) leftover--;
		}
		total = decayed.reduce((s, e) => s + e.bps, 0);
	}

	// Drop any entry that scaled to zero, re-sort by depth for a stable receipt.
	const entries = decayed.filter((e) => e.bps > 0).sort((a, b) => a.depth - b.depth);
	total = entries.reduce((s, e) => s + e.bps, 0);

	// Invariant the whole feature rests on: the forker keeps the clear majority.
	const keep = 10000 - total;
	if (keep < MIN_FORKER_KEEP_BPS) {
		// Unreachable given the cap, but assert rather than silently over-tax.
		throw new Error(`royalty schedule would leave forker ${keep}bps (< ${MIN_FORKER_KEEP_BPS})`);
	}

	return { total_bps: total, keep_bps: keep, entries };
}

/**
 * Split a lamport income amount across a resolved schedule for one income type.
 * Pure. Entries whose eligibility excludes `kind` get nothing. Shares below the
 * dust floor are marked skipped (not paid). Returns the per-ancestor breakdown
 * plus what the forker keeps — the exact numbers both sides see.
 *
 * @param {bigint} amountLamports
 * @param {{ entries:Array }} schedule  (from resolveSchedule / a stored snapshot)
 * @param {'tips'|'stream'} kind
 */
export function splitIncome(amountLamports, schedule, kind) {
	const amount = typeof amountLamports === 'bigint' ? amountLamports : BigInt(amountLamports || 0);
	const out = [];
	let upstream = 0n;
	for (const e of schedule?.entries || []) {
		const eligible = e.eligible ? e.eligible[kind] !== false : true;
		const share = eligible ? (amount * BigInt(e.bps)) / 10000n : 0n;
		const skipped = !eligible || share < ROYALTY_MIN_PAYOUT_LAMPORTS;
		out.push({
			ancestor_agent_id: e.ancestor_agent_id,
			ancestor_owner_id: e.ancestor_owner_id ?? null,
			ancestor_owner_name: e.ancestor_owner_name ?? null,
			ancestor_wallet: e.ancestor_wallet ?? null,
			depth: e.depth,
			bps: e.bps,
			amount_lamports: skipped ? 0n : share,
			skipped,
			reason: !eligible ? 'ineligible_income_type' : share < ROYALTY_MIN_PAYOUT_LAMPORTS ? 'below_dust' : null,
		});
		if (!skipped) upstream += share;
	}
	return { upstream_lamports: upstream, keep_lamports: amount - upstream, splits: out };
}

// ── DB: lineage resolution + snapshot ────────────────────────────────────────

const MAX_LINEAGE_DEPTH = 12; // cap the walk; deeper ancestors are decayed to ~0 anyway

/**
 * Walk a forked avatar's lineage (avatars.parent_avatar_id) up to the root,
 * resolving each ancestor's live agent + its CURRENT royalty config + wallet.
 * Returns the ordered ancestor list (depth 1 = immediate parent) ready for
 * resolveSchedule. A missing agent/wallet still yields an entry (set_bps from
 * config) so the snapshot is complete; payout-time re-resolution handles the
 * deleted-ancestor case.
 *
 * @param {string} forkAvatarId  the NEW (forked) avatar's id — its parent is depth 1
 */
export async function resolveAncestorChain(forkAvatarId) {
	const ancestors = [];
	const seen = new Set([forkAvatarId]);
	let cursorAvatarId = forkAvatarId;
	let depth = 1;

	while (depth <= MAX_LINEAGE_DEPTH) {
		const [parent] = await sql`
			select a.id, a.owner_id, a.parent_avatar_id, u.display_name as owner_name
			from avatars a
			join avatars child on child.parent_avatar_id = a.id
			left join users u on u.id = a.owner_id
			where child.id = ${cursorAvatarId} and a.deleted_at is null
			limit 1
		`;
		if (!parent || seen.has(parent.id)) break; // root reached or cycle guard
		seen.add(parent.id);

		// The ancestor's live agent: its current royalty config + payout wallet.
		const [agent] = await sql`
			select id, user_id, meta, deleted_at
			from agent_identities
			where avatar_id = ${parent.id}
			order by created_at asc
			limit 1
		`;
		const cfg = getRoyaltyConfig(agent?.meta);
		ancestors.push({
			depth,
			ancestor_agent_id: agent?.id ?? null,
			ancestor_avatar_id: parent.id,
			ancestor_owner_id: parent.owner_id ?? null,
			ancestor_owner_name: parent.owner_name ?? null,
			ancestor_wallet: agent?.meta?.solana_address ?? null,
			set_bps: agent ? cfg.bps : 0,
			eligible: cfg.eligible,
		});

		cursorAvatarId = parent.id;
		depth++;
	}

	// Only ancestors with a resolvable agent can actually receive a royalty.
	return ancestors.filter((a) => a.ancestor_agent_id);
}

/**
 * Resolve the upstream royalty schedule a fork of `sourceAvatarId` WOULD carry.
 * The source avatar becomes the fork's parent (depth 1), so the source's own
 * royalty config is the first entry, followed by its ancestors. Used by both the
 * fork consent preview and the fork-time snapshot.
 *
 * @param {string} sourceAvatarId  the avatar being forked
 */
export async function resolveScheduleForSource(sourceAvatarId) {
	const [source] = await sql`
		select a.id, a.owner_id, u.display_name as owner_name
		from avatars a left join users u on u.id = a.owner_id
		where a.id = ${sourceAvatarId} and a.deleted_at is null
		limit 1
	`;
	if (!source) return resolveSchedule([]);

	const [sourceAgent] = await sql`
		select id, meta from agent_identities
		where avatar_id = ${source.id}
		order by created_at asc limit 1
	`;
	const sourceCfg = getRoyaltyConfig(sourceAgent?.meta);

	const ancestors = [];
	if (sourceAgent?.id) {
		ancestors.push({
			depth: 1,
			ancestor_agent_id: sourceAgent.id,
			ancestor_avatar_id: source.id,
			ancestor_owner_id: source.owner_id ?? null,
			ancestor_owner_name: source.owner_name ?? null,
			ancestor_wallet: sourceAgent.meta?.solana_address ?? null,
			set_bps: sourceCfg.bps,
			eligible: sourceCfg.eligible,
		});
	}
	// The source's own ancestors shift down one generation for the new fork.
	const upstream = await resolveAncestorChain(source.id);
	for (const a of upstream) ancestors.push({ ...a, depth: a.depth + 1 });

	return resolveSchedule(ancestors);
}

/**
 * Persist the immutable consent snapshot for a freshly created fork. Idempotent
 * on fork_agent_id (a re-run updates nothing). Skips writing when the schedule
 * is empty — a free fork carries no terms row.
 */
export async function snapshotForkRoyaltyTerms({ forkAgentId, forkAvatarId, acceptedBy, schedule }) {
	if (!forkAgentId || !schedule || schedule.total_bps <= 0 || !schedule.entries?.length) {
		return { written: false };
	}
	await sql`
		insert into fork_royalty_terms (fork_agent_id, fork_avatar_id, total_bps, schedule, accepted_by)
		values (
			${forkAgentId}, ${forkAvatarId ?? null}, ${schedule.total_bps},
			${JSON.stringify(schedule.entries)}::jsonb, ${acceptedBy ?? null}
		)
		on conflict (fork_agent_id) do nothing
	`;
	return { written: true, total_bps: schedule.total_bps };
}

/** Load a fork's stored consent snapshot (or null when it carries no terms). */
export async function loadForkRoyaltyTerms(forkAgentId) {
	const [row] = await sql`
		select id, fork_agent_id, fork_avatar_id, total_bps, schedule, created_at
		from fork_royalty_terms where fork_agent_id = ${forkAgentId} limit 1
	`;
	if (!row) return null;
	return {
		id: row.id,
		fork_agent_id: row.fork_agent_id,
		fork_avatar_id: row.fork_avatar_id,
		total_bps: Number(row.total_bps),
		entries: Array.isArray(row.schedule) ? row.schedule : [],
		created_at: row.created_at,
	};
}

// ── DB + chain: the real payout engine ───────────────────────────────────────

/**
 * Apply fork royalties for ONE eligible income event on a fork.
 *
 * Flow (idempotent + audited):
 *   1. Load the fork's frozen consent snapshot. No terms → honest no-op.
 *   2. Split the income per the snapshot for this income type (decay+cap already
 *      baked into the snapshot bps). Nothing owed → no-op.
 *   3. Claim one ledger row per ancestor via INSERT … RETURNING with the
 *      (source_event_id, ancestor_agent_id) unique key. Only rows THIS call
 *      created are paid — concurrent triggers and retries claim nothing and so
 *      never double-pay.
 *   4. Re-resolve each ancestor's LIVE wallet (a deleted ancestor / missing
 *      wallet reroutes to the platform treasury per the disclosed rule).
 *   5. Send the real on-chain transfers FROM the fork's custodial signer, mark
 *      rows confirmed/failed, and mirror an audit event onto both sides.
 *
 * Fire-and-forget from the income path — never throws into the caller.
 *
 * @param {string} forkAgentId
 * @param {{ eventId:number|string, kind:'tip'|'stream', amountLamports:bigint|number|string,
 *           asset?:string, network?:string, fromWallet?:string }} income
 */
export async function applyForkRoyalties(forkAgentId, income) {
	try {
		const asset = (income.asset || 'SOL').toUpperCase();
		if (asset !== ROYALTY_ELIGIBLE_ASSET) return { applied: false, reason: 'ineligible_asset' };
		const kind = income.kind === 'stream' ? 'stream' : 'tips';
		const network = income.network === 'devnet' ? 'devnet' : 'mainnet';
		const sourceEventId = income.eventId != null ? String(income.eventId) : null;
		if (!sourceEventId) return { applied: false, reason: 'no_event_id' };

		const terms = await loadForkRoyaltyTerms(forkAgentId);
		if (!terms || terms.total_bps <= 0) return { applied: false, reason: 'no_terms' };

		const amount = typeof income.amountLamports === 'bigint'
			? income.amountLamports
			: BigInt(income.amountLamports || 0);
		if (amount <= 0n) return { applied: false, reason: 'zero_income' };

		const { splits, upstream_lamports } = splitIncome(amount, terms, kind);
		const payable = splits.filter((s) => !s.skipped && s.amount_lamports > 0n);
		if (!payable.length) {
			// Record skipped obligations so the ledger is honest (e.g. dust), then stop.
			await recordSkips(forkAgentId, sourceEventId, kind, network, splits);
			return { applied: false, reason: 'nothing_payable', upstream_lamports: upstream_lamports.toString() };
		}

		// 3. Claim ledger rows. Only freshly-inserted rows are ours to pay.
		const claimed = [];
		for (const s of payable) {
			const [row] = await sql`
				insert into fork_royalty_payouts (
					fork_agent_id, ancestor_agent_id, recipient_wallet, depth, bps,
					source_event_id, source_kind, network, asset, amount_lamports, status, meta
				) values (
					${forkAgentId}, ${s.ancestor_agent_id}, ${s.ancestor_wallet ?? null}, ${s.depth}, ${s.bps},
					${sourceEventId}, ${kind === 'stream' ? 'stream' : 'tip'}, ${network}, 'SOL',
					${s.amount_lamports.toString()}::bigint, 'pending',
					${JSON.stringify({ owner_name: s.ancestor_owner_name, from: income.fromWallet || null })}::jsonb
				)
				on conflict (source_event_id, ancestor_agent_id) do nothing
				returning id, ancestor_agent_id, amount_lamports, depth, bps
			`;
			if (row) claimed.push({ ...s, payoutId: row.id });
		}
		if (!claimed.length) return { applied: false, reason: 'already_processed' };

		// 4 + 5. Resolve live wallets, send, settle.
		await settlePayouts({ forkAgentId, network, claimed, sourceEventId, kind });
		return { applied: true, paid: claimed.length, upstream_lamports: upstream_lamports.toString() };
	} catch (err) {
		console.error('[fork-royalties] applyForkRoyalties failed', forkAgentId, err?.message);
		return { applied: false, reason: 'error', error: err?.message };
	}
}

// Record dust/ineligible obligations as 'skipped' ledger rows so the split view
// is fully honest about what was and wasn't owed. Idempotent.
async function recordSkips(forkAgentId, sourceEventId, kind, network, splits) {
	for (const s of splits) {
		if (!s.skipped) continue;
		await sql`
			insert into fork_royalty_payouts (
				fork_agent_id, ancestor_agent_id, recipient_wallet, depth, bps,
				source_event_id, source_kind, network, asset, amount_lamports, status, reason, meta
			) values (
				${forkAgentId}, ${s.ancestor_agent_id}, ${s.ancestor_wallet ?? null}, ${s.depth}, ${s.bps},
				${sourceEventId}, ${kind === 'stream' ? 'stream' : 'tip'}, ${network}, 'SOL',
				0, 'skipped', ${s.reason || 'below_dust'},
				${JSON.stringify({ owner_name: s.ancestor_owner_name })}::jsonb
			)
			on conflict (source_event_id, ancestor_agent_id) do nothing
		`.catch(() => {});
	}
}

/**
 * Resolve live recipient wallets (reroute deleted ancestors), execute the real
 * SOL transfers from the fork's custodial signer, and settle each ledger row.
 */
async function settlePayouts({ forkAgentId, network, claimed, sourceEventId, kind }) {
	// Load the fork's signer + verify it can cover the splits.
	const [forkAgent] = await sql`
		select id, user_id, name, meta from agent_identities where id = ${forkAgentId} and deleted_at is null limit 1
	`;
	if (!forkAgent?.meta?.encrypted_solana_secret) {
		await failRows(claimed, 'fork_wallet_unavailable');
		return;
	}

	// Resolve each ancestor's LIVE wallet; reroute the deleted/wallet-less per rule.
	const { loadCoinTreasury } = await import('./coin/treasury.js');
	let treasuryAddr = null;
	const transfers = [];
	for (const c of claimed) {
		const [anc] = await sql`
			select id, meta, deleted_at from agent_identities where id = ${c.ancestor_agent_id} limit 1
		`;
		let wallet = anc && !anc.deleted_at ? anc.meta?.solana_address || null : null;
		let rerouted = false;
		let reason = null;
		if (!wallet) {
			// Disclosed rule: a deleted / wallet-less ancestor's share routes to the
			// platform treasury rather than vanishing or blocking the others.
			if (!treasuryAddr) {
				try { treasuryAddr = loadCoinTreasury().publicKey.toBase58(); } catch { treasuryAddr = null; }
			}
			wallet = treasuryAddr;
			rerouted = true;
			reason = anc?.deleted_at ? 'ancestor_deleted' : 'ancestor_no_wallet';
		}
		if (!wallet) { // no treasury configured either — cannot pay; fail (retryable)
			await failRows([c], 'no_recipient');
			continue;
		}
		transfers.push({ ...c, to: wallet, lamports: BigInt(c.amount_lamports), rerouted, reason });
	}
	if (!transfers.length) return;

	// Affordability: the income just landed in the fork wallet, but a vanity swap
	// or concurrent spend could shrink it. Never overdraw — fail (retryable) if so.
	const total = transfers.reduce((s, t) => s + t.lamports, 0n);
	try {
		const { solanaConnection } = await import('./agent-pumpfun.js');
		const { PublicKey } = await import('@solana/web3.js');
		const conn = solanaConnection(network);
		const bal = BigInt(await conn.getBalance(new PublicKey(forkAgent.meta.solana_address)));
		if (bal < total + ROYALTY_FEE_RESERVE_LAMPORTS) {
			await failRows(transfers, 'insufficient_balance');
			return;
		}
	} catch {
		// Balance read failed — proceed; the on-chain send still guards against
		// overdraw (a transfer exceeding balance reverts and is marked failed).
	}

	// Recover the fork's signer (audited) and send the real transfers.
	const { recoverSolanaAgentKeypair } = await import('./agent-wallet.js');
	const { sendSolBatched } = await import('./coin/treasury.js');
	let signer;
	try {
		signer = await recoverSolanaAgentKeypair(forkAgent.meta.encrypted_solana_secret, {
			agentId: forkAgentId,
			userId: forkAgent.user_id,
			reason: 'fork_royalty',
			meta: { source_event_id: sourceEventId, kind, recipients: transfers.length },
		});
	} catch (e) {
		await failRows(transfers, 'key_recover_failed');
		return;
	}

	const results = await sendSolBatched({
		from: signer,
		transfers: transfers.map((t) => ({ to: t.to, lamports: t.lamports, ref: t })),
		network,
	});

	for (const r of results) {
		for (const recipient of r.recipients) {
			const t = recipient.ref;
			if (r.error || !r.signature) {
				await sql`
					update fork_royalty_payouts set status='failed', reason=${r.error || 'send_failed'},
						recipient_wallet=${t.to}, rerouted=${t.rerouted}
					where id=${t.payoutId}
				`.catch(() => {});
				continue;
			}
			await sql`
				update fork_royalty_payouts set status='confirmed', signature=${r.signature},
					recipient_wallet=${t.to}, rerouted=${t.rerouted}, reason=${t.reason},
					confirmed_at=now()
				where id=${t.payoutId}
			`.catch(() => {});
			await mirrorCustody({ forkAgentId, ancestorAgentId: t.ancestor_agent_id, recipient: t.to,
				lamports: t.lamports, signature: r.signature, network, kind, rerouted: t.rerouted });
			if (t.ancestor_owner_id) {
				let usd = null;
				try { const { lamportsToUsd } = await import('./agent-trade-guards.js'); usd = await lamportsToUsd(t.lamports); } catch { /* unpriced */ }
				insertNotification(t.ancestor_owner_id, 'royalty_paid', {
					actor: forkAgent.name || 'A fork of your avatar',
					sol: Number(t.lamports) / 1e9,
					usd,
					depth: t.depth,
					signature: r.signature,
					tx_signature: r.signature,
					link: `/agents/${encodeURIComponent(t.ancestor_agent_id)}`,
				});
			}
		}
	}
}

async function failRows(rows, reason) {
	for (const r of rows) {
		await sql`update fork_royalty_payouts set status='failed', reason=${reason} where id=${r.payoutId}`.catch(() => {});
	}
}

/**
 * Mirror a confirmed royalty into the custody/audit trail on BOTH sides:
 *   - the fork (descendant) sees an outbound 'royalty_paid' spend row;
 *   - the ancestor sees an inbound 'royalty' income row (distinct from tips so it
 *     never inflates patron totals), which surfaces in its earnings + Money Pulse.
 * Best-effort — the ledger row is already the source of truth.
 */
async function mirrorCustody({ forkAgentId, ancestorAgentId, recipient, lamports, signature, network, kind, rerouted }) {
	const { recordCustodyEvent } = await import('./agent-trade-guards.js');
	let usd = null;
	try { const { lamportsToUsd } = await import('./agent-trade-guards.js'); usd = await lamportsToUsd(lamports); } catch { /* unpriced */ }
	const idem = `royalty:${signature}:${ancestorAgentId}`;
	await recordCustodyEvent({
		agentId: forkAgentId, eventType: 'royalty_paid', category: 'royalty', network, asset: 'SOL',
		amountLamports: lamports, usd, destination: recipient, signature, status: 'confirmed',
		idempotencyKey: idem, reason: `fork_royalty_${kind}`,
		meta: { ancestor_agent_id: ancestorAgentId, rerouted: !!rerouted },
	}).catch(() => {});
	if (!rerouted && ancestorAgentId) {
		await recordCustodyEvent({
			agentId: ancestorAgentId, eventType: 'royalty', category: 'royalty', network, asset: 'SOL',
			amountLamports: lamports, usd, destination: recipient, signature, status: 'confirmed',
			idempotencyKey: idem, reason: `fork_royalty_${kind}`,
			meta: { from_fork_agent_id: forkAgentId },
		}).catch(() => {});
	}
}

// ── Read models for the transparent split ledger (both sides) ────────────────

/**
 * The descendant view: what this agent (as a fork) shares upstream, plus every
 * royalty it has actually paid. Returns honest zeros when it carries no terms.
 */
export async function getDescendantLedger(agentId, { limit = 50 } = {}) {
	const terms = await loadForkRoyaltyTerms(agentId);
	const payouts = await sql`
		select id, ancestor_agent_id, recipient_wallet, depth, bps, amount_lamports, usd,
		       status, signature, rerouted, reason, source_kind, network, created_at, confirmed_at, meta
		from fork_royalty_payouts
		where fork_agent_id = ${agentId} and status in ('confirmed','pending','failed')
		order by created_at desc limit ${Math.min(Math.max(limit, 1), 200)}
	`;
	const [agg] = await sql`
		select coalesce(sum(amount_lamports) filter (where status='confirmed'),0)::bigint as paid_lamports,
		       coalesce(sum(usd) filter (where status='confirmed'),0) as paid_usd,
		       count(*) filter (where status='confirmed') as paid_count
		from fork_royalty_payouts where fork_agent_id = ${agentId}
	`;
	return {
		shares_upstream: !!terms,
		total_bps: terms?.total_bps || 0,
		keep_bps: terms ? 10000 - terms.total_bps : 10000,
		schedule: terms?.entries || [],
		paid_lamports: String(agg?.paid_lamports || 0n),
		paid_usd: Number(agg?.paid_usd || 0),
		paid_count: Number(agg?.paid_count || 0),
		payouts: payouts.map(serializePayout),
	};
}

/**
 * The ancestor view: royalty income this agent has earned from descendants'
 * forks, grouped by descendant, plus the live config (rate + eligible sources)
 * and how many forks have opted into its terms.
 */
export async function getAncestorLedger(agentId, { limit = 50 } = {}) {
	const incoming = await sql`
		select id, fork_agent_id, recipient_wallet, depth, bps, amount_lamports, usd,
		       status, signature, source_kind, network, created_at, confirmed_at, meta
		from fork_royalty_payouts
		where ancestor_agent_id = ${agentId} and status in ('confirmed','pending')
		order by created_at desc limit ${Math.min(Math.max(limit, 1), 200)}
	`;
	const [agg] = await sql`
		select coalesce(sum(amount_lamports) filter (where status='confirmed'),0)::bigint as earned_lamports,
		       coalesce(sum(usd) filter (where status='confirmed'),0) as earned_usd,
		       count(distinct fork_agent_id) filter (where status='confirmed') as paying_forks
		from fork_royalty_payouts where ancestor_agent_id = ${agentId}
	`;
	// How many forks have this agent in their consent snapshot at all.
	const [forks] = await sql`
		select count(*)::int as n from fork_royalty_terms
		where schedule @> ${JSON.stringify([{ ancestor_agent_id: agentId }])}::jsonb
	`;
	return {
		earns_royalties: Number(forks?.n || 0) > 0,
		fork_count: Number(forks?.n || 0),
		earned_lamports: String(agg?.earned_lamports || 0n),
		earned_usd: Number(agg?.earned_usd || 0),
		paying_forks: Number(agg?.paying_forks || 0),
		income: incoming.map(serializePayout),
	};
}

function serializePayout(r) {
	return {
		id: r.id,
		fork_agent_id: r.fork_agent_id ?? null,
		ancestor_agent_id: r.ancestor_agent_id ?? null,
		recipient_wallet: r.recipient_wallet ?? null,
		depth: Number(r.depth),
		bps: Number(r.bps),
		amount_lamports: r.amount_lamports != null ? String(r.amount_lamports) : '0',
		amount_sol: r.amount_lamports != null ? Number(r.amount_lamports) / 1e9 : 0,
		usd: r.usd != null ? Number(r.usd) : null,
		status: r.status,
		signature: r.signature ?? null,
		rerouted: !!r.rerouted,
		reason: r.reason ?? null,
		source_kind: r.source_kind,
		network: r.network,
		created_at: r.created_at ? new Date(r.created_at).toISOString() : null,
		confirmed_at: r.confirmed_at ? new Date(r.confirmed_at).toISOString() : null,
		meta: r.meta || {},
	};
}