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.

29.7 KB
Raw Blame
// Cross-chain Subject Reputation — a pre-transaction trust primitive for ANY
// counterparty, not just three.ws agents.
//
// The question this answers is the one every autonomous agent has right before it
// pays, trades, or delegates: "should I trust the thing on the other side?" That
// counterparty ("subject") might be minted anywhere — a Solana wallet, an EVM
// wallet, a pump.fun coin, an ERC-8004 on-chain agent, or a three.ws agent. This
// module auto-detects which, reads the REAL on-chain evidence available for that
// identifier, and collapses it into one deterministic 0–100 trust score with the
// evidence and caveats attached, so the buyer can decide.
//
// Two layers, cleanly split so the score is unit-testable without any network:
//   • detectSubject() + scoreSignals()  — pure, deterministic, no I/O.
//   • loadSubjectReputation()           — the live reads (Solana RPC, EVM RPC,
//     the ERC-8004 reputation registry, DexScreener, and the three.ws on-chain
//     index) that gather the signals, each read soft so a dead source degrades to
//     a caveat instead of failing the whole call.
//
// Score rule (documented in docs/trust-primitives.md and mirrored here): six
// weighted trust dimensions, each normalized to 0..1, averaged over ONLY the
// dimensions readable for this subject, scaled to 0–100. No readable dimension →
// score:null, tier:'unknown' — never a fabricated number.

import { isUuid, isValidSolanaAddress, isValidEvmAddress } from '../validate.js';
import { CHAIN_BY_ID } from '../erc8004-chains.js';

const DEFAULT_EVM_CHAIN = 8453; // Base — where ERC-8004 sees the most agent activity.

export const SUBJECT_TYPES = [
	'threews_agent',
	'solana_wallet',
	'solana_mint',
	'evm_wallet',
	'erc8004_agent',
	'unknown',
];

// ── Detection (pure) ─────────────────────────────────────────────────────────

/**
 * Classify an arbitrary identifier into a subject type without any I/O. Solana
 * base58 strings can be either a wallet or a mint — the format alone can't tell,
 * so they resolve to the coarse family 'solana' here and loadSubjectReputation()
 * refines them to 'solana_wallet' / 'solana_mint' using the on-chain index.
 *
 * @param {string} raw                     the identifier to classify
 * @param {object} [opts]
 * @param {number|string} [opts.chain]     chain id for bare EVM/ERC-8004 subjects
 * @returns {{ subjectType:string, subject:string, chainId?:number, agentId?:string, reason?:string }}
 */
export function detectSubject(raw, opts = {}) {
	const id = String(raw ?? '').trim();
	if (!id) return { subjectType: 'unknown', subject: '', reason: 'empty identifier' };

	// three.ws agent_id (UUID) — the platform's own agents.
	if (isUuid(id)) return { subjectType: 'threews_agent', subject: id.toLowerCase() };

	// ERC-8004 agent id in CAIP-flavoured form: erc8004:<chainId>:<agentId> or
	// eip155:<chainId>:<numericAgentId>. The last segment is numeric (a token id),
	// which is what distinguishes it from a CAIP-10 account (…:0x-address).
	const prefixed = id.match(/^(?:erc8004|eip155):(\d+):(\d+)$/i);
	if (prefixed) {
		const chainId = Number(prefixed[1]);
		return { subjectType: 'erc8004_agent', subject: `erc8004:${chainId}:${prefixed[2]}`, chainId, agentId: prefixed[2] };
	}

	// EVM wallet / contract address.
	if (isValidEvmAddress(id)) {
		const chainId = normChain(opts.chain) ?? DEFAULT_EVM_CHAIN;
		return { subjectType: 'evm_wallet', subject: id.toLowerCase(), chainId };
	}

	// A bare integer is an ERC-8004 agent id whose chain wasn't spelled out — take
	// it from ?chain= (default Base). Capped at 18 digits so a 32+ char all-numeric
	// string still falls through to the Solana branch below.
	if (/^\d{1,18}$/.test(id)) {
		const chainId = normChain(opts.chain) ?? DEFAULT_EVM_CHAIN;
		return { subjectType: 'erc8004_agent', subject: `erc8004:${chainId}:${id}`, chainId, agentId: id };
	}

	// Solana base58 — wallet or mint, refined by the loader.
	if (isValidSolanaAddress(id)) return { subjectType: 'solana', subject: id };

	return { subjectType: 'unknown', subject: id, reason: 'unrecognized identifier format' };
}

