@odatano/x402 0.1.0

package/srv/core/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Public type surface for x402 Cardano-v2.
+ *
+ * The shapes here match the v2 spec excerpt in
+ * `docs/x402-cardano-integration.md` (envelope, requirements, payload).
+ * Keep them as the single source of truth — middleware, facilitator and
+ * helpers all import from here.
+ */
+import type { Network } from './network';
+/** Asset-transfer method. v2 spec.  MVP supports only `default`. */
+export type AssetTransferMethod = 'default' | 'masumi' | 'script';
+/** v2 resource descriptor — was a bare string in v1. */
+export interface ResourceDescriptor {
+    url: string;
+    description: string;
+    mimeType: string;
+    /** Optional, free-form JSON Schema for the resource's response body. */
+    outputSchema?: unknown;
+}
+/** A single `accepts[]` entry of the 402 body. */
+export interface PaymentRequirementEntry {
+    scheme: 'exact';
+    network: Network;
+    /**
+     * v2 asset format: `<policyIdHex>.<assetNameHex>` (dot-separated) OR
+     * the literal `'lovelace'` for ADA payments.
+     */
+    asset: string;
+    /** Required asset amount in raw units (BigInt-safe string). */
+    amount: string;
+    /** Bech32 recipient. */
+    payTo: string;
+    resource: ResourceDescriptor;
+    assetTransferMethod: AssetTransferMethod;
+    maxTimeoutSeconds: number;
+    /** Optional opaque extra fields (e.g. UI hints, decimals). */
+    extra?: Record<string, unknown>;
+}
+/** Canonical 402-response body. */
+export interface PaymentRequirementsBody {
+    x402Version: 2;
+    error?: string;
+    accepts: PaymentRequirementEntry[];
+}
+/**
+ * Decoded `PAYMENT-SIGNATURE` envelope. The envelope payload references
+ * a buyer-funded UTxO (the **nonce**) which must also appear in the
+ * payment tx's inputs — this is the v2 replay defense, on-chain.
+ */
+export interface PaymentEnvelope {
+    x402Version: 2;
+    scheme: 'exact';
+    network: string;
+    payload: {
+        /** base64 CBOR of the signed payment tx */
+        transaction: string;
+        /** `<txHash>#<outputIndex>` — UTxO acting as replay nonce */
+        nonce: string;
+    };
+}
+/** Result of pure validation (no chain calls). */
+export interface PaymentClaim {
+    /** Hash of the buyer's signed payment tx (lowercase hex, 64 chars). */
+    txHash: string;
+    /** Amount actually paid to `payTo` for `asset`, summed across outputs. */
+    amountUnits: string;
+    network: Network;
+    /** Resolved v2 unit key (`policyId+nameHex` or empty for lovelace). */
+    unit: string;
+    /** The v2 asset string from requirements (passed-through for audit). */
+    asset: string;
+    /** The route / resource URL the buyer paid for. */
+    resourceUrl: string;
+    /** UTxO-ref nonce as `<txHash>#<index>`. */
+    nonceRef: string;
+    /** Earliest of the buyer's input tx hashes; useful for analytics. */
+    payerAddr?: string;
+}
+/** Diagnostic shape returned by `decode()` for downstream validation. */
+export interface DecodedPayment {
+    envelope: PaymentEnvelope;
+    /** Hex of the signed-tx CBOR (preserved bytes, NOT a re-encode). */
+    txCborHex: string;
+    /** Hash of the tx body, lowercase 64-char hex. */
+    txHash: string;
+    outputs: DecodedOutput[];
+    inputs: DecodedInput[];
+    vkeyWitnessCount: number;
+    /** Validity-range upper bound in slots (`null` ⇒ no TTL set). */
+    ttlSlot: number | null;
+    /** Validity-range lower bound in slots (`null` ⇒ no lower bound set). */
+    validityStartSlot: number | null;
+    /** Parsed nonce reference. */
+    nonce: {
+        txHash: string;
+        index: number;
+    };
+}
+export interface DecodedOutput {
+    outputIndex: number;
+    address: string;
+    lovelace: string;
+    assets: DecodedAsset[];
+}
+export interface DecodedAsset {
+    unit: string;
+    policyId: string;
+    assetNameHex: string;
+    quantity: string;
+}
+export interface DecodedInput {
+    txHash: string;
+    outputIndex: number;
+}
+export type { Network };
+//# sourceMappingURL=types.d.ts.map

