dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/index.js

@@ -0,0 +1,208 @@
+// @dexterm/data public surface. Lane B (D-02) owns this package; the shared model
+// types were agreed on day 1 (D-01) and live in ./model.ts.
+export * from "./model.js";
+export * from "./clock.js";
+export * from "./limiter.js";
+export * from "./health.js";
+export * from "./cache.js";
+export * from "./http.js";
+export * from "./fixtures.js";
+export * from "./store.js";
+export * from "./sources/dexscreener.js";
+export * from "./sources/jupiter.js";
+export * from "./sources/jupiter-swap.js";
+export * from "./sources/geckoterminal.js";
+export * from "./sources/solana-rpc.js";
+export * from "./sources/rugcheck.js";
+export * from "./sources/goplus.js";
+export * from "./sources/pumpportal.js";
+export * from "./sources/solana-ws.js";
+export * from "./sources/pump-curve.js";
+export * from "./sources/pda.js";
+export * from "./fast-lane.js";
+export * from "./candles.js";
+export * from "./detail.js";
+export * from "./rpc-config.js";
+export * from "./rpc-pool.js";
+export * from "./credits.js";
+export * from "./budget.js";
+export * from "./watchlist.js";
+export * from "./paper.js";
+export * from "./trade/caps.js";
+export * from "./trade/bridge.js";
+export * from "./trade/swap-build.js";
+export * from "./trade/rpc-exec.js";
+export * from "./trade/executor.js";
+export * from "./trade/link-store.js";
+export * from "./trade/tx-decode.js";
+export * from "./trade/sol-usd.js";
+export * from "./trade/kill-switch.js";
+export * from "./trade/token-delta.js";
+export * from "./trade/signer/protocol.js";
+export * from "./trade/signer/service.js";
+export * from "./trade/signer/host.js";
+export * from "./trade/signer/client.js";
+export * from "./trade/signer/probe-builder.js";
+export * from "./trade/signer/fast-wallet.js";
+export * from "./trade/signer/sol-usd-feed.js";
+export { parseSignerArgs, buildSignerService } from "./trade/signer/main.js";
+export * from "./larp/links.js";
+export * from "./larp/safe-fetch.js";
+export * from "./larp/evidence.js";
+export * from "./analyst-actions.js";
+export * from "./intel/rules.js";
+export * from "./intel/holder-class.js";
+export * from "./intel/helius-history.js";
+export * from "./intel/scan.js";
+export * from "./images/index.js";
+// task-1330 (I-03): social / news / trending layer. `Provenance` and `Credibility`-style names are
+// namespaced under `Social*` where they would collide with the core model.
+export { POST_DISPLAY_MAX, POST_STORED_MAX, BIO_MAX, } from "./social/model.js";
+export * from "./social/firewall.js";
+export * from "./social/dedupe.js";
+export * from "./social/rank.js";
+export * from "./social/kol.js";
+export * from "./social/venues.js";
+export * from "./social/rss.js";
+export * from "./social/chain.js";
+export * from "./social/summary.js";
+export * from "./social/feed.js";
+// task-1357 (I-02): Login with X (OAuth2 PKCE on a loopback callback) + the user-authorized X read adapter.
+export * from "./x/index.js";
+import { Cache } from "./cache.js";
+import { systemClock } from "./clock.js";
+import { HealthRegistry } from "./health.js";
+import { HttpClient, liveTransport } from "./http.js";
+import { DEFAULT_BUCKETS, RateLimiter, SOURCE_BUCKET } from "./limiter.js";
+import { DexScreener } from "./sources/dexscreener.js";
+import { Jupiter } from "./sources/jupiter.js";
+import { JupiterSwap } from "./sources/jupiter-swap.js";
+import { GeckoTerminal } from "./sources/geckoterminal.js";
+import { RugCheck } from "./sources/rugcheck.js";
+import { GoPlus } from "./sources/goplus.js";
+import { SOLANA_PUBLIC_RPC, SolanaRpc } from "./sources/solana-rpc.js";
+import { CandleStore } from "./candles.js";
+import { TokenDetail } from "./detail.js";
+import { Store } from "./store.js";
+import { HELIUS_RPC_HOST, PUBLIC_RPC_POOL } from "./rpc-config.js";
+import { RpcPool, bucketFor } from "./rpc-pool.js";
+import { CreditMeter } from "./credits.js";
+import { BudgetMeter } from "./budget.js";
+/** `helius` for a Helius endpoint (keyed source S9), else the public/custom RPC source S6. */
+export function rpcSourceFor(url) {
+    if (!url)
+        return 'solana-rpc';
+    try {
+        return new URL(url).hostname === HELIUS_RPC_HOST ? 'helius' : 'solana-rpc';
+    }
+    catch {
+        return 'solana-rpc';
+    }
+}
+export function createDataLayer(opts = {}) {
+    const clock = opts.clock ?? systemClock;
+    const limiter = new RateLimiter(opts.buckets ?? DEFAULT_BUCKETS, clock, opts.safety);
+    const rpcSource = rpcSourceFor(opts.rpcUrl);
+    const keys = { ...opts.keys };
+    if (rpcSource === 'helius')
+        keys.helius = true;
+    const health = new HealthRegistry({
+        clock,
+        keys,
+        disabled: opts.disabled,
+        usage: (source) => {
+            const bucket = SOURCE_BUCKET[source];
+            if (!bucket)
+                return undefined;
+            const s = limiter.bucket(bucket).stats();
+            return { rpmUsed: s.rpmUsed, rpmLimit: s.rpmLimit };
+        },
+    });
+    const cache = new Cache({ path: opts.dbPath, clock });
+    // Helius credit meter: every request to the keyed endpoint is charged; at 90 % of the day budget or the
+    // per-run cap the source is switched off (health `disabled`) so holders fall back to the public RPC.
+    const credits = rpcSource === 'helius'
+        ? new CreditMeter({
+            ...opts.credits,
+            clock,
+            cache,
+            onLevel: (level) => health.setDisabled('helius', level === 'degraded'),
+        })
+        : null;
+    if (credits && credits.level() === 'degraded')
+        health.setDisabled('helius', true);
+    // Per-source request budget meter: counts every request (persisted per UTC day) so usage is visible.
+    const budget = new BudgetMeter({ ...opts.budget, clock, cache });
+    const onRequest = (req, meta, o) => {
+        budget.charge(meta.source);
+        if (credits && meta.source === 'helius') {
+            let method = null;
+            try {
+                method = req.body ? (JSON.parse(req.body).method ?? null) : null;
+            }
+            catch {
+                method = null;
+            }
+            credits.charge(CreditMeter.costOf(method));
+        }
+        opts.onRequest?.(req, meta, o);
+    };
+    // Shutdown signal (task-1319): close() aborts it so any in-flight live fetch rejects immediately and
+    // the event loop is not held for the per-request timeout. A caller that builds its own transport must
+    // pass its controller as opts.shutdownController and build that transport with its signal, so close()
+    // reaches the real app's transport (createLiveFeed does exactly this); otherwise we own the controller
+    // and wire it into the default live transport.
+    const shutdown = opts.shutdownController ?? new AbortController();
+    const http = new HttpClient({ transport: opts.transport ?? liveTransport({ shutdownSignal: shutdown.signal }), limiter, health, clock, onRequest, ...(opts.rateLimitPauseMs !== undefined ? { rateLimitPauseMs: opts.rateLimitPauseMs } : {}) });
+    const dexscreener = new DexScreener(http);
+    const jupiter = new Jupiter(http);
+    const jupiterSwap = new JupiterSwap(http);
+    const gecko = new GeckoTerminal(http);
+    const rpc = new SolanaRpc(http, { url: opts.rpcUrl, source: rpcSource });
+    const fallbackUrl = opts.rpcFallbackUrl === undefined ? (rpc.url === SOLANA_PUBLIC_RPC ? null : SOLANA_PUBLIC_RPC) : opts.rpcFallbackUrl;
+    const rpcFallback = fallbackUrl && fallbackUrl !== rpc.url ? new SolanaRpc(http, { url: fallbackUrl, source: 'solana-rpc' }) : null;
+    // The pool the detail layer reads through. By default it mirrors the old primary+fallback pair exactly
+    // (so behaviour is unchanged); extra user endpoints and the keyless public seed list are opt-in.
+    const pool = new RpcPool(http, limiter, buildEndpointSpecs({ rpcUrl: rpc.url, rpcSource, fallbackUrl, opts }), { clock });
+    // Keyless holder aggregate: Jupiter's holder count + top-10 share, used when no RPC endpoint serves the ranked list.
+    const holdersAggregate = async (mint) => {
+        const views = await jupiter.search(mint);
+        const v = views.find((x) => x.token.mint === mint) ?? views[0];
+        if (!v)
+            return null;
+        return { holderCount: v.stats.holderCount, top10Pct: v.audit.top10Pct, source: 'jupiter-tokens', fetchedAt: v.stats.fetchedAt };
+    };
+    const rugcheck = new RugCheck(http);
+    const goplus = new GoPlus(http);
+    const candles = new CandleStore({ cache, gecko, clock });
+    const detail = new TokenDetail({ cache, gecko, pool, holdersAggregate, rugcheck, goplus, candles });
+    const store = new Store({ cache, dexscreener, jupiter });
+    return { clock, cache, limiter, health, http, dexscreener, jupiter, jupiterSwap, gecko, rpc, rpcFallback, rpcPool: pool, rugcheck, goplus, credits, budget, candles, detail, store, close: () => { shutdown.abort(); limiter.close(); cache.close(); } };
+}
+/** Pool endpoints: the primary first (keyed when Helius/custom), then the public fallback, then any opt-in extras. */
+function buildEndpointSpecs(args) {
+    const { rpcUrl, rpcSource, fallbackUrl, opts } = args;
+    const specs = [];
+    const seen = new Set();
+    const add = (spec) => {
+        if (seen.has(spec.url))
+            return;
+        seen.add(spec.url);
+        specs.push(spec);
+    };
+    // Primary keeps its natural source bucket (helius 600rpm / solana-rpc 30rpm) and credit-meter semantics.
+    const keyed = rpcSource === 'helius';
+    add({ url: rpcUrl, source: rpcSource, bucket: rpcSource, rpm: keyed ? 600 : 30, burst: keyed ? 5 : 1, label: keyed ? 'Helius (free key)' : 'public RPC', keyed });
+    if (fallbackUrl && fallbackUrl !== rpcUrl)
+        add({ url: fallbackUrl, source: 'solana-rpc', bucket: 'solana-rpc', rpm: 30, burst: 1, label: 'public RPC (fallback)' });
+    for (const url of opts.rpcExtraUrls ?? []) {
+        const src = rpcSourceFor(url);
+        add({ url, source: src, bucket: bucketFor(url), rpm: src === 'helius' ? 600 : 30, burst: src === 'helius' ? 5 : 1, label: 'user RPC', basis: 'env DEXTERM_RPC_URLS', keyed: src === 'helius' });
+    }
+    if (opts.rpcPublicPool) {
+        for (const p of PUBLIC_RPC_POOL)
+            add({ url: p.url, source: 'solana-rpc', bucket: bucketFor(p.url), rpm: 30, burst: 1, label: p.label, basis: p.basis });
+    }
+    return specs;
+}
+export { fetchPage, robotsAllows } from "./larp/robots.js";