function normChain(c) {
	if (c == null || c === '') return null;
	const n = Number(c);
	return Number.isInteger(n) && n > 0 ? n : null;
}

// ── Scoring (pure, deterministic) ────────────────────────────────────────────

// Six trust dimensions. Each has a weight (its share of the 100-point scale when
// present) and a saturation cap (the value at which its normalized sub-score
// reaches 1.0). A subject is scored only over the dimensions that could actually
// be read for it — see scoreSignals().
export const DIMENSIONS = [
	{ key: 'activity', weight: 25, cap: 200, label: 'on-chain activity (tx / payments)' },
	{ key: 'age', weight: 15, cap: 365, label: 'account age (days)' },
	{ key: 'counterparties', weight: 15, cap: 25, label: 'distinct counterparties' },
	{ key: 'holdings', weight: 10, cap: 1000, label: 'holdings (USD)' },
	{ key: 'reliability', weight: 15, label: 'settlement reliability' },
	{ key: 'attestations', weight: 20, cap: 10, label: 'signed attestations / feedback' },
];
const DIM = Object.fromEntries(DIMENSIONS.map((d) => [d.key, d]));

// A banned/denylisted subject is capped here regardless of any positive signal —
// a known-bad counterparty is never "medium trust" because it has volume.
const BANNED_SCORE_CAP = 10;

const clamp01 = (n) => Math.min(1, Math.max(0, Number(n) || 0));
const isNum = (n) => typeof n === 'number' && Number.isFinite(n);
const numOrNull = (n) => (isNum(n) ? n : null);
const round2 = (n) => Math.round(n * 100) / 100;

/**
 * Collapse a signal bundle into a deterministic 0–100 trust score. Pure: the same
 * signals always yield the same score, so it is safe to unit-test and to compare
 * across time. Dimensions whose signal is absent (null/undefined) are dropped from
 * BOTH the numerator and denominator, so a subject with only two readable
 * dimensions is scored fairly against its own evidence rather than penalised for
 * chains we couldn't read.
 *
 * @param {object} sig
 * @param {number|null} [sig.activity]          tx / confirmed-payment count
 * @param {number|null} [sig.ageDays]           account/first-activity age in days
 * @param {number|null} [sig.counterparties]    distinct payers / tippers / peers
 * @param {number|null} [sig.holdingsUsd]       USD value held on-chain
 * @param {number|null} [sig.failureRate]       0..1 settlement failure rate
 * @param {number|null} [sig.attestationCount]  signed attestations / feedback count
 * @param {number|null} [sig.attestationAvg]    ERC-8004 average feedback [-100,100]
 * @param {boolean} [sig.banned]                hard denylist hit
 * @returns {{ score:number|null, tier:string, dimensions:object, weight_considered:number }}
 */
