@mcpaid/sdk 2.0.0

package/dist/sdk/server-sdk.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ToolPay Server SDK
+ * Intuitive developer toolkit for building monetized MCP servers in TypeScript.
+ */
+import { McpToolDefinition, JsonRpcRequest, McpToolCallResult } from '../types/mcp.js';
+import { ServerPricingConfig, DynamicPricingFn } from '../types/pricing.js';
+import { ToolPayGateway, GatewayRequestContext, GatewayResponse } from '../gateway/toolpay-gateway.js';
+import { PaymentOrchestrator } from '../settlement/payment-orchestrator.js';
+import { OnChainRpcProvider } from '../settlement/onchain-verifier.js';
+import { FeeLedger } from '../fee/fee-ledger.js';
+export type ToolHandler = (args: Record<string, any>) => Promise<McpToolCallResult>;
+export interface ToolPayServerOptions {
+    serverId: string;
+    serverName: string;
+    payoutWallet: string;
+    network?: 'base' | 'solana' | 'ethereum' | 'arbitrum';
+    currency?: string;
+    platformFeeBps?: number;
+    platformTreasuryWallet?: string;
+    rpcProvider?: OnChainRpcProvider;
+}
+export declare class ToolPayServer {
+    readonly config: ServerPricingConfig;
+    readonly gateway: ToolPayGateway;
+    readonly feeLedger: FeeLedger;
+    readonly orchestrator: PaymentOrchestrator;
+    private tools;
+    constructor(options: ToolPayServerOptions);
+    /**
+     * Registers a free tool on this MCP server.
+     */
+    freeTool(name: string, definition: Omit<McpToolDefinition, 'name'>, handler: ToolHandler): this;
+    /**
+     * Registers a fixed-price paid tool.
+     */
+    paidTool(name: string, definition: Omit<McpToolDefinition, 'name'>, pricing: {
+        priceUsd: string;
+        maxCallsPerMinute?: number;
+        maxSessionSpendUsd?: string;
+        freeCallsFreemium?: number;
+    }, handler: ToolHandler): this;
+    /**
+     * Registers a dynamically-priced tool (cost computed per input arguments).
+     */
+    dynamicTool(name: string, definition: Omit<McpToolDefinition, 'name'>, pricingFn: DynamicPricingFn, handler: ToolHandler): this;
+    /**
+     * Executes an incoming JSON-RPC request through the ToolPay monetization gateway.
+     */
+    handleRequest(request: JsonRpcRequest, context?: Partial<GatewayRequestContext>): Promise<GatewayResponse>;
+}
+//# sourceMappingURL=server-sdk.d.ts.map

package/dist/sdk/server-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-sdk.d.ts","sourceRoot":"","sources":["../../src/sdk/server-sdk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,iBAAiB,EACjB,cAAc,EAGd,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAmB,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACvG,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAG5E,OAAO,EAAmB,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAGxF,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEpF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,qBAAa,aAAa;IACxB,SAAgB,MAAM,EAAE,mBAAmB,CAAC;IAC5C,SAAgB,OAAO,EAAE,cAAc,CAAC;IACxC,SAAgB,SAAS,EAAE,SAAS,CAAC;IACrC,SAAgB,YAAY,EAAE,mBAAmB,CAAC;IAClD,OAAO,CAAC,KAAK,CAAmF;gBAEpF,OAAO,EAAE,oBAAoB;IAgGzC;;OAEG;IACI,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,EAC3C,OAAO,EAAE,WAAW,GACnB,IAAI;IAaP;;OAEG;IACI,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,EAC3C,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,EACD,OAAO,EAAE,WAAW,GACnB,IAAI;IAwBP;;OAEG;IACI,WAAW,CAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,EAC3C,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,WAAW,GACnB,IAAI;IAiBP;;OAEG;IACU,aAAa,CACxB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC;CAS5B"}

package/dist/sdk/server-sdk.js

