@odatano/x402 0.1.0

package/srv/facilitator/verify.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * 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.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.process = process;
+const cds_1 = __importDefault(require("@sap/cds"));
+const decode_1 = require("../core/decode");
+const validate_1 = require("../core/validate");
+const requirements_1 = require("../core/requirements");
+const errors_1 = require("../core/errors");
+const nonce_1 = require("./nonce");
+const settle_1 = require("./settle");
+const bridge = __importStar(require("../bridge"));
+const log = cds_1.default.log('x402');
+function paymentResponseHeaderB64(network, txHash) {
+    return Buffer.from(JSON.stringify({
+        success: true, network, transaction: txHash,
+    }), 'utf8').toString('base64');
+}
+async function runOnAccepted(claim, cb) {
+    if (!cb)
+        return;
+    try {
+        await cb(claim);
+    }
+    catch (err) {
+        log.warn('onAccepted callback failed (non-fatal):', err?.message ?? err);
+    }
+}
+async function process(args) {
+    const headerStr = Array.isArray(args.paymentHeader)
+        ? args.paymentHeader[0]
+        : args.paymentHeader;
+    if (!headerStr) {
+        return {
+            kind: 'rejected',
+            code: errors_1.Codes.MISSING_HEADER,
+            reason: 'PAYMENT-SIGNATURE header is required',
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    const requirements = (0, requirements_1.flatRequirements)(args.requirementsBody);
+    // ─── 1. Decode ──────────────────────────────────────────────────────
+    let decoded;
+    try {
+        decoded = (0, decode_1.decode)(headerStr);
+    }
+    catch (err) {
+        if (err instanceof errors_1.X402Error) {
+            return {
+                kind: 'rejected',
+                code: err.code,
+                reason: err.message,
+                requirementsBody: args.requirementsBody,
+            };
+        }
+        throw err;
+    }
+    // ─── 2. Validate (6 checks, pure) ───────────────────────────────────
+    let currentSlot;
+    try {
+        currentSlot = await bridge.getCurrentSlot();
+    }
+    catch (err) {
+        return {
+            kind: 'rejected',
+            code: err.code ?? errors_1.Codes.BRIDGE_UNAVAILABLE,
+            reason: `bridge.getCurrentSlot failed: ${err?.message ?? err}`,
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    const v = (0, validate_1.validatePayment)(decoded, requirements, {
+        currentSlot,
+        allowNoTtl: args.allowNoTtl,
+    });
+    if (!v.ok) {
+        return {
+            kind: 'rejected',
+            code: v.code,
+            reason: v.reason,
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    // ─── 3. Nonce — UTxO still unspent (chain) ──────────────────────────
+    const nonceResult = await (0, nonce_1.checkNonceUnspent)({
+        txHash: decoded.nonce.txHash,
+        outputIndex: decoded.nonce.index,
+    });
+    if (!nonceResult.ok) {
+        return {
+            kind: 'rejected',
+            code: nonceResult.code,
+            reason: nonceResult.reason,
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    // ─── 4. Settle (submit + poll-until-confirmed) ──────────────────────
+    const settleArgs = {
+        signedTxCborHex: decoded.txCborHex,
+        expectedTxHash: decoded.txHash,
+    };
+    if (args.settlePollBudgetMs !== undefined) {
+        settleArgs.pollBudgetMs = args.settlePollBudgetMs;
+    }
+    const settled = await (0, settle_1.settle)(settleArgs);
+    if (!settled.confirmed) {
+        if (settled.pending) {
+            return {
+                kind: 'pending',
+                code: settled.code ?? errors_1.Codes.PENDING,
+                ...(settled.reason !== undefined ? { reason: settled.reason } : {}),
+                ...(settled.txHash !== undefined ? { txHash: settled.txHash } : {}),
+                requirementsBody: args.requirementsBody,
+            };
+        }
+        return {
+            kind: 'rejected',
+            code: settled.code ?? errors_1.Codes.SUBMIT_FAILED,
+            reason: settled.reason ?? 'submit failed',
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    // ─── 5. onAccepted (consumer audit, best-effort) ────────────────────
+    await runOnAccepted(v.claim, args.onAccepted);
+    // ─── 6. Success ─────────────────────────────────────────────────────
+    return {
+        kind: 'accepted',
+        txHash: v.claim.txHash,
+        payment: v.claim,
+        paymentResponseB64: paymentResponseHeaderB64(v.claim.network, v.claim.txHash),
+    };
+}

package/srv/helpers/build-unsigned-tx.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Server-side unsigned payment-tx builder for browser-buyer flows.
+ *
+ * The browser knows the buyer's bech32 (via CIP-30) but not the
+ * signing keys. Replicating CSL coin-selection + protocol-params
+ * fetch in the browser would mean shipping ~2 MB of WASM. So we
+ * build the unsigned tx server-side, return the CBOR for the
+ * wallet to sign, and let the browser submit the signed CBOR as
+ * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
+ *
+ * Diff vs v1 of CHAINFEED's same-named helper:
+ *   - Asset-agnostic — parses requirements.asset as a v2 string
+ *     (`'lovelace'` or `'<policy>.<nameHex>'`).
+ *   - Returns `nonceRef` alongside the unsigned CBOR — the server
+ *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
+ *     so the browser doesn't have to reason about it.
+ *
+ * **x402-spec deviation:** strict v2 has the buyer construct the
+ * tx end-to-end. This helper is a "self-facilitator" pattern: the
+ * server builds, the buyer signs, the server still validates the
+ * signed tx against requirements before settling. Same security
+ * model (the buyer's signature still authorises the spend), easier
+ * browser ergonomics.
+ */
+import type { PaymentRequirementEntry } from '../core/types';
+export interface BuildUnsignedTxArgs {
+    /** Buyer's bech32 address (must be Base or Enterprise with VKey-hash payment cred). */
+    buyerBech32: string;
+    /** A single accepts[] entry — call `flatRequirements(body)` to extract. */
+    requirements: PaymentRequirementEntry;
+    /**
+     * Optional TTL in slots from "now" (= current chain tip slot).
+     * Default 1800 (≈30 min on Cardano's 1s-slot networks).
+     */
+    ttlSlotsFromNow?: number;
+}
+export interface UnsignedTxResult {
+    /** CBOR hex of the unsigned tx (empty witness set). Ready for CIP-30 signTx. */
+    unsignedTxCborHex: string;
+    /** Hex tx hash — what the buyer's wallet will display. */
+    txHashHex: string;
+    /** Buyer's payment-cred VKey hash — wallet must sign for this. */
+    requiredSignerHex: string;
+    /** v2 nonce reference `<txHash>#<index>`, picked from the buyer's chosen inputs. */
+    nonceRef: string;
+    /** Echo of the inputs chosen so the buyer's UI can show "spends these UTxOs". */
+    inputs: Array<{
+        txHash: string;
+        outputIndex: number;
+        lovelace: string;
+    }>;
+    /** TTL slot used for the validity-range upper bound. */
+    ttlSlot: number;
+}
+export declare function buildUnsignedPaymentTx(args: BuildUnsignedTxArgs): Promise<UnsignedTxResult>;
+//# sourceMappingURL=build-unsigned-tx.d.ts.map

package/srv/helpers/build-unsigned-tx.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Server-side unsigned payment-tx builder for browser-buyer flows.
+ *
+ * The browser knows the buyer's bech32 (via CIP-30) but not the
+ * signing keys. Replicating CSL coin-selection + protocol-params
+ * fetch in the browser would mean shipping ~2 MB of WASM. So we
+ * build the unsigned tx server-side, return the CBOR for the
+ * wallet to sign, and let the browser submit the signed CBOR as
+ * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
+ *
+ * Diff vs v1 of CHAINFEED's same-named helper:
+ *   - Asset-agnostic — parses requirements.asset as a v2 string
+ *     (`'lovelace'` or `'<policy>.<nameHex>'`).
+ *   - Returns `nonceRef` alongside the unsigned CBOR — the server
+ *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
+ *     so the browser doesn't have to reason about it.
+ *
+ * **x402-spec deviation:** strict v2 has the buyer construct the
+ * tx end-to-end. This helper is a "self-facilitator" pattern: the
+ * server builds, the buyer signs, the server still validates the
+ * signed tx against requirements before settling. Same security
+ * model (the buyer's signature still authorises the spend), easier
+ * browser ergonomics.
+ */
+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.buildUnsignedPaymentTx = buildUnsignedPaymentTx;
+const CSL = __importStar(require("@emurgo/cardano-serialization-lib-nodejs"));
+const bridge = __importStar(require("../bridge"));
+const asset_1 = require("../core/asset");
+async function buildUnsignedPaymentTx(args) {
+    const { buyerBech32, requirements } = args;
+    // 1. Decode buyer address; derive payment-cred VKey hash.
+    let buyerAddress;
+    try {
+        buyerAddress = CSL.Address.from_bech32(buyerBech32);
+    }
+    catch {
+        throw new Error(`buildUnsignedPaymentTx: invalid bech32 address: ${buyerBech32}`);
+    }
+    const baseAddr = CSL.BaseAddress.from_address(buyerAddress);
+    const enterpriseAddr = CSL.EnterpriseAddress.from_address(buyerAddress);
+    const paymentCred = baseAddr?.payment_cred() ?? enterpriseAddr?.payment_cred();
+    if (!paymentCred) {
+        throw new Error('buildUnsignedPaymentTx: only Base / Enterprise addresses are supported');
+    }
+    const buyerVkeyHash = paymentCred.to_keyhash();
+    if (!buyerVkeyHash) {
+        throw new Error('buildUnsignedPaymentTx: payment credential must be a VKey hash, not a script');
+    }
+    const requiredSignerHex = Buffer.from(buyerVkeyHash.to_bytes()).toString('hex');
+    // 2. Fetch buyer UTxOs + protocol params + current slot in parallel.
+    const [utxos, params, currentSlot] = await Promise.all([
+        bridge.getUtxosAtAddress(buyerBech32),
+        bridge.getProtocolParameters(),
+        bridge.getCurrentSlot(),
+    ]);
+    if (utxos.length === 0) {
+        throw new Error(`buildUnsignedPaymentTx: no UTxOs at ${buyerBech32}`);
+    }
+    // 3. Pick the input(s) for coin-selection.
+    //    Strategy:
+    //      - If lovelace asset: pick largest-ADA UTxO; add second-largest as padding if first < 3 ADA.
+    //      - If native asset:   pick largest-ADA UTxO that ALSO holds enough of the asset;
+    //                           add padding the same way.
+    const parsedAsset = (0, asset_1.parseAsset)(requirements.asset);
+    const required = BigInt(requirements.amount);
+    const sortedByAda = [...utxos].sort((a, b) => (BigInt(b.lovelace) - BigInt(a.lovelace) > 0n ? 1 : -1));
+    let inputs;
+    if (parsedAsset.isLovelace) {
+        // ADA payment: largest UTxO must cover required + fees + min-ADA change.
+        // Heuristic: required + 2_000_000 (≈2 ADA fee+change headroom).
+        const headroom = required + 2000000n;
+        const ok = sortedByAda.find(u => BigInt(u.lovelace) >= headroom);
+        if (!ok) {
+            throw new Error(`buildUnsignedPaymentTx: no UTxO at ${buyerBech32} with ≥ ${headroom} lovelace`);
+        }
+        inputs = [ok];
+    }
+    else {
+        const candidates = sortedByAda.filter(u => u.assets.some(a => a.unit === parsedAsset.unit && BigInt(a.quantity) >= required));
+        if (candidates.length === 0) {
+            throw new Error(`buildUnsignedPaymentTx: no UTxO at ${buyerBech32} holds ≥ ${required} of ${parsedAsset.unit}`);
+        }
+        const tokenInput = candidates[0];
+        inputs = [tokenInput];
+        if (BigInt(tokenInput.lovelace) < 3000000n) {
+            const padding = sortedByAda.find(u => u !== tokenInput);
+            if (!padding) {
+                throw new Error('buildUnsignedPaymentTx: no second UTxO available to fund fees');
+            }
+            inputs.push(padding);
+        }
+    }
+    // 4. Configure CSL TransactionBuilder from live protocol params.
+    const builder = CSL.TransactionBuilder.new(CSL.TransactionBuilderConfigBuilder.new()
+        .fee_algo(CSL.LinearFee.new(CSL.BigNum.from_str(String(params.minFeeA)), CSL.BigNum.from_str(String(params.minFeeB))))
+        .pool_deposit(CSL.BigNum.from_str(String(params.poolDeposit)))
+        .key_deposit(CSL.BigNum.from_str(String(params.keyDeposit)))
+        .max_value_size(Number(params.maxValSize))
+        .max_tx_size(Number(params.maxTxSize))
+        .coins_per_utxo_byte(CSL.BigNum.from_str(String(params.coinsPerUtxoSize)))
+        .build());
+    // 5. Wire inputs (preserve full multi-asset payload).
+    for (const u of inputs) {
+        const inMa = CSL.MultiAsset.new();
+        const byPolicy = new Map();
+        for (const a of u.assets) {
+            const arr = byPolicy.get(a.policyId) ?? [];
+            arr.push({ name: a.assetNameHex, qty: a.quantity });
+            byPolicy.set(a.policyId, arr);
+        }
+        for (const [policyHex, items] of byPolicy) {
+            const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyHex, 'hex'));
+            const assetMap = CSL.Assets.new();
+            for (const { name, qty } of items) {
+                assetMap.insert(CSL.AssetName.new(Buffer.from(name, 'hex')), CSL.BigNum.from_str(qty));
+            }
+            inMa.insert(policyHash, assetMap);
+        }
+        const inV = CSL.Value.new(CSL.BigNum.from_str(u.lovelace));
+        if (u.assets.length)
+            inV.set_multiasset(inMa);
+        builder.add_key_input(buyerVkeyHash, CSL.TransactionInput.new(CSL.TransactionHash.from_bytes(Buffer.from(u.txHash, 'hex')), u.outputIndex), inV);
+    }
+    // 6. Output to payTo.
+    const payToAddr = CSL.Address.from_bech32(requirements.payTo);
+    let payOut;
+    if (parsedAsset.isLovelace) {
+        const v = CSL.Value.new(CSL.BigNum.from_str(required.toString()));
+        payOut = CSL.TransactionOutput.new(payToAddr, v);
+    }
+    else {
+        const payOutMa = CSL.MultiAsset.new();
+        const payAssets = CSL.Assets.new();
+        const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(parsedAsset.policyId, 'hex'));
+        payAssets.insert(CSL.AssetName.new(Buffer.from(parsedAsset.assetNameHex, 'hex')), CSL.BigNum.from_str(required.toString()));
+        payOutMa.insert(policyHash, payAssets);
+        const payOutV = CSL.Value.new(CSL.BigNum.from_str('0'));
+        payOutV.set_multiasset(payOutMa);
+        const provisional = CSL.TransactionOutput.new(payToAddr, payOutV);
+        const minAda = CSL.min_ada_for_output(provisional, CSL.DataCost.new_coins_per_byte(CSL.BigNum.from_str(String(params.coinsPerUtxoSize))));
+        payOutV.set_coin(minAda);
+        payOut = CSL.TransactionOutput.new(payToAddr, payOutV);
+    }
+    builder.add_output(payOut);
+    // 7. TTL (slot of upper bound). Default 1800 slots ≈ 30 min.
+    const ttlSlot = currentSlot + (args.ttlSlotsFromNow ?? 1800);
+    builder.set_ttl_bignum(CSL.BigNum.from_str(String(ttlSlot)));
+    // 8. Change to buyer.
+    builder.add_change_if_needed(buyerAddress);
+    // 9. Build body, compute hash, return unsigned tx.
+    const txBody = builder.build();
+    const txHash = CSL.FixedTransaction.new_from_body_bytes(txBody.to_bytes()).transaction_hash();
+    const emptyWits = CSL.TransactionWitnessSet.new();
+    const unsigned = CSL.Transaction.new(txBody, emptyWits);
+    // Pick the first input as the v2 nonce UTxO.
+    // It MUST appear in tx.inputs (which it does by construction) and be
+    // unspent (which it is — we just queried it from the buyer's UTxO set).
+    const nonceInput = inputs[0];
+    const nonceRef = `${nonceInput.txHash}#${nonceInput.outputIndex}`;
+    return {
+        unsignedTxCborHex: Buffer.from(unsigned.to_bytes()).toString('hex'),
+        txHashHex: Buffer.from(txHash.to_bytes()).toString('hex').toLowerCase(),
+        requiredSignerHex,
+        nonceRef,
+        inputs: inputs.map(i => ({ txHash: i.txHash, outputIndex: i.outputIndex, lovelace: i.lovelace })),
+        ttlSlot,
+    };
+}

package/srv/helpers/verify-confirmed.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Post-confirmed payment verifier.
+ *
+ * Use case: buyer pays out-of-band (CLI, hardware wallet, etc.), then
+ * presents a **txHash** to your server. This module fetches the tx
+ * from chain via the bridge and confirms it pays the right amount of
+ * the right asset to the right address on the right network.
+ *
+ * Differences from the middleware path (`facilitator/verify.ts`):
+ *   - No envelope, no PAYMENT-SIGNATURE header — just a tx hash.
+ *   - The tx is presumed already on-chain (the network already accepted
+ *     witnesses), so we skip the witness-presence check.
+ *   - No on-chain nonce check: replay defense for confirmed-payment
+ *     flows is the consumer's job (e.g. "this txHash already redeemed
+ *     a subscription" → consumer's DB). v2 still applies for the
+ *     middleware path; this helper is for grants that outlive a
+ *     single HTTP request.
+ *
+ * Asset-agnostic: pass either `'lovelace'` or `'<policy>.<nameHex>'`.
+ */
+import { type X402Code } from '../core/errors';
+import { type Network } from '../core/network';
+export interface VerifyConfirmedArgs {
+    txHash: string;
+    /** Required asset amount in raw units (BigInt-safe). */
+    requiredAmount: string | number | bigint;
+    /** v2 asset string. */
+    asset: string;
+    /** Bech32 recipient. */
+    payTo: string;
+    network: Network | string;
+}
+export type VerifyConfirmedResult = {
+    ok: true;
+    txHash: string;
+    amountUnits: string;
+} | {
+    ok: false;
+    code: X402Code;
+    reason: string;
+};
+export declare function verifyConfirmedPayment(args: VerifyConfirmedArgs): Promise<VerifyConfirmedResult>;
+//# sourceMappingURL=verify-confirmed.d.ts.map

package/srv/helpers/verify-confirmed.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Post-confirmed payment verifier.
+ *
+ * Use case: buyer pays out-of-band (CLI, hardware wallet, etc.), then
+ * presents a **txHash** to your server. This module fetches the tx
+ * from chain via the bridge and confirms it pays the right amount of
+ * the right asset to the right address on the right network.
+ *
+ * Differences from the middleware path (`facilitator/verify.ts`):
+ *   - No envelope, no PAYMENT-SIGNATURE header — just a tx hash.
+ *   - The tx is presumed already on-chain (the network already accepted
+ *     witnesses), so we skip the witness-presence check.
+ *   - No on-chain nonce check: replay defense for confirmed-payment
+ *     flows is the consumer's job (e.g. "this txHash already redeemed
+ *     a subscription" → consumer's DB). v2 still applies for the
+ *     middleware path; this helper is for grants that outlive a
+ *     single HTTP request.
+ *
+ * Asset-agnostic: pass either `'lovelace'` or `'<policy>.<nameHex>'`.
+ */
+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.verifyConfirmedPayment = verifyConfirmedPayment;
+const bridge = __importStar(require("../bridge"));
+const errors_1 = require("../core/errors");
+const asset_1 = require("../core/asset");
+const network_1 = require("../core/network");
+function totalPaidToAddress(tx, payTo, isLovelace, unit) {
+    let total = 0n;
+    for (const o of tx.outputs ?? []) {
+        if (o.address !== payTo)
+            continue;
+        if (isLovelace) {
+            total += BigInt(o.lovelace ?? '0');
+        }
+        else {
+            for (const a of o.assets ?? []) {
+                if (String(a.unit ?? '').toLowerCase() === unit) {
+                    total += BigInt(a.quantity ?? '0');
+                }
+            }
+        }
+    }
+    return total;
+}
+async function verifyConfirmedPayment(args) {
+    if (typeof args.txHash !== 'string' || !/^[0-9a-f]{64}$/i.test(args.txHash)) {
+        return { ok: false, code: errors_1.Codes.INVALID_CBOR, reason: 'txHash must be 64-char lowercase hex' };
+    }
+    // Parse / validate the user-supplied descriptors up front so we
+    // return precise diagnostics instead of failing later in the flow.
+    let network;
+    try {
+        network = (0, network_1.parseNetwork)(args.network);
+    }
+    catch (e) {
+        return { ok: false, code: errors_1.Codes.INVALID_NETWORK_FORMAT, reason: e.message };
+    }
+    let parsedAsset;
+    try {
+        parsedAsset = (0, asset_1.parseAsset)(args.asset);
+    }
+    catch (e) {
+        return { ok: false, code: errors_1.Codes.INVALID_ASSET_FORMAT, reason: e.message };
+    }
+    // 1. Fetch from chain.
+    let tx;
+    try {
+        tx = await bridge.getTransactionByHash(args.txHash);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: errors_1.Codes.PENDING,
+            reason: `bridge.getTransactionByHash failed: ${err?.message ?? err}`,
+        };
+    }
+    if (!tx) {
+        return {
+            ok: false,
+            code: errors_1.Codes.PENDING,
+            reason: `tx ${args.txHash} not found on-chain (network=${network})`,
+        };
+    }
+    // 2. Quantity check, summed across all outputs to payTo.
+    const paid = totalPaidToAddress(tx, args.payTo, parsedAsset.isLovelace, parsedAsset.unit);
+    const required = BigInt(args.requiredAmount);
+    if (paid < required) {
+        return {
+            ok: false,
+            code: paid === 0n ? errors_1.Codes.WRONG_ASSET : errors_1.Codes.INSUFFICIENT_AMOUNT,
+            reason: `paid ${paid} < required ${required} of ${args.asset} to ${args.payTo}`,
+        };
+    }
+    return { ok: true, txHash: args.txHash, amountUnits: paid.toString() };
+}

package/srv/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @odatano/x402 — public API barrel.
+ *
+ * Cardano-x402-v2 payment library for SAP CAP applications.
+ *
+ * Three usage shapes:
+ *
+ *   // 1. Express middleware (mount under a path)
+ *   import { x402Middleware } from '@odatano/x402';
+ *   app.use('/api/premium', x402Middleware({
+ *     payTo: 'addr_test1...',
+ *     network: 'cardano:preprod',
+ *     asset: '16a55b...ddde.0014df105553444d',
+ *     priceUnits: '1000000',
+ *     onAccepted: async (claim) => { ... },
+ *   }));
+ *
+ *   // 2. CAP service gate (registers a before-* handler)
+ *   import { gateService } from '@odatano/x402';
+ *   class MyService extends cds.ApplicationService {
+ *     async init() {
+ *       gateService(this, {
+ *         payTo, network, asset,
+ *         routePricing: { Prices: '10000', getBestPrice: '10000' },
+ *       });
+ *       return super.init();
+ *     }
+ *   }
+ *
+ *   // 3. Programmatic — verify a confirmed payment by tx hash
+ *   import { verifyConfirmedPayment } from '@odatano/x402';
+ *   const r = await verifyConfirmedPayment({
+ *     txHash, requiredAmount, asset, payTo, network,
+ *   });
+ */
+export { buildPaymentRequirements, buildEntry, flatRequirements, type BuildPaymentRequirementsArgs, } from './core/requirements';
+export { decode } from './core/decode';
+export { validatePayment, type ValidationResult, type ValidateOptions } from './core/validate';
+export { parseAsset, buildAssetString, type ParsedAsset } from './core/asset';
+export { parseNetwork, isNetwork, networksMatch, type Network } from './core/network';
+export { X402Error, Codes, type X402Code } from './core/errors';
+export type { AssetTransferMethod, ResourceDescriptor, PaymentRequirementEntry, PaymentRequirementsBody, PaymentEnvelope, PaymentClaim, DecodedPayment, DecodedOutput, DecodedAsset, DecodedInput, } from './core/types';
+export { process as verifyPayment, type ProcessArgs, type ProcessResult, type ProcessKind, } from './facilitator/verify';
+export { settle, type SettleArgs, type SettleResult } from './facilitator/settle';
+export { checkNonceUnspent, type NonceCheckArgs, type NonceResult } from './facilitator/nonce';
+export { verifyConfirmedPayment, type VerifyConfirmedArgs, type VerifyConfirmedResult, } from './helpers/verify-confirmed';
+export { buildUnsignedPaymentTx, type BuildUnsignedTxArgs, type UnsignedTxResult, } from './helpers/build-unsigned-tx';
+export { x402Middleware, type X402MiddlewareOptions } from './middleware/express';
+export { gateService, type X402CapOptions } from './middleware/cap';
+export * as bridge from './bridge';
+//# sourceMappingURL=index.d.ts.map