export function scoreSignals(sig = {}) {
	const dimensions = {};
	let sumW = 0;
	let sumWN = 0;

	const add = (key, available, norm, extra = {}) => {
		const d = DIM[key];
		const n = available ? clamp01(norm) : 0;
		if (available) {
			sumW += d.weight;
			sumWN += d.weight * n;
		}
		dimensions[key] = {
			available,
			weight: d.weight,
			norm: available ? round2(n) : null,
			points: available ? Math.round(d.weight * n) : 0,
			...extra,
		};
	};

	add('activity', isNum(sig.activity), (sig.activity || 0) / DIM.activity.cap, { value: numOrNull(sig.activity) });
	add('age', isNum(sig.ageDays), (sig.ageDays || 0) / DIM.age.cap, { days: numOrNull(sig.ageDays) });
	add('counterparties', isNum(sig.counterparties), (sig.counterparties || 0) / DIM.counterparties.cap, {
		value: numOrNull(sig.counterparties),
	});
	add('holdings', isNum(sig.holdingsUsd), (sig.holdingsUsd || 0) / DIM.holdings.cap, { usd: numOrNull(sig.holdingsUsd) });
	add('reliability', isNum(sig.failureRate), 1 - (sig.failureRate || 0), { failure_rate: numOrNull(sig.failureRate) });

	// Attestations: count saturates at 10; ERC-8004 feedback average (when present)
	// scales the contribution down for net-negative feedback, never up.
	const attAvail = isNum(sig.attestationCount);
	const qual = isNum(sig.attestationAvg)
		? sig.attestationAvg >= 0
			? 1
			: Math.max(0, (100 + sig.attestationAvg) / 100)
		: 1;
	add('attestations', attAvail, (Math.min(sig.attestationCount || 0, DIM.attestations.cap) / DIM.attestations.cap) * qual, {
		count: numOrNull(sig.attestationCount),
		avg_feedback: numOrNull(sig.attestationAvg),
	});

	let score = sumW > 0 ? Math.round((100 * sumWN) / sumW) : null;
	if (score != null && sig.banned) score = Math.min(score, BANNED_SCORE_CAP);

	return { score, tier: tierForScore(score), dimensions, weight_considered: sumW };
}

/**
 * Map a score to a coarse trust tier. Documented thresholds so callers can gate
 * on the tier without re-deriving the bands.
 *   null → unknown · <30 → low · 30–59 → medium · 60–84 → high · ≥85 → elite
 */
export function tierForScore(score) {
	if (score == null) return 'unknown';
	if (score < 30) return 'low';
	if (score < 60) return 'medium';
	if (score < 85) return 'high';
	return 'elite';
}

// ── Live subject loaders ─────────────────────────────────────────────────────

// Every dimension a given subject type can never supply is turned into a caveat
// so the buyer knows the score reflects partial evidence, not a full audit.
const DIM_LABEL = Object.fromEntries(DIMENSIONS.map((d) => [d.key, d.label]));
function missingCaveats(sig, keys) {
	return keys
		.filter((k) => {
			if (k === 'reliability') return !isNum(sig.failureRate);
			if (k === 'attestations') return !isNum(sig.attestationCount);
			const map = { activity: 'activity', age: 'ageDays', counterparties: 'counterparties', holdings: 'holdingsUsd' };
			return !isNum(sig[map[k]]);
		})
		.map((k) => `${DIM_LABEL[k]} not readable for this subject`);
}

function finalize({ subject, subjectType, chainId, sig, evidence = [], caveats = [], raw = {}, ts }) {
	const { score, tier, dimensions, weight_considered } = scoreSignals(sig);
	const signals = { dimensions, weight_considered, ...(chainId ? { chain: chainId } : {}), ...raw };
	if (sig.banned) caveats = ['subject is on the three.ws denylist — score capped', ...caveats];
	return { subject, subjectType, score, tier, signals, evidence, caveats, ts };
}

function unknownResult(subject, reason, ts, subjectType = 'unknown') {
	return {
		subject,
		subjectType,
		score: null,
		tier: 'unknown',
		signals: { dimensions: {}, weight_considered: 0 },
		evidence: [],
		caveats: [reason || 'subject could not be identified or scanned'],
		ts,
	};
}

// soft(): resolve a read to a fallback on any error, recording the failure as a
// caveat so a degraded source is visible in the result rather than silent.
async function soft(promise, fallback, caveats, note) {
	try {
		return await promise;
	} catch (err) {
		if (caveats && note) caveats.push(`${note}: ${err?.message || 'read failed'}`);
		return fallback;
	}
}

/**
 * Reputation for ANY subject. Auto-detects the type, reads the real evidence, and
 * returns a uniform { subject, subjectType, score, tier, signals, evidence,
 * caveats, ts } object. Never throws for an unknown/unscannable subject and never
 * fabricates a score — those return score:null, tier:'unknown'.
 *
 * @param {string} identifier
 * @param {object} [opts]  { chain } for bare EVM / ERC-8004 subjects
 */