@@ -0,0 +1,170 @@
+/**
+ * ToolPay Server SDK
+ * Intuitive developer toolkit for building monetized MCP servers in TypeScript.
+ */
+import { ServerRegistry } from '../gateway/server-registry.js';
+import { ToolPayGateway } from '../gateway/toolpay-gateway.js';
+import { PaymentOrchestrator } from '../settlement/payment-orchestrator.js';
+import { NonceStore } from '../settlement/nonce-store.js';
+import { PermitVerifier } from '../settlement/permit-verifier.js';
+import { OnChainVerifier } from '../settlement/onchain-verifier.js';
+import { SessionWalletManager } from '../settlement/session-wallet.js';
+import { FeeCalculator } from '../fee/fee-calculator.js';
+import { FeeLedger } from '../fee/fee-ledger.js';
+import { CircuitBreaker } from '../circuit-breaker/circuit-breaker.js';
+export class ToolPayServer {
+    config;
+    gateway;
+    feeLedger;
+    orchestrator;
+    tools = new Map();
+    constructor(options) {
+        this.config = {
+            serverId: options.serverId,
+            serverName: options.serverName,
+            payoutWallet: options.payoutWallet,
+            network: options.network || 'base',
+            currency: options.currency || 'USDC',
+            platformFee: {
+                platformFeeBasisPoints: options.platformFeeBps ?? 300,
+                platformTreasuryWallet: options.platformTreasuryWallet,
+            },
+            tools: [],
+        };
+        const registry = new ServerRegistry();
+        registry.registerServer(this.config);
+        const feeLedger = new FeeLedger(options.platformTreasuryWallet || '0x1001001001001001001001001001001001001001');
+        this.feeLedger = feeLedger;
+        const feeCalculator = new FeeCalculator(options.platformTreasuryWallet, options.platformFeeBps ?? 300);
+        const mockRpc = options.rpcProvider || {
+            getTransaction: async () => null,
+        };
+        const orchestrator = new PaymentOrchestrator({
+            nonceStore: new NonceStore(),
+            permitVerifier: new PermitVerifier(),
+            onChainVerifier: new OnChainVerifier(mockRpc),
+            sessionWalletManager: new SessionWalletManager(),
+            feeCalculator,
+            feeLedger,
+        });
+        this.orchestrator = orchestrator;
+        const circuitBreaker = new CircuitBreaker();
+        // Internal upstream MCP dispatcher
+        const upstreamHandler = async (req) => {
+            if (req.method === 'tools/list') {
+                const toolList = Array.from(this.tools.values()).map((t) => t.definition);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id ?? null,
+                    result: { tools: toolList },
+                };
+            }
+            if (req.method === 'tools/call') {
+                const params = req.params;
+                const entry = this.tools.get(params.name);
+                if (!entry) {
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id ?? null,
+                        error: { code: -32601, message: `Tool "${params.name}" not found` },
+                    };
+                }
+                try {
+                    const res = await entry.handler(params.arguments || {});
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id ?? null,
+                        result: res,
+                    };
+                }
+                catch (err) {
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id ?? null,
+                        error: { code: -32000, message: `Tool execution error: ${err.message}` },
+                    };
+                }
+            }
+            return {
+                jsonrpc: '2.0',
+                id: req.id ?? null,
+                result: { status: 'ok' },
+            };
+        };
+        this.gateway = new ToolPayGateway({
+            registry,
+            orchestrator,
+            circuitBreaker,
+            upstreamHandler,
+        });
+    }
+    /**
+     * Registers a free tool on this MCP server.
+     */
+    freeTool(name, definition, handler) {
+        this.tools.set(name, {
+            definition: { ...definition, name },
+            handler,
+        });
+        this.config.tools.push({
+            toolName: name,
+            type: 'free',
+            description: definition.description,
+        });
+        return this;
+    }
+    /**
+     * Registers a fixed-price paid tool.
+     */
+    paidTool(name, definition, pricing, handler) {
+        this.tools.set(name, {
+            definition: { ...definition, name },
+            handler,
+        });
+        const rule = {
+            toolName: name,
+            type: 'fixed',
+            priceUsd: pricing.priceUsd,
+            description: definition.description,
+            circuitBreaker: {
+                maxCallsPerMinute: pricing.maxCallsPerMinute,
+                maxSessionSpendUsd: pricing.maxSessionSpendUsd,
+            },
+            freemium: pricing.freeCallsFreemium
+                ? { freeCallsPerPeriod: pricing.freeCallsFreemium }
+                : undefined,
+        };
+        this.config.tools.push(rule);
+        return this;
+    }
+    /**
+     * Registers a dynamically-priced tool (cost computed per input arguments).
+     */
+    dynamicTool(name, definition, pricingFn, handler) {
+        this.tools.set(name, {
+            definition: { ...definition, name },
+            handler,
+        });
+        const rule = {
+            toolName: name,
+            type: 'dynamic',
+            dynamicPricing: pricingFn,
+            description: definition.description,
+        };
+        this.config.tools.push(rule);
+        return this;
+    }
+    /**
+     * Executes an incoming JSON-RPC request through the ToolPay monetization gateway.
+     */
+    async handleRequest(request, context) {
+        return this.gateway.handleRequest(request, {
+            serverId: this.config.serverId,
+            agentWallet: context?.agentWallet,
+            paymentProof: context?.paymentProof,
+            idempotencyKey: context?.idempotencyKey,
+            nowSec: context?.nowSec,
+        });
+    }
+}
+//# sourceMappingURL=server-sdk.js.map

