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.

36.4 KB
Raw Blame
// Rug/Honeypot Simulation Firewall — the shared pre-trade safety kernel.
//
// Every buy path on the platform (the autonomous sniper worker, both
// discretionary server-signed endpoints, and the public read-only API) calls
// `assessTradeSafety` BEFORE broadcasting. The differentiator over a heuristic
// "risk badge" is that this runs a REAL on-chain simulated buy→sell round-trip
// (connection.simulateTransaction, sigVerify:false) plus a live SPL authority
// audit — so a coin that can be bought but not sold (a honeypot) is BLOCKED, not
// merely flagged. The verdict is structured, scored 0..100, and every check
// carries a plain-language reason the UI renders verbatim.
//
// Honest degradation is the rule: a check whose data source is unavailable
// (RPC outage after failover, intel not yet computed) NEVER fabricates an
// `allow`. It degrades to `warn` with an explicit reason. No check throws past
// the boundary — `assessTradeSafety` always resolves to a verdict.
//
// $THREE is the only coin three.ws promotes. This kernel is coin-agnostic trade
// plumbing: it assesses whatever runtime mint a buy path hands it and never
// names, hardcodes, or recommends any token.

import { PublicKey, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
import { unpackMint, NATIVE_MINT } from '@solana/spl-token';
import { sql } from './db.js';
import { getPumpTradeClient, getAmmPoolState, getConnection } from './pump.js';
import { checkPriceImpact } from './agent-trade-guards.js';
import { getSmartMoneyForMint } from './smart-money.js';

const LINKAGE_BAND_ORDER = ['none', 'weak', 'moderate', 'strong', 'confirmed'];
const LINKAGE_WARN_BAND = 'strong'; // same-controller score >= the "strong" band (65+) trips the check
const MAX_EARLY_BUYERS_CHECKED = 9; // + the creator = 10, @three-ws/wallet-linkage's hard cap per call

const WSOL_MINT = NATIVE_MINT.toBase58();

// Per-mint micro-cache for the cheap authority + curve reads only. The hot snipe
// path can hit the same fresh mint many times in a burst; an authority/curve
// snapshot is stable on the seconds timescale, so a brief cache shaves real RPC
// latency off block-0 without ever caching a stale verdict (the round-trip
// simulation is never cached — it re-runs against live reserves every call).
const MINT_CACHE_TTL_MS = 8_000;
const _mintCache = new Map(); // mint:network → { at, mintAccount, curve }

// ── scoring weights ───────────────────────────────────────────────────────────
// Each check contributes a penalty to a 0..100 score (100 = perfectly clean).
// A single fatal failure (sell leg dead, no venue) forces a `block` regardless of
// the residual score, so the score is a severity gradient, not the sole gate.
const PENALTY = Object.freeze({
	mint_authority_active: 22, // infinite-supply risk (dev can mint more)
	freeze_authority_active: 28, // dev can freeze your tokens — you can't sell
	sim_unavailable: 18, // couldn't prove the round-trip (degraded)
	buy_leg_reverted: 10, // the sim's BUY leg failed (balance/slippage): not a honeypot shape
	concentration: 16, // one wallet holds an outsized share
	dev_dumped: 14, // dev sold inside the observation window
	bundle: 12, // coordinated-launch likelihood
	price_impact: 10, // this size moves the market a lot
	sybil_cluster: 14, // buyers dominated by one funder cluster (manufactured demand)
	creator_linkage: 18, // an early buyer shares control with the creator (fake demand / insider exit)
});

const BLOCK_SCORE = 45; // at/under this composite → block on warnings alone
const WARN_SCORE = 70; // at/under this → warn

// Reasons that are too dangerous to buy through on a `warn` verdict. The composite
// score keeps these as `warn` (so a hiccup never halts a whole fleet), but for a
// caller that opted into fail-closed enforcement they are hard blocks: we did NOT
// prove the coin is safe. `criticalFirewallReason` lets such a caller (the sniper
// at firewall_level='block') refuse the buy instead of proceeding on a warn — the
// exact hole that was buying honeypots and infinite-mint rugs.
//   simulation_unavailable → the buy→sell round-trip couldn't run: sellability unproven
//   mint_authority_active  → dev can mint unlimited supply and dilute you to zero
//   freeze_authority_active→ dev can freeze your token so you can never sell
//   authority_read_failed  → couldn't read the mint's authorities at all
//   probe_unaffordable     → the payer can't fund even a minimum probe: unproven
//   mint_not_found         → the mint account isn't there to vet
export const CRITICAL_FIREWALL_REASONS = Object.freeze(new Set([
	'simulation_unavailable',
	'probe_unaffordable',
	'mint_authority_active',
	'freeze_authority_active',
	'authority_read_failed',
	'mint_not_found',
]));

/**
 * First critical (unproven-safety) reason in an assessment, or null when none.
 * Pure — safe to unit-test. Used by fail-closed callers to block a `warn` verdict
 * whose warnings mean "couldn't verify", not "verified safe".
 * @param {{ checks?: Array<{status?:string, reason?:string}> }} assessment
 * @returns {string|null}
 */
export function criticalFirewallReason(assessment) {
	if (!assessment) return null;
	for (const c of assessment.checks || []) {
		if (c && c.status !== 'pass' && CRITICAL_FIREWALL_REASONS.has(c.reason)) return c.reason;
	}
	return null;
}

function clampScore(n) {
	return Math.max(0, Math.min(100, Math.round(n)));
}

function toPubkey(v) {
	return v instanceof PublicKey ? v : new PublicKey(v);
}

// A typed sub-result every named check returns. `status` drives the UI dot.
function result(name, status, reason, detail = {}) {
	return { name, status, reason, detail }; // status: 'pass' | 'warn' | 'fail' | 'skip'
}

// ── check 1: SPL mint authority audit ─────────────────────────────────────────
// A non-null mintAuthority means the creator can mint unlimited new supply and
// dilute holders to zero. A set freezeAuthority means the creator can freeze your
// token account so you can never sell — the cleanest honeypot primitive. Both are
// read directly off the SPL mint account, the authoritative on-chain source.
async function checkMintAuthority(connection, mintPk, cacheKey) {
	try {
		let mintAccount = readCache(cacheKey)?.mintAccount;
		if (mintAccount === undefined) {
			const info = await connection.getAccountInfo(mintPk, 'confirmed');
			if (!info) return result('mint_authority', 'warn', 'mint_not_found', {});
			mintAccount = unpackMint(mintPk, info, info.owner);
			writeCache(cacheKey, { mintAccount });
		}
		const mintActive = mintAccount.mintAuthority != null;
		const freezeActive = mintAccount.freezeAuthority != null;
		const detail = {
			mint_authority: mintAccount.mintAuthority ? mintAccount.mintAuthority.toBase58() : null,
			freeze_authority: mintAccount.freezeAuthority ? mintAccount.freezeAuthority.toBase58() : null,
		};
		if (freezeActive) {
			return result('mint_authority', 'fail', 'freeze_authority_active', detail);
		}
		if (mintActive) {
			return result('mint_authority', 'warn', 'mint_authority_active', detail);
		}
		return result('mint_authority', 'pass', 'authorities_renounced', detail);
	} catch (err) {
		return result('mint_authority', 'warn', 'authority_read_failed', { message: short(err) });
	}
}

// ── check 2: tradable venue + reserves ────────────────────────────────────────
// Pre-graduation: read the bonding-curve account — it must exist, not be marked
// `complete` mid-flight, and hold real virtual reserves. Post-graduation: resolve
// the canonical AMM pool and confirm non-trivial liquidity. No venue → BLOCK:
// there is nothing to sell back into.
async function checkVenue(network, mintPk, cacheKey) {
	try {
		const { getPumpSdkV2 } = await import('./pump.js');
		const v2 = await getPumpSdkV2({ network });
		const { onlineSdk } = v2;
		let curve = readCache(cacheKey)?.curve;
		if (curve === undefined) {
			try {
				curve = await onlineSdk.fetchBondingCurve(mintPk);
			} catch {
				curve = null;
			}
			writeCache(cacheKey, { curve });
		}

		if (curve && !curve.complete) {
			const vTok = bigOf(curve.virtualTokenReserves);
			const vQuote = bigOf(curve.virtualQuoteReserves);
			if (vTok <= 0n || vQuote <= 0n) {
				return result('venue', 'fail', 'curve_reserves_empty', {
					virtual_token_reserves: vTok.toString(),
					virtual_quote_reserves: vQuote.toString(),
				});
			}
			return result('venue', 'pass', 'live_bonding_curve', {
				stage: 'bonding_curve',
				virtual_quote_reserves: vQuote.toString(),
			});
		}

		// Graduated (or no curve): the coin must trade on the canonical AMM pool.
		try {
			const amm = await getAmmPoolState({ network, mint: mintPk });
			const baseRes = bigOf(amm.baseReserve);
			// Liquidity is judged on EFFECTIVE quote reserves (vault + virtual):
			// a boost pool can hold real quote-side depth in its virtual
			// reserves, and gating on the raw vault alone would fail a tradable
			// pool as `pool_reserves_empty`. The virtual leg is an i128 and can
			// be negative, so the `<= 0n` check below is also what correctly
			// rejects a pool whose effective depth has gone non-positive.
			const quoteRes = bigOf(amm.effectiveQuoteReserve);
			if (baseRes <= 0n || quoteRes <= 0n) {
				return result('venue', 'fail', 'pool_reserves_empty', {
					base_reserve: baseRes.toString(),
					quote_reserve: quoteRes.toString(),
				});
			}
			return result('venue', 'pass', 'live_amm_pool', {
				stage: 'amm',
				quote_reserve: quoteRes.toString(),
			});
		} catch (poolErr) {
			if (poolErr?.code === 'pool_not_found') {
				return result('venue', 'fail', 'no_tradable_venue', {});
			}
			return result('venue', 'warn', 'venue_read_failed', { message: short(poolErr) });
		}
	} catch (err) {
		return result('venue', 'warn', 'venue_read_failed', { message: short(err) });
	}
}

// Simulation errors that mean "this payer is too poor to run the probe", in the
// shapes the runtime produces both as a top-level `err` and inside program logs.
const FUNDING_SHAPED_ERR = /insufficient (lamports|funds)|InsufficientFunds(ForFee|ForRent)?|AccountNotFound|account with insufficient funds/i;

// ── round-trip probe sizing ───────────────────────────────────────────────────
// A honeypot traps the exit at ANY size — sellability is a property of the coin,
// not of how much you bought. So the probe only ever needs a quote the payer can
// actually simulate. Sizing it at the full entry when the wallet cannot cover
// that is what turned "this wallet is poor" into "this coin is a honeypot": one
// underfunded arm produced 336 consecutive false honeypot verdicts on ordinary
// bonding-curve launches. When the payer's balance is known, the probe shrinks to
// fit it and the honeypot signal stays intact.
const PROBE_RESERVE_LAMPORTS = 6_000_000n; // ~0.006 SOL: token ATA rent + fees, both legs
const MIN_PROBE_LAMPORTS = 1_000_000n; // 0.001 SOL — under this the quote rounds to noise

/**
 * Largest round-trip probe `balanceLamports` can fund, or null when it can fund
 * none. Never returns more than the real entry size. Pure — safe to unit-test.
 * @param {bigint} quoteLamports the entry the caller intends to make
 * @param {bigint|null} balanceLamports payer balance, or null when unknown
 * @returns {bigint|null}
 */
export function probeQuoteLamports(quoteLamports, balanceLamports) {
	if (balanceLamports == null) return quoteLamports;
	const affordable = BigInt(balanceLamports) - PROBE_RESERVE_LAMPORTS;
	if (affordable < MIN_PROBE_LAMPORTS) return null;
	return affordable < quoteLamports ? affordable : quoteLamports;
}

/**
 * Classify a reverted round-trip simulation by WHICH leg failed. The honeypot
 * shape is "you can buy but you cannot sell": only a SELL-leg failure has it,
 * and only it stays a fatal `roundtrip_reverted`. A BUY-leg revert says nothing
 * about sellability. On the pump.fun curve the sell path is the curve program
 * itself, so buy-leg reverts were pure false positives: most commonly the probe
 * payer not affording the simulated buy (system program error 0x1,
 * "insufficient lamports"), else the curve moving past the quote's slippage
 * mid-launch. Both would fail the real entry too, but neither is a trapped
 * exit. Pure — safe to unit-test.
 * @param {object|string} simErr `simulateTransaction().value.err`
 * @param {string[]} logs simulation logs
 * @param {number} buyIxCount instructions in the buy leg (sell ixs follow them)
 * @returns {{ leg:'buy'|'sell', status:'warn'|'fail', reason:string, err:string }}
 */
export function classifyRoundTripRevert(simErr, logs, buyIxCount) {
	const err = typeof simErr === 'object' ? JSON.stringify(simErr).slice(0, 200) : String(simErr);
	const ixIndex = Array.isArray(simErr?.InstructionError) ? Number(simErr.InstructionError[0]) : null;
	if (ixIndex != null && Number.isFinite(ixIndex) && ixIndex < buyIxCount) {
		const underfunded = (logs || []).some((l) => /insufficient lamports/i.test(String(l)));
		return { leg: 'buy', status: 'warn', reason: underfunded ? 'buy_leg_underfunded' : 'buy_leg_reverted', err };
	}
	// A funding failure is not always attributable to an instruction index: a payer
	// whose account does not exist, or cannot cover the fee, fails the whole message
	// (`AccountNotFound`, `InsufficientFundsForFee`, `InsufficientFundsForRent`) with
	// no `InstructionError` to read a leg off. That is the poorest possible wallet,
	// not the most dangerous possible coin, and reading it as a trapped exit is what
	// labelled a fleet's worth of ordinary bonding-curve launches "honeypot".
	if (FUNDING_SHAPED_ERR.test(err) || (logs || []).some((l) => FUNDING_SHAPED_ERR.test(String(l)))) {
		return { leg: 'buy', status: 'warn', reason: 'buy_leg_underfunded', err };
	}
	// Sell leg, or a genuinely unattributable failure: keep the fail-closed reading.
	return { leg: 'sell', status: 'fail', reason: 'roundtrip_reverted', err };
}

// ── check 3: simulated buy→sell round-trip (the honeypot detector) ────────────
// Build a real buy of `quoteAmount`, then a real sell of the tokens that buy
// would yield, pack BOTH legs into one v0 message, and simulate it on real RPC
// with sigVerify:false + replaceRecentBlockhash:true. If the simulation errors on
// the SELL leg — or the sell would return ~0 SOL — the coin cannot be exited: a
// honeypot. BLOCK. Only runs pre-graduation (the bonding-curve buy/sell builders);
// graduated coins are covered by the venue + authority checks (their AMM sell
// builders need full swap state we don't assemble on the hot path).
async function checkRoundTrip({ network, mintPk, payer, quoteAmount, connection, payerBalanceLamports = null }) {
	if (!payer) {
		return { res: result('round_trip', 'skip', 'no_payer_for_simulation', {}), simulated: false };
	}
	let payerPk;
	try {
		payerPk = toPubkey(payer);
	} catch {
		return { res: result('round_trip', 'skip', 'invalid_payer', {}), simulated: false };
	}

	// Shrink the probe to what this payer can actually simulate (see
	// `probeQuoteLamports`). A wallet that cannot fund even the minimum probe
	// cannot fund a real buy either, so its sellability stays unproven — a
	// critical reason, not a silent pass.
	const probeAmount = probeQuoteLamports(quoteAmount, payerBalanceLamports);
	if (probeAmount == null) {
		return {
			res: result('round_trip', 'warn', 'probe_unaffordable', {
				payer_balance: String(payerBalanceLamports),
				min_probe: MIN_PROBE_LAMPORTS.toString(),
			}),
			simulated: false,
		};
	}

	let client;
	try {
		({ client } = await getPumpTradeClient({ network }));
	} catch (err) {
		return { res: result('round_trip', 'warn', 'simulation_unavailable', { message: short(err) }), simulated: false };
	}

	const BNmod = (await import('bn.js')).default;
	const quoteBn = new BNmod(probeAmount.toString());

	// Build the buy. A graduated/zero-out/curve-not-found error here is not a
	// honeypot signal — it means this simulation path doesn't apply, so skip
	// (the venue check already owns "is there a market").
	let buyBuilt;
	try {
		buyBuilt = await client.buildBuyInstructions({ mint: mintPk, user: payerPk, quoteAmount: quoteBn, slippagePct: 15 });
	} catch (err) {
		const code = err?.name || err?.code || '';
		if (code === 'CoinGraduatedError' || code === 'CoinNotFoundError') {
			return { res: result('round_trip', 'skip', 'simulation_not_applicable', { reason: code }), simulated: false };
		}
		if (code === 'InsufficientLiquidityError') {
			return { res: result('round_trip', 'fail', 'buy_yields_nothing', {}), simulated: false };
		}
		return { res: result('round_trip', 'warn', 'simulation_unavailable', { message: short(err) }), simulated: false };
	}

	const baseOut = bigOf(buyBuilt.expectedBaseTokens);
	if (baseOut <= 0n) {
		return { res: result('round_trip', 'fail', 'buy_yields_nothing', {}), simulated: false };
	}

	// Build the matching sell of exactly what the buy yields. A wide slippage on
	// the sim's sell leg keeps the min-out floor from tripping for a reason other
	// than a true honeypot — we want to learn whether the sell *executes at all*.
	let sellBuilt;
	try {
		sellBuilt = await client.buildSellInstructions({ mint: mintPk, user: payerPk, baseAmount: new BNmod(baseOut.toString()), slippagePct: 99 });
	} catch (err) {
		return { res: result('round_trip', 'warn', 'simulation_unavailable', { message: short(err) }), simulated: false };
	}

	const expectedSolBack = bigOf(sellBuilt.expectedQuoteOut);

	// Pack both legs into one message and simulate against real RPC.
	let sim;
	try {
		const bh = await connection.getLatestBlockhash('confirmed').catch(() => null);
		const message = new TransactionMessage({
			payerKey: payerPk,
			recentBlockhash: bh?.blockhash || '11111111111111111111111111111111',
			instructions: [...buyBuilt.instructions, ...sellBuilt.instructions],
		}).compileToV0Message();
		const vtx = new VersionedTransaction(message);
		sim = await connection.simulateTransaction(vtx, {
			sigVerify: false,
			replaceRecentBlockhash: true,
			commitment: 'confirmed',
		});
	} catch (err) {
		return { res: result('round_trip', 'warn', 'simulation_unavailable', { message: short(err) }), simulated: false };
	}

	const simErr = sim?.value?.err ?? null;
	const logs = Array.isArray(sim?.value?.logs) ? sim.value.logs : [];
	const unitsConsumed = sim?.value?.unitsConsumed ?? null;

	if (simErr) {
		const verdict = classifyRoundTripRevert(simErr, logs, buyBuilt.instructions.length);
		return {
			res: result('round_trip', verdict.status, verdict.reason, {
				leg: verdict.leg,
				err: verdict.err,
				log_tail: logs.slice(-4),
				units_consumed: unitsConsumed,
				probe_lamports: probeAmount.toString(),
			}),
			simulated: true,
		};
	}

	if (expectedSolBack <= 0n) {
		return {
			res: result('round_trip', 'fail', 'sell_returns_nothing', { expected_sol_back: '0' }),
			simulated: true,
		};
	}

	return {
		res: result('round_trip', 'pass', 'roundtrip_simulated_ok', {
			expected_sol_back: expectedSolBack.toString(),
			expected_base_tokens: baseOut.toString(),
			units_consumed: unitsConsumed,
			probe_lamports: probeAmount.toString(),
			probe_shrunk: probeAmount < BigInt(quoteAmount),
		}),
		simulated: true,
	};
}

// ── check 4: concentration / bundle / dev-dump (reuse computed intel) ─────────
// Reuse the Coin Intelligence Engine's already-computed structural signals
// instead of recomputing them. Missing intel (a brand-new mint observed for <90s)
// is a `skip`, not a fail — the round-trip + authority checks still gate it.
async function checkIntel(mint, network) {
	let row;
	try {
		const rows = await sql`
			SELECT bundle_score, concentration_top10, dev_sold, risk_flags, signals
			FROM pump_coin_intel
			WHERE mint = ${mint} AND network = ${network}
			LIMIT 1
		`;
		row = rows[0];
	} catch {
		return result('concentration', 'skip', 'intel_unavailable', {});
	}
	if (!row) return result('concentration', 'skip', 'no_intel_yet', {});

	const signals = row.signals && typeof row.signals === 'object' ? row.signals : {};
	const top1 = numOr(signals.concentration_top1);
	const top10 = numOr(row.concentration_top10);
	const bundle = numOr(row.bundle_score);
	const devDumped = row.dev_sold === true;
	const detail = {
		concentration_top1: top1,
		concentration_top10: top10,
		bundle_score: bundle,
		dev_dumped: devDumped,
		risk_flags: Array.isArray(row.risk_flags) ? row.risk_flags : [],
	};

	const fails = [];
	if (top1 != null && top1 >= 0.35) fails.push('concentration');
	if (devDumped) fails.push('dev_dumped');
	if (bundle != null && bundle >= 0.75) fails.push('bundle');

	if (fails.length) {
		return result('concentration', 'warn', fails.join('+'), detail);
	}
	return result('concentration', 'pass', 'structure_clean', detail);
}

// ── check 5: price-impact ceiling (shared guard math) ─────────────────────────
// Reuse the exact `checkPriceImpact` predicate the spend guards use so this
// firewall and the spend ceiling agree on what "too much impact" means. A null
// impact (couldn't compute) is a skip, not a warn.
function checkImpact(priceImpactPct) {
	if (priceImpactPct == null || !Number.isFinite(Number(priceImpactPct))) {
		return result('price_impact', 'skip', 'impact_unknown', {});
	}
	const breach = checkPriceImpact(Number(priceImpactPct), 20);
	if (breach) {
		return result('price_impact', 'warn', 'high_price_impact', { impact_pct: Number(priceImpactPct), max_pct: 20 });
	}
	return result('price_impact', 'pass', 'impact_ok', { impact_pct: Number(priceImpactPct) });
}

// ── check 5: smart-money sybil dominance (task 03 graph) ──────────────────────
// The buyers "in" this coin are scored against the wallet-reputation graph: when
// the net-buy flow is dominated by a single shared-funder cluster, the demand is
// likely manufactured (one entity across many wallets), so WARN. Pure additive
// signal — if the graph has no data or the DB is unreachable, this degrades to a
// silent skip and never blocks the trade.
async function checkSybil(mint, network) {
	try {
		const sm = await getSmartMoneyForMint(mint, network);
		if (!sm || sm.sybil_flag !== true) {
			return result('smart_money', sm && sm.count > 0 ? 'pass' : 'skip',
				sm && sm.count > 0 ? 'smart_money_clean' : 'no_smart_money_data',
				{ count: sm?.count ?? 0, smart_money_score: sm?.smart_money_score ?? null });
		}
		return result('smart_money', 'warn', 'sybil_cluster_dominant', {
			count: sm.count ?? 0,
			smart_money_score: sm.smart_money_score ?? null,
			dominant_cluster: sm.dominant_cluster ?? null,
		});
	} catch {
		return result('smart_money', 'skip', 'smart_money_unavailable', {});
	}
}

// ── check 6: early buyers linked to the creator (wash-trading / fake demand) ──
// Reuses the same intel the concentration check reads: the coin's creator
// wallet (`pump_coin_intel.creator`) and its earliest non-creator buyers
// (`pump_coin_wallets`, ordered by `first_seen_at`). Capped to the creator plus
// the earliest `MAX_EARLY_BUYERS_CHECKED` buyers: @three-ws/wallet-linkage
// scores at most 10 addresses per call. Missing creator/intel is a `skip`,
// never a `warn`: a brand-new mint with no intel yet is not evidence of
// anything, and this check must never fabricate a verdict from absent data.
async function fetchCreatorAndEarlyBuyers(mint, network, limit = MAX_EARLY_BUYERS_CHECKED) {
	try {
		const rows = await sql`
			select ci.creator, cw.wallet
			from pump_coin_intel ci
			join pump_coin_wallets cw on cw.mint = ci.mint
			where ci.mint = ${mint} and ci.network = ${network} and cw.is_creator = false
			order by cw.first_seen_at asc
			limit ${limit}
		`;
		const creator = rows[0]?.creator ?? null;
		const buyers = [...new Set(rows.map((r) => r.wallet).filter(Boolean))];
		return { creator, buyers };
	} catch {
		return { creator: null, buyers: [] };
	}
}

/**
 * Pure decision over an `analyzeLinkage()` result: does any early buyer share
 * control with the creator? Takes the raw `pairs` array so it is unit-testable
 * with synthetic pairs, no DB or RPC involved. Pass `band` to tune the trip
 * threshold (default: the "strong" band, score 65+, the same bar the package
 * itself treats as more-likely-than-not shared control).
 * @param {string} creator
 * @param {Array<{a:string,b:string,score:number,band:string,topSignal:string|null,evidence:any}>} pairs
 * @param {{ band?: string }} [opts]
 */
export function evaluateCreatorLinkagePairs(creator, pairs, { band = LINKAGE_WARN_BAND } = {}) {
	const threshold = LINKAGE_BAND_ORDER.indexOf(band);
	const hits = [];
	for (const p of pairs || []) {
		if (p.a !== creator && p.b !== creator) continue;
		const wallet = p.a === creator ? p.b : p.a;
		if (LINKAGE_BAND_ORDER.indexOf(p.band) >= threshold) {
			hits.push({ wallet, score: p.score, band: p.band, topSignal: p.topSignal ?? null });
		}
	}
	if (!hits.length) {
		return result('creator_linkage', 'pass', 'creator_linkage_clean', { pairs_checked: (pairs || []).length });
	}
	hits.sort((x, y) => y.score - x.score);
	return result('creator_linkage', 'warn', 'early_buyer_linked_to_creator', {
		linked_wallets: hits.map((h) => h.wallet),
		top_match: hits[0],
	});
}

async function checkCreatorLinkage(mint, network, connection) {
	const { creator, buyers } = await fetchCreatorAndEarlyBuyers(mint, network);
	if (!creator) return result('creator_linkage', 'skip', 'no_intel_yet', {});
	if (!buyers.length) return result('creator_linkage', 'skip', 'no_early_buyers_yet', {});

	const addresses = [...new Set([creator, ...buyers])].slice(0, 10);
	if (addresses.length < 2) return result('creator_linkage', 'skip', 'insufficient_addresses', {});

	try {
		const { analyzeLinkage } = await import('@three-ws/wallet-linkage');
		const { pairs } = await analyzeLinkage(connection, addresses);
		return evaluateCreatorLinkagePairs(creator, pairs);
	} catch (err) {
		return result('creator_linkage', 'skip', 'creator_linkage_unavailable', { message: short(err) });
	}
}

// ── verdict composition ───────────────────────────────────────────────────────
function compose(checks, simulated) {
	let score = 100;
	const reasons = [];
	let fatal = false;

	for (const c of checks) {
		if (c.status === 'pass' || c.status === 'skip') continue;

		switch (c.reason) {
			case 'freeze_authority_active':
				score -= PENALTY.freeze_authority_active;
				reasons.push('The creator can freeze your tokens — you may be unable to sell.');
				fatal = true;
				break;
			case 'mint_authority_active':
				score -= PENALTY.mint_authority_active;
				reasons.push('The mint authority is still active — supply can be inflated, diluting holders.');
				break;
			case 'roundtrip_reverted':
				score -= 60;
				reasons.push('A simulated buy→sell round-trip reverted on-chain — this behaves like a honeypot you cannot exit.');
				fatal = true;
				break;
			case 'sell_returns_nothing':
			case 'buy_yields_nothing':
				score -= 60;
				reasons.push('The simulated sell leg returns nothing — there is no working exit for this coin.');
				fatal = true;
				break;
			case 'no_tradable_venue':
			case 'curve_reserves_empty':
			case 'pool_reserves_empty':
				score -= 50;
				reasons.push('No tradable market with real liquidity was found — there is nowhere to sell back into.');
				fatal = true;
				break;
			case 'simulation_unavailable':
				score -= PENALTY.sim_unavailable;
				reasons.push('The round-trip simulation could not run (RPC unavailable) — safety could not be fully verified.');
				break;
			case 'probe_unaffordable':
				score -= PENALTY.sim_unavailable;
				reasons.push('This wallet cannot fund even a minimum simulated round-trip, so the exit went unproven — a balance condition, not a honeypot signal.');
				break;
			case 'buy_leg_underfunded':
				score -= PENALTY.buy_leg_reverted;
				reasons.push('The simulated buy leg could not be funded at this size, so the sell leg went unproven; this is a wallet-balance condition, not a honeypot signal.');
				break;
			case 'buy_leg_reverted':
				score -= PENALTY.buy_leg_reverted;
				reasons.push('The simulated buy leg reverted (the market likely moved past the quoted slippage), so the sell leg went unproven; the entry itself may fail at execution.');
				break;
			case 'high_price_impact':
				score -= PENALTY.price_impact;
				reasons.push(`Price impact is high (${Number(c.detail.impact_pct).toFixed(1)}%) — you may receive far less than market.`);
				break;
			case 'sybil_cluster_dominant':
				score -= PENALTY.sybil_cluster;
				reasons.push('Buying is dominated by one funder cluster — the demand looks manufactured by a single entity, not organic.');
				break;
			case 'early_buyer_linked_to_creator':
				score -= PENALTY.creator_linkage;
				reasons.push('An early buyer shares control with the creator wallet (shared fee payer or first funder): this looks like the creator buying their own launch, not organic demand.');
				break;
			case 'venue_read_failed':
			case 'authority_read_failed':
			case 'mint_not_found':
				score -= PENALTY.sim_unavailable;
				reasons.push('Some on-chain data could not be read — safety could not be fully verified.');
				break;
			default: {
				// Composite intel reason like "concentration+dev_dumped+bundle".
				const parts = String(c.reason).split('+');
				if (parts.includes('concentration')) {
					score -= PENALTY.concentration;
					reasons.push('Holdings are highly concentrated in one wallet — a single seller can crater the price.');
				}
				if (parts.includes('dev_dumped')) {
					score -= PENALTY.dev_dumped;
					reasons.push('The creator already sold during the launch window — a classic exit signal.');
				}
				if (parts.includes('bundle')) {
					score -= PENALTY.bundle;
					reasons.push('The launch shows coordinated-bundle behavior — buys may be manufactured, not organic.');
				}
				break;
			}
		}
	}

	score = clampScore(score);

	let verdict;
	if (fatal || score <= BLOCK_SCORE) verdict = 'block';
	else if (score <= WARN_SCORE || reasons.length > 0) verdict = 'warn';
	else verdict = 'allow';

	if (verdict === 'allow' && !reasons.length) {
		reasons.push(simulated
			? 'Authorities are renounced and a simulated round-trip confirmed you can sell back out.'
			: 'On-chain authority and venue checks passed.');
	}

	return { verdict, score, reasons };
}

/**
 * The shared pre-trade safety kernel. Runs every check concurrently against real
 * on-chain state and composes a structured verdict. NEVER throws — a data-source
 * outage degrades the affected check to `warn` with a reason, never a fake allow.
 *
 * @param {object} o
 * @param {'mainnet'|'devnet'} [o.network='mainnet']
 * @param {string|PublicKey} o.mint              the coin being assessed (runtime input)
 * @param {'buy'} [o.side='buy']                 firewall guards buys (the risky direction)
 * @param {string|PublicKey} [o.payer]           wallet the round-trip is simulated against
 * @param {bigint|number|string} o.quoteAmount   lamports the buy would spend
 * @param {import('@solana/web3.js').Connection} [o.connection]  injected RPC (else resolved)
 * @param {number} [o.priceImpactPct]            pre-computed buy impact, if the caller has it
 * @param {bigint|number|string|null} [o.payerBalanceLamports]  payer's SOL, when the caller
 *   already read it — lets the round-trip probe shrink to a size this wallet can simulate
 *   instead of misreading a poor wallet as a trapped coin
 * @returns {Promise<{ verdict:'allow'|'warn'|'block', score:number, checks:Array, simulated:boolean, reasons:string[] }>}
 */
export async function assessTradeSafety({
	network = 'mainnet',
	mint,
	side = 'buy',
	payer = null,
	quoteAmount,
	connection = null,
	priceImpactPct = null,
	payerBalanceLamports = null,
} = {}) {
	const net = network === 'devnet' ? 'devnet' : 'mainnet';

	let mintPk;
	try {
		mintPk = toPubkey(mint);
	} catch {
		return {
			verdict: 'block',
			score: 0,
			simulated: false,
			reasons: ['The coin address is not a valid Solana mint.'],
			checks: [result('input', 'fail', 'invalid_mint', {})],
		};
	}
	if (mintPk.toBase58() === WSOL_MINT) {
		return {
			verdict: 'block',
			score: 0,
			simulated: false,
			reasons: ['Wrapped SOL is not a tradable coin.'],
			checks: [result('input', 'fail', 'wsol_not_a_coin', {})],
		};
	}

	const lamports = (() => {
		try { return BigInt(quoteAmount ?? 0n); } catch { return 0n; }
	})();
	// Unparseable balance is treated as "unknown", which keeps the full-size probe
	// — never as zero, which would read every coin as unprovable.
	const balance = (() => {
		if (payerBalanceLamports == null) return null;
		try { return BigInt(payerBalanceLamports); } catch { return null; }
	})();

	const conn = connection || getConnection({ network: net });
	const cacheKey = `${mintPk.toBase58()}:${net}`;

	// Run the independent checks concurrently — the kernel adds a few hundred ms,
	// not seconds, even on the hot snipe path.
	const [authorityRes, venueRes, roundTrip, intelRes, sybilRes, creatorLinkageRes] = await Promise.all([
		checkMintAuthority(conn, mintPk, cacheKey),
		checkVenue(net, mintPk, cacheKey),
		lamports > 0n
			? checkRoundTrip({ network: net, mintPk, payer, quoteAmount: lamports, connection: conn, payerBalanceLamports: balance })
			: Promise.resolve({ res: result('round_trip', 'skip', 'no_quote_amount', {}), simulated: false }),
		checkIntel(mintPk.toBase58(), net),
		checkSybil(mintPk.toBase58(), net),
		checkCreatorLinkage(mintPk.toBase58(), net, conn),
	]);

	const impactRes = checkImpact(priceImpactPct);

	const checks = [authorityRes, venueRes, roundTrip.res, intelRes, impactRes, sybilRes, creatorLinkageRes];
	const { verdict, score, reasons } = compose(checks, roundTrip.simulated);

	return { verdict, score, simulated: roundTrip.simulated, reasons, checks };
}

/**
 * Persist a firewall verdict to the audit trail. Fire-and-forget safe: callers in
 * a hot path should `.catch()`. Returns the new row id (or null on failure).
 */
export async function recordFirewallDecision({
	mint, network = 'mainnet', side = 'buy', verdict, score, simulated = false,
	checks = [], reasons = [], source = null, agentId = null, userId = null,
	quoteLamports = null, enforced = true,
}) {
	try {
		const [row] = await sql`
			INSERT INTO firewall_decisions
				(mint, network, side, verdict, score, simulated, checks, reasons,
				 source, agent_id, user_id, quote_lamports, enforced)
			VALUES (
				${mint}, ${network}, ${side}, ${verdict}, ${Math.round(score) || 0}, ${!!simulated},
				${JSON.stringify(checks ?? [])}::jsonb, ${reasons ?? []},
				${source}, ${agentId}, ${userId},
				${quoteLamports != null ? String(quoteLamports) : null}, ${!!enforced}
			)
			RETURNING id
		`;
		return row?.id ?? null;
	} catch (err) {
		console.warn('[trade-firewall] decision record failed', err?.message);
		return null;
	}
}

/**
 * Map a `block` verdict onto the platform's structured guard-response shape so the
 * discretionary endpoints can return it with the same envelope as a spend-limit
 * breach. Status 422 (unprocessable) — the request was well-formed but the trade
 * is refused on safety grounds.
 */
export function firewallGuardResponse(assessment) {
	const reason = assessment.reasons?.[0] || 'This trade was blocked by the safety firewall.';
	return {
		status: 422,
		code: 'firewall_blocked',
		message: reason,
		detail: {
			verdict: assessment.verdict,
			score: assessment.score,
			simulated: assessment.simulated,
			reasons: assessment.reasons,
			checks: assessment.checks,
		},
	};
}

// ── tiny internal helpers ─────────────────────────────────────────────────────
function readCache(key) {
	const e = _mintCache.get(key);
	if (!e) return undefined;
	if (Date.now() - e.at > MINT_CACHE_TTL_MS) {
		_mintCache.delete(key);
		return undefined;
	}
	return e;
}
function writeCache(key, patch) {
	const prev = _mintCache.get(key);
	const fresh = prev && Date.now() - prev.at <= MINT_CACHE_TTL_MS ? prev : { at: Date.now() };
	_mintCache.set(key, { ...fresh, ...patch, at: fresh.at });
}
function bigOf(v) {
	try {
		if (v == null) return 0n;
		if (typeof v === 'bigint') return v;
		return BigInt(v.toString());
	} catch {
		return 0n;
	}
}
function numOr(v, d = null) {
	if (v == null || v === '') return d;
	const n = Number(v);
	return Number.isFinite(n) ? n : d;
}
function short(err) {
	return String(err?.message || err || 'error').slice(0, 160);
}