export async function loadSubjectReputation(identifier, opts = {}) {
	const det = detectSubject(identifier, opts);
	const ts = new Date().toISOString();
	try {
		switch (det.subjectType) {
			case 'threews_agent':
				return await scoreThreewsAgent(det, ts);
			case 'erc8004_agent':
				return await scoreErc8004Agent(det, ts);
			case 'evm_wallet':
				return await scoreEvmWallet(det, ts);
			case 'solana':
				return await scoreSolanaSubject(det, ts);
			default:
				return unknownResult(det.subject, det.reason, ts);
		}
	} catch (err) {
		// Absolute backstop — a subject type is known but every read blew up. Degrade
		// to unknown with the reason rather than 500. Solana stays 'solana_wallet'
		// (the safe assumption) so the type field is still informative.
		const fallbackType = det.subjectType === 'solana' ? 'solana_wallet' : det.subjectType;
		return unknownResult(det.subject, `scan failed: ${err?.message || 'error'}`, ts, fallbackType);
	}
}

/** Score a batch of arbitrary subjects concurrently. Resilient per-item. */
export async function scoreSubjectBatch(identifiers = [], { concurrency = 6, chain } = {}) {
	const ids = identifiers.map((s) => String(s ?? '').trim()).filter(Boolean);
	const out = [];
	for (let i = 0; i < ids.length; i += concurrency) {
		const chunk = ids.slice(i, i + concurrency);
		const settled = await Promise.all(
			chunk.map((id) =>
				loadSubjectReputation(id, { chain }).catch((err) =>
					unknownResult(id, `scan failed: ${err?.message || 'error'}`, new Date().toISOString()),
				),
			),
		);
		out.push(...settled);
	}
	return out;
}

// ── three.ws agent ───────────────────────────────────────────────────────────

// Map a three.ws on-chain reputation snapshot (from the pump-agent index) into the
// shared signal vocabulary. Shared by the agent path and the Solana-wallet /
// solana-mint paths when they resolve to a three.ws agent.
function sigFromAgentRep(rep) {
	const p = rep.payments || {};
	const a = rep.attestations || {};
	const settled = (p.confirmed_count || 0) + (p.failed_count || 0);
	return {
		activity: p.confirmed_count || 0,
		counterparties: p.distinct_payers || 0,
		failureRate: settled > 0 ? Number(p.failure_rate) || 0 : null,
		attestationCount: (a.feedback_count || 0) + (a.validation_count || 0),
	};
}

async function scoreThreewsAgent(det, ts) {
	const { loadAgentReputation } = await import('./solana-bouncer.js');
	const { sql } = await import('../db.js');
	let rep;
	try {
		rep = await loadAgentReputation(det.subject);
	} catch (err) {
		if (err?.status === 404) return unknownResult(det.subject, 'no three.ws agent with this id', ts, 'threews_agent');
		throw err;
	}
	const caveats = [];
	// Age from the identity row (one light indexed read).
	const [row] = await soft(
		sql`select created_at from agent_identities where id = ${det.subject} limit 1`,
		[null],
		caveats,
		'agent age read',
	);
	const ageDays = row?.created_at ? (Date.now() - new Date(row.created_at).getTime()) / 86_400_000 : null;

	const sig = { ...sigFromAgentRep(rep), ageDays };
	caveats.push(...missingCaveats(sig, ['holdings']));

	const evidence = [{ kind: 'threews_agent', ref: `/agents/${det.subject}` }];
	if (rep.wallet_address) evidence.push({ kind: 'solana_account', ref: `https://solscan.io/account/${rep.wallet_address}` });
	const firstMint = rep.mints?.[0]?.mint;
	if (firstMint) evidence.push({ kind: 'launched_coin', ref: `https://solscan.io/token/${firstMint}` });

	return finalize({
		subject: det.subject,
		subjectType: 'threews_agent',
		sig,
		evidence,
		caveats,
		raw: {
			name: rep.name || null,
			wallet_address: rep.wallet_address || null,
			deployed_mints: rep.deployed_mints || 0,
			payments: rep.payments,
			distributions: rep.distributions,
			buybacks: rep.buybacks,
			attestations: rep.attestations,
		},
		ts,
	});
}