package/dist/sdk/server-sdk.js.map

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

package/dist/settlement/base-contract-client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ToolPay Base Contract Client
+ * Connects to live Base L2 RPC, decodes ToolPayRouter on-chain events, and verifies settlements.
+ */
+import { type Address, type Hex, type PublicClient } from 'viem';
+import { X402ChallengeData } from '../types/x402.js';
+export declare const BASE_MAINNET: {
+    blockExplorers?: {
+        [key: string]: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+        default: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+    } | undefined | undefined;
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 8453;
+    name: "Base";
+    nativeCurrency: {
+        readonly name: "Ether";
+        readonly symbol: "ETH";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://mainnet.base.org"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+export declare const BASE_SEPOLIA: {
+    blockExplorers?: {
+        [key: string]: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+        default: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+    } | undefined | undefined;
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 84532;
+    name: "Base Sepolia";
+    nativeCurrency: {
+        readonly name: "Ether";
+        readonly symbol: "ETH";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://sepolia.base.org"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet: true;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+export interface VerifiedContractPayment {
+    challengeNonce: string;
+    agent: string;
+    developer: string;
+    token: string;
+    grossAmountMicro: bigint;
+    platformCutMicro: bigint;
+    developerPayoutMicro: bigint;
+    serverId: string;
+    toolName: string;
+    blockNumber: bigint;
+    transactionHash: string;
+}
+export declare class BaseContractClient {
+    publicClient: PublicClient;
+    routerAddress?: Address;
+    chainId: number;
+    private claimedTxHashes;
+    constructor(options?: {
+        rpcUrl?: string;
+        network?: 'base' | 'base-sepolia';
+        routerAddress?: Address;
+        publicClient?: PublicClient;
+    });
+    /**
+     * Verifies an on-chain transaction receipt against ToolPayRouter PaymentSettled events.
+     */
+    verifyContractPayment(params: {
+        txHash: Hex;
+        challenge: X402ChallengeData;
+        signerWallet?: string;
+    }): Promise<{
+        valid: boolean;
+        error?: string;
+        payment?: VerifiedContractPayment;
+    }>;
+}
+//# sourceMappingURL=base-contract-client.d.ts.map

package/dist/settlement/base-contract-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-contract-client.d.ts","sourceRoot":"","sources":["../../src/settlement/base-contract-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,GAAG,EACR,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAEd,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKvB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMvB,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,kBAAkB;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,eAAe,CAA0B;gBAErC,OAAO,CAAC,EAAE;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;QAClC,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,YAAY,CAAC,EAAE,YAAY,CAAC;KAC7B;IAcD;;OAEG;IACU,qBAAqB,CAAC,MAAM,EAAE;QACzC,MAAM,EAAE,GAAG,CAAC;QACZ,SAAS,EAAE,iBAAiB,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,uBAAuB,CAAA;KAAE,CAAC;CAkInF"}

package/dist/settlement/base-contract-client.js

@@ -0,0 +1,156 @@
+/**
+ * ToolPay Base Contract Client
+ * Connects to live Base L2 RPC, decodes ToolPayRouter on-chain events, and verifies settlements.
+ */
+import { createPublicClient, http, defineChain, parseEventLogs, } from 'viem';
+import { TOOLPAY_ROUTER_ABI } from '../contracts/ToolPayRouter.js';
+import { normalizeNonceToBytes32 } from '../utils/units.js';
+export const BASE_MAINNET = defineChain({
+    id: 8453,
+    name: 'Base',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    rpcUrls: { default: { http: ['https://mainnet.base.org'] } },
+});
+export const BASE_SEPOLIA = defineChain({
+    id: 84532,
+    name: 'Base Sepolia',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    rpcUrls: { default: { http: ['https://sepolia.base.org'] } },
+    testnet: true,
+});
+export class BaseContractClient {
+    publicClient;
+    routerAddress;
+    chainId;
+    claimedTxHashes = new Set();
+    constructor(options) {
+        const network = options?.network || 'base';
+        const chain = network === 'base-sepolia' ? BASE_SEPOLIA : BASE_MAINNET;
+        this.chainId = chain.id;
+        this.routerAddress = options?.routerAddress;
+        this.publicClient =
+            options?.publicClient ||
+                createPublicClient({
+                    chain,
+                    transport: http(options?.rpcUrl || chain.rpcUrls.default.http[0]),
+                });
+    }
+    /**
+     * Verifies an on-chain transaction receipt against ToolPayRouter PaymentSettled events.
+     */
+    async verifyContractPayment(params) {
+        const txHashNormalized = params.txHash.toLowerCase();
+        if (this.claimedTxHashes.has(txHashNormalized)) {
+            return {
+                valid: false,
+                error: `Transaction ${params.txHash} has already been claimed for another payment`,
+            };
+        }
+        this.claimedTxHashes.add(txHashNormalized);
+        try {
+            const receipt = await this.publicClient.waitForTransactionReceipt({
+                hash: params.txHash,
+                timeout: 15_000,
+            });
+            if (receipt.status !== 'success') {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return { valid: false, error: `Transaction reverted on-chain (status: ${receipt.status})` };
+            }
+            // Filter and decode PaymentSettled logs
+            const logs = parseEventLogs({
+                abi: TOOLPAY_ROUTER_ABI,
+                eventName: 'PaymentSettled',
+                logs: receipt.logs,
+            });
+            if (logs.length === 0) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return { valid: false, error: 'No ToolPayRouter.PaymentSettled event found in transaction logs' };
+            }
+            const expectedNonceBytes32 = normalizeNonceToBytes32(params.challenge.challengeNonce).toLowerCase();
+            // Find event specifically matching challenge nonce
+            const matchingLog = logs.find((l) => {
+                const ev = l.args;
+                return ev.challengeNonce && ev.challengeNonce.toLowerCase() === expectedNonceBytes32;
+            });
+            if (!matchingLog) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `No PaymentSettled event matching challenge nonce ${params.challenge.challengeNonce} (${expectedNonceBytes32})`,
+                };
+            }
+            if (this.routerAddress && matchingLog.address && matchingLog.address.toLowerCase() !== this.routerAddress.toLowerCase()) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event emitted from unexpected contract address (expected ${this.routerAddress}, got ${matchingLog.address})`,
+                };
+            }
+            const event = matchingLog.args;
+            if (params.signerWallet && event.agent && event.agent.toLowerCase() !== params.signerWallet.toLowerCase()) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event agent mismatch: on-chain transaction was paid by ${event.agent}, but payment proof was signed by ${params.signerWallet}`,
+                };
+            }
+            const expectedDeveloper = (params.challenge.developerWallet || params.challenge.recipientWallet).toLowerCase();
+            if (event.developer.toLowerCase() !== expectedDeveloper) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event developer mismatch (expected ${expectedDeveloper}, got ${event.developer})`,
+                };
+            }
+            if (params.challenge.serverId && event.serverId && event.serverId !== params.challenge.serverId) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event serverId mismatch (expected ${params.challenge.serverId}, got ${event.serverId})`,
+                };
+            }
+            if (params.challenge.toolName && event.toolName && event.toolName !== params.challenge.toolName) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event toolName mismatch (expected ${params.challenge.toolName}, got ${event.toolName})`,
+                };
+            }
+            if (event.grossAmount < params.challenge.amountMicro) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event gross amount ${event.grossAmount} is less than required ${params.challenge.amountMicro}`,
+                };
+            }
+            if (params.challenge.tokenAddress && event.token.toLowerCase() !== params.challenge.tokenAddress.toLowerCase()) {
+                this.claimedTxHashes.delete(txHashNormalized);
+                return {
+                    valid: false,
+                    error: `Event token mismatch (expected ${params.challenge.tokenAddress}, got ${event.token})`,
+                };
+            }
+            return {
+                valid: true,
+                payment: {
+                    challengeNonce: event.challengeNonce,
+                    agent: event.agent,
+                    developer: event.developer,
+                    token: event.token,
+                    grossAmountMicro: event.grossAmount,
+                    platformCutMicro: event.platformCut,
+                    developerPayoutMicro: event.developerPayout,
+                    serverId: event.serverId,
+                    toolName: event.toolName,
+                    blockNumber: receipt.blockNumber,
+                    transactionHash: params.txHash,
+                },
+            };
+        }
+        catch (err) {
+            this.claimedTxHashes.delete(txHashNormalized);
+            return { valid: false, error: `RPC verification error: ${err.message}` };
+        }
+    }
+}
+//# sourceMappingURL=base-contract-client.js.map

