@agentbadge/payment-forensics 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @agentbadge/payment-forensics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pure-TypeScript payment-graph forensics core for x402 settles on Arc. **Zero I/O** — no fetch/fs/db; callers supply edges and funding events.
+
+## What it does
+
+Distinguishes **organic revenue** from **circular/farmed volume** per seller address:
+
+- **Loop detection** — Tarjan SCC over the payment graph. Inside a loop only *net inflow* counts: money the seller pumped back into its own loop is netted out.
+- **Self-funding strike** — payer whose *first* funder is the seller (or a wallet the seller funded, one hop) → zero organic.
+- **Shared-funder strike** — ≥2 of the seller's payers sharing one *private* first funder → all struck. Public sources (exchange, bridge, `custody_provider`, contract) are exempt — a custodian like Crossmint funding thousands of agents is not a farm.
+- **effectivePayers** — inverse Herfindahl over organic volumes (one dominant payer → ≈1).
+- **coveredPct** — honest coverage: share of payers with observed funding data.
+- **thinFile** — D-204-5 flag: <5 settles or <2 payers or <$0.05 gross → callers should answer `no_data`, not a verdict.
+
+## Usage
+
+```ts
+import { analyzeAddress } from "@agentbadge/payment-forensics";
+
+const analysis = analyzeAddress(seller, edges, fundingEvents, {
+  publicSources: [
+    { address: "0x…", kind: "custody_provider", name: "Crossmint" },
+    { address: "0x…", kind: "exchange" },
+  ],
+});
+// → { organicShare, organicVolume, grossVolume, effectivePayers,
+//     loops, selfFunded, sharedFunder, coveredPct, thinFile, payers }
+```
+
+## Conventions
+
+- Addresses normalized to lowercase internally.
+- Amounts: `bigint`, USDC atomic units (decimals=6).
+- `PaymentEdge` = one settle `{payer, seller, amount, txHash, block, ts}` — built by the 204-4 indexer from `AuthorizationUsed`/`Transfer` logs.
+- `FundingEvent` = `{funder, funded, ts}` — first observed funding transfer.
+
+## Scripts
+
+- `bun run build` / `typecheck` — tsc → dist
+- `bun test` / `bun run test` — vitest (5 forensic scenarios)
+
+Reference: Assay `packages/core` (MIT) model, adapted to Arc USDC per EPIC-204.
+
+## Questions & Contact
+
+- **Site**: https://agentbadge.xyz/
+- **Contact page**: https://agentbadge.xyz/contact
+- **Discord / Telegram / e-mail**: see https://agentbadge.xyz/contact

package/dist/funding.d.ts

@@ -0,0 +1,21 @@
+import type { Address, FundingEvent, PublicSource, PublicSourceKind } from "./types.js";
+export type PublicSourceMap = Map<Address, PublicSourceKind>;
+export declare function toPublicSourceMap(sources: PublicSource[] | PublicSourceMap | undefined): PublicSourceMap;
+export declare function firstFunders(funding: FundingEvent[]): Map<Address, Address>;
+export type FundingVerdict = {
+    kind: "organic";
+} | {
+    kind: "unknown";
+} | {
+    kind: "public";
+    funder: Address;
+    sourceKind: PublicSourceKind;
+} | {
+    kind: "self_funded";
+    funder: Address;
+} | {
+    kind: "shared_funder";
+    funder: Address;
+};
+export declare function classifyFunding(payer: Address, seller: Address, first: Map<Address, Address>, publicSources: PublicSourceMap, funderPayerCounts: Map<Address, number>, sharedMin?: number): FundingVerdict;
+export declare function funderPayerCounts(payers: Address[], first: Map<Address, Address>, publicSources: PublicSourceMap): Map<Address, number>;

package/dist/funding.js