// ── ERC-8004 agent ───────────────────────────────────────────────────────────

async function readErc8004(chainId, agentId) {
	const { REGISTRY_DEPLOYMENTS, IDENTITY_REGISTRY_ABI } = await import('../../../src/erc8004/abi.js');
	const { readAgentReputation } = await import('../../../src/erc8004/reputation-read.js');
	const deployment = REGISTRY_DEPLOYMENTS[chainId];
	if (!deployment) throw Object.assign(new Error(`ERC-8004 not deployed on chain ${chainId}`), { code: 'no_deployment' });
	const { Contract } = await import('ethers');
	const { evmFallbackProvider } = await import('../evm/rpc.js');
	const provider = await evmFallbackProvider(chainId);

	const out = { average: null, count: 0, wallet: null };
	if (deployment.reputationRegistry) {
		const rep = await readAgentReputation({ address: deployment.reputationRegistry, runner: provider, agentId });
		out.count = rep.count;
		out.average = rep.count === 0 ? null : rep.average;
		out.dialect = rep.dialect;
	}
	if (deployment.identityRegistry) {
		try {
			const idreg = new Contract(deployment.identityRegistry, IDENTITY_REGISTRY_ABI, provider);
			const w = await idreg.getAgentWallet(BigInt(agentId));
			if (w && /^0x[0-9a-fA-F]{40}$/.test(w) && !/^0x0{40}$/.test(w)) out.wallet = w.toLowerCase();
		} catch {
			/* getAgentWallet is optional — some registries don't bind a wallet */
		}
	}
	return out;
}

async function scoreErc8004Agent(det, ts) {
	const caveats = [];
	const reg = await soft(readErc8004(det.chainId, det.agentId), null, caveats, 'erc8004 registry read');
	if (!reg) {
		return {
			...unknownResult(det.subject, `ERC-8004 registry unreadable on chain ${det.chainId}`, ts, 'erc8004_agent'),
			signals: { dimensions: {}, weight_considered: 0, chain: det.chainId },
		};
	}

	const sig = {
		attestationCount: reg.count,
		attestationAvg: reg.average,
	};

	// If the identity registry binds a wallet, fold that wallet's raw EVM activity
	// + holdings in — the agent's own on-chain footprint, not just its reviews.
	const evidence = [{ kind: 'erc8004_reputation', ref: `eip155:${det.chainId}:agent/${det.agentId}` }];
	let walletReads = null;
	if (reg.wallet) {
		walletReads = await soft(readEvmWallet(det.chainId, reg.wallet), null, caveats, 'erc8004 agent wallet read');
		if (walletReads) {
			sig.activity = walletReads.txCount;
			sig.holdingsUsd = walletReads.holdingsUsd;
		}
		const explorer = CHAIN_BY_ID[det.chainId]?.explorer;
		if (explorer) evidence.push({ kind: 'evm_account', ref: `${explorer}/address/${reg.wallet}` });
	} else {
		caveats.push('no wallet bound to this ERC-8004 agent — activity / holdings not scored');
	}

	caveats.push(...missingCaveats(sig, ['age', 'counterparties', 'reliability']));
	if (reg.count === 0) caveats.push('no ERC-8004 feedback on record yet');

	return finalize({
		subject: det.subject,
		subjectType: 'erc8004_agent',
		chainId: det.chainId,
		sig,
		evidence,
		caveats,
		raw: {
			agent_id: det.agentId,
			erc8004: { feedback_count: reg.count, avg_feedback: reg.average, wallet: reg.wallet },
			...(walletReads ? { native_balance: walletReads.native, tx_count: walletReads.txCount } : {}),
		},
		ts,
	});
}

// ── EVM wallet ───────────────────────────────────────────────────────────────