package/srv/core/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Public type surface for x402 Cardano-v2.
+ *
+ * The shapes here match the v2 spec excerpt in
+ * `docs/x402-cardano-integration.md` (envelope, requirements, payload).
+ * Keep them as the single source of truth — middleware, facilitator and
+ * helpers all import from here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/srv/core/validate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Validate a decoded payment against payment requirements.
+ *
+ * Implements the **6 mandatory facilitator checks** from
+ * Cardano-x402-v2:
+ *
+ *   1. Network validation
+ *   2. Recipient verification           — ≥1 output to payTo
+ *   3. Amount verification              — sum of payTo outputs for asset ≥ required
+ *   4. Asset verification               — exact policy + name match
+ *   5. Nonce / replay prevention
+ *      - 5a. UTxO referenced by `payload.nonce` appears as a tx input
+ *      - 5b. that UTxO is still unspent on chain  ← chain-touching, lives in `nonce.ts`
+ *   6. TTL / expiry                     — tx.validity_range.upper_bound in future
+ *
+ * This module covers (1), (2), (3), (4), (5a) and (6). The chain-touching
+ * part of (5) — checking the UTxO is unspent — and (5b) live in
+ * `facilitator/nonce.ts` and run after this. We also keep a sanity guard
+ * for "no vkey witnesses" so an unsigned CBOR is rejected with a precise
+ * code rather than blowing up at submit time.
+ *
+ * Pure function. No I/O.
+ */
+import { type X402Code } from './errors';
+import type { DecodedPayment, PaymentRequirementEntry, PaymentClaim } from './types';
+export type ValidationResult = {
+    ok: true;
+    claim: PaymentClaim;
+} | {
+    ok: false;
+    code: X402Code;
+    reason: string;
+};
+export interface ValidateOptions {
+    /** Required: current slot, for TTL upper-bound check. */
+    currentSlot: number;
+    /**
+     * If true, allow tx with no `ttl()` set (validity-range upper bound
+     * absent). Default false — v2 spec recommends a TTL. Callers that
+     * want to accept no-TTL txs (e.g. legacy wallets) opt-in.
+     */
+    allowNoTtl?: boolean;
+}
+export declare function validatePayment(decoded: DecodedPayment, requirements: PaymentRequirementEntry, opts: ValidateOptions): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/srv/core/validate.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Validate a decoded payment against payment requirements.
+ *
+ * Implements the **6 mandatory facilitator checks** from
+ * Cardano-x402-v2:
+ *
+ *   1. Network validation
+ *   2. Recipient verification           — ≥1 output to payTo
+ *   3. Amount verification              — sum of payTo outputs for asset ≥ required
+ *   4. Asset verification               — exact policy + name match
+ *   5. Nonce / replay prevention
+ *      - 5a. UTxO referenced by `payload.nonce` appears as a tx input
+ *      - 5b. that UTxO is still unspent on chain  ← chain-touching, lives in `nonce.ts`
+ *   6. TTL / expiry                     — tx.validity_range.upper_bound in future
+ *
+ * This module covers (1), (2), (3), (4), (5a) and (6). The chain-touching
+ * part of (5) — checking the UTxO is unspent — and (5b) live in
+ * `facilitator/nonce.ts` and run after this. We also keep a sanity guard
+ * for "no vkey witnesses" so an unsigned CBOR is rejected with a precise
+ * code rather than blowing up at submit time.
+ *
+ * Pure function. No I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePayment = validatePayment;
+const errors_1 = require("./errors");
+const network_1 = require("./network");
+const asset_1 = require("./asset");
+function quantityOf(output, isLovelace, unit) {
+    if (isLovelace)
+        return BigInt(output.lovelace);
+    const a = output.assets.find(x => x.unit === unit);
+    return a ? BigInt(a.quantity) : 0n;
+}
+/**
+ * Total amount of `unit` paid to `payTo`, summed across ALL matching
+ * outputs. Summing is correct: a wallet may split a payment across
+ * multiple outputs (e.g. token + change), and we credit the full amount
+ * sent to our address.
+ */
+function totalPaid(decoded, payTo, isLovelace, unit) {
+    let total = 0n;
+    let anyOutputToRecipient = false;
+    for (const o of decoded.outputs) {
+        if (o.address !== payTo)
+            continue;
+        anyOutputToRecipient = true;
+        total += quantityOf(o, isLovelace, unit);
+    }
+    return { total, anyOutputToRecipient };
+}
+function validatePayment(decoded, requirements, opts) {
+    // ─── Sanity: witness present ───────────────────────────────────────
+    // An unsigned CBOR can't be submitted. Catch this here with a precise
+    // code rather than letting the submit step fail with a generic 400.
+    if (!decoded.vkeyWitnessCount || decoded.vkeyWitnessCount < 1) {
+        return {
+            ok: false,
+            code: errors_1.Codes.UNSIGNED_TRANSACTION,
+            reason: 'transaction has no vkey witnesses',
+        };
+    }
+    // ─── Check 1: network ──────────────────────────────────────────────
+    if (!(0, network_1.networksMatch)(decoded.envelope.network, requirements.network)) {
+        return {
+            ok: false,
+            code: errors_1.Codes.NETWORK_MISMATCH,
+            reason: `payment network '${decoded.envelope.network}' does not match requirements '${requirements.network}'`,
+        };
+    }
+    // Parse the asset string once — also normalises the requirement's
+    // unit key for output comparison.
+    const parsed = (0, asset_1.parseAsset)(requirements.asset);
+    const unit = parsed.unit; // empty when lovelace; checks short-circuit via isLovelace
+    const required = BigInt(requirements.amount);
+    const { total: paid, anyOutputToRecipient } = totalPaid(decoded, requirements.payTo, parsed.isLovelace, unit);
+    // ─── Check 2: recipient ────────────────────────────────────────────
+    if (!anyOutputToRecipient) {
+        return {
+            ok: false,
+            code: errors_1.Codes.WRONG_RECIPIENT,
+            reason: `no output to payTo address ${requirements.payTo}`,
+        };
+    }
+    // ─── Check 4: asset (run before amount so amount=0 reports as
+    //              WRONG_ASSET rather than INSUFFICIENT_AMOUNT) ─────────
+    if (paid === 0n) {
+        return {
+            ok: false,
+            code: errors_1.Codes.WRONG_ASSET,
+            reason: `outputs to payTo do not contain asset ${requirements.asset}`,
+        };
+    }
+    // ─── Check 3: amount ───────────────────────────────────────────────
+    if (paid < required) {
+        return {
+            ok: false,
+            code: errors_1.Codes.INSUFFICIENT_AMOUNT,
+            reason: `paid ${paid.toString()} < required ${required.toString()} of asset ${requirements.asset}`,
+        };
+    }
+    // ─── Check 5a: nonce UTxO appears in tx inputs ─────────────────────
+    // (5b — UTxO is unspent — runs in facilitator/nonce.ts after we've
+    // confirmed the buyer's structural intent here.)
+    const nonceInInputs = decoded.inputs.some(i => i.txHash === decoded.nonce.txHash && i.outputIndex === decoded.nonce.index);
+    if (!nonceInInputs) {
+        return {
+            ok: false,
+            code: errors_1.Codes.NONCE_NOT_REFERENCED,
+            reason: `nonce UTxO ${decoded.nonce.txHash}#${decoded.nonce.index} is not referenced as a tx input`,
+        };
+    }
+    // ─── Check 6: TTL / expiry ─────────────────────────────────────────
+    // Slot semantics: `ttl_bignum` is the FIRST slot at which the tx is
+    // INVALID — so the tx must be submitted before that slot. We require
+    // `currentSlot < ttlSlot`; equality means the window just closed.
+    if (decoded.ttlSlot === null) {
+        if (!opts.allowNoTtl) {
+            return {
+                ok: false,
+                code: errors_1.Codes.EXPIRED_TTL,
+                reason: 'transaction has no validity-range upper bound (ttl); set one or call with allowNoTtl=true',
+            };
+        }
+    }
+    else if (opts.currentSlot >= decoded.ttlSlot) {
+        return {
+            ok: false,
+            code: errors_1.Codes.EXPIRED_TTL,
+            reason: `ttl ${decoded.ttlSlot} already passed (current slot ${opts.currentSlot})`,
+        };
+    }
+    // ─── All structural checks pass ────────────────────────────────────
+    // `payerAddr` is intentionally omitted here — we don't have the
+    // buyer's input addresses without resolving the referenced UTxOs.
+    // The facilitator can fill it in via `bridge.getTransactionByHash`
+    // on the nonce input, if the caller cares for audit purposes.
+    const network = requirements.network;
+    return {
+        ok: true,
+        claim: {
+            txHash: decoded.txHash,
+            amountUnits: paid.toString(),
+            network,
+            unit,
+            asset: requirements.asset,
+            resourceUrl: requirements.resource.url,
+            nonceRef: `${decoded.nonce.txHash}#${decoded.nonce.index}`,
+        },
+    };
+}

