@xfuel/verify 0.1.1 → 0.3.0

package/dist/index.js

@@ -12,16 +12,24 @@
  * See docs/specs/RECEIPT_V2_SEMANTICS.md for the verification algorithm.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyIssuerJws = exports.resolvePinnedIssuerJwk = exports.canonicalSignedPayload = exports.BASE_SEPOLIA_RPC_URL = exports.ZK_VERIFIER_ADDRESS = exports.decodeJwsPayload = exports.receiptPayerClaimsFromEnvelope = exports.verifyPayerBinding = exports.SOLANA_USDC_MINT_DEVNET = exports.SOLANA_USDC_MINT_MAINNET = exports.SOLANA_RPC_URL = exports.fetchSolanaTransaction = exports.inferUsdcOutflowFromBalances = exports.extractUsdcTransfersFromTx = exports.isSolanaBase58Pubkey = exports.parseSolanaPaymentRef = exports.verifySolanaPayer = exports.BASE_RPC_URL = exports.ERC20_TRANSFER_TOPIC = exports.USDC_ADDRESSES = exports.fetchBaseTransactionReceipt = exports.sumUsdcTransfersFromPayer = exports.isEvmAddress = exports.parseBasePaymentRef = exports.verifyBasePayer = exports.computeInferenceBinding = exports.computePaymentCommitment = void 0;
+exports.REFUSAL_SCHEMA = exports.verifyRefusal = exports.isRefusalDocument = exports.HEAD_BINDING_PAYLOAD_VERSION = exports.outerHeadDisagrees = exports.signedHeadBinding = exports.headBindingVerdict = exports.RECEIPT_LANE_BOUNDARY = exports.RECEIPT_LANE_ORDERING = exports.RECEIPT_LANE_RULE = exports.RECEIPT_LANE_SCHEMA = exports.anchorChangedSinceBinding = exports.deriveSettled = exports.deriveSettledBy = exports.receiptLaneDecision = exports.receiptLaneFromVerification = exports.buildReceiptLane = exports.jwksHostAllowed = exports.isPinnedTrustedJwk = exports.jwkThumbprint = exports.KEY_UNTRUSTED = exports.DEFAULT_TRUSTED_JWKS_HOSTS = exports.DEFAULT_TRUSTED_ISSUER_KIDS = exports.verifyIssuerJws = exports.resolvePinnedIssuerJwk = exports.canonicalSignedPayload = exports.BASE_SEPOLIA_RPC_URL = exports.ZK_VERIFIER_ADDRESS = exports.decodeJwsPayload = exports.receiptPayerClaimsFromEnvelope = exports.verifyPayerBinding = exports.SOLANA_USDC_MINT_DEVNET = exports.SOLANA_USDC_MINT_MAINNET = exports.SOLANA_RPC_URL = exports.fetchSolanaTransaction = exports.inferUsdcOutflowFromBalances = exports.extractUsdcTransfersFromTx = exports.isSolanaBase58Pubkey = exports.parseSolanaPaymentRef = exports.verifySolanaPayer = exports.BASE_RPC_URL = exports.ERC20_TRANSFER_TOPIC = exports.USDC_ADDRESSES = exports.fetchBaseTransactionReceipt = exports.sumUsdcTransfersFromPayer = exports.isEvmAddress = exports.parseBasePaymentRef = exports.verifyBasePayer = exports.computeInferenceBinding = exports.computePaymentCommitment = void 0;
+exports.issuerHistoryDocumentHash = exports.readIssuerHistoryPin = exports.CANONICAL_PAYLOAD_VERSION = exports.verifyCanonicalPreimageBytes = exports.BASE_MAINNET_CHAIN_ID = exports.SOLANA_GENESIS = exports.ANCHOR_DOES_NOT_PROVE = exports.ANCHOR_PROVES = exports.leafHash = exports.parseAnchorMemo = exports.extractMemos = exports.verifyMerkleInclusion = exports.verifyAnchoredRoot = exports.REFUSAL_DOES_NOT_PROVE = exports.REFUSAL_PROVES = exports.REFUSAL_PAYLOAD_VERSION = void 0;
+exports.canonicalPayloadVersion = canonicalPayloadVersion;
 exports.canonicalIssuerPayload = canonicalIssuerPayload;
+exports.sumUsdcTransfersToPayee = sumUsdcTransfersToPayee;
+exports.reconcileSettledTransfer = reconcileSettledTransfer;
 exports.verifyIssuerSignature = verifyIssuerSignature;
 exports.verifyIssuerSignatureWithJwks = verifyIssuerSignatureWithJwks;
 exports.verifyBinding = verifyBinding;
 exports.verifyNullifier = verifyNullifier;
 exports.hashCanonicalPayload = hashCanonicalPayload;
+exports.claimIdVerdict = claimIdVerdict;
+exports.diffOuterClaims = diffOuterClaims;
+exports.fetchIssuerJwks = fetchIssuerJwks;
 exports.receiptPayerClaims = receiptPayerClaims;
 exports.verifyReceipt = verifyReceipt;
 const ethers_1 = require("ethers");
+const anchor_witness_js_1 = require("./anchor-witness.js");
 const node_crypto_1 = require("node:crypto");
 const binding_js_1 = require("./binding.js");
 Object.defineProperty(exports, "computePaymentCommitment", { enumerable: true, get: function () { return binding_js_1.computePaymentCommitment; } });