// Cheap, keyless EVM reads: outbound tx count (nonce) for activity and native
// balance priced to USD for holdings. Age + counterparties need an indexer we
// don't require, so they stay unread (→ caveats).
async function readEvmWallet(chainId, address) {
	const { evmFallbackProvider } = await import('../evm/rpc.js');
	const provider = await evmFallbackProvider(chainId);
	const [nonce, balanceWei] = await Promise.all([
		provider.getTransactionCount(address),
		provider.getBalance(address),
	]);
	const native = Number(balanceWei) / 1e18;
	const price = await evmNativePriceUsd(chainId);
	return { txCount: Number(nonce), native, holdingsUsd: price != null ? native * price : null };
}

// Native-asset USD price by chain, keyless, through the shared coin-price
// failover (CoinGecko → DefiLlama → exchange tickers). Best-effort: a miss just
// leaves holdings unpriced (dimension unavailable), never an error.
// The chain→coin-id table lives in the EVM chain registry, which the portfolio
// asset lane reads too; a second copy here drifted the moment one of them
// gained a chain.
async function evmNativePriceUsd(chainId) {
	const { evmNativeCoingeckoId } = await import('../evm/chain-market.js');
	const cgId = evmNativeCoingeckoId(chainId);
	if (!cgId) return null;
	const { fetchCoinPriceUsdOrNull } = await import('../market-fallbacks.js');
	return await fetchCoinPriceUsdOrNull(cgId);
}

async function scoreEvmWallet(det, ts) {
	const caveats = [];
	const reads = await soft(readEvmWallet(det.chainId, det.subject), null, caveats, 'evm wallet read');
	if (!reads) {
		return {
			...unknownResult(det.subject, `EVM chain ${det.chainId} unreadable for this wallet`, ts, 'evm_wallet'),
			signals: { dimensions: {}, weight_considered: 0, chain: det.chainId },
		};
	}
	const sig = { activity: reads.txCount, holdingsUsd: reads.holdingsUsd };
	caveats.push(...missingCaveats(sig, ['age', 'counterparties', 'reliability', 'attestations']));

	const explorer = CHAIN_BY_ID[det.chainId]?.explorer;
	const evidence = explorer ? [{ kind: 'evm_account', ref: `${explorer}/address/${det.subject}` }] : [];

	return finalize({
		subject: det.subject,
		subjectType: 'evm_wallet',
		chainId: det.chainId,
		sig,
		evidence,
		caveats,
		raw: { tx_count: reads.txCount, native_balance: reads.native, native_symbol: nativeSymbol(det.chainId) },
		ts,
	});
}

function nativeSymbol(chainId) {
	if (chainId === 56) return 'BNB';
	if (chainId === 137) return 'MATIC';
	if (chainId === 43114) return 'AVAX';
	if (chainId === 250) return 'FTM';
	if (chainId === 42220) return 'CELO';
	if (chainId === 1284) return 'GLMR';
	if (chainId === 5000) return 'MNT';
	return 'ETH';
}

// ── Solana subject (wallet or mint) ──────────────────────────────────────────

async function scoreSolanaSubject(det, ts) {
	const { sql } = await import('../db.js');

	// (1) A pump.fun mint three.ws indexed → score its owning agent's behavior.
	const mintRows = await sql`
		select agent_id, symbol, network from pump_agent_mints where mint = ${det.subject} limit 1
	`.catch(() => []);
	if (mintRows[0]?.agent_id) return scoreThreewsMint(det, mintRows[0], ts);

	// (2) A known three.ws agent wallet → score that agent (folding wallet reads).
	const agentRows = await sql`
		select id from agent_identities
		 where (wallet_address = ${det.subject} or meta->>'solana_address' = ${det.subject})
		   and deleted_at is null
		 limit 1
	`.catch(() => []);
	const knownAgentId = agentRows[0]?.id || null;

	// (3) Not ours — is it a live token? DexScreener resolves mints; if it returns a
	//     Solana pair, treat the subject as an external mint scored from its market.
	if (!knownAgentId) {
		const market = await dexscreenerToken(det.subject).catch(() => null);
		if (market) return scoreExternalMint(det, market, ts);
	}

	// (4) Fall through: score it as a raw Solana wallet (folding agent signals if known).
	return scoreSolanaWallet(det, { knownAgentId }, ts);
}

