pivx-402 1.0.0

package/dist/src/backends/explorer.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplorerBackend = void 0;
+class ExplorerBackend {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async getTransaction(txid) {
+        const fetchImpl = this.cfg.fetchImpl ?? fetch;
+        const url = `${this.cfg.baseUrl.replace(/\/$/, "")}/api/v2/tx/${encodeURIComponent(txid)}`;
+        const res = await fetchImpl(url, { headers: { accept: "application/json" } });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`explorer ${url} returned ${res.status}`);
+        const tx = (await res.json());
+        return {
+            txid: tx.txid,
+            confirmations: tx.confirmations ?? 0,
+            outputs: tx.vout.map(mapVout),
+        };
+    }
+}
+exports.ExplorerBackend = ExplorerBackend;
+function mapVout(v) {
+    const opReturn = v.hex && v.hex.startsWith("6a") ? decodeOpReturnHex(v.hex) : null;
+    if (opReturn !== null) {
+        return { value: null, address: null, opReturnText: opReturn };
+    }
+    return {
+        value: satsStringToPivString(v.value),
+        address: v.addresses && v.addresses[0] ? v.addresses[0] : null,
+        opReturnText: null,
+    };
+}
+function satsStringToPivString(sats) {
+    // BlockBook reports satoshi-equivalents as a decimal string.
+    const n = BigInt(sats);
+    const whole = n / 100000000n;
+    const frac = (n % 100000000n).toString().padStart(8, "0");
+    return `${whole}.${frac}`;
+}
+function decodeOpReturnHex(scriptHex) {
+    // scriptHex: "6a" + push opcode/length + data
+    // Common forms: 6a <1-75 length><data>, 6a 4c <length><data> (OP_PUSHDATA1), etc.
+    let i = 2;
+    let len;
+    const next = parseInt(scriptHex.slice(i, i + 2), 16);
+    if (Number.isNaN(next))
+        return null;
+    if (next <= 0x4b) {
+        len = next;
+        i += 2;
+    }
+    else if (next === 0x4c) {
+        len = parseInt(scriptHex.slice(i + 2, i + 4), 16);
+        i += 4;
+    }
+    else if (next === 0x4d) {
+        // little-endian uint16
+        const b0 = parseInt(scriptHex.slice(i + 2, i + 4), 16);
+        const b1 = parseInt(scriptHex.slice(i + 4, i + 6), 16);
+        len = b0 | (b1 << 8);
+        i += 6;
+    }
+    else {
+        return null;
+    }
+    const dataHex = scriptHex.slice(i, i + len * 2);
+    if (dataHex.length !== len * 2)
+        return null;
+    try {
+        return Buffer.from(dataHex, "hex").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/backends/index.d.ts

@@ -0,0 +1,15 @@
+import type { ShieldedTxInfo, TxInfo } from "../types";
+export interface PivxBackend {
+    /** Returns the transaction, or null if not (yet) known to the backend. */
+    getTransaction(txid: string): Promise<TxInfo | null>;
+    /**
+     * Decode the shielded portion of a transaction using viewing keys held by
+     * this backend. Optional: explorer-only backends cannot implement this, since
+     * shielded outputs are encrypted on-chain.
+     */
+    viewShieldedTransaction?(txid: string): Promise<ShieldedTxInfo | null>;
+}
+export { NodeRpcBackend } from "./node-rpc";
+export type { NodeRpcConfig } from "./node-rpc";
+export { ExplorerBackend } from "./explorer";
+export type { ExplorerConfig } from "./explorer";

package/dist/src/backends/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplorerBackend = exports.NodeRpcBackend = void 0;
+var node_rpc_1 = require("./node-rpc");
+Object.defineProperty(exports, "NodeRpcBackend", { enumerable: true, get: function () { return node_rpc_1.NodeRpcBackend; } });
+var explorer_1 = require("./explorer");
+Object.defineProperty(exports, "ExplorerBackend", { enumerable: true, get: function () { return explorer_1.ExplorerBackend; } });

package/dist/src/backends/node-rpc.d.ts

@@ -0,0 +1,17 @@
+import type { PivxBackend } from "./index";
+import type { ShieldedTxInfo, TxInfo } from "../types";
+export interface NodeRpcConfig {
+    /** e.g. http://127.0.0.1:51473 */
+    url: string;
+    username?: string;
+    password?: string;
+    /** Optional fetch override (for tests). */
+    fetchImpl?: typeof fetch;
+}
+export declare class NodeRpcBackend implements PivxBackend {
+    private readonly cfg;
+    constructor(cfg: NodeRpcConfig);
+    getTransaction(txid: string): Promise<TxInfo | null>;
+    viewShieldedTransaction(txid: string): Promise<ShieldedTxInfo | null>;
+    private call;
+}

package/dist/src/backends/node-rpc.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRpcBackend = void 0;
+class NodeRpcBackend {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async getTransaction(txid) {
+        let raw;
+        try {
+            raw = await this.call("getrawtransaction", [txid, true]);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/No such mempool|No information available|-5/i.test(msg))
+                return null;
+            throw err;
+        }
+        if (!raw)
+            return null;
+        const outputs = raw.vout.map((v) => {
+            const isOpReturn = v.scriptPubKey.asm?.startsWith("OP_RETURN");
+            if (isOpReturn) {
+                return {
+                    value: null,
+                    address: null,
+                    opReturnText: decodeOpReturnAsm(v.scriptPubKey.asm),
+                };
+            }
+            const address = v.scriptPubKey.address ??
+                (v.scriptPubKey.addresses && v.scriptPubKey.addresses[0]) ??
+                null;
+            return {
+                value: typeof v.value === "number" ? v.value.toFixed(8) : String(v.value),
+                address,
+                opReturnText: null,
+            };
+        });
+        return {
+            txid: raw.txid,
+            confirmations: raw.confirmations ?? 0,
+            outputs,
+        };
+    }
+    async viewShieldedTransaction(txid) {
+        // viewshieldtransaction returns the decrypted outputs (requires viewing keys
+        // in the wallet) but no confirmations; getrawtransaction returns
+        // confirmations for any tx the node knows about. Fire both in parallel —
+        // they're independent and each is a network round-trip.
+        const [rawResult, chainResult] = await Promise.allSettled([
+            this.call("viewshieldtransaction", [txid]),
+            this.call("getrawtransaction", [txid, true]),
+        ]);
+        if (rawResult.status === "rejected") {
+            const msg = rawResult.reason instanceof Error
+                ? rawResult.reason.message
+                : String(rawResult.reason);
+            // -5: not in wallet (no viewing key for any output). Treat as "not visible".
+            // -1: txid not found. Either way the verifier should see "tx_not_found".
+            if (/No such mempool|No information available|-5|-1/i.test(msg))
+                return null;
+            throw rawResult.reason;
+        }
+        const raw = rawResult.value;
+        if (!raw)
+            return null;
+        let confirmations = 0;
+        if (chainResult.status === "fulfilled") {
+            confirmations = chainResult.value?.confirmations ?? 0;
+        }
+        else {
+            const msg = chainResult.reason instanceof Error
+                ? chainResult.reason.message
+                : String(chainResult.reason);
+            if (!/No such mempool|No information available|-5/i.test(msg))
+                throw chainResult.reason;
+            // tx not yet on the chain or in mempool — treat as 0 confirmations.
+        }
+        const shieldedOutputs = (raw.outputs ?? []).map((o) => ({
+            address: o.address,
+            value: typeof o.value === "number"
+                ? o.value.toFixed(8)
+                : typeof o.valueSat === "number"
+                    ? satsNumToPivStr(o.valueSat)
+                    : "0.00000000",
+            memoText: o.memoStr ?? decodeMemoHex(o.memo),
+            outgoing: o.outgoing === true,
+        }));
+        return {
+            txid: raw.txid,
+            confirmations,
+            shieldedOutputs,
+        };
+    }
+    async call(method, params) {
+        const fetchImpl = this.cfg.fetchImpl ?? fetch;
+        const headers = { "content-type": "application/json" };
+        if (this.cfg.username || this.cfg.password) {
+            const token = Buffer.from(`${this.cfg.username ?? ""}:${this.cfg.password ?? ""}`).toString("base64");
+            headers["authorization"] = `Basic ${token}`;
+        }
+        const res = await fetchImpl(this.cfg.url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ jsonrpc: "1.0", id: "pivx402", method, params }),
+        });
+        const body = (await res.json());
+        if (body.error)
+            throw new Error(`pivxd rpc ${method}: ${body.error.message}`);
+        return body.result;
+    }
+}
+exports.NodeRpcBackend = NodeRpcBackend;
+function satsNumToPivStr(sats) {
+    const whole = Math.trunc(sats / 1e8);
+    const frac = (sats - whole * 1e8).toString().padStart(8, "0");
+    return `${whole}.${frac}`;
+}
+function decodeMemoHex(memo) {
+    if (!memo)
+        return null;
+    if (!/^[0-9a-fA-F]*$/.test(memo) || memo.length % 2 !== 0)
+        return null;
+    try {
+        // Sapling memos are 512 bytes padded with 0x00; strip trailing nulls.
+        const buf = Buffer.from(memo, "hex");
+        let end = buf.length;
+        while (end > 0 && buf[end - 1] === 0x00)
+            end--;
+        return buf.subarray(0, end).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function decodeOpReturnAsm(asm) {
+    // asm looks like "OP_RETURN <hex>" or "OP_RETURN -1234" for numeric pushes.
+    const rest = asm.slice("OP_RETURN".length).trim();
+    if (!rest)
+        return "";
+    // Take the first whitespace-delimited token; PIVX's OP_RETURN typically holds one push.
+    const token = rest.split(/\s+/)[0];
+    if (/^[0-9a-fA-F]+$/.test(token) && token.length % 2 === 0) {
+        try {
+            return Buffer.from(token, "hex").toString("utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/src/client.d.ts

@@ -0,0 +1,40 @@
+import type { PaymentRequirement } from "./types";
+/**
+ * A function that pays a payment requirement and returns the broadcast txid.
+ *
+ * Implementations are responsible for:
+ *   - constructing a PIVX transaction that pays `req.maxAmountRequired` PIV to `req.payTo`
+ *   - embedding `req.nonce` (as OP_RETURN for transparent, as the memo for shield)
+ *   - broadcasting it
+ *
+ * AI agents typically supply a payer that calls into a wallet, custodian, or signer.
+ */
+export type Payer = (req: PaymentRequirement) => Promise<string>;
+export interface PayAndFetchOptions {
+    /** Request init forwarded to fetch (method, headers, body, etc.). */
+    init?: RequestInit;
+    /** Optional fetch override (for tests or non-browser runtimes). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Choose a payment requirement when the server advertises more than one.
+     * Default: pick the first.
+     */
+    pickRequirement?: (accepts: PaymentRequirement[]) => PaymentRequirement;
+}
+export interface PayAndFetchResult {
+    response: Response;
+    requirement: PaymentRequirement;
+    txid: string;
+}
+/**
+ * Fetch a 402-gated URL, paying it through the supplied `payer` if required.
+ *
+ * Flow:
+ *   1. GET the URL.
+ *   2. If 200, return immediately (no payment needed).
+ *   3. If 402, decode the X-Payment-Required header, hand the requirement to
+ *      the payer, and retry the request with X-Payment set to the proof.
+ *
+ * Any other status surfaces directly on the returned `response`.
+ */
+export declare function payAndFetch(url: string, payer: Payer, opts?: PayAndFetchOptions): Promise<PayAndFetchResult>;

package/dist/src/client.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.payAndFetch = payAndFetch;
+const headers_1 = require("./headers");
+/**
+ * Fetch a 402-gated URL, paying it through the supplied `payer` if required.
+ *
+ * Flow:
+ *   1. GET the URL.
+ *   2. If 200, return immediately (no payment needed).
+ *   3. If 402, decode the X-Payment-Required header, hand the requirement to
+ *      the payer, and retry the request with X-Payment set to the proof.
+ *
+ * Any other status surfaces directly on the returned `response`.
+ */
+async function payAndFetch(url, payer, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const first = await fetchImpl(url, opts.init);
+    if (first.status !== 402) {
+        return { response: first, requirement: emptyRequirement(), txid: "" };
+    }
+    const header = first.headers.get(headers_1.HEADER_PAYMENT_REQUIRED.toLowerCase());
+    if (!header) {
+        throw new Error(`server returned 402 with no ${headers_1.HEADER_PAYMENT_REQUIRED} header`);
+    }
+    // Drain so the connection can be reused.
+    await first.arrayBuffer();
+    const envelope = (0, headers_1.decodeRequirements)(header);
+    if (!envelope.accepts.length) {
+        throw new Error("X-Payment-Required envelope has no accepted payment options");
+    }
+    const requirement = opts.pickRequirement
+        ? opts.pickRequirement(envelope.accepts)
+        : envelope.accepts[0];
+    const txid = await payer(requirement);
+    if (!txid)
+        throw new Error("payer returned an empty txid");
+    const proof = {
+        x402Version: 1,
+        scheme: requirement.scheme,
+        network: requirement.network,
+        payload: { txid, nonce: requirement.nonce },
+    };
+    const init = {
+        ...(opts.init ?? {}),
+        headers: {
+            ...(opts.init?.headers ?? {}),
+            [headers_1.HEADER_PAYMENT]: (0, headers_1.encodeProof)(proof),
+        },
+    };
+    const response = await fetchImpl(url, init);
+    return { response, requirement, txid };
+}
+function emptyRequirement() {
+    return {
+        scheme: "pivx-transparent",
+        network: "pivx-mainnet",
+        asset: "PIV",
+        maxAmountRequired: "0",
+        payTo: "",
+        nonce: "",
+        minConfirmations: 0,
+        maxTimeoutSeconds: 0,
+        resource: "",
+    };
+}

package/dist/src/headers.d.ts

@@ -0,0 +1,20 @@
+import type { PaymentProof, PaymentRequiredEnvelope } from "./types";
+export declare const HEADER_PAYMENT_REQUIRED = "X-Payment-Required";
+export declare const HEADER_PAYMENT = "X-Payment";
+/**
+ * Hard cap on the base64-encoded X-Payment header. A valid proof is ~200 bytes;
+ * 8KB leaves comfortable headroom while bounding what we'll decode and parse.
+ */
+export declare const MAX_PAYMENT_HEADER_BYTES: number;
+export declare function encodeRequirements(env: PaymentRequiredEnvelope): string;
+export declare function decodeRequirements(header: string): PaymentRequiredEnvelope;
+export declare function encodeProof(proof: PaymentProof): string;
+/**
+ * Decode and validate an X-Payment header. Throws on:
+ *   - oversized input (> MAX_PAYMENT_HEADER_BYTES)
+ *   - invalid JSON
+ *   - wrong shape (missing/typed-wrong fields, unknown scheme/network)
+ *
+ * Callers should treat any throw as a 400-class client error.
+ */
+export declare function decodeProof(header: string): PaymentProof;

package/dist/src/headers.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PAYMENT_HEADER_BYTES = exports.HEADER_PAYMENT = exports.HEADER_PAYMENT_REQUIRED = void 0;
+exports.encodeRequirements = encodeRequirements;
+exports.decodeRequirements = decodeRequirements;
+exports.encodeProof = encodeProof;
+exports.decodeProof = decodeProof;
+exports.HEADER_PAYMENT_REQUIRED = "X-Payment-Required";
+exports.HEADER_PAYMENT = "X-Payment";
+/**
+ * Hard cap on the base64-encoded X-Payment header. A valid proof is ~200 bytes;
+ * 8KB leaves comfortable headroom while bounding what we'll decode and parse.
+ */
+exports.MAX_PAYMENT_HEADER_BYTES = 8 * 1024;
+function b64encode(json) {
+    return Buffer.from(JSON.stringify(json), "utf8").toString("base64");
+}
+function b64decode(value) {
+    return JSON.parse(Buffer.from(value, "base64").toString("utf8"));
+}
+function encodeRequirements(env) {
+    return b64encode(env);
+}
+function decodeRequirements(header) {
+    return b64decode(header);
+}
+function encodeProof(proof) {
+    return b64encode(proof);
+}
+const VALID_SCHEMES = new Set(["pivx-transparent", "pivx-shield"]);
+const VALID_NETWORKS = new Set([
+    "pivx-mainnet",
+    "pivx-testnet",
+    "pivx-regtest",
+]);
+/**
+ * Decode and validate an X-Payment header. Throws on:
+ *   - oversized input (> MAX_PAYMENT_HEADER_BYTES)
+ *   - invalid JSON
+ *   - wrong shape (missing/typed-wrong fields, unknown scheme/network)
+ *
+ * Callers should treat any throw as a 400-class client error.
+ */
+function decodeProof(header) {
+    if (header.length > exports.MAX_PAYMENT_HEADER_BYTES) {
+        throw new Error(`X-Payment header exceeds ${exports.MAX_PAYMENT_HEADER_BYTES} bytes`);
+    }
+    const parsed = b64decode(header);
+    if (!isPaymentProof(parsed)) {
+        throw new Error("malformed payment proof");
+    }
+    return parsed;
+}
+function isPaymentProof(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const p = v;
+    if (p.x402Version !== 1)
+        return false;
+    if (typeof p.scheme !== "string" || !VALID_SCHEMES.has(p.scheme))
+        return false;
+    if (typeof p.network !== "string" || !VALID_NETWORKS.has(p.network))
+        return false;
+    if (!p.payload || typeof p.payload !== "object")
+        return false;
+    const payload = p.payload;
+    // PIVX txids are 32-byte hashes: exactly 64 hex chars. Rejecting anything
+    // else here keeps malformed ids from reaching the backend RPC/explorer.
+    if (typeof payload.txid !== "string" || !/^[0-9a-fA-F]{64}$/.test(payload.txid))
+        return false;
+    if (typeof payload.nonce !== "string" || payload.nonce.length === 0)
+        return false;
+    return true;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./headers";
+export * from "./amount";
+export * from "./nonce-store";
+export * from "./verifier";
+export * from "./middleware";
+export * from "./backends";
+export * from "./client";

package/dist/src/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./headers"), exports);
+__exportStar(require("./amount"), exports);
+__exportStar(require("./nonce-store"), exports);
+__exportStar(require("./verifier"), exports);
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./backends"), exports);
+__exportStar(require("./client"), exports);

package/dist/src/middleware.d.ts

@@ -0,0 +1,50 @@
+import type { Request, RequestHandler } from "express";
+import { type NonceStore } from "./nonce-store";
+import type { PivxBackend } from "./backends";
+import type { Network, Scheme } from "./types";
+export interface PriceConfig {
+    /** Decimal PIV, e.g. "0.01". */
+    amount: string;
+    /** Receiving PIVX address. */
+    payTo: string;
+    description?: string;
+}
+/**
+ * Per-request price, returned either synchronously or asynchronously.
+ * Use the async form when the price depends on a database/external lookup.
+ */
+export type PriceResolver = (req: Request) => PriceConfig | Promise<PriceConfig>;
+export interface MiddlewareOptions {
+    backend: PivxBackend;
+    network: Network;
+    scheme?: Scheme;
+    minConfirmations?: number;
+    maxTimeoutSeconds?: number;
+    /** Static price, or a per-request function (may be async). */
+    price: PriceConfig | PriceResolver;
+    /**
+     * Replay-protection store. Defaults to a per-middleware in-memory store.
+     *
+     * IMPORTANT: if you mount pivx402() on multiple routes that share the same
+     * payTo, scheme, and price, you MUST pass the *same* nonceStore instance to
+     * each — otherwise a single broadcast tx can be redeemed against every route.
+     * For multi-process deployments, supply a shared backing store (e.g. Redis).
+     */
+    nonceStore?: NonceStore;
+}
+/** Data the middleware attaches to a successful request before next(). */
+export interface Pivx402RequestContext {
+    txid: string;
+    nonce: string;
+    scheme: Scheme;
+    network: Network;
+    amount: string;
+    payTo: string;
+}
+declare module "express-serve-static-core" {
+    interface Request {
+        /** Set by the pivx402 middleware after a successful payment verification. */
+        pivx402?: Pivx402RequestContext;
+    }
+}
+export declare function pivx402(opts: MiddlewareOptions): RequestHandler;

package/dist/src/middleware.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pivx402 = pivx402;
+const headers_1 = require("./headers");
+const nonce_store_1 = require("./nonce-store");
+const verifier_1 = require("./verifier");
+function pivx402(opts) {
+    const scheme = opts.scheme ?? "pivx-transparent";
+    const nonceStore = opts.nonceStore ?? new nonce_store_1.InMemoryNonceStore();
+    const verifier = new verifier_1.Verifier({ backend: opts.backend, nonceStore });
+    return async (req, res, next) => {
+        const price = await (typeof opts.price === "function" ? opts.price(req) : opts.price);
+        const header = req.header(headers_1.HEADER_PAYMENT);
+        if (!header) {
+            return sendPaymentRequired(res, {
+                scheme,
+                network: opts.network,
+                asset: "PIV",
+                maxAmountRequired: price.amount,
+                payTo: price.payTo,
+                nonce: (0, nonce_store_1.randomNonce)(),
+                minConfirmations: opts.minConfirmations ?? 1,
+                maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 600,
+                resource: req.originalUrl,
+                description: price.description,
+            });
+        }
+        let proof;
+        try {
+            proof = (0, headers_1.decodeProof)(header);
+        }
+        catch (err) {
+            return res.status(400).json({ error: "malformed_payment_header" });
+        }
+        // Reconstruct the requirement from the proof's nonce + current price.
+        // The nonce came from a prior 402 we issued; the client echoes it back.
+        const requirement = {
+            scheme,
+            network: opts.network,
+            asset: "PIV",
+            maxAmountRequired: price.amount,
+            payTo: price.payTo,
+            nonce: proof.payload.nonce,
+            minConfirmations: opts.minConfirmations ?? 1,
+            maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 600,
+            resource: req.originalUrl,
+            description: price.description,
+        };
+        let result;
+        try {
+            result = await verifier.verify(requirement, proof);
+        }
+        catch (err) {
+            // Backend RPC/explorer failures shouldn't crash the process. Surface as
+            // a retryable 402 so the client (e.g. pay-cli) treats it like an upstream
+            // hiccup and reissues the proof. Don't leak the error string to the wire.
+            // eslint-disable-next-line no-console
+            console.error("[pivx402] backend error during verify:", err);
+            return sendPaymentRequired(res, { ...requirement, nonce: (0, nonce_store_1.randomNonce)() }, "tx_not_found: backend temporarily unavailable");
+        }
+        if (!result.ok) {
+            return sendPaymentRequired(res, { ...requirement, nonce: (0, nonce_store_1.randomNonce)() }, `${result.reason}${result.details ? `: ${result.details}` : ""}`);
+        }
+        req.pivx402 = {
+            txid: proof.payload.txid,
+            nonce: requirement.nonce,
+            scheme: requirement.scheme,
+            network: requirement.network,
+            amount: requirement.maxAmountRequired,
+            payTo: requirement.payTo,
+        };
+        return next();
+    };
+}
+function sendPaymentRequired(res, req, error) {
+    res
+        .status(402)
+        .setHeader(headers_1.HEADER_PAYMENT_REQUIRED, (0, headers_1.encodeRequirements)({ x402Version: 1, accepts: [req], error }))
+        .json({
+        x402Version: 1,
+        accepts: [req],
+        ...(error ? { error } : {}),
+    });
+}

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

@@ -0,0 +1,16 @@
+export interface NonceStore {
+    /** Returns true if claimed by this caller; false if already used. */
+    claim(nonce: string): Promise<boolean>;
+}
+/** In-memory store. Fine for a single process; swap for Redis in production. */
+export declare class InMemoryNonceStore implements NonceStore {
+    private readonly ttlMs;
+    private readonly used;
+    private lastSweep;
+    /** Minimum gap between sweeps. Sweep is O(n); don't run it on every claim. */
+    private static readonly SWEEP_INTERVAL_MS;
+    constructor(ttlMs?: number);
+    claim(nonce: string): Promise<boolean>;
+    private maybeSweep;
+}
+export declare function randomNonce(): string;