package/dist/packages/data/src/intel/helius-history.js

@@ -0,0 +1,59 @@
+import { rpcBodyCheck } from "../sources/solana-rpc.js";
+export const HISTORY_METHODS = new Set(['getTransactionsForAddress']);
+export class HeliusHistory {
+    http;
+    /** May carry an api-key: never print it. */
+    url;
+    meta = { source: 'helius', bucket: 'helius' };
+    constructor(http, url) {
+        this.http = http;
+        this.url = url;
+    }
+    async call(method, params) {
+        if (!HISTORY_METHODS.has(method))
+            throw new Error(`refusing non-history RPC method ${method}`);
+        const body = { jsonrpc: '2.0', id: 1, method, params };
+        const r = await this.http.postJson(this.url, body, this.meta, rpcBodyCheck);
+        if (r.data.result === undefined)
+            throw new Error(`rpc ${method}: no result`);
+        return { result: r.data.result, fetchedAt: r.fetchedAt };
+    }
+    /**
+     * Succeeded transactions referencing `address`, full jsonParsed, oldest first by default. `limit` ≤ 1000
+     * (Helius pages at 100 credits-wise: 10 credits per 100 txs).
+     */
+    async transactions(address, opts) {
+        const limit = Math.max(1, Math.min(1000, Math.floor(opts.limit)));
+        const params = {
+            transactionDetails: 'full', sortOrder: opts.sortOrder ?? 'asc', limit, encoding: 'jsonParsed', maxSupportedTransactionVersion: 0,
+            filters: { status: 'succeeded' },
+        };
+        if (opts.paginationToken)
+            params.paginationToken = opts.paginationToken;
+        const { result, fetchedAt } = await this.call('getTransactionsForAddress', [address, params]);
+        return { data: Array.isArray(result.data) ? result.data.map(slimTx) : [], paginationToken: result.paginationToken ?? null, fetchedAt };
+    }
+    /** A wallet's oldest 3 succeeded txs (funding source + wallet age). 10 credits. */
+    firstTxs(wallet) {
+        return this.transactions(wallet, { limit: 3, sortOrder: 'asc' });
+    }
+    /** The mint's oldest `limit` succeeded txs (launch window). 10 credits per 100. */
+    launchWindow(mint, limit, paginationToken) {
+        return this.transactions(mint, { limit, sortOrder: 'asc', paginationToken });
+    }
+}
+/**
+ * Keep only the fields the rules read (account keys with the signer flag, balances, token balances, slot,
+ * time, first signature). A full jsonParsed tx is 10–15 KB; this is ≈ 1–3 KB, which is what the cache stores.
+ */
+export function slimTx(tx) {
+    const keys = (tx.transaction?.message?.accountKeys ?? []).map((k) => (typeof k === 'string' ? k : { pubkey: k.pubkey, signer: !!k.signer }));
+    const tb = (arr) => (arr ?? []).map((b) => ({ accountIndex: b.accountIndex, mint: b.mint, owner: b.owner, uiTokenAmount: { amount: b.uiTokenAmount.amount } }));
+    return {
+        slot: tx.slot,
+        blockTime: tx.blockTime ?? null,
+        transactionIndex: tx.transactionIndex ?? null,
+        transaction: { signatures: tx.transaction?.signatures?.slice(0, 1) ?? [], message: { accountKeys: keys } },
+        meta: tx.meta ? { preBalances: tx.meta.preBalances ?? [], postBalances: tx.meta.postBalances ?? [], preTokenBalances: tb(tx.meta.preTokenBalances), postTokenBalances: tb(tx.meta.postTokenBalances) } : null,
+    };
+}