async function scoreThreewsMint(det, mintRow, ts) {
	const { loadAgentReputation } = await import('./solana-bouncer.js');
	const caveats = [];
	const rep = await soft(loadAgentReputation(mintRow.agent_id), null, caveats, 'agent reputation read');
	if (!rep) return unknownResult(det.subject, 'mint owner reputation unreadable', ts, 'solana_mint');

	const market = await dexscreenerToken(det.subject).catch(() => null);
	const sig = { ...sigFromAgentRep(rep) };
	if (market) {
		sig.ageDays = market.ageDays;
		sig.holdingsUsd = market.liquidityUsd; // pool liquidity = skin-in-the-game proxy for a coin
	}
	caveats.push(...missingCaveats(sig, ['age', 'holdings']));

	const evidence = [
		{ kind: 'solana_token', ref: `https://solscan.io/token/${det.subject}` },
		{ kind: 'threews_agent', ref: `/agents/${mintRow.agent_id}` },
	];
	if (market) evidence.push({ kind: 'dexscreener', ref: `https://dexscreener.com/solana/${det.subject}` });

	return finalize({
		subject: det.subject,
		subjectType: 'solana_mint',
		sig,
		evidence,
		caveats,
		raw: {
			mint: det.subject,
			symbol: mintRow.symbol || rep.mints?.find((m) => m.mint === det.subject)?.symbol || null,
			owner_agent_id: mintRow.agent_id,
			owner_name: rep.name || null,
			payments: rep.payments,
			attestations: rep.attestations,
			...(market ? { market: { liquidity_usd: market.liquidityUsd, volume_24h_usd: market.volumeUsd, txns_24h: market.txns24h } } : {}),
		},
		ts,
	});
}

async function scoreExternalMint(det, market, ts) {
	const caveats = [
		'external mint — scored from live market signals (liquidity, activity, age), not agent behavior',
	];
	const sig = {
		activity: market.txns24h,
		ageDays: market.ageDays,
		holdingsUsd: market.liquidityUsd,
	};
	caveats.push(...missingCaveats(sig, ['counterparties', 'reliability', 'attestations']));

	return finalize({
		subject: det.subject,
		subjectType: 'solana_mint',
		sig,
		evidence: [
			{ kind: 'solana_token', ref: `https://solscan.io/token/${det.subject}` },
			{ kind: 'dexscreener', ref: `https://dexscreener.com/solana/${det.subject}` },
		],
		caveats,
		raw: {
			mint: det.subject,
			symbol: market.symbol || null,
			market: {
				price_usd: market.priceUsd,
				liquidity_usd: market.liquidityUsd,
				volume_24h_usd: market.volumeUsd,
				txns_24h: market.txns24h,
				pair_created_at: market.pairCreatedAt,
			},
		},
		ts,
	});
}

