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.

5.1 KB
Raw Blame
// @ts-check
// GET /api/cron/rewards-distribute — the holder-rewards (reflections) loop.
//
// The `rewards` leg of every $THREE spend accrues in THREE_REWARDS_WALLET. This
// cron reads the live pool balance + a $THREE holder snapshot, computes the
// pro-rata distribution (computeRewardsDistribution — pure + tested), and returns
// the plan. The plan is the deflation-free alternative to a burn: value flows back
// to holders rather than being destroyed.
//
// Execution: this endpoint PLANS and never sends. Moving $THREE to thousands of
// holder wallets is an irreversible on-chain spend, so it stays owner-gated and
// is not something a schedule may trigger on its own. Every run is therefore an
// authoritative dry run: it reports exactly who would receive what, down to the
// atomic unit, so the plan is auditable offline before anyone signs it. Whether
// REWARDS_DISTRIBUTOR_SECRET happens to be configured changes only the reported
// reason, never the outcome; executed is always false.
//
// Standalone (not [name].js) so the import graph stays minimal — just the token
// config, the holder snapshot reader, and the pure distribution math.

import { json, method, wrapCron } from '../_lib/http.js';
import { TOKEN_MINT, ATOMICS_PER_TOKEN, treasuryWalletOrNull, rewardsWalletOrNull } from '../_lib/token/config.js';
import { fetchHolderBalances } from '../_lib/coin/holders.js';
import { getBalances } from '../_lib/balances.js';
import { computeRewardsDistribution } from '../_lib/token/rewards.js';
import { recordRewardsDistribution } from '../_lib/token/payments.js';
import { requireCron } from '../_lib/cron-auth.js';

// Read the rewards pool's current $THREE balance (atomics). Returns 0n on any
// failure so the cron degrades to "nothing to distribute" rather than erroring.
async function readPoolAtomics(poolWallet) {
	try {
		const balances = await getBalances({ chain: 'solana', address: poolWallet });
		const entry = (balances?.tokens ?? []).find((t) => t.mint === TOKEN_MINT);
		const ui = entry?.amount || 0;
		return BigInt(Math.floor(ui * Number(ATOMICS_PER_TOKEN)));
	} catch {
		return 0n;
	}
}

export default wrapCron(async (req, res) => {
	if (!method(req, res, ['GET', 'POST'])) return;
	if (!requireCron(req, res)) return;

	const rewardsWallet = rewardsWalletOrNull();
	const treasuryWallet = treasuryWalletOrNull();
	if (!rewardsWallet) {
		return json(res, 200, {
			ok: true,
			executed: false,
			reason: 'THREE_REWARDS_WALLET not configured — no pool to distribute',
		});
	}

	// Min payout floor: skip dust so we don't pay a holder less than it costs to
	// create their ATA. One $THREE worth of atomics is a sane, mint-agnostic floor.
	const minPayoutAtomics = ATOMICS_PER_TOKEN;

	const [poolAtomics, snapshot] = await Promise.all([
		readPoolAtomics(rewardsWallet),
		fetchHolderBalances({ mint: TOKEN_MINT, network: 'mainnet' }),
	]);

	// Holders eligible for reflections = everyone holding $THREE, EXCLUDING the
	// platform's own wallets (pool can't pay itself; treasury isn't a holder).
	const exclude = new Set([rewardsWallet, treasuryWallet].filter(Boolean));
	const holders = (snapshot || [])
		.filter((h) => h?.wallet && !exclude.has(h.wallet))
		.map((h) => ({ wallet: h.wallet, balance: h.balance ?? h.amount ?? 0 }));

	const plan = computeRewardsDistribution({ poolAtomics, holders, minPayoutAtomics });

	// The plan is exact and auditable either way; only the reason text differs, so
	// an operator reading the ledger can tell a missing signer from a present one.
	const distributorConfigured = Boolean(process.env.REWARDS_DISTRIBUTOR_SECRET);
	const note = distributorConfigured
		? 'plan only: sending is owner-gated and never auto-executed'
		: 'REWARDS_DISTRIBUTOR_SECRET not configured; plan only';

	// Record the run so /three can show a real, verifiable distribution history.
	// Status 'planned' (dry run) is logged but excluded from the reflected total —
	// only 'completed' on-chain runs count toward "reflected to holders". A logging
	// failure must never fail the cron, so it's best-effort.
	let recordId = null;
	try {
		const rec = await recordRewardsDistribution({
			mint: TOKEN_MINT,
			poolWallet: rewardsWallet,
			poolAtomics,
			distributedAtomics: plan.distributed,
			dustAtomics: plan.dust,
			holderCount: plan.payouts.length,
			eligibleSupplyAtomics: plan.eligibleSupply,
			status: 'planned',
			note,
		});
		recordId = rec.id;
	} catch (err) {
		console.error('[rewards-distribute] failed to record run', err?.message || err);
	}

	return json(res, 200, {
		distribution_id: recordId,
		ok: true,
		executed: false,
		dry_run: true,
		reason: note,
		mint: TOKEN_MINT,
		pool_wallet: rewardsWallet,
		pool_atomics: poolAtomics.toString(),
		eligible_holders: plan.payouts.length,
		eligible_supply_atomics: plan.eligibleSupply.toString(),
		distributable_atomics: plan.distributed.toString(),
		dust_atomics: plan.dust.toString(),
		// Cap the returned payout list so a 200k-holder snapshot doesn't blow the
		// response; the headline totals above cover the full set.
		payouts_preview: plan.payouts.slice(0, 100).map((p) => ({
			wallet: p.wallet,
			atomics: p.atomics.toString(),
		})),
	});
});