@@ -0,0 +1,61 @@
+import { norm } from "./graph.js";
+export function toPublicSourceMap(sources) {
+    if (!sources)
+        return new Map();
+    if (sources instanceof Map) {
+        const m = new Map();
+        for (const [a, k] of sources)
+            m.set(norm(a), k);
+        return m;
+    }
+    return new Map(sources.map((s) => [norm(s.address), s.kind]));
+}
+export function firstFunders(funding) {
+    const first = new Map();
+    for (const f of funding) {
+        const funded = norm(f.funded);
+        const cur = first.get(funded);
+        if (!cur || f.ts < cur.ts) {
+            first.set(funded, { funder: norm(f.funder), ts: f.ts });
+        }
+    }
+    const out = new Map();
+    for (const [a, v] of first)
+        out.set(a, v.funder);
+    return out;
+}
+export function classifyFunding(payer, seller, first, publicSources, funderPayerCounts, sharedMin = 2) {
+    const p = norm(payer);
+    const s = norm(seller);
+    const funder = first.get(p);
+    if (!funder)
+        return { kind: "unknown" };
+    if (funder === s)
+        return { kind: "self_funded", funder };
+    const kind = publicSources.get(funder);
+    if (kind)
+        return { kind: "public", funder, sourceKind: kind };
+    if (first.get(funder) === s)
+        return { kind: "self_funded", funder };
+    if ((funderPayerCounts.get(funder) ?? 0) >= sharedMin) {
+        return { kind: "shared_funder", funder };
+    }
+    return { kind: "organic" };
+}
+export function funderPayerCounts(payers, first, publicSources) {
+    const counts = new Map();
+    for (const raw of payers) {
+        const p = norm(raw);
+        const f = first.get(p);
+        if (!f || publicSources.has(f))
+            continue;
+        let set = counts.get(f);
+        if (!set)
+            counts.set(f, (set = new Set()));
+        set.add(p);
+    }
+    const out = new Map();
+    for (const [f, set] of counts)
+        out.set(f, set.size);
+    return out;
+}

package/dist/graph.d.ts

@@ -0,0 +1,10 @@
+import type { Address, PaymentEdge } from "./types.js";
+export declare const norm: (a: Address) => Address;
+export interface PaymentGraph {
+    nodes: Set<Address>;
+    adjacency: Map<Address, Map<Address, bigint>>;
+    outVolume: Map<Address, bigint>;
+    inVolume: Map<Address, bigint>;
+}
+export declare function buildGraph(edges: PaymentEdge[]): PaymentGraph;
+export declare function edgeVolume(g: PaymentGraph, from: Address, to: Address): bigint;

package/dist/graph.js

