@mnemopay/sdk 0.3.0 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 **Give any AI agent memory and a wallet in 5 lines.**
 
-MnemoPay unifies [Mnemosyne](https://github.com/t49qnsx7qt-kpanks/mnemosyne-engine) (cognitive memory) and [AgentPay](https://github.com/t49qnsx7qt-kpanks/agentpay-roa) (escrow economics) into a single SDK. The core innovation: **payment outcomes reinforce the memories that led to successful decisions**.
+MnemoPay unifies [Mnemosyne](https://github.com/mnemopay/mnemosyne-engine) (cognitive memory) and [AgentPay](https://github.com/mnemopay/agentpay-roa) (escrow economics) into a single SDK. The core innovation: **payment outcomes reinforce the memories that led to successful decisions**.
 
 ```typescript
 import { MnemoPay } from "@mnemopay/sdk";
@@ -190,4 +190,4 @@ npm test  # 67 tests covering memory, payments, feedback loop, security, concurr
 
 MIT
 
-Built by [J&B Enterprise LLC](https://github.com/t49qnsx7qt-kpanks)
+Built by [J&B Enterprise LLC](https://github.com/mnemopay)

package/dist/fraud-ml.d.ts

@@ -0,0 +1,174 @@
+/**
+ * MnemoPay Advanced Fraud Detection — ML-grade algorithms in pure TypeScript.
+ *
+ * Three systems that close the depth gap with Stripe/Coinbase:
+ *
+ * 1. IsolationForest — Adaptive anomaly detection that LEARNS each agent's
+ *    normal behavior and catches deviations. Replaces static z-scores.
+ *
+ * 2. TransactionGraph — Directed graph of money flows between agents.
+ *    Detects wash trading (A→B→A cycles), fraud rings (dense subgraphs),
+ *    and sybil attacks (correlated agents from same source).
+ *
+ * 3. BehaviorProfile — Fingerprints each agent's behavioral signature:
+ *    typical amounts, timing patterns, charge frequency, memory-to-payment
+ *    ratio. Detects drift from established baseline.
+ *
+ * Zero external dependencies. Runs in-process alongside FraudGuard.
+ */
+export declare class IsolationForest {
+    private trees;
+    private readonly numTrees;
+    private readonly maxSamples;
+    private readonly maxDepth;
+    /** Training data buffer — keeps recent samples for incremental retraining */
+    private buffer;
+    private readonly bufferSize;
+    private readonly featureNames;
+    constructor(opts?: {
+        numTrees?: number;
+        maxSamples?: number;
+        maxDepth?: number;
+        bufferSize?: number;
+    });
+    /** Number of features expected per sample */
+    get numFeatures(): number;
+    /**
+     * Add a sample and retrain if buffer is full enough.
+     * Features: [amount, hourOfDay, minutesSinceLast, chargesLast10Min,
+     *            avgAmountLast10, stdDevLast10, pendingCount, reputation]
+     */
+    addSample(features: number[]): void;
+    /** Train forest from buffer */
+    private train;
+    /** Build a single isolation tree */
+    private buildTree;
+    /**
+     * Score a sample. Returns 0-1 where higher = more anomalous.
+     * Returns -1 if not enough training data yet.
+     */
+    score(features: number[]): number;
+    /** Traverse tree and return path length to isolation */
+    private pathLength;
+    /** Average path length of unsuccessful search in BST (used for normalization) */
+    private avgPathLength;
+    /** Random subsample without replacement */
+    private subsample;
+    /** Has enough data to score */
+    get isReady(): boolean;
+    get sampleCount(): number;
+    serialize(): string;
+    static deserialize(json: string, opts?: ConstructorParameters<typeof IsolationForest>[0]): IsolationForest;
+}
+export interface CollusionSignal {
+    type: "wash_trading" | "fraud_ring" | "sybil_cluster" | "self_dealing";
+    agents: string[];
+    evidence: string;
+    severity: number;
+}
+export declare class TransactionGraph {
+    /** Adjacency list: agent → list of outgoing edges */
+    private edges;
+    /** Agent metadata: IP, creation time, etc. */
+    private agentMeta;
+    /** Total edge count */
+    private edgeCount;
+    /**
+     * Record a transaction between two agents.
+     * fromAgent paid toAgent.
+     */
+    addTransaction(fromAgent: string, toAgent: string, amount: number, txId: string): void;
+    /** Register agent metadata for sybil detection */
+    registerAgent(agentId: string, ip?: string): void;
+    /**
+     * Detect wash trading: cycles where money flows A→B→...→A.
+     * Returns cycles of length 2-4 (direct and indirect wash trading).
+     */
+    detectWashTrading(maxCycleLength?: number): CollusionSignal[];
+    private findCycles;
+    private getCycleFlow;
+    /**
+     * Detect sybil clusters: multiple agents sharing the same IP(s)
+     * that also transact with each other.
+     */
+    detectSybilClusters(): CollusionSignal[];
+    /**
+     * Detect self-dealing: agent transacting with itself via intermediaries.
+     * A→X→A pattern where X is a thin shell.
+     */
+    detectSelfDealing(): CollusionSignal[];
+    /**
+     * Run all collusion detectors and return combined signals.
+     */
+    detectAll(): CollusionSignal[];
+    /** Get graph stats */
+    stats(): {
+        agents: number;
+        edges: number;
+        avgDegree: number;
+    };
+    serialize(): string;
+    static deserialize(json: string): TransactionGraph;
+}
+export interface BehaviorSnapshot {
+    /** Average charge amount */
+    avgAmount: number;
+    /** Standard deviation of charge amounts */
+    stdAmount: number;
+    /** Typical hour of day for activity (0-23) */
+    peakHour: number;
+    /** Average minutes between charges */
+    avgInterval: number;
+    /** Ratio of memory ops to payment ops */
+    memoryToPaymentRatio: number;
+    /** Average charges per active day */
+    chargesPerDay: number;
+    /** Number of samples used to build this profile */
+    sampleCount: number;
+    /** When this profile was last updated */
+    updatedAt: number;
+}
+export interface DriftSignal {
+    type: "amount_drift" | "timing_drift" | "frequency_drift" | "behavior_shift";
+    description: string;
+    /** How far from baseline (standard deviations) */
+    deviation: number;
+    /** Severity 0-1 */
+    severity: number;
+}
+interface BehaviorEvent {
+    type: "charge" | "settle" | "refund" | "remember" | "recall";
+    amount?: number;
+    timestamp: number;
+}
+export declare class BehaviorProfile {
+    /** Per-agent behavior history */
+    private agentEvents;
+    /** Per-agent baseline snapshots */
+    private baselines;
+    /** Minimum events before baseline is established */
+    private readonly minEvents;
+    /** Max events to retain per agent */
+    private readonly maxEvents;
+    constructor(opts?: {
+        minEvents?: number;
+        maxEvents?: number;
+    });
+    /** Record an event for an agent */
+    recordEvent(agentId: string, type: BehaviorEvent["type"], amount?: number): void;
+    /** Build/update baseline from historical events */
+    private buildBaseline;
+    /**
+     * Check if current behavior drifts from baseline.
+     * Pass recent charge amount and context.
+     */
+    detectDrift(agentId: string, currentAmount?: number): DriftSignal[];
+    /** Get an agent's current baseline (if established) */
+    getBaseline(agentId: string): BehaviorSnapshot | undefined;
+    /** Check if agent has established baseline */
+    hasBaseline(agentId: string): boolean;
+    serialize(): string;
+    static deserialize(json: string, opts?: ConstructorParameters<typeof BehaviorProfile>[0]): BehaviorProfile;
+}
+export {};
+//# sourceMappingURL=fraud-ml.d.ts.map

package/dist/fraud-ml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fraud-ml.d.ts","sourceRoot":"","sources":["../src/fraud-ml.ts"],"names":[],"mappings":"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"}