package/srv/facilitator/nonce.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cardano-x402-v2 replay-defense check (mandatory check #5).
+ *
+ * v1 had a CDS entity `X402PaymentNonces` with a UNIQUE on txHash —
+ * replay defense was a DB UNIQUE-constraint race. v2 moves replay
+ * defense **on-chain**: the buyer references a specific UTxO in the
+ * envelope (`payload.nonce = "<txHash>#<index>"`), that UTxO must
+ * appear as an input of the payment tx, and once the tx settles the
+ * UTxO is permanently consumed. No DB table needed.
+ *
+ * Check #5 has two parts:
+ *   - 5a — the nonce UTxO appears in the tx inputs   (in validate.ts, pure)
+ *   - 5b — the nonce UTxO is still unspent on chain  (here, chain-touching)
+ *
+ * Order in the pipeline: `validate.ts` (which runs 5a) MUST run before
+ * `checkNonceUnspent` here. The chain-touching call below is a single
+ * `bridge.isUtxoUnspent` round-trip, backed by Blockfrost `consumed_by`
+ * / Koios `is_spent` / Ogmios `queryLedgerState/utxo`. Spent and
+ * nonexistent UTxOs both surface as `false` — both translate to REPLAY.
+ */
+import { type X402Code } from '../core/errors';
+export interface NonceCheckArgs {
+    /** 64-char hex tx-hash of the UTxO acting as replay nonce. */
+    txHash: string;
+    outputIndex: number;
+}
+export type NonceResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: X402Code;
+    reason: string;
+};
+export declare function checkNonceUnspent(args: NonceCheckArgs): Promise<NonceResult>;
+//# sourceMappingURL=nonce.d.ts.map