async function scoreSolanaWallet(det, { knownAgentId }, ts) {
	const caveats = [];
	const { solanaConnection } = await import('../solana/connection.js');
	const { PublicKey } = await import('@solana/web3.js');
	const { findBan, normalizeWallet } = await import('../club/cover-pass.js');

	let pk;
	try {
		pk = new PublicKey(det.subject);
	} catch {
		return unknownResult(det.subject, 'not a valid Solana address', ts, 'solana_wallet');
	}
	const conn = solanaConnection({ network: 'mainnet' });

	// Bounded signature scan: count (capped at 1000/page) → activity. Age is only
	// derivable when the scan reached the START of history (page NOT saturated) —
	// for a hyperactive wallet that fills the 1000-tx page, the oldest signature in
	// the page is merely the oldest *recent* tx, not the account's age, so we must
	// NOT treat it as age (doing so wrongly tanks an ancient, busy wallet's score).
	const sigs = await soft(conn.getSignaturesForAddress(pk, { limit: 1000 }), null, caveats, 'solana signatures read');
	let activity = null;
	let ageDays = null;
	if (Array.isArray(sigs)) {
		activity = sigs.length;
		if (sigs.length >= 1000) {
			caveats.push(
				'activity is a lower bound and account age is not derivable — signature history exceeds the 1000-tx scan window',
			);
		} else {
			const oldest = sigs[sigs.length - 1]?.blockTime;
			if (oldest) ageDays = Math.max(0, (Date.now() - oldest * 1000) / 86_400_000);
		}
	}

	// Native SOL balance priced to USD → holdings.
	const lamports = await soft(conn.getBalance(pk), null, caveats, 'solana balance read');
	let holdingsUsd = null;
	let solAmount = null;
	if (isNum(lamports)) {
		solAmount = lamports / 1e9;
		const price = await soft(solPriceUsd(), null, caveats, 'SOL price read');
		if (isNum(price)) holdingsUsd = solAmount * price;
	}

	// Denylist → hard risk override.
	const ban = await soft(findBan(normalizeWallet(det.subject)), null, caveats, 'denylist read');

	const sig = { activity, ageDays, holdingsUsd, banned: Boolean(ban) };

	// Fold the agent's settled-payment behavior in when this wallet is a known
	// three.ws agent wallet — richer, third-party-attested signals.
	let agentRaw = null;
	if (knownAgentId) {
		const { loadAgentReputation } = await import('./solana-bouncer.js');
		const rep = await soft(loadAgentReputation(knownAgentId), null, caveats, 'agent reputation read');
		if (rep) {
			const arep = sigFromAgentRep(rep);
			sig.counterparties = arep.counterparties;
			sig.failureRate = arep.failureRate;
			sig.attestationCount = arep.attestationCount;
			if (!isNum(sig.activity)) sig.activity = arep.activity;
			agentRaw = { agent_id: knownAgentId, name: rep.name || null, payments: rep.payments, attestations: rep.attestations };
		}
	}
	caveats.push(...missingCaveats(sig, knownAgentId ? [] : ['counterparties', 'reliability', 'attestations']));

	const evidence = [{ kind: 'solana_account', ref: `https://solscan.io/account/${det.subject}` }];
	if (knownAgentId) evidence.push({ kind: 'threews_agent', ref: `/agents/${knownAgentId}` });

	return finalize({
		subject: det.subject,
		subjectType: 'solana_wallet',
		sig,
		evidence,
		caveats,
		raw: {
			sol_balance: solAmount,
			signature_count: activity,
			denylisted: Boolean(ban),
			...(agentRaw ? { agent: agentRaw } : {}),
		},
		ts,
	});
}

// ── shared upstream reads ────────────────────────────────────────────────────

async function solPriceUsd() {
	const { solPriceUsd: solSpotUsd } = await import('../sol-price.js');
	const p = await solSpotUsd();
	return p > 0 ? p : null;
}

// DexScreener token lookup → normalized market signals, or null if it's not a
// tradeable Solana token (i.e. probably a wallet, not a mint). Keyless, public.
async function dexscreenerToken(mint) {
	const r = await fetch(`https://api.dexscreener.com/latest/dex/tokens/${mint}`, {
		headers: { accept: 'application/json' },
		signal: AbortSignal.timeout(6000),
	});
	if (!r.ok) return null;
	const data = await r.json();
	const pairs = (data.pairs || []).filter((p) => p.chainId === 'solana' && p.baseToken?.address === mint);
	if (!pairs.length) return null;
	pairs.sort((a, b) => (b.liquidity?.usd ?? 0) - (a.liquidity?.usd ?? 0));
	const p = pairs[0];
	const txns = (p.txns?.h24?.buys ?? 0) + (p.txns?.h24?.sells ?? 0);
	const created = p.pairCreatedAt ? Number(p.pairCreatedAt) : null;
	return {
		symbol: p.baseToken?.symbol || null,
		priceUsd: parseFloat(p.priceUsd) || null,
		liquidityUsd: p.liquidity?.usd ?? null,
		volumeUsd: p.volume?.h24 ?? null,
		txns24h: txns,
		pairCreatedAt: created ? new Date(created).toISOString() : null,
		ageDays: created ? Math.max(0, (Date.now() - created) / 86_400_000) : null,
	};
}