package/dist/settlement/base-contract-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-contract-client.js","sourceRoot":"","sources":["../../src/settlement/base-contract-client.ts"],"names":[],"mappings":"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"}

package/dist/settlement/nonce-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ToolPay Nonce Store & Replay Prevention Engine
+ * Manages atomic challenge nonces, expiration TTLs, and prevents replay attacks.
+ */
+import { X402ChallengeData } from '../types/x402.js';
+export type NonceStatus = 'PENDING' | 'EXPENDED' | 'EXPIRED';
+export interface StoredChallenge {
+    data: X402ChallengeData;
+    status: NonceStatus;
+    createdAt: number;
+    expendedAt?: number;
+}
+export declare const DEFAULT_CHALLENGE_TTL_SECONDS = 120;
+export declare const MAX_STORED_NONCES = 10000;
+export declare class NonceStore {
+    private store;
+    private ttlSeconds;
+    private opCount;
+    constructor(ttlSeconds?: number);
+    /**
+     * Generates a unique, cryptographically random challenge nonce and stores the challenge data.
+     */
+    createChallenge(challengeDataOmitNonce: Omit<X402ChallengeData, 'challengeNonce' | 'expiresAt'>, customTtlSeconds?: number, nowSec?: number): X402ChallengeData;
+    /**
+     * Checks if a challenge nonce is present in memory.
+     */
+    hasChallenge(nonce: string): boolean;
+    /**
+     * Records or restores an existing challenge into the store (e.g. from KV across isolates).
+     */
+    recordChallenge(challenge: X402ChallengeData): void;
+    /**
+     * Validates that a nonce exists, is pending, and has not expired without consuming it.
+     */
+    peekChallenge(nonce: string, nowSec?: number): X402ChallengeData;
+    /**
+     * Consumes a validated nonce, transitioning it to EXPENDED.
+     */
+    consumeChallenge(nonce: string): void;
+    /**
+     * Verifies that a nonce exists, is pending, and has not expired.
+     * Atomically marks it as EXPENDED.
+     */
+    verifyAndConsume(nonce: string, nowSec?: number): X402ChallengeData;
+    /**
+     * Checks the status of a nonce without consuming it.
+     */
+    getChallenge(nonce: string): StoredChallenge | undefined;
+    /**
+     * Garbage collects expired nonces.
+     */
+    pruneExpired(nowSec?: number): number;
+}
+//# sourceMappingURL=nonce-store.d.ts.map

package/dist/settlement/nonce-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-store.d.ts","sourceRoot":"","sources":["../../src/settlement/nonce-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAa;gBAEhB,UAAU,GAAE,MAAsC;IAI9D;;OAEG;IACI,eAAe,CACpB,sBAAsB,EAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,WAAW,CAAC,EAC/E,gBAAgB,CAAC,EAAE,MAAM,EACzB,MAAM,GAAE,MAAsC,GAC7C,iBAAiB;IAmCpB;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI3C;;OAEG;IACI,eAAe,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAQ1D;;OAEG;IACI,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAsC,GAAG,iBAAiB;IAmBtG;;OAEG;IACI,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY5C;;;OAGG;IACI,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAsC,GAAG,iBAAiB;IAMzG;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI/D;;OAEG;IACI,YAAY,CAAC,MAAM,GAAE,MAAsC,GAAG,MAAM;CAU5E"}