@@ -50,6 +58,12 @@ Object.defineProperty(exports, "verifyPayerBinding", { enumerable: true, get: fu
 Object.defineProperty(exports, "receiptPayerClaimsFromEnvelope", { enumerable: true, get: function () { return payer_js_1.receiptPayerClaimsFromEnvelope; } });
 Object.defineProperty(exports, "decodeJwsPayload", { enumerable: true, get: function () { return payer_js_1.decodeJwsPayload; } });
 const jws_js_1 = require("./jws.js");
+const head_binding_js_1 = require("./head-binding.js");
+const receipt_lane_js_1 = require("./receipt-lane.js");
+const refusal_js_1 = require("./refusal.js");
+const preimage_js_1 = require("./preimage.js");
+const issuer_history_js_1 = require("./issuer-history.js");
+const canonical_preimage_js_1 = require("./canonical-preimage.js");
 /** ZKVerifierSP1 contract on Base mainnet. */
 exports.ZK_VERIFIER_ADDRESS = '0x9373499645292715a2275A78eD65B14215C41c06';
 /** Base Sepolia testnet RPC. */
@@ -59,28 +73,28 @@ const ZK_VERIFIER_ABI = [
     'function usedNullifiers(bytes32) view returns (bool)',
 ];
 /**
- * Canonical, order-stable payload an issuer signature covers.
- * MUST match `canonicalSignedPayload` in services/gateway/src/receipt.js exactly.
- *
- * Signed fields (15 total):
- *   1. task_id
- *   2. payment.rail
- *   3. payment.ref
- *   4. payment.gross_amount
- *   5. payment.net_amount
- *   6. payment.fee_amount
- *   7. payment.protocol_fee_bps ?? payment.fee_bps
- *   8. payment.platform_fee
- *   9. payment.platform_fee_bps
- *  10. provider_cogs.actual
- *  11. route.model
- *  12. route.model_commitment.commitment
- *  13. route.provider
- *  14. output.hash
- *  15. binding.expected_commitment
+ * HMAC payload version.
+ * Versions <= 7 keep the historical net/fee field list.
+ * Version 8 signs settled_amount plus the internal accounting breakdown.
+ * Lockstep with `canonicalPayloadVersion` in services/gateway/src/receipt.js
+ * for the v8 list (the v7 list here is the historical 15-field public formula).
  */
-function canonicalIssuerPayload(receipt) {
-    return JSON.stringify([
+function canonicalPayloadVersion(receipt) {
+    const stamped = receipt.hmac_attestation?.payload_version
+        ?? receipt.signature?.payload_version;
+    if (stamped != null)
+        return Number(stamped);
+    const issuerV = receipt.issuer_signature?.payload_version;
+    if (issuerV != null)
+        return Number(issuerV);
+    const payment = receipt.payment;
+    if (payment?.accounting || (payment && Object.prototype.hasOwnProperty.call(payment, 'settled_amount'))) {
+        return 8;
+    }
+    return 7;
+}
+function canonicalFieldsV7(receipt) {
+    return [
         receipt.task_id ?? null,
         receipt.payment?.rail ?? null,
         receipt.payment?.ref ?? null,
@@ -96,7 +110,204 @@ function canonicalIssuerPayload(receipt) {
         receipt.route?.provider ?? null,
         receipt.output?.hash ?? null,
         receipt.binding?.expected_commitment ?? null,
-    ]);
+    ];
+}
+function canonicalFieldsV8(receipt) {
+    const breakdown = receipt.payment?.accounting?.internal_breakdown;
+    const caller = receipt.caller_binding;
+    return [
+        receipt.task_id ?? null,
+        receipt.payment?.rail ?? null,
+        receipt.payment?.ref ?? null,
+        receipt.payment?.gross_amount ?? null,
+        receipt.payment?.settled_amount ?? null,
+        breakdown?.route_margin_bps ?? null,
+        breakdown?.route_margin_amount ?? null,
+        breakdown?.receipt_floor_amount ?? null,
+        breakdown?.provider_cogs_amount ?? null,
+        breakdown?.tier2_proof_amount ?? null,
+        receipt.provider_cogs?.actual ?? null,
+        receipt.route?.model ?? null,
+        receipt.route?.model_commitment?.commitment ?? null,
+        receipt.route?.provider ?? null,
+        receipt.output?.hash ?? null,
+        receipt.binding?.expected_commitment ?? null,
+        caller?.payer_wallet ?? null,
+        caller?.agent_pubkey ?? null,
+        caller?.api_key_hash ?? null,
+    ];
+}
+/**
+ * Canonical, order-stable payload an HMAC issuer signature covers.
+ * v8 matches `canonicalSignedPayload` in services/gateway/src/receipt.js.
+ * v7 and earlier stay on the historical 15-field list so old signatures verify.
+ */
+function canonicalIssuerPayload(receipt) {
+    const fields = canonicalPayloadVersion(receipt) >= 8
+        ? canonicalFieldsV8(receipt)
+        : canonicalFieldsV7(receipt);
+    return JSON.stringify(fields);
+}
+function topicAddress(topic) {
+    const hex = topic.toLowerCase().replace(/^0x/, '');
+    return `0x${hex.slice(-40)}`;
+}
+/**
+ * Sum USDC Transfer values to `payee` in a transaction's logs.
+ * Non-Transfer logs are ignored. When `usdcAddress` is set, other contracts are ignored.
+ */
+function sumUsdcTransfersToPayee(logs, payee, usdcAddress) {
+    if (!payee || !(0, base_payer_js_1.isEvmAddress)(payee))
+        return null;
+    const payeeLower = payee.toLowerCase();
+    const usdcLower = usdcAddress?.toLowerCase();
+    let total = 0n;
+    let found = false;
+    for (const log of logs || []) {
+        if (usdcLower && log.address?.toLowerCase() !== usdcLower)
+            continue;
+        const topics = log.topics || [];
+        if (topics[0]?.toLowerCase() !== base_payer_js_1.ERC20_TRANSFER_TOPIC)
+            continue;
+        if (topics.length < 3 || !topics[2])
+            continue;
+        if (topicAddress(topics[2]) !== payeeLower)
+            continue;
+        found = true;
+        total += BigInt(log.data || '0x0');
+    }
+    return found ? total : null;
+}
+/**
+ * Payment facts for on-chain reconciliation.
+ * A JWS is used only after `verifyIssuerSignatureWithJwks` accepts the key.
+ * An untrusted or invalid JWS is not decoded into the comparison, and the
+ * unsigned outer `payment` copy is not a fallback for those claims.
+ * Receipts with no JWS still use the outer payment (legacy envelopes).
+ */
+function trustedPaymentForReconcile(receipt, options) {
+    const outerVersion = Number(receipt.issuer_signature?.payload_version ?? canonicalPayloadVersion(receipt));
+    const jws = receipt.issuer_signature?.jws;
+    if (!jws) {
+        return { ok: true, version: outerVersion, payment: receipt.payment || {} };
+    }
+    const verification = verifyIssuerSignatureWithJwks(receipt, options.jwks, {
+        trustedKids: options.trustedKids,
+    });
+    if (!verification.valid || verification.key_trusted === false) {
+        return {
+            ok: false,
+            version: outerVersion,
+            reason: verification.reason || jws_js_1.KEY_UNTRUSTED,
+        };
+    }
+    const claims = verification.payload;
+    const claimPayment = (claims?.payment && typeof claims.payment === 'object')
+        ? claims.payment
+        : null;
+    if (!claimPayment) {
+        return { ok: false, version: outerVersion, reason: 'no_signed_amount' };
+    }
+    const version = typeof claims?.payload_version === 'number'
+        ? claims.payload_version
+        : outerVersion;
+    return { ok: true, version: Number(version), payment: claimPayment };
+}
+/**
+ * Optional on-chain reconciliation. Given a tx receipt's logs, the signed
+ * amount the payee was supposed to receive must equal the USDC Transfer to payee.
+ *
+ * The amount and payee come from JWS claims only after a key-trust check
+ * (JWKS by kid, or an embedded key whose thumbprint is a pinned kid). An
+ * untrusted signature does not contribute those facts.
+ *
+ * v8 compares `settled_amount` (falling back to `gross_amount`): that is the
+ * on-chain transfer. v7 and earlier compare `net_amount`, which those receipts
+ * defined as "amount after fees". A single direct transfer of gross will not
+ * match a net that subtracts a fee that never moved on chain.
+ */
+function reconcileSettledTransfer(receipt, logs, options = {}) {
+    const trusted = trustedPaymentForReconcile(receipt, options);
+    if (!trusted.ok) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: trusted.version,
+            signed_field: null,
+            signed_amount: null,
+            transfer_amount: null,
+            payee: null,
+            reason: trusted.reason,
+        };
+    }
+    const { version, payment } = trusted;
+    const payee = payment.payee ?? null;
+    let signed_field = null;
+    let signed_amount = null;
+    if (version >= 8) {
+        if (payment.settled_amount != null && payment.settled_amount !== '') {
+            signed_field = 'settled_amount';
+            signed_amount = String(payment.settled_amount);
+        }
+        else if (payment.gross_amount != null && payment.gross_amount !== '') {
+            signed_field = 'gross_amount';
+            signed_amount = String(payment.gross_amount);
+        }
+    }
+    else {
+        signed_field = 'net_amount';
+        signed_amount = payment.net_amount != null ? String(payment.net_amount) : null;
+    }
+    if (!payee || !(0, base_payer_js_1.isEvmAddress)(payee)) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_payee',
+        };
+    }
+    if (signed_amount == null) {
+        return {
+            checked: false,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_signed_amount',
+        };
+    }
+    const transfer = sumUsdcTransfersToPayee(logs, payee, options.usdcAddress);
+    if (transfer == null) {
+        return {
+            checked: true,
+            matches: false,
+            payload_version: version,
+            signed_field,
+            signed_amount,
+            transfer_amount: null,
+            payee,
+            reason: 'no_transfer_to_payee',
+        };
+    }
+    const matches = BigInt(signed_amount) === transfer;
+    return {
+        checked: true,
+        matches,
+        payload_version: version,
+        signed_field,
+        signed_amount,
+        transfer_amount: transfer.toString(),
+        payee,
+        reason: matches
+            ? undefined
+            : `amount_mismatch: signed ${signed_field} ${signed_amount} !== transfer ${transfer.toString()}`,
+    };
 }
 /**
  * Verify a receipt's ES256 issuer signature against a JWK (public key).
@@ -146,59 +357,122 @@ function verifyIssuerSignature(receipt, jwk) {
  * @param receipt - Receipt JSON with issuer_signature
  * @param jwks - JWKS with keys array
  */
