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.

feat(trade-firewall): flag a coin's creator buying through an early-buyer alt

nirholas0044f262f1b5
diff --git a/api/_lib/trade-firewall.js b/api/_lib/trade-firewall.js
index 76328dc6f..60390b9aa 100644
--- a/api/_lib/trade-firewall.js
+++ b/api/_lib/trade-firewall.js
@@ -25,6 +25,10 @@ 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
@@ -49,6 +53,7 @@ const PENALTY = Object.freeze({
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
@@ -482,6 +487,79 @@ async function checkSybil(mint, network) {
}
}
+// ── 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;
@@ -543,6 +621,10 @@ function compose(checks, simulated) {
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':
@@ -652,7 +734,7 @@ export async function assessTradeSafety({
// 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] = await Promise.all([
+ const [authorityRes, venueRes, roundTrip, intelRes, sybilRes, creatorLinkageRes] = await Promise.all([
checkMintAuthority(conn, mintPk, cacheKey),
checkVenue(net, mintPk, cacheKey),
lamports > 0n
@@ -660,11 +742,12 @@ export async function assessTradeSafety({
: 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];
+ 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 };
diff --git a/tests/trade-firewall-creator-linkage.test.js b/tests/trade-firewall-creator-linkage.test.js
new file mode 100644
index 000000000..c9f103aa0
--- /dev/null
+++ b/tests/trade-firewall-creator-linkage.test.js
@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+
+import { evaluateCreatorLinkagePairs } from '../api/_lib/trade-firewall.js';
+
+// Synthetic addresses only, no real wallets. These are plain strings, not
+// signed keys: the function under test is pure band/score arithmetic over an
+// `analyzeLinkage()`-shaped `pairs` array, it never touches the network.
+const CREATOR = 'Creator11111111111111111111111111111111111';
+const BUYER_LINKED = 'BuyerLinked111111111111111111111111111111';
+const BUYER_CLEAN = 'BuyerClean1111111111111111111111111111111';
+const BUYER_WEAK = 'BuyerWeak11111111111111111111111111111111';
+
+describe('evaluateCreatorLinkagePairs (early buyers linked to the creator)', () => {
+ it('warns when an early buyer shares control with the creator at the strong band or above', () => {
+ const pairs = [
+ { a: CREATOR, b: BUYER_LINKED, score: 90, band: 'confirmed', topSignal: 'solana-fee-payer', evidence: [] },
+ { a: CREATOR, b: BUYER_CLEAN, score: 0, band: 'none', topSignal: null, evidence: [] },
+ ];
+ const res = evaluateCreatorLinkagePairs(CREATOR, pairs);
+ expect(res.status).toBe('warn');
+ expect(res.reason).toBe('early_buyer_linked_to_creator');
+ expect(res.detail.linked_wallets).toEqual([BUYER_LINKED]);
+ expect(res.detail.top_match.score).toBe(90);
+ });
+
+ it('passes clean when no pair involving the creator reaches the warn band', () => {
+ const pairs = [
+ { a: CREATOR, b: BUYER_CLEAN, score: 5, band: 'none', topSignal: null, evidence: [] },
+ { a: CREATOR, b: BUYER_WEAK, score: 30, band: 'weak', topSignal: 'direct-transfer', evidence: [] },
+ // A strong link between two buyers that does NOT involve the creator is irrelevant here.
+ { a: BUYER_CLEAN, b: BUYER_WEAK, score: 95, band: 'confirmed', topSignal: 'solana-fee-payer', evidence: [] },
+ ];
+ const res = evaluateCreatorLinkagePairs(CREATOR, pairs);
+ expect(res.status).toBe('pass');
+ expect(res.reason).toBe('creator_linkage_clean');
+ });
+
+ it('picks the highest-scoring linked buyer as the top match when several are linked', () => {
+ const pairs = [
+ { a: CREATOR, b: BUYER_LINKED, score: 70, band: 'strong', topSignal: 'peer-first-funding', evidence: [] },
+ { a: BUYER_WEAK, b: CREATOR, score: 95, band: 'confirmed', topSignal: 'solana-fee-payer', evidence: [] },
+ ];
+ const res = evaluateCreatorLinkagePairs(CREATOR, pairs);
+ expect(res.status).toBe('warn');
+ expect(res.detail.linked_wallets).toEqual(expect.arrayContaining([BUYER_LINKED, BUYER_WEAK]));
+ expect(res.detail.top_match.wallet).toBe(BUYER_WEAK);
+ });
+
+ it('honors a custom band threshold', () => {
+ const pairs = [{ a: CREATOR, b: BUYER_WEAK, score: 30, band: 'weak', topSignal: 'direct-transfer', evidence: [] }];
+ expect(evaluateCreatorLinkagePairs(CREATOR, pairs).status).toBe('pass');
+ expect(evaluateCreatorLinkagePairs(CREATOR, pairs, { band: 'weak' }).status).toBe('warn');
+ });
+
+ it('treats an empty or missing pairs array as clean, never throws', () => {
+ expect(evaluateCreatorLinkagePairs(CREATOR, []).status).toBe('pass');
+ expect(evaluateCreatorLinkagePairs(CREATOR, undefined).status).toBe('pass');
+ });
+});