@@ -0,0 +1,23 @@
+export const norm = (a) => a.toLowerCase();
+export function buildGraph(edges) {
+    const nodes = new Set();
+    const adjacency = new Map();
+    const outVolume = new Map();
+    const inVolume = new Map();
+    for (const e of edges) {
+        const from = norm(e.payer);
+        const to = norm(e.seller);
+        nodes.add(from);
+        nodes.add(to);
+        let row = adjacency.get(from);
+        if (!row)
+            adjacency.set(from, (row = new Map()));
+        row.set(to, (row.get(to) ?? 0n) + e.amount);
+        outVolume.set(from, (outVolume.get(from) ?? 0n) + e.amount);
+        inVolume.set(to, (inVolume.get(to) ?? 0n) + e.amount);
+    }
+    return { nodes, adjacency, outVolume, inVolume };
+}
+export function edgeVolume(g, from, to) {
+    return g.adjacency.get(norm(from))?.get(norm(to)) ?? 0n;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { buildGraph, edgeVolume, norm, type PaymentGraph } from "./graph.js";
+export { findSccs, loopsFor } from "./loops.js";
+export { classifyFunding, firstFunders, funderPayerCounts, toPublicSourceMap, type FundingVerdict, type PublicSourceMap, } from "./funding.js";
+export { analyzeAddress, THIN_GROSS_FLOOR, THIN_MIN_PAYERS, THIN_MIN_SETTLES, type AnalyzeOptions, } from "./score.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { buildGraph, edgeVolume, norm } from "./graph.js";
+export { findSccs, loopsFor } from "./loops.js";
+export { classifyFunding, firstFunders, funderPayerCounts, toPublicSourceMap, } from "./funding.js";
+export { analyzeAddress, THIN_GROSS_FLOOR, THIN_MIN_PAYERS, THIN_MIN_SETTLES, } from "./score.js";

package/dist/loops.d.ts

@@ -0,0 +1,4 @@
+import type { Address, LoopInfo, PaymentEdge } from "./types.js";
+import { type PaymentGraph } from "./graph.js";
+export declare function findSccs(g: PaymentGraph): Address[][];
+export declare function loopsFor(seller: Address, edges: PaymentEdge[]): LoopInfo[];

package/dist/loops.js

@@ -0,0 +1,85 @@
+import { buildGraph, edgeVolume, norm } from "./graph.js";
+export function findSccs(g) {
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    for (const start of g.nodes) {
+        if (index.has(start))
+            continue;
+        const work = [
+            [start, (g.adjacency.get(start) ?? new Map()).keys()],
+        ];
+        index.set(start, counter);
+        low.set(start, counter);
+        counter++;
+        stack.push(start);
+        onStack.add(start);
+        while (work.length > 0) {
+            const [node, it] = work[work.length - 1];
+            const next = it.next();
+            if (next.done) {
+                if (low.get(node) === index.get(node)) {
+                    const scc = [];
+                    for (;;) {
+                        const w = stack.pop();
+                        onStack.delete(w);
+                        scc.push(w);
+                        if (w === node)
+                            break;
+                    }
+                    if (scc.length > 1 || edgeVolume(g, node, node) > 0n)
+                        sccs.push(scc);
+                }
+                work.pop();
+                if (work.length > 0) {
+                    const parent = work[work.length - 1][0];
+                    low.set(parent, Math.min(low.get(parent), low.get(node)));
+                }
+                continue;
+            }
+            const w = next.value;
+            if (!index.has(w)) {
+                index.set(w, counter);
+                low.set(w, counter);
+                counter++;
+                stack.push(w);
+                onStack.add(w);
+                work.push([w, (g.adjacency.get(w) ?? new Map()).keys()]);
+            }
+            else if (onStack.has(w)) {
+                low.set(node, Math.min(low.get(node), index.get(w)));
+            }
+        }
+    }
+    return sccs;
+}
+export function loopsFor(seller, edges) {
+    const s = norm(seller);
+    const g = buildGraph(edges);
+    const sccs = findSccs(g);
+    const loops = [];
+    for (const members of sccs) {
+        if (!members.includes(s))
+            continue;
+        const set = new Set(members);
+        let grossInternal = 0n;
+        let inflow = 0n;
+        let outflow = 0n;
+        for (const e of edges) {
+            const p = norm(e.payer);
+            const t = norm(e.seller);
+            if (set.has(p) && set.has(t))
+                grossInternal += e.amount;
+            if (set.has(p) && t === s)
+                inflow += e.amount;
+            if (p === s && set.has(t) && t !== s)
+                outflow += e.amount;
+        }
+        const netInflow = inflow - outflow > 0n ? inflow - outflow : 0n;
+        loops.push({ members: members.sort(), grossInternal, netInflow });
+    }
+    return loops;
+}

package/dist/score.d.ts

@@ -0,0 +1,10 @@
+import type { Address, AddressAnalysis, FundingEvent, PaymentEdge, PublicSource } from "./types.js";
+import { type PublicSourceMap } from "./funding.js";
+export interface AnalyzeOptions {
+    publicSources?: PublicSource[] | PublicSourceMap;
+    sharedFunderMin?: number;
+}
+export declare const THIN_GROSS_FLOOR = 50000n;
+export declare const THIN_MIN_SETTLES = 5;
+export declare const THIN_MIN_PAYERS = 2;
+export declare function analyzeAddress(address: Address, edges: PaymentEdge[], funding: FundingEvent[], opts?: AnalyzeOptions): AddressAnalysis;

package/dist/score.js

@@ -0,0 +1,108 @@
+import { norm } from "./graph.js";
+import { loopsFor } from "./loops.js";
+import { classifyFunding, funderPayerCounts, firstFunders, toPublicSourceMap, } from "./funding.js";
+export const THIN_GROSS_FLOOR = 50000n;
+export const THIN_MIN_SETTLES = 5;
+export const THIN_MIN_PAYERS = 2;
+export function analyzeAddress(address, edges, funding, opts = {}) {
+    const seller = norm(address);
+    const pub = toPublicSourceMap(opts.publicSources);
+    const sharedMin = opts.sharedFunderMin ?? 2;
+    const inbound = edges.filter((e) => norm(e.seller) === seller);
+    const gross = inbound.reduce((a, e) => a + e.amount, 0n);
+    const payerVolumes = new Map();
+    for (const e of inbound) {
+        const p = norm(e.payer);
+        payerVolumes.set(p, (payerVolumes.get(p) ?? 0n) + e.amount);
+    }
+    const payerList = [...payerVolumes.keys()];
+    const loops = loopsFor(seller, edges);
+    const loopOf = new Map();
+    for (const l of loops)
+        for (const m of l.members)
+            if (m !== seller)
+                loopOf.set(m, l);
+    const first = firstFunders(funding);
+    const counts = funderPayerCounts(payerList, first, pub);
+    const selfFunded = [];
+    const sharedFunder = [];
+    const payers = [];
+    let covered = 0;
+    let organic = 0n;
+    for (const p of payerList) {
+        const v = payerVolumes.get(p);
+        const vrd = classifyFunding(p, seller, first, pub, counts, sharedMin);
+        if (vrd.kind !== "unknown")
+            covered++;
+        let loopOrganic = v;
+        const loop = loopOf.get(p);
+        let inLoop = false;
+        if (loop) {
+            inLoop = true;
+            const memberIn = loop.members
+                .filter((m) => m !== seller)
+                .reduce((a, m) => a + (payerVolumes.get(m) ?? 0n), 0n);
+            loopOrganic = memberIn > 0n ? (v * loop.netInflow) / memberIn : 0n;
+        }
+        let organicV;
+        let struck = false;
+        let strikeReason;
+        let funder;
+        if (vrd.kind === "self_funded") {
+            organicV = 0n;
+            struck = true;
+            strikeReason = "self_funded";
+            funder = vrd.funder;
+            selfFunded.push(p);
+        }
+        else if (vrd.kind === "shared_funder") {
+            organicV = 0n;
+            struck = true;
+            strikeReason = "shared_funder";
+            funder = vrd.funder;
+            sharedFunder.push(p);
+        }
+        else {
+            organicV = loopOrganic;
+            struck = inLoop && organicV === 0n;
+            if (inLoop)
+                strikeReason = "loop";
+        }
+        organic += organicV;
+        payers.push({
+            payer: p,
+            grossVolume: v,
+            organicVolume: organicV,
+            struck,
+            strikeReason,
+            funder,
+            fundingUnknown: vrd.kind === "unknown",
+        });
+    }
+    const organicShare = gross > 0n ? Number(organic) / Number(gross) : 0;
+    let hhi = 0;
+    if (organic > 0n) {
+        for (const p of payers) {
+            const s = Number(p.organicVolume) / Number(organic);
+            hhi += s * s;
+        }
+    }
+    const effectivePayers = hhi > 0 ? 1 / hhi : 0;
+    const thinFile = inbound.length < THIN_MIN_SETTLES ||
+        payerList.length < THIN_MIN_PAYERS ||
+        gross < THIN_GROSS_FLOOR;
+    return {
+        address: seller,
+        payerCount: payerList.length,
+        grossVolume: gross,
+        organicVolume: organic,
+        organicShare,
+        effectivePayers,
+        loops,
+        selfFunded,
+        sharedFunder,
+        coveredPct: payerList.length > 0 ? covered / payerList.length : 0,
+        thinFile,
+        payers,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export type Address = string;
+export interface PaymentEdge {
+    payer: Address;
+    seller: Address;
+    amount: bigint;
+    txHash: string;
+    block: number;
+    ts: number;
+}
+export interface FundingEvent {
+    funder: Address;
+    funded: Address;
+    ts: number;
+    txHash?: string;
+}
+export type PublicSourceKind = "exchange" | "bridge" | "custody_provider" | "contract";
+export interface PublicSource {
+    address: Address;
+    kind: PublicSourceKind;
+    name?: string;
+}
+export interface LoopInfo {
+    members: Address[];
+    grossInternal: bigint;
+    netInflow: bigint;
+}
+export interface PayerBreakdown {
+    payer: Address;
+    grossVolume: bigint;
+    organicVolume: bigint;
+    struck: boolean;
+    strikeReason?: "loop" | "self_funded" | "shared_funder";
+    funder?: Address;
+    fundingUnknown: boolean;
+}
+export interface AddressAnalysis {
+    address: Address;
+    payerCount: number;
+    grossVolume: bigint;
+    organicVolume: bigint;
+    organicShare: number;
+    effectivePayers: number;
+    loops: LoopInfo[];
+    selfFunded: Address[];
+    sharedFunder: Address[];
+    coveredPct: number;
+    thinFile: boolean;
+    payers: PayerBreakdown[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@agentbadge/payment-forensics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Pure-TypeScript payment-graph forensics core — loop detection (Tarjan SCC), self-funding trace, shared-funder strike, organic revenue share. Zero I/O.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "author": "AgentBadge",
+  "license": "MIT",
+  "keywords": [
+    "x402",
+    "arc",
+    "usdc",
+    "payment-forensics",
+    "organic-revenue",
+    "agentbadge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}