-function verifyIssuerSignatureWithJwks(receipt, jwks) {
+function jwksCandidates(jwks, kid) {
+    const keys = jwks?.keys || [];
+    const es256 = keys.filter((k) => (0, jws_js_1.isEs256PublicJwk)(k) && (k.alg == null || k.alg === 'ES256'));
+    if (!kid)
+        return es256;
+    return es256.filter((k) => k.kid === kid);
+}
+/**
+ * Verify an issuer signature against trusted keys only.
+ *
+ * Trust, in order:
+ *   1. A JWKS entry matched by `kid` (supplied file or fetched issuer JWKS).
+ *   2. An embedded `issuer_jwk` whose RFC 7638 thumbprint equals a pinned trusted kid.
+ *
+ * An embedded key that merely verifies the bytes is `key untrusted`.
+ */
+function verifyIssuerSignatureWithJwks(receipt, jwks, options = {}) {
     const sig = receipt.issuer_signature;
     if (!sig) {
-        return { checked: false, valid: false, reason: 'no_issuer_signature' };
-    }
-    const pinned = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
-    if (pinned && sig.jws) {
-        const jwsResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, pinned);
-        return {
-            checked: true,
-            valid: jwsResult.valid,
-            kid: pinned.kid || sig.kid,
-            reason: jwsResult.reason,
-        };
+        return { checked: false, valid: false, key_trusted: false, reason: 'no_issuer_signature' };
     }
+    const trustedKids = options.trustedKids ?? jws_js_1.DEFAULT_TRUSTED_ISSUER_KIDS;
+    const header = sig.jws ? (0, jws_js_1.readJwsHeader)(sig.jws) : null;
+    const kid = header?.kid || sig.kid;
+    const embedded = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
+    const pinned = !!(embedded && (0, jws_js_1.isPinnedTrustedJwk)(embedded, trustedKids));
     if (sig.jws) {
-        if (!jwks || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
-            return { checked: false, valid: false, reason: 'empty_jwks' };
-        }
-        const candidates = sig.kid
-            ? jwks.keys.filter(k => k.kid === sig.kid && k.alg === 'ES256')
-            : jwks.keys.filter(k => k.alg === 'ES256');
-        if (candidates.length === 0) {
-            return { checked: false, valid: false, reason: 'no_matching_key' };
-        }
-        for (const jwk of candidates) {
+        const fromJwks = jwksCandidates(jwks, kid);
+        for (const jwk of fromJwks) {
             const jwsResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, jwk);
             if (jwsResult.valid) {
-                return { checked: true, valid: true, kid: jwk.kid || sig.kid };
+                return {
+                    checked: true,
+                    valid: true,
+                    key_trusted: true,
+                    trust: 'jwks',
+                    kid: jwk.kid || kid,
+                    payload: jwsResult.payload,
+                };
+            }
+        }
+        if (pinned && embedded) {
+            const pinResult = (0, jws_js_1.verifyIssuerJws)(sig.jws, embedded);
+            if (pinResult.valid) {
+                return {
+                    checked: true,
+                    valid: true,
+                    key_trusted: true,
+                    trust: 'pinned_kid',
+                    kid: embedded.kid || (0, jws_js_1.jwkThumbprint)(embedded),
+                    payload: pinResult.payload,
+                };
             }
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: true,
+                kid: kid || embedded.kid,
+                reason: pinResult.reason || 'signature_invalid',
+            };
         }
-        return { checked: true, valid: false, reason: 'signature_invalid' };
+        if (embedded && (0, jws_js_1.verifyIssuerJws)(sig.jws, embedded).valid) {
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: false,
+                kid: embedded.kid || kid,
+                reason: jws_js_1.KEY_UNTRUSTED,
+            };
+        }
+        if (fromJwks.length === 0 && !pinned) {
+            return {
+                checked: true,
+                valid: false,
+                key_trusted: false,
+                kid,
+                reason: jws_js_1.KEY_UNTRUSTED,
+            };
+        }
+        return {
+            checked: true,
+            valid: false,
+            key_trusted: fromJwks.length > 0 || pinned,
+            kid,
+            reason: 'signature_invalid',
+        };
     }
     if (!sig.value) {
-        return { checked: false, valid: false, reason: 'no_issuer_signature' };
+        return { checked: false, valid: false, key_trusted: false, reason: 'no_issuer_signature' };
     }
-    if (!jwks || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
-        return { checked: false, valid: false, reason: 'empty_jwks' };
+    if (!jwks || !Array.isArray(jwks.keys)) {
+        return {
+            checked: false,
+            valid: false,
+            key_trusted: false,
+            kid: sig.kid,
+            reason: 'JWKS not provided — pass jwks option to verify issuer signature',
+        };
+    }
+    if (jwks.keys.length === 0) {
+        return { checked: false, valid: false, key_trusted: false, kid: sig.kid, reason: 'empty_jwks' };
     }
     // Find matching key by kid, or try all ES256 keys if no kid on signature
     const candidates = sig.kid
         ? jwks.keys.filter(k => k.kid === sig.kid && k.alg === 'ES256')
         : jwks.keys.filter(k => k.alg === 'ES256');
     if (candidates.length === 0) {
-        return { checked: false, valid: false, reason: 'no_matching_key' };
+        return { checked: false, valid: false, key_trusted: false, kid: sig.kid, reason: 'no_matching_key' };
     }
     for (const jwk of candidates) {
         const result = verifyIssuerSignature(receipt, jwk);
         if (result.valid) {
-            return result;
+            return { ...result, key_trusted: true, trust: 'jwks', kid: jwk.kid || sig.kid };
         }
     }
-    return { checked: true, valid: false, reason: 'signature_invalid' };
+    return { checked: true, valid: false, key_trusted: true, kid: sig.kid, reason: 'signature_invalid' };
 }
 /**
  * Verify a receipt's payment binding locally (no network required).
@@ -206,8 +480,18 @@ function verifyIssuerSignatureWithJwks(receipt, jwks) {
  * This recomputes the commitment from the receipt's fields and compares
  * it to the stored `binding.expected_commitment`.
  */