package/srv/facilitator/nonce.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Cardano-x402-v2 replay-defense check (mandatory check #5).
+ *
+ * v1 had a CDS entity `X402PaymentNonces` with a UNIQUE on txHash —
+ * replay defense was a DB UNIQUE-constraint race. v2 moves replay
+ * defense **on-chain**: the buyer references a specific UTxO in the
+ * envelope (`payload.nonce = "<txHash>#<index>"`), that UTxO must
+ * appear as an input of the payment tx, and once the tx settles the
+ * UTxO is permanently consumed. No DB table needed.
+ *
+ * Check #5 has two parts:
+ *   - 5a — the nonce UTxO appears in the tx inputs   (in validate.ts, pure)
+ *   - 5b — the nonce UTxO is still unspent on chain  (here, chain-touching)
+ *
+ * Order in the pipeline: `validate.ts` (which runs 5a) MUST run before
+ * `checkNonceUnspent` here. The chain-touching call below is a single
+ * `bridge.isUtxoUnspent` round-trip, backed by Blockfrost `consumed_by`
+ * / Koios `is_spent` / Ogmios `queryLedgerState/utxo`. Spent and
+ * nonexistent UTxOs both surface as `false` — both translate to REPLAY.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkNonceUnspent = checkNonceUnspent;
+const bridge = __importStar(require("../bridge"));
+const errors_1 = require("../core/errors");
+async function checkNonceUnspent(args) {
+    const unspent = await bridge.isUtxoUnspent(args.txHash, args.outputIndex);
+    if (!unspent) {
+        return {
+            ok: false,
+            code: errors_1.Codes.REPLAY,
+            reason: `nonce UTxO ${args.txHash}#${args.outputIndex} is spent or does not exist on chain`,
+        };
+    }
+    return { ok: true };
+}

package/srv/facilitator/settle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Submit a signed payment tx to Cardano and confirm settlement.
+ *
+ * Confirmation policy (v2 spec): accept after first chain sighting.
+ * `mempool` status is explicitly discouraged in v2 — Cardano's
+ * Ouroboros Praos has probabilistic finality, so "in mempool" gives
+ * no economic guarantee. We poll for first-chain-sighting via
+ * `getTransactionByHash` (resolves to non-null when Blockfrost / Koios
+ * has indexed the tx; that's effectively ≥1 confirmation).
+ *
+ * Confirmation budget: middleware paths use ~60s (covers preprod's
+ * worst-case block time of ~20s plus indexer lag). On timeout we
+ * return `{ confirmed: false, pending: true }` — the spec contract is
+ * that the buyer retries with the same `PAYMENT-SIGNATURE`. Replay
+ * defense (on-chain via UTxO nonce) ensures only one retry actually
+ * gets served.
+ */
+import { type X402Code } from '../core/errors';
+export interface SettleArgs {
+    /** Hex of the signed tx (NOT base64). */
+    signedTxCborHex: string;
+    /** Locally-computed tx hash from the FixedTransaction; we cross-check submit's response. */
+    expectedTxHash: string;
+    pollBudgetMs?: number;
+    pollIntervalMs?: number;
+}
+export interface SettleResult {
+    confirmed: boolean;
+    /** True iff submit succeeded but the tx is not yet indexed. */
+    pending?: boolean;
+    txHash?: string;
+    code?: X402Code;
+    reason?: string;
+}
+export declare function settle({ signedTxCborHex, expectedTxHash, pollBudgetMs, pollIntervalMs, }: SettleArgs): Promise<SettleResult>;
+//# sourceMappingURL=settle.d.ts.map

package/srv/facilitator/settle.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Submit a signed payment tx to Cardano and confirm settlement.
+ *
+ * Confirmation policy (v2 spec): accept after first chain sighting.
+ * `mempool` status is explicitly discouraged in v2 — Cardano's
+ * Ouroboros Praos has probabilistic finality, so "in mempool" gives
+ * no economic guarantee. We poll for first-chain-sighting via
+ * `getTransactionByHash` (resolves to non-null when Blockfrost / Koios
+ * has indexed the tx; that's effectively ≥1 confirmation).
+ *
+ * Confirmation budget: middleware paths use ~60s (covers preprod's
+ * worst-case block time of ~20s plus indexer lag). On timeout we
+ * return `{ confirmed: false, pending: true }` — the spec contract is
+ * that the buyer retries with the same `PAYMENT-SIGNATURE`. Replay
+ * defense (on-chain via UTxO nonce) ensures only one retry actually
+ * gets served.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settle = settle;
+const bridge = __importStar(require("../bridge"));
+const errors_1 = require("../core/errors");
+/**
+ * Patterns surfaced by the submit step that mean "the tx is already
+ * known to the network" — either in mempool or already mined. In
+ * both cases we should NOT treat as failure; we should fall through
+ * to polling.
+ *
+ *   - Blockfrost:    "Transaction is already in the mempool"
+ *   - Cardano node:  "ConwayMempoolFailure ... Transaction has probably already been included"
+ *   - Ouroboros:     "BadInputsUTxO" / "all inputs are spent"  (already mined)
+ *   - Generic:       "transaction already exists"
+ *
+ * The submit step's failure modes are heterogeneous across backends;
+ * regex matching is the only portable detector.
+ */
+const TX_ALREADY_KNOWN_RE = new RegExp([
+    'already (in (the )?(mempool|chain)|exists|been included)',
+    'transaction has probably already been included',
+    'all inputs are spent',
+    'badinputsutxo',
+    'valuenotconserved',
+    'inputsdepleted',
+].join('|'), 'i');
+async function settle({ signedTxCborHex, expectedTxHash, pollBudgetMs = 60_000, pollIntervalMs = 2_500, }) {
+    if (!signedTxCborHex)
+        throw new TypeError('settle: signedTxCborHex required');
+    if (!expectedTxHash)
+        throw new TypeError('settle: expectedTxHash required');
+    // 1. Submit
+    let submittedHash;
+    try {
+        submittedHash = await bridge.submitTransaction(signedTxCborHex);
+    }
+    catch (err) {
+        const msg = String(err?.message ?? err ?? '');
+        if (TX_ALREADY_KNOWN_RE.test(msg)) {
+            // Idempotency: another submit of the same CBOR already happened.
+            // Proceed to polling.
+            submittedHash = expectedTxHash;
+        }
+        else {
+            return {
+                confirmed: false,
+                code: errors_1.Codes.SUBMIT_FAILED,
+                reason: msg.slice(0, 200),
+            };
+        }
+    }
+    // Cross-check: backend's hash must match our locally-computed one.
+    // If it doesn't, something is structurally off — bail loudly.
+    if (submittedHash && submittedHash.toLowerCase() !== expectedTxHash.toLowerCase()) {
+        return {
+            confirmed: false,
+            code: errors_1.Codes.SUBMIT_FAILED,
+            reason: `submit returned hash ${submittedHash} but tx hashes to ${expectedTxHash}`,
+        };
+    }
+    // 2. Poll for first chain sighting.
+    const deadline = Date.now() + pollBudgetMs;
+    while (Date.now() < deadline) {
+        const tx = await bridge.getTransactionByHash(expectedTxHash);
+        if (tx)
+            return { confirmed: true, txHash: expectedTxHash };
+        await new Promise(r => setTimeout(r, pollIntervalMs));
+    }
+    // 3. Timed out.
+    return {
+        confirmed: false,
+        pending: true,
+        txHash: expectedTxHash,
+        code: errors_1.Codes.PENDING,
+        reason: 'transaction submitted but not yet visible on chain',
+    };
+}

package/srv/facilitator/verify.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The facilitator orchestrator: end-to-end pipeline from raw header to
+ * an `accepted | rejected | pending` outcome.
+ *
+ * Pipeline (v2):
+ *   1. decode               (PAYMENT-SIGNATURE → DecodedPayment)
+ *   2. validate             (6 mandatory checks, pure)
+ *   3. checkNonceUnspent    (chain — UTxO still spendable)
+ *   4. settle               (submit + poll-until-confirmed)
+ *   5. onAccepted callback  (consumer-side audit, best-effort)
+ *
+ * Order rationale:
+ *   - `validate` runs the input-side (5a) BEFORE `checkNonceUnspent`
+ *     does the chain-side (5b), so we avoid the round-trip for txs
+ *     whose inputs don't include the claimed nonce.
+ *   - `checkNonceUnspent` runs BEFORE `settle`, because submitting a
+ *     CBOR whose nonce was already spent will fail at the network
+ *     level anyway, and we want to return a precise REPLAY code
+ *     instead of a generic SUBMIT_FAILED.
+ *   - `onAccepted` runs ONLY after settle confirms — we never call it
+ *     for pending/rejected outcomes.
+ */
+import { type X402Code } from '../core/errors';
+import type { PaymentClaim, PaymentRequirementsBody } from '../core/types';
+export type ProcessKind = 'accepted' | 'rejected' | 'pending';
+export interface ProcessArgs {
+    /** Raw header value (undefined if missing). */
+    paymentHeader: string | string[] | undefined;
+    /** Full 402 body — the validator inspects `accepts[0]`. */
+    requirementsBody: PaymentRequirementsBody;
+    /** Optional override of the settle poll budget (ms). Default 60_000. */
+    settlePollBudgetMs?: number;
+    /**
+     * Optional: callback invoked on successful payment. Use for consumer-
+     * side audit (e.g. CHAINFEED writing to FeedReads, ODATAPAY writing to
+     * Receipts). Throws here are swallowed and logged — the canonical
+     * record is on chain.
+     */
+    onAccepted?: (claim: PaymentClaim) => void | Promise<void>;
+    /**
+     * Optional: TTL check tolerance. Default false — txs without a
+     * validity-range upper bound are rejected.
+     */
+    allowNoTtl?: boolean;
+}
+export type ProcessResult = {
+    kind: 'accepted';
+    txHash: string;
+    payment: PaymentClaim;
+    /** base64 of `{ success: true, network, transaction }` for X-PAYMENT-RESPONSE header. */
+    paymentResponseB64: string;
+} | {
+    kind: 'rejected';
+    code: X402Code;
+    reason: string;
+    requirementsBody: PaymentRequirementsBody;
+} | {
+    kind: 'pending';
+    code: X402Code;
+    reason?: string;
+    txHash?: string;
+    requirementsBody: PaymentRequirementsBody;
+};
+export declare function process(args: ProcessArgs): Promise<ProcessResult>;
+//# sourceMappingURL=verify.d.ts.map