package/dist/packages/data/src/intel/holder-class.js

@@ -0,0 +1,125 @@
+// Holder CLASSIFICATION (task-1367): what kind of owner holds a top token account — a pool, a bonding curve, a
+// launch/escrow vault, a lock, an exchange, the burn address, the creator, a wallet linked to other top holders —
+// or UNLABELLED when the chain facts we already have do not say. Pure: the inputs are the token account's owner
+// (getMultipleAccounts over the token accounts) and the OWNER account's program (getMultipleAccounts over the
+// owners), both fetched by the wallet-intel scan already, plus the launch-window labels the rules derived. No new
+// request, no paid API, no scraping.
+//
+// Never a guess. A class is only given when the owner is (a) a program authority we can re-derive (the constant
+// pool-authority PDAs below are checked in the tests with findProgramAddress), (b) an account owned by a program
+// in PROGRAM_CLASS, (c) the incinerator / system address, (d) a seed-list exchange wallet (always "unverified"),
+// or (e) an on-chain launch rule (D1 creator, P1 pool, linked cluster). Anything else — a plain wallet, an account
+// of a program we do not list, a PDA with no account — is UNLABELLED with what we do know, and is COUNTED in the
+// ex-pool concentration: an unknown program could be the dev's own contract, so it is never hidden.
+import { SYSTEM_PROGRAM } from "../trade/tx-decode.js";
+import { TOKEN_PROGRAM, TOKEN_2022_PROGRAM } from "../sources/solana-rpc.js";
+import { PUMP_PROGRAM_ID, pumpBondingCurve, base58Decode, isOnCurve } from "../sources/pda.js";
+/** Classes whose balance is not a person's position: dropped from the ex-pool top-10. */
+export const EX_POOL_TAGS = new Set(['POOL', 'CURVE', 'VAULT', 'LOCK', 'BURN']);
+/** An unlabelled (or creator / linked) owner above this share is called out as the main risk. */
+export const BIG_HOLDER_PCT = 30;
+/**
+ * Programs whose ACCOUNTS own token accounts that are not a person's position. Keyed by program id: when the
+ * token account's owner is an account owned by one of these programs, the owner is that program's pool / curve
+ * / vault / escrow state.
+ */
+export const PROGRAM_CLASS = {
+    '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8': { tag: 'POOL', name: 'Raydium AMM v4', what: 'AMM pool vault' },
+    CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C: { tag: 'POOL', name: 'Raydium CPMM', what: 'AMM pool vault' },
+    CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK: { tag: 'POOL', name: 'Raydium CLMM', what: 'concentrated-liquidity pool vault' },
+    LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj: { tag: 'CURVE', name: 'Raydium LaunchLab', what: 'bonding-curve vault' },
+    whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc: { tag: 'POOL', name: 'Orca Whirlpool', what: 'concentrated-liquidity pool vault' },
+    LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo: { tag: 'POOL', name: 'Meteora DLMM', what: 'DLMM pool reserve' },
+    Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB: { tag: 'POOL', name: 'Meteora DAMM v1', what: 'dynamic AMM pool' },
+    cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG: { tag: 'POOL', name: 'Meteora DAMM v2', what: 'dynamic AMM pool' },
+    dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN: { tag: 'CURVE', name: 'Meteora DBC', what: 'dynamic bonding-curve vault (Jupiter Studio / Meteora launches)' },
+    '24Uqj9JCLxUeoC3hGfh5W3s9FM9uCHDS2SG3LYwBpyTi': { tag: 'VAULT', name: 'Meteora dynamic vault', what: 'vault backing Meteora pool liquidity' },
+    vaU6kP7iNEGkbmPkLmZfGwiGxd4Mob24QQCie5R9kd2: { tag: 'VAULT', name: 'Meteora Alpha Vault', what: 'launch vault: tokens owed to its depositors' },
+    [PUMP_PROGRAM_ID]: { tag: 'CURVE', name: 'pump.fun', what: 'bonding curve' },
+    pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA: { tag: 'POOL', name: 'PumpSwap', what: 'AMM pool vault' },
+    strmRqUCoQUgGUan5YhzUZa6KqdzwX5L6FpUxfmKg5m: { tag: 'LOCK', name: 'Streamflow', what: 'vesting / lock escrow' },
+    LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn: { tag: 'LOCK', name: 'Jupiter Lock', what: 'vesting / lock escrow' },
+};
+/**
+ * Constant program-derived authorities that own the vaults of EVERY pool of their program. They are PDAs with no
+ * account of their own, so the owner-program lookup cannot see them; the tests re-derive each with
+ * findProgramAddress(seed, program) so a typo can never ship.
+ */
+export const AUTHORITY_CLASS = {
+    '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1': { tag: 'POOL', name: 'Raydium AMM v4', what: 'pool authority', program: '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8', seed: 'amm authority' },
+    GpMZbSM2GgvTKHJirzeGfMFoaZ8UR2X7F4v8vHTvxFbL: { tag: 'POOL', name: 'Raydium CPMM', what: 'vault authority', program: 'CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C', seed: 'vault_and_lp_mint_auth_seed' },
+    WLHv2UAZm6z4KyaaELi5pjdbJh6RESMva1Rnn8pJVVh: { tag: 'CURVE', name: 'Raydium LaunchLab', what: 'curve vault authority', program: 'LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj', seed: 'vault_auth_seed' },
+    FhVo3mqL8PW5pH5U2CN4XE33DokiyZnUwuGpH2hmHLuM: { tag: 'CURVE', name: 'Meteora DBC', what: 'pool authority (holds every DBC curve vault: Jupiter Studio / Meteora launches)', program: 'dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN', seed: 'pool_authority' },
+    HLnpSz9h2S4hiLQ43rnSD9XkcUThA7B8hQMKmDaiTLcC: { tag: 'POOL', name: 'Meteora DAMM v2', what: 'pool authority', program: 'cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG', seed: 'pool_authority' },
+};
+export const INCINERATOR = '1nc1nerator11111111111111111111111111111111';
+const short = (a) => (a ? `${a.slice(0, 4)}…${a.slice(-4)}` : '—');
+/** Whether `a` is a valid ed25519 point (a keypair can sign) — false for a PDA. Null for a malformed address. */
+export function onCurve(a) {
+    try {
+        const b = base58Decode(a);
+        return b.length === 32 ? isOnCurve(b) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const curveCache = new Map();
+function pumpCurveOf(mint) {
+    if (!curveCache.has(mint)) {
+        let c = null;
+        try {
+            c = pumpBondingCurve(mint);
+        }
+        catch {
+            c = null;
+        }
+        curveCache.set(mint, c);
+        if (curveCache.size > 512)
+            curveCache.delete(curveCache.keys().next().value);
+    }
+    return curveCache.get(mint) ?? null;
+}
+function escrowOf(owner, e) {
+    if (e.tag !== 'LOCK' && e.tag !== 'VAULT')
+        return null;
+    return { escrow: owner, program: e.name, unlock: null, authority: null, note: `unlock schedule not decoded: open escrow ${short(owner)} on ${e.name} to read it` };
+}
+/** Classify one top holder. Order: burn → derived authority → owner program → creator → linked → exchange → P1 → unlabelled. */
+export function classifyHolder(x) {
+    const { owner, meta } = x;
+    if (owner === INCINERATOR)
+        return { tag: 'BURN', reason: 'owner is the incinerator address (1nc1nerator…): tokens sent there can never move', program: null, lock: null };
+    if (owner === SYSTEM_PROGRAM)
+        return { tag: 'BURN', reason: 'owner is the System Program address (1111…1111): no key can sign for it', program: null, lock: null };
+    const auth = AUTHORITY_CLASS[owner];
+    if (auth)
+        return { tag: auth.tag, reason: `${auth.name} ${auth.what} (${short(owner)}, a PDA of the ${auth.name} program)`, program: auth.name, lock: null };
+    if (owner === pumpCurveOf(x.mint))
+        return { tag: 'CURVE', reason: `pump.fun bonding curve of this mint (${short(owner)} = PDA "bonding-curve" + mint)`, program: 'pump.fun', lock: null };
+    const prog = meta?.exists ? meta.programOwner : null;
+    const pe = prog ? PROGRAM_CLASS[prog] : undefined;
+    if (pe)
+        return { tag: pe.tag, reason: `owner ${short(owner)} is an account of the ${pe.name} program: ${pe.what}`, program: pe.name, lock: escrowOf(owner, pe) };
+    if (x.dev)
+        return { tag: 'DEV', reason: x.dev, program: null, lock: null };
+    if (x.linked)
+        return { tag: 'LINKED', reason: x.linked, program: null, lock: null };
+    if (x.cex)
+        return { tag: 'CEX', reason: `exchange hot wallet: ${x.cex} (seed list, unverified by a second source)`, program: null, lock: null };
+    if (x.poolRule)
+        return { tag: 'POOL', reason: x.poolRule, program: null, lock: null };
+    // ---- unlabelled: say what we know, never what it "probably" is
+    if (!meta)
+        return { tag: 'UNLABELLED', reason: 'owner kind not resolved (account lookup did not answer): treat as a person', program: null, lock: null };
+    if (prog === TOKEN_PROGRAM || prog === TOKEN_2022_PROGRAM) {
+        const self = x.tokenAccounts.includes(owner);
+        return { tag: 'UNLABELLED', reason: `owner ${short(owner)} is ${self ? 'its own token account' : 'an SPL Token account'}: a program escrow, but the program that controls it is not identified, so it is counted`, program: null, lock: null };
+    }
+    if (meta.exists && prog !== SYSTEM_PROGRAM)
+        return { tag: 'UNLABELLED', reason: `owner is an account of program ${short(prog)}, which is not in dexterm's program list: not a keypair wallet, but not a known pool or lock either, so it is counted`, program: null, lock: null };
+    const curve = onCurve(owner);
+    if (curve === false)
+        return { tag: 'UNLABELLED', reason: `owner ${short(owner)} is a PDA (off-curve${meta.exists ? ', System-owned' : ', no account'}) of an unidentified program: counted`, program: null, lock: null };
+    return { tag: 'UNLABELLED', reason: `plain wallet (${meta.exists ? 'System-owned' : 'no SOL account'}${curve ? ', a keypair address' : ''}): no pool, lock, exchange or launch rule matched`, program: null, lock: null };
+}