+function noCommitmentReason(rail) {
+    if (rail === 'unmetered' || rail === 'tfuel') {
+        return 'No binding present on receipt (unmetered or TFUEL rail)';
+    }
+    if (rail === 'usdc' || rail === 'reported') {
+        return 'No payment-binding commitment (expected_commitment is null)';
+    }
+    return 'No binding present on receipt (may be unmetered or TFUEL rail)';
+}
 function verifyBinding(receipt) {
     const binding = receipt.binding;
+    const railHint = binding?.rail || receipt.payment?.rail || null;
     if (!binding) {
         return {
             verified: false,
@@ -215,7 +499,17 @@ function verifyBinding(receipt) {
             recomputed: null,
             matches: false,
             covers: [],
-            reason: 'No binding present on receipt (may be unmetered or TFUEL rail)',
+            reason: noCommitmentReason(railHint),
+        };
+    }
+    if (binding.expected_commitment == null || binding.expected_commitment === '') {
+        return {
+            verified: false,
+            expected: null,
+            recomputed: null,
+            matches: false,
+            covers: binding.covers || [],
+            reason: noCommitmentReason(railHint),
         };
     }
     const paymentRef = receipt.payment?.ref ?? null;
@@ -329,88 +623,424 @@ function hashCanonicalPayload(receipt) {
     return (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)((0, exports.canonicalSignedPayload)(receipt)));
 }
 /**
- * Full receipt verification — binding + issuer signature + optional nullifier check.
+ * claim_id-era receipts include the key even when the value is null.
+ * Older payloads omit the key and stay valid.
+ */
+function claimIdVerdict(claims) {
+    if (!claims || !Object.prototype.hasOwnProperty.call(claims, 'claim_id')) {
+        return 'not_present_legacy';
+    }
+    const payment = asRecord(claims.payment);
+    const ref = payment?.ref;
+    const hasRef = ref != null && String(ref) !== '';
+    const id = claims.claim_id;
+    const missing = id == null || id === '';
+    if (hasRef && missing)
+        return 'refused';
+    return 'ok';
+}
+function claimString(value) {
+    if (value == null || value === '')
+        return null;
+    return String(value);
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function normFact(value, address = false) {
+    const text = claimString(value);
+    if (text == null)
+        return null;
+    return address ? text.toLowerCase() : text;
+}
+/**
+ * Fields a verifier may quote. Compared only when both the unsigned outer
+ * copy and the JWS payload carry a value.
+ */
+const CLAIM_COMPARE = [
+    { field: 'task_id', outer: (r) => r.task_id, signed: (c) => c.task_id },
+    { field: 'payment.rail', outer: (r) => r.payment?.rail, signed: (c) => asRecord(c.payment)?.rail },
+    { field: 'payment.ref', outer: (r) => r.payment?.ref, signed: (c) => asRecord(c.payment)?.ref },
+    { field: 'payment.gross_amount', outer: (r) => r.payment?.gross_amount, signed: (c) => asRecord(c.payment)?.gross_amount },
+    { field: 'payment.settled_amount', outer: (r) => r.payment?.settled_amount, signed: (c) => asRecord(c.payment)?.settled_amount },
+    { field: 'payment.net_amount', outer: (r) => r.payment?.net_amount, signed: (c) => asRecord(c.payment)?.net_amount },
+    { field: 'payment.asset', outer: (r) => r.payment?.asset, signed: (c) => asRecord(c.payment)?.asset, address: true },
+    { field: 'payment.payee', outer: (r) => r.payment?.payee, signed: (c) => asRecord(c.payment)?.payee, address: true },
+    { field: 'caller_binding.payer_wallet', outer: (r) => r.caller_binding?.payer_wallet, signed: (c) => asRecord(c.caller_binding)?.payer_wallet, address: true },
+    { field: 'caller_binding.agent_pubkey', outer: (r) => r.caller_binding?.agent_pubkey, signed: (c) => asRecord(c.caller_binding)?.agent_pubkey },
+    { field: 'caller_binding.api_key_hash', outer: (r) => r.caller_binding?.api_key_hash, signed: (c) => asRecord(c.caller_binding)?.api_key_hash },
+    { field: 'claim_id', outer: (r) => r.claim_id, signed: (c) => c.claim_id },
+    { field: 'route.model', outer: (r) => r.route?.model, signed: (c) => asRecord(c.route)?.model },
+    { field: 'route.provider', outer: (r) => r.route?.provider, signed: (c) => asRecord(c.route)?.provider },
+    { field: 'output.hash', outer: (r) => r.output?.hash, signed: (c) => asRecord(c.output)?.hash },
+    { field: 'binding.expected_commitment', outer: (r) => r.binding?.expected_commitment, signed: (c) => asRecord(c.binding)?.expected_commitment },
+    { field: 'provider_cogs.actual', outer: (r) => r.provider_cogs?.actual, signed: (c) => asRecord(c.provider_cogs)?.actual },
+];
+/** Flag unsigned outer copies that disagree with the JWS payload. */
+function diffOuterClaims(receipt, claims) {
+    if (!claims)
+        return [];
+    const mismatches = [];
+    for (const spec of CLAIM_COMPARE) {
+        const outer = normFact(spec.outer(receipt), spec.address);
+        const signed = normFact(spec.signed(claims), spec.address);
+        if (outer == null || signed == null || outer === signed)
+            continue;
+        mismatches.push({
+            field: spec.field,
+            outer: claimString(spec.outer(receipt)),
+            signed: claimString(spec.signed(claims)),
+        });
+    }
+    // v9 head pair. Compared when the outer key is present, including a null
+    // signed hash against a filled-in outer copy. v8 claims skip this.
+    if ((0, head_binding_js_1.headBindingVerdict)(claims) === 'ok') {
+        const disagree = (0, head_binding_js_1.outerHeadDisagrees)(receipt, claims);
+        if (disagree) {
+            const outerValue = disagree === 'tree_head_hash' ? receipt.tree_head_hash : receipt.tolerance;
+            const signedValue = disagree === 'tree_head_hash' ? claims.tree_head_hash : claims.tolerance;
+            mismatches.push({
+                field: disagree,
+                outer: outerValue == null ? null : JSON.stringify(outerValue),
+                signed: signedValue == null ? null : JSON.stringify(signedValue),
+            });
+        }
+    }
+    return mismatches;
+}
+function receiptViewFromClaims(receipt, claims) {
+    const payment = asRecord(claims.payment);
+    const binding = asRecord(claims.binding);
+    const route = asRecord(claims.route);
+    const output = asRecord(claims.output);
+    const caller = asRecord(claims.caller_binding);
+    const modelCommitment = claimString(route?.model_commitment);
+    return {
+        ...receipt,
+        task_id: claimString(claims.task_id) || receipt.task_id,
+        payment: {
+            rail: claimString(payment?.rail) ?? undefined,
+            ref: claimString(payment?.ref),
+            gross_amount: claimString(payment?.gross_amount),
+            settled_amount: claimString(payment?.settled_amount),
+            net_amount: claimString(payment?.net_amount),
+            asset: claimString(payment?.asset),
+            payee: claimString(payment?.payee),
+            fee_amount: claimString(payment?.fee_amount),
+            protocol_fee_bps: typeof payment?.protocol_fee_bps === 'number' ? payment.protocol_fee_bps : null,
+            platform_fee: claimString(payment?.platform_fee),
+            platform_fee_bps: typeof payment?.platform_fee_bps === 'number' ? payment.platform_fee_bps : null,
+        },
+        route: {
+            model: claimString(route?.model) ?? undefined,
+            provider: claimString(route?.provider) ?? undefined,
+            model_commitment: modelCommitment ? { commitment: modelCommitment } : null,
+        },
+        output: output?.hash ? { hash: claimString(output.hash) ?? undefined } : null,
+        caller_binding: caller
+            ? {
+                payer_wallet: claimString(caller.payer_wallet),
+                agent_pubkey: claimString(caller.agent_pubkey),
+                api_key_hash: claimString(caller.api_key_hash),
+            }
+            : null,
+        provider_cogs: asRecord(claims.provider_cogs)?.actual != null
+            ? { actual: claimString(asRecord(claims.provider_cogs)?.actual) ?? undefined }
+            : receipt.provider_cogs,
+        binding: {
+            expected_commitment: binding && 'expected_commitment' in binding
+                ? (claimString(binding.expected_commitment) ?? undefined)
+                : undefined,
+            amount: claimString(binding?.amount)
+                || claimString(payment?.net_amount)
+                || claimString(payment?.gross_amount)
+                || '0',
+            rail: claimString(binding?.rail) || claimString(payment?.rail) || undefined,
+            covers: Array.isArray(binding?.covers) ? binding.covers : ['payment', 'settlement'],
+            model_commitment: claimString(binding?.model_commitment) || modelCommitment,
+            output_hash: claimString(binding?.output_hash) || claimString(output?.hash),
+        },
+    };
+}
+function payerClaimsFromPayload(payload) {
+    const payment = asRecord(payload.payment);
+    const caller = asRecord(payload.caller_binding);
+    return {
+        payment: {
+            ref: claimString(payment?.ref),
+            gross_amount: claimString(payment?.gross_amount),
+            payee: claimString(payment?.payee),
+            asset: claimString(payment?.asset),
+            rail: claimString(payment?.rail),
+        },
+        caller_binding: caller ? { payer_wallet: claimString(caller.payer_wallet) } : null,
+    };
+}
+function factsFromClaims(claims) {
+    if (!claims) {
+        return { hub: null, model: null, amount_usdc: null, tx: null, output_hash: null };
+    }
+    const payment = asRecord(claims.payment);
+    const route = asRecord(claims.route);
+    const output = asRecord(claims.output);
+    return {
+        hub: claimString(route?.provider),
+        model: claimString(route?.model),
+        amount_usdc: claimString(payment?.gross_amount),
+        tx: claimString(payment?.ref),
+        output_hash: claimString(output?.hash),
+    };
+}
+function issuerJwksUri(receipt) {
+    const fromVerification = receipt.verification?.jwks_uri;
+    if (typeof fromVerification === 'string' && fromVerification.startsWith('https://'))
+        return fromVerification;
+    const jws = receipt.issuer_signature?.jws;
+    const header = jws ? (0, jws_js_1.readJwsHeader)(jws) : null;
+    if (header?.jku && header.jku.startsWith('https://'))
+        return header.jku;
+    return null;
+}
+function httpsUrl(uri) {
+    try {
+        return new URL(uri).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function mergeJwks(primary, extra) {
+    const keys = [...(primary?.keys || []), ...(extra?.keys || [])];
+    if (keys.length === 0)
+        return undefined;
+    const seen = new Set();
+    const deduped = [];
+    for (const key of keys) {
+        const id = `${key.kid || ''}:${key.x || ''}:${key.y || ''}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        deduped.push(key);
+    }
+    return { keys: deduped };
+}
+/** Fetch a JWKS document. Caller decides whether the URL is a trust root. */
+async function fetchIssuerJwks(uri, fetchImpl = globalThis.fetch) {
+    if (!httpsUrl(uri))
+        throw new Error('jwks_uri must be https');
+    const res = await fetchImpl(uri);
+    if (!res.ok)
+        throw new Error(`jwks_fetch_failed: ${res.status}`);
+    const body = await res.json();
+    if (!body || !Array.isArray(body.keys))
+        throw new Error('jwks_malformed');
+    return body;
+}
+/**
+ * Full receipt verification — trusted issuer signature, signed-claim facts,
+ * optional on-chain payer and nullifier checks.
  *
- * @param receipt The Chit402 receipt JSON
- * @param options.jwks JWKS for issuer signature verification (no network fetch)
- * @param options.checkNullifier Whether to verify nullifier on-chain (requires network)
- * @param options.rpcUrl RPC URL for on-chain checks
+ * Facts (amount, payer, payee, asset, tx, model) are taken only from a JWS
+ * that verified under a trusted key. The embedded `issuer_jwk` is not trusted
+ * unless its RFC 7638 thumbprint is a pinned kid, or the same key is in a JWKS.
  */
-/** Extract JWS claims for payer binding when present. */
+/** Extract JWS claims for payer binding. Prefers the JWS payload over the outer copy. */
 function receiptPayerClaims(receipt) {
     return (0, payer_js_1.receiptPayerClaimsFromEnvelope)(receipt);
 }
+function normalizeBoundRoot(root) {
+    if (root == null || root === '')
+        return null;
+    const hex = String(root).replace(/^0x/i, '').toLowerCase();
+    return /^[0-9a-f]{64}$/.test(hex) ? hex : null;
+}
+/**
+ * True when the supplied head is the signed prefix, or a later head whose
+ * inclusion proof contains this receipt's leaf.
+ */
+function suppliedHeadCovers(receipt, signedRoot, head, inclusion) {
+    const signed = normalizeBoundRoot(signedRoot);
+    const supplied = normalizeBoundRoot(head?.root);
+    if (!signed || !supplied)
+        return false;
+    if (signed === supplied)
+        return true;
+    if (!inclusion || !Array.isArray(inclusion.proof) || inclusion.leaf_index == null)
+        return true;
+    if (receipt.task_id == null)
+        return false;
+    const row = inclusion.row_hash ?? receipt.book_chain?.row_hash ?? '';
+    const leaf = (0, anchor_witness_js_1.leafHash)(Buffer.from(`${receipt.task_id}|${row}`));
+    if (typeof inclusion.leaf === 'string' && /^[0-9a-fA-F]{64}$/.test(inclusion.leaf)
+        && inclusion.leaf.toLowerCase() !== leaf.toString('hex')) {
+        return false;
+    }
+    const size = inclusion.tree_size ?? head.tree_size;
+    if (size == null || !Number.isInteger(Number(size)))
+        return false;
+    return (0, anchor_witness_js_1.verifyMerkleInclusion)(leaf, Number(inclusion.leaf_index), Number(size), supplied, inclusion.proof);
+}
 async function verifyReceipt(receipt, options = {}) {
     const errors = [];
-    // Verify binding locally
-    const binding = verifyBinding(receipt);
-    if (!binding.matches && binding.expected) {
-        errors.push('Payment binding mismatch');
-    }
-    // Verify issuer signature — pinned JWK in receipt, optional JWKS file, or legacy detached sig
-    let issuer_signature;
-    const pinned = (0, jws_js_1.resolvePinnedIssuerJwk)(receipt);
-    if (pinned && receipt.issuer_signature?.jws) {
-        const jwsResult = (0, jws_js_1.verifyIssuerJws)(receipt.issuer_signature.jws, pinned);
-        issuer_signature = {
-            checked: true,
-            valid: jwsResult.valid,
-            kid: pinned.kid || receipt.issuer_signature.kid,
-            reason: jwsResult.reason,
-        };
-        if (!jwsResult.valid) {
-            errors.push(`Issuer signature invalid: ${jwsResult.reason}`);
+    const trustedKids = options.trustedKids ?? jws_js_1.DEFAULT_TRUSTED_ISSUER_KIDS;
+    const trustedHosts = options.trustedJwksHosts ?? jws_js_1.DEFAULT_TRUSTED_JWKS_HOSTS;
+    let jwks = options.jwks;
+    if (options.jwksUri || options.fetchJwks) {
+        const uri = options.jwksUri || issuerJwksUri(receipt);
+        const allowed = !!uri && (options.jwksUri ? httpsUrl(uri) : (0, jws_js_1.jwksHostAllowed)(uri, trustedHosts));
+        if (uri && allowed) {
+            try {
+                const fetched = await fetchIssuerJwks(uri, options.fetchImpl);
+                jwks = mergeJwks(jwks, fetched);
+            }
+            catch (err) {
+                errors.push(`JWKS fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else if (options.jwksUri) {
+            errors.push('JWKS URI rejected — only https URLs are fetched');
+        }
+        else if (options.fetchJwks && uri) {
+            errors.push(`JWKS host untrusted: ${uri}`);
         }
     }
-    else if (options.jwks) {
-        issuer_signature = verifyIssuerSignatureWithJwks(receipt, options.jwks);
+    let issuer_signature;
+    if (receipt.issuer_signature?.jws || receipt.issuer_signature?.value) {
+        issuer_signature = verifyIssuerSignatureWithJwks(receipt, jwks, { trustedKids });
         if (issuer_signature.checked && !issuer_signature.valid) {
-            errors.push(`Issuer signature invalid: ${issuer_signature.reason}`);
+            errors.push(issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+                ? jws_js_1.KEY_UNTRUSTED
+                : `Issuer signature invalid: ${issuer_signature.reason}`);
         }
     }
     else if (receipt.issuer_signature) {
         issuer_signature = {
             checked: false,
             valid: false,
+            key_trusted: false,
             kid: receipt.issuer_signature.kid,
-            reason: receipt.issuer_signature.jws
-                ? 'No pinned issuer_jwk and JWKS not provided — pass jwks option or use a receipt with issuer_signature.issuer_jwk'
-                : 'JWKS not provided — pass jwks option to verify issuer signature',
+            reason: 'JWKS not provided — pass jwks option to verify issuer signature',
         };
     }
     else {
         issuer_signature = {
             checked: false,
             valid: false,
+            key_trusted: false,
             reason: 'No issuer signature present on receipt',
         };
     }
-    // Verify payer on-chain when requested (Base USDC or Solana USDC)
+    const decoded = receipt.issuer_signature?.jws
+        ? (0, payer_js_1.decodeJwsPayload)(receipt.issuer_signature.jws)
+        : null;
+    const claim_mismatches = diffOuterClaims(receipt, decoded);
+    for (const mismatch of claim_mismatches) {
+        errors.push(`outer/signed mismatch: ${mismatch.field} (outer ${mismatch.outer}, signed ${mismatch.signed})`);
+    }
+    const verifiedClaims = issuer_signature.valid ? issuer_signature.payload : undefined;
+    const claim_id = claimIdVerdict(issuer_signature.valid ? verifiedClaims : decoded);
+    if (issuer_signature.valid && claim_id === 'refused') {
+        errors.push('payment.ref is set and claim_id is null');
+    }
+    const headVerdict = (0, head_binding_js_1.headBindingVerdict)(issuer_signature.valid ? verifiedClaims : null);
+    const headMissing = headVerdict === 'missing';
+    if (headMissing) {
+        errors.push('payload v9 requires tree_head_hash and tolerance inside signed claims');
+    }
+    const signedBinding = headVerdict === 'ok' ? (0, head_binding_js_1.signedHeadBinding)(verifiedClaims) : null;
+    // A published head may differ from the signed prefix. That is not a failure.
+    // An inclusion proof, when one is supplied, must be for this receipt's leaf
+    // (`task_id|row_hash`), not an arbitrary hash already in the tree.
+    let headMismatch = false;
+    if (signedBinding?.tree_head_hash && options.head?.root && options.inclusion) {
+        if (!suppliedHeadCovers(receipt, signedBinding.tree_head_hash, options.head, options.inclusion)) {
+            headMismatch = true;
+            errors.push('tree_head_mismatch');
+        }
+    }
+    let binding;
+    if (receipt.issuer_signature?.jws) {
+        if (verifiedClaims) {
+            binding = verifyBinding(receiptViewFromClaims(receipt, verifiedClaims));
+        }
+        else {
+            binding = {
+                verified: false,
+                expected: null,
+                recomputed: null,
+                matches: false,
+                covers: [],
+                reason: issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+                    ? 'Binding not checked — issuer key untrusted'
+                    : 'Binding not checked — issuer signature not verified',
+            };
+        }
+    }
+    else {
+        binding = verifyBinding(receipt);
+    }
+    if (!binding.matches && binding.expected) {
+        errors.push('Payment binding mismatch');
+    }
+    const signedPayerClaims = verifiedClaims ? payerClaimsFromPayload(verifiedClaims) : null;
     let payer;
     if (options.checkPayer) {
-        const payerResult = await (0, payer_js_1.verifyPayerBinding)(receiptPayerClaims(receipt), {
-            rpcUrl: options.rpcUrl,
-            solanaRpcUrl: options.solanaRpcUrl,
-            fetchSolanaTransaction: options.fetchSolanaTransaction,
-            fetchBaseReceipt: options.fetchBaseReceipt,
-        });
+        if (!signedPayerClaims) {
+            payer = {
+                checked: false,
+                valid: false,
+                reason: 'Payer facts come from verified signed claims — issuer signature is not trusted',
+            };
+        }
+        else {
+            const payerResult = await (0, payer_js_1.verifyPayerBinding)(signedPayerClaims, {
+                rpcUrl: options.rpcUrl,
+                solanaRpcUrl: options.solanaRpcUrl,
+                fetchSolanaTransaction: options.fetchSolanaTransaction,
+                fetchBaseReceipt: options.fetchBaseReceipt,
+            });
+            payer = {
+                checked: payerResult.checked,
+                valid: payerResult.valid,
+                rail: payerResult.rail,
+                reason: payerResult.reason,
+                payer_wallet: payerResult.payerWallet ?? signedPayerClaims.caller_binding?.payer_wallet ?? null,
+                payee: signedPayerClaims.payment?.payee ?? null,
+                asset: signedPayerClaims.payment?.asset ?? null,
+                amount: payerResult.expectedAmount ?? signedPayerClaims.payment?.gross_amount ?? null,
+            };
+            if (payerResult.checked && !payerResult.valid) {
+                errors.push(`Payer binding mismatch: ${payerResult.reason}`);
+            }
+        }
+    }
+    else if (signedPayerClaims?.caller_binding?.payer_wallet && signedPayerClaims.payment?.ref) {
         payer = {
-            checked: payerResult.checked,
-            valid: payerResult.valid,
-            rail: payerResult.rail,
-            reason: payerResult.reason,
+            checked: false,
+            valid: false,
+            payer_wallet: signedPayerClaims.caller_binding.payer_wallet,
+            payee: signedPayerClaims.payment.payee ?? null,
+            asset: signedPayerClaims.payment.asset ?? null,
+            amount: signedPayerClaims.payment.gross_amount ?? null,
+            reason: 'On-chain payer check not requested — pass checkPayer: true',
         };
-        if (payerResult.checked && !payerResult.valid) {
-            errors.push(`Payer binding mismatch: ${payerResult.reason}`);
-        }
     }
-    else if (receipt.caller_binding?.payer_wallet && receipt.payment?.ref) {
+    else if (!receipt.issuer_signature?.jws && receipt.caller_binding?.payer_wallet && receipt.payment?.ref) {
         payer = {
             checked: false,
             valid: false,
             reason: 'On-chain payer check not requested — pass checkPayer: true',
         };
     }
+    else if (receipt.issuer_signature?.jws && !issuer_signature.valid) {
+        payer = {
+            checked: false,
+            valid: false,
+            reason: 'Payer facts come from verified signed claims — issuer signature is not trusted',
+        };
+    }
     else {
         payer = {
             checked: false,
@@ -418,7 +1048,6 @@ async function verifyReceipt(receipt, options = {}) {
             reason: 'No payer_wallet or payment.ref to verify',
         };
     }
-    // Verify nullifier on-chain if requested
     let nullifier;
     if (options.checkNullifier && receipt.proof?.nullifier) {
         nullifier = await verifyNullifier(receipt, {
@@ -439,64 +1068,166 @@ async function verifyReceipt(receipt, options = {}) {
                 : 'On-chain check not requested',
         };
     }
-    // Extract frozen fields
-    const hub = receipt.route?.provider ?? null;
-    const model = receipt.route?.model ?? null;
-    const amount_usdc = receipt.payment?.gross_amount ?? null;
-    const tx = receipt.payment?.ref ?? null;
-    const output_hash = receipt.output?.hash ?? null;
-    // Determine overall status with strict signature semantics:
-    // - If JWKS provided and signature invalid/kid mismatch/no matching key → 'failed'
-    // - If receipt has issuer_signature but no JWKS provided → 'partial' (cannot verify)
-    // - Unsigned receipts can be 'partial' or 'verified' based on binding
-    let overall;
-    // Check for signature verification failure (JWKS provided but signature invalid)
-    const jwksProvided = !!options.jwks;
+    const facts = factsFromClaims(verifiedClaims);
+    const warnings = [];
+    const preimages = await (0, preimage_js_1.verifyPublishedPreimages)(receipt, {
+        requirePreimages: options.requirePreimages === true,
+        fetchImpl: options.fetchImpl,
+        trustedHosts,
+    });
+    if (!preimages.ok)
+        errors.push(...preimages.errors);
+    const signedPayloadHash = verifiedClaims && 'payload_hash' in verifiedClaims
+        ? verifiedClaims.payload_hash
+        : null;
+    const storedPreimage = typeof receipt.issuer_signature?.canonical_preimage === 'string'
+        ? receipt.issuer_signature.canonical_preimage
+        : null;
+    let canonicalPreimageFailed = false;
+    if (storedPreimage != null) {
+        const storedCheck = (0, canonical_preimage_js_1.verifyCanonicalPreimageBytes)(storedPreimage, signedPayloadHash);
+        if (!storedCheck.ok) {
+            canonicalPreimageFailed = true;
+            if (storedCheck.reason)
+                errors.push(`canonical preimage: ${storedCheck.reason}`);
+        }
+    }
+    if (typeof options.canonicalPreimage === 'string') {
+        const fileCheck = (0, canonical_preimage_js_1.verifyCanonicalPreimageBytes)(options.canonicalPreimage, signedPayloadHash);
+        if (!fileCheck.ok) {
+            canonicalPreimageFailed = true;
+            if (fileCheck.reason)
+                errors.push(`canonical preimage: ${fileCheck.reason}`);
+        }
+    }
+    const issuedAt = (verifiedClaims && 'iat' in verifiedClaims ? verifiedClaims.iat : null)
+        ?? decoded?.iat
+        ?? receipt.created_at
+        ?? null;
+    const historyPin = (0, issuer_history_js_1.readIssuerHistoryPin)(verifiedClaims);
+    const payloadVersion = Number(verifiedClaims?.payload_version);
+    // Payload v10 signs the history pin. A missing pin fails even when the
+    // caller did not pass a history file or ask for a fetch.
+    const pinRequired = !options.skipIssuerHistory
+        && Number.isFinite(payloadVersion)
+        && payloadVersion >= canonical_preimage_js_1.CANONICAL_PAYLOAD_VERSION;
+    const historyAsked = pinRequired || (!options.skipIssuerHistory && !!(options.issuerHistory
+        || options.issuerHistoryBytes
+        || options.fetchIssuerHistory
+        || options.strictIssuerHistory
+        || options.issuerHistoryUrl
+        || historyPin));
+    const issuer_history = historyAsked
+        ? await (0, issuer_history_js_1.checkReceiptIssuerHistory)(receipt, {
+            document: options.issuerHistory ?? null,
+            documentBytes: options.issuerHistoryBytes ?? null,
+            fetchHistory: options.fetchIssuerHistory === true || options.strictIssuerHistory === true,
+            strict: options.strictIssuerHistory === true,
+            historyUrl: options.issuerHistoryUrl ?? null,
+            jwks,
+            trustedKids,
+            fetchImpl: options.fetchImpl,
+            trustedHosts,
+            issuedAt,
+            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
+            pin: historyPin,
+            requirePin: pinRequired,
+        })
+        : {
+            checked: false,
+            ok: true,
+            unreachable: false,
+            warning: null,
+            reason: null,
+            kid: issuer_signature.kid ?? receipt.issuer_signature?.kid ?? null,
+        };
+    if (issuer_history.warning)
+        warnings.push(issuer_history.warning);
+    if (issuer_history.checked && !issuer_history.ok && issuer_history.reason) {
+        errors.push(`issuer history: ${issuer_history.reason}`);
+    }
     const hasIssuerSig = !!receipt.issuer_signature;
-    const hasPinnedJwk = !!pinned && !!receipt.issuer_signature?.jws;
-    const issuerSigInvalid = (jwksProvided || hasPinnedJwk) && hasIssuerSig && !issuer_signature.valid;
-    // Binding failure
-    const bindingFailed = binding.expected && !binding.matches;
-    const payerFailed = options.checkPayer && payer.checked && !payer.valid;
-    if (issuerSigInvalid || bindingFailed || payerFailed) {
-        // JWKS provided but signature invalid, OR binding mismatch → failed
+    const jwksWasSupplied = !!(options.jwks || options.jwksUri || (options.fetchJwks && jwks));
+    const claimRefused = issuer_signature.valid && claim_id === 'refused';
+    const signatureFailed = hasIssuerSig && !issuer_signature.valid && (!!issuer_signature.checked
+        || jwksWasSupplied
+        || issuer_signature.reason === jws_js_1.KEY_UNTRUSTED
+        || issuer_signature.reason === 'no_matching_key'
+        || issuer_signature.reason === 'empty_jwks');
+    const mismatchFailed = claim_mismatches.length > 0;
+    const bindingFailed = !!(binding.expected && !binding.matches);
+    const payerFailed = !!(options.checkPayer && payer.checked && !payer.valid);
+    const nullifierFailed = !!(options.checkNullifier
+        && receipt.proof?.nullifier
+        && nullifier.anchored === false);
+    const signatureUnchecked = hasIssuerSig && !issuer_signature.checked;
+    let overall;
+    const preimageFailed = !preimages.ok;
+    const historyFailed = issuer_history.checked && !issuer_history.ok;
+    if (signatureFailed || mismatchFailed || bindingFailed || payerFailed || nullifierFailed || claimRefused || headMissing || headMismatch || preimageFailed || historyFailed || canonicalPreimageFailed) {
         overall = 'failed';
     }
-    else if (hasIssuerSig && !jwksProvided && !hasPinnedJwk) {
-        // Receipt has signature but no offline key material → partial
+    else if (signatureUnchecked) {
         overall = 'partial';
     }
-    else if (binding.matches
+    else if (!binding.expected && !hasIssuerSig && !options.checkPayer) {
+        overall = 'partial';
+    }
+    else if ((binding.matches || !binding.expected)
         && (!options.checkPayer || payer.valid)
-        && (!options.checkNullifier || nullifier.anchored)) {
-        // Binding matches, signature OK (or no signature), nullifier OK → verified
+        && (!options.checkNullifier || !receipt.proof?.nullifier || nullifier.anchored === true)
+        && (issuer_signature.valid || !hasIssuerSig)) {
         overall = 'verified';
     }
-    else if (binding.matches
-        || issuer_signature.valid
-        || (options.checkPayer && payer.valid)
-        || (nullifier.verified && nullifier.anchored)) {
-        // At least one check passed → partial
-        overall = 'partial';
-    }
-    else if (!binding.expected && !receipt.proof?.nullifier && !hasIssuerSig) {
-        // No binding/sig/nullifier to verify (unmetered/demo) → partial
+    else {
         overall = 'partial';
     }
-    else {
+    // A refusal is a different document. Recognition uses the signed JWS
+    // schema, not only the unsigned outer schema. A valid issuer signature
+    // here must not be reported as a verified payment.
+    const verifiedSchema = typeof verifiedClaims?.schema === 'string' ? verifiedClaims.schema : null;
+    if (verifiedSchema === refusal_js_1.REFUSAL_SCHEMA || (0, refusal_js_1.isRefusalDocument)(receipt)) {
+        errors.push('refusal document is not a payment receipt');
         overall = 'failed';
     }
+    const signedPayment = asRecord(verifiedClaims?.payment);
+    const signedSettlement = asRecord(verifiedClaims?.settlement);
+    const receipt_lane = (0, receipt_lane_js_1.receiptLaneFromVerification)({
+        receipt,
+        claims: {
+            payment: signedPayment ? {
+                ref: typeof signedPayment.ref === 'string' ? signedPayment.ref : null,
+                rail: typeof signedPayment.rail === 'string' ? signedPayment.rail : null,
+                collected: typeof signedPayment.collected === 'boolean' ? signedPayment.collected : null,
+            } : null,
+            settlement: signedSettlement ? {
+                kind: typeof signedSettlement.kind === 'string' ? signedSettlement.kind : null,
+            } : null,
+        },
+        issuerValid: issuer_signature.valid === true,
+        payer: { checked: payer.checked, valid: payer.valid },
+        head: options.head ?? null,
+    });
     return {
         receipt_id: receipt.task_id,
         binding,
         issuer_signature,
         payer,
         nullifier,
-        output_hash,
-        hub,
-        model,
-        amount_usdc,
-        tx,
+        output_hash: facts.output_hash,
+        hub: facts.hub,
+        model: facts.model,
+        amount_usdc: facts.amount_usdc,
+        tx: facts.tx,
+        claim_mismatches,
+        claim_id,
+        head_binding: signedBinding
+            ? { tree_head_hash: signedBinding.tree_head_hash, tolerance: signedBinding.tolerance }
+            : null,
+        receipt_lane,
+        preimages,
+        issuer_history,
+        warnings,
         overall,
         errors,
     };
@@ -504,6 +1235,51 @@ async function verifyReceipt(receipt, options = {}) {
 var jws_js_2 = require("./jws.js");
 Object.defineProperty(exports, "resolvePinnedIssuerJwk", { enumerable: true, get: function () { return jws_js_2.resolvePinnedIssuerJwk; } });
 Object.defineProperty(exports, "verifyIssuerJws", { enumerable: true, get: function () { return jws_js_2.verifyIssuerJws; } });
+Object.defineProperty(exports, "DEFAULT_TRUSTED_ISSUER_KIDS", { enumerable: true, get: function () { return jws_js_2.DEFAULT_TRUSTED_ISSUER_KIDS; } });
+Object.defineProperty(exports, "DEFAULT_TRUSTED_JWKS_HOSTS", { enumerable: true, get: function () { return jws_js_2.DEFAULT_TRUSTED_JWKS_HOSTS; } });
+Object.defineProperty(exports, "KEY_UNTRUSTED", { enumerable: true, get: function () { return jws_js_2.KEY_UNTRUSTED; } });
+Object.defineProperty(exports, "jwkThumbprint", { enumerable: true, get: function () { return jws_js_2.jwkThumbprint; } });
+Object.defineProperty(exports, "isPinnedTrustedJwk", { enumerable: true, get: function () { return jws_js_2.isPinnedTrustedJwk; } });
+Object.defineProperty(exports, "jwksHostAllowed", { enumerable: true, get: function () { return jws_js_2.jwksHostAllowed; } });
+var receipt_lane_js_2 = require("./receipt-lane.js");
+Object.defineProperty(exports, "buildReceiptLane", { enumerable: true, get: function () { return receipt_lane_js_2.buildReceiptLane; } });
+Object.defineProperty(exports, "receiptLaneFromVerification", { enumerable: true, get: function () { return receipt_lane_js_2.receiptLaneFromVerification; } });
+Object.defineProperty(exports, "receiptLaneDecision", { enumerable: true, get: function () { return receipt_lane_js_2.receiptLaneDecision; } });
+Object.defineProperty(exports, "deriveSettledBy", { enumerable: true, get: function () { return receipt_lane_js_2.deriveSettledBy; } });
+Object.defineProperty(exports, "deriveSettled", { enumerable: true, get: function () { return receipt_lane_js_2.deriveSettled; } });
+Object.defineProperty(exports, "anchorChangedSinceBinding", { enumerable: true, get: function () { return receipt_lane_js_2.anchorChangedSinceBinding; } });
+Object.defineProperty(exports, "RECEIPT_LANE_SCHEMA", { enumerable: true, get: function () { return receipt_lane_js_2.RECEIPT_LANE_SCHEMA; } });
+Object.defineProperty(exports, "RECEIPT_LANE_RULE", { enumerable: true, get: function () { return receipt_lane_js_2.RECEIPT_LANE_RULE; } });
+Object.defineProperty(exports, "RECEIPT_LANE_ORDERING", { enumerable: true, get: function () { return receipt_lane_js_2.RECEIPT_LANE_ORDERING; } });
+Object.defineProperty(exports, "RECEIPT_LANE_BOUNDARY", { enumerable: true, get: function () { return receipt_lane_js_2.RECEIPT_LANE_BOUNDARY; } });
+var head_binding_js_2 = require("./head-binding.js");
+Object.defineProperty(exports, "headBindingVerdict", { enumerable: true, get: function () { return head_binding_js_2.headBindingVerdict; } });
+Object.defineProperty(exports, "signedHeadBinding", { enumerable: true, get: function () { return head_binding_js_2.signedHeadBinding; } });
+Object.defineProperty(exports, "outerHeadDisagrees", { enumerable: true, get: function () { return head_binding_js_2.outerHeadDisagrees; } });
+Object.defineProperty(exports, "HEAD_BINDING_PAYLOAD_VERSION", { enumerable: true, get: function () { return head_binding_js_2.HEAD_BINDING_PAYLOAD_VERSION; } });
+var refusal_js_2 = require("./refusal.js");
+Object.defineProperty(exports, "isRefusalDocument", { enumerable: true, get: function () { return refusal_js_2.isRefusalDocument; } });
+Object.defineProperty(exports, "verifyRefusal", { enumerable: true, get: function () { return refusal_js_2.verifyRefusal; } });
+Object.defineProperty(exports, "REFUSAL_SCHEMA", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_SCHEMA; } });
+Object.defineProperty(exports, "REFUSAL_PAYLOAD_VERSION", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_PAYLOAD_VERSION; } });
+Object.defineProperty(exports, "REFUSAL_PROVES", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_PROVES; } });
+Object.defineProperty(exports, "REFUSAL_DOES_NOT_PROVE", { enumerable: true, get: function () { return refusal_js_2.REFUSAL_DOES_NOT_PROVE; } });
+var anchor_witness_js_2 = require("./anchor-witness.js");
+Object.defineProperty(exports, "verifyAnchoredRoot", { enumerable: true, get: function () { return anchor_witness_js_2.verifyAnchoredRoot; } });
+Object.defineProperty(exports, "verifyMerkleInclusion", { enumerable: true, get: function () { return anchor_witness_js_2.verifyMerkleInclusion; } });
+Object.defineProperty(exports, "extractMemos", { enumerable: true, get: function () { return anchor_witness_js_2.extractMemos; } });
+Object.defineProperty(exports, "parseAnchorMemo", { enumerable: true, get: function () { return anchor_witness_js_2.parseAnchorMemo; } });
+Object.defineProperty(exports, "leafHash", { enumerable: true, get: function () { return anchor_witness_js_2.leafHash; } });
+Object.defineProperty(exports, "ANCHOR_PROVES", { enumerable: true, get: function () { return anchor_witness_js_2.ANCHOR_PROVES; } });
+Object.defineProperty(exports, "ANCHOR_DOES_NOT_PROVE", { enumerable: true, get: function () { return anchor_witness_js_2.ANCHOR_DOES_NOT_PROVE; } });
+Object.defineProperty(exports, "SOLANA_GENESIS", { enumerable: true, get: function () { return anchor_witness_js_2.SOLANA_GENESIS; } });
+Object.defineProperty(exports, "BASE_MAINNET_CHAIN_ID", { enumerable: true, get: function () { return anchor_witness_js_2.BASE_MAINNET_CHAIN_ID; } });
+var canonical_preimage_js_2 = require("./canonical-preimage.js");
+Object.defineProperty(exports, "verifyCanonicalPreimageBytes", { enumerable: true, get: function () { return canonical_preimage_js_2.verifyCanonicalPreimageBytes; } });
+Object.defineProperty(exports, "CANONICAL_PAYLOAD_VERSION", { enumerable: true, get: function () { return canonical_preimage_js_2.CANONICAL_PAYLOAD_VERSION; } });
+var issuer_history_js_2 = require("./issuer-history.js");
+Object.defineProperty(exports, "readIssuerHistoryPin", { enumerable: true, get: function () { return issuer_history_js_2.readIssuerHistoryPin; } });
+Object.defineProperty(exports, "issuerHistoryDocumentHash", { enumerable: true, get: function () { return issuer_history_js_2.issuerHistoryDocumentHash; } });
 exports.default = {
     verifyBinding,
     verifyIssuerSignature,
@@ -521,7 +1297,10 @@ exports.default = {
     computePaymentCommitment: binding_js_1.computePaymentCommitment,
     computeInferenceBinding: binding_js_1.computeInferenceBinding,
     canonicalIssuerPayload,
+    canonicalPayloadVersion,
     canonicalSignedPayload: exports.canonicalSignedPayload,
+    reconcileSettledTransfer,
+    sumUsdcTransfersToPayee,
     hashCanonicalPayload,
     ZK_VERIFIER_ADDRESS: exports.ZK_VERIFIER_ADDRESS,
     BASE_RPC_URL: base_payer_js_1.BASE_RPC_URL,