@twzrd1111/clawrouter-mpp 0.2.0 → 0.4.0

package/README.md

@@ -3,6 +3,34 @@
 MPP (Machine Payments Protocol) payment rails for [ClawRouter](https://github.com/BlockRunAI/ClawRouter):
 pay an MPP seller over **Tempo** or **Solana** instead of x402, under ClawRouter's own spend limits.
 
+## Upgrading to 0.4.0 from 0.3.0
+
+This release includes the standalone Solana receipt verifier (#16), fulfillment wiring (#18),
+and the per-RPC deadline (#19). Verification is opt-in and does not verify Tempo receipts.
+Purchase binding remains `null/no_buyer_nonce`; Echo and a durable reference index are not supplied
+by this release. The reference index is caller-supplied and its operations have no built-in timeout.
+
+- Fulfillment rows now use `twzrd.mpp.fulfillment.v3`. v3 adds eight `receipt_reference_*`
+  verification fields (below); every other field is unchanged. Readers must accept the new schema.
+  The fields are null unless the Solana rail was given `receiptVerification`, so Tempo rows and
+  unconfigured Solana rows carry them as null ("not evaluated", never "clean").
+- `createSolanaMppFetch({ receiptVerification: { verify } })` retains the transaction the buyer
+  signed and chain-verifies the seller's receipt reference before writing the row.
+- Each `getTransaction` call made by the verifier has a deadline: `rpcTimeoutMs`, default 10000.
+  When it passes, the row records `null/rpc_unavailable` and the `signal` passed to the fetcher
+  aborts, so a hung RPC cannot hold the row. Pass that `signal` to `fetch()`.
+
+## Upgrading from 0.2.0
+
+- Fulfillment rows now use `twzrd.mpp.fulfillment.v2`. Readers must accept the new schema to retain
+  `response_bytes` and `body_sha256`; these fields are null when the recorder does not read a complete
+  body within its 1 MiB cap.
+- Credit rows carry an optional `reference` matching the error and spend record. It is a local
+  signed-payload hash, not a settlement signature.
+- `payFetch.flush({ timeoutMs })` bounds waiting for both records and ledger persistence. A timeout
+  leaves the paid response and background writes intact; an omitted timeout keeps the previous
+  unbounded wait. Values above 2,147,483,647 ms are rejected.
+
 ```ts
 import { startProxy, SpendControl, FileSpendControlStorage } from "@twzrd1111/clawrouter";
 import { createMppFetch, createSolanaMppFetch } from "@twzrd1111/clawrouter-mpp";
@@ -36,7 +64,13 @@ run asynchronously so they do not hold the response stream. `payFetch.flush?.()`
 records and fsyncs the local ledger during orderly shutdown. `startProxy` calls the rail's flush hook
 after closing its listener, and direct rail users must call `payFetch.flush()` themselves. It waits for
 active SSE responses too, so drain or cancel them before flushing; an open stream can keep the flush
-pending. Network contribution remains off unless separately enabled. It blocks unscored
+pending. `payFetch.flush({ timeoutMs })` bounds the entire wait for records and ledger persistence
+(0 through 2,147,483,647 ms). At the deadline it still attempts the ledger flush in the background,
+then rejects with an `AggregateError` holding an `MppFlushTimeoutError`. Its `pending` field counts
+unfinished records; `ledgerPending` indicates whether ledger flushing is still in progress.
+A late ledger failure is reported once: by a flush still waiting on that ledger, otherwise by the next explicit flush. (Ownership is tracked per ledger promise; an integration that returns a fresh wrapper promise for the same failure to each caller can still see it twice.) A timeout does not confirm durability.
+It never cancels or reads a response body, so a late reader still gets the whole paid response,
+and its record lands when that body is drained. Network contribution remains off unless separately enabled. It blocks unscored
 networks by default, including Tempo mainnet and Moderato, until TWZRD has a reputation corpus for
 them. The default provider also fails closed on outages; the ledger sink itself makes no network
 call. An explicit `allowUnscoredNetwork: true` requires `policy.maxAmountUsd` and returns
@@ -45,7 +79,7 @@ fulfillment row omits prompts, responses, credentials, and raw receipt headers;
 field is explicitly a seller claim. Network contribution remains a separate opt-in.
 
 This integration requires `twzrd-x402-gate@0.17.0`, which is not published yet. npm's current
-`0.16.1` does not include Tempo charge evaluation or this shared-ledger adapter.
+`0.16.2` does not include Tempo charge evaluation or the shared-ledger adapter.
 
 Receipt-safe payment metadata is available through `readPaidCallEvidence(response)` for a paid
 response from this rail. The
@@ -57,6 +91,58 @@ intent match the challenge; it is not an on-chain verification. `seller_reported
 compares labels only and does not verify model identity. A failed local write does not change an
 already-paid response; `payFetch.flush()` surfaces persistence failures to the shutdown caller.
 
+Rows use schema `twzrd.mpp.fulfillment.v3`. `response_bytes` and `body_sha256` (lowercase hex
+SHA-256) describe the complete response body as the recorder read it: a JSON body read through its
+clone, or an SSE body tapped to its end. Both are `null` when the recorder did not read the body,
+it exceeded 1 MiB, or the stream was cancelled or errored before its end; a partial body is never
+hashed. The digest is of bytes the seller sent and is not a seller attestation.
+
+### Receipt reference chain verification (Solana, opt-in)
+
+```ts
+import { createReceiptChainVerifier, createSolanaMppFetch } from "@twzrd1111/clawrouter-mpp";
+
+const verify = createReceiptChainVerifier({
+  cluster: "mainnet", // must match the rail's network; a mismatch throws at construction
+  getTransaction, // your finalized getTransaction (base64, maxSupportedTransactionVersion 0)
+  index, // a durable ReceiptReferenceIndex with an atomic bind
+  rpcTimeoutMs: 10_000, // per getTransaction call (the default); pass the given signal to fetch()
+});
+const payFetch = await createSolanaMppFetch({
+  signer,
+  rpcUrl,
+  network: "mainnet",
+  spend,
+  integration,
+  receiptVerification: { verify, finalityWaitMs: 30_000 },
+});
+```
+
+The rail keeps the base64 wire transaction from the SDK's `signed` event, the buyer clock when it
+fired, and a buyer-generated purchase id (every send of one credential is one purchase). After a
+paid response, the recorder passes the seller's `valid_format` receipt reference with those facts to
+the verifier and writes its result into the row:
+
+- `receipt_reference_chain_verified` (`true`, `false`, or `null`), `receipt_reference_finalized_slot`,
+  `receipt_reference_mismatch` (why `false`), and `receipt_reference_unverified_reason` (why `null`;
+  `verifier_error` when the verifier threw).
+- `receipt_reference_purchase_bound` and its reason. It stays `null/no_buyer_nonce` until a seller
+  echoes a buyer nonce; `chain_verified: true` does not mean the payment belongs to this purchase alone.
+- `receipt_reference_local_acceptance` (`accepted`, `refused`, or `null`) and
+  `receipt_reference_refusal_reason` (`reference_reused`, `stale_by_local_clock`): this sink's
+  policy, which never changes a chain field.
+
+Verification never delays or changes the response. It delays only the row and `flush()`.
+`finalityWaitMs` (default 0) re-checks a reference that is not finalized yet every `finalityPollMs`
+(default 2000); with the default, an unfinalized reference is recorded as `null/not_finalized`.
+`finalityWaitMs` is not an RPC timeout: each `getTransaction` call has its own deadline,
+`rpcTimeoutMs` on the verifier (default 10000). When it passes, the fetcher's `signal` aborts and
+the reference is recorded as `null/rpc_unavailable`. A row therefore waits at most about
+`finalityWaitMs + rpcTimeoutMs` on the chain. The reference index has no deadline, so a durable
+index must bound its own calls; `flush({ timeoutMs })` bounds only how long the caller waits.
+No RPC URL ships with the package. `InMemoryReceiptReferenceIndex` forgets on restart and is for
+tests. See `docs/receipt-chain-verify.md` for each check.
+
 This candidate requires `@twzrd1111/clawrouter >=0.12.309`, including deferred streaming headers.
 The fork is the release target. Upstream PRs #545 and #546 are independent of this release.
 
@@ -121,6 +207,13 @@ synchronous claim gives concurrent duplicates one winner. The claim remains spen
 model fails. This helper does not verify a payment itself,
 and installing a buyer rail cannot add replay protection to a remote seller.
 
+`SpentProofLedger` keeps claims in memory, so a restart or a second process forgets spent
+proofs, and a proof can be redeemed again while its challenge is still valid. A seller with
+more than one process, or one that restarts, needs a durable, atomic uniqueness check shared by
+every worker (for example a unique key on network plus transaction signature, as an
+authoritative settlement table provides). Rejecting expired challenges narrows the window but
+does not close it on its own.
+
 ## Credits for signed calls with no completion
 
 ```ts
@@ -155,6 +248,9 @@ and request deadlines cancel the upstream reader and clean up coalesced callers.
 `CreditLedger` and `creditPaidNoCompletion(ledger, error, fields)` are also public for callers
 with their own ledger; `readCredits(ledger)` reads that ledger. Retrying the credit operation
 returns the same immutable row and invokes no signer. It does not retry a model request.
+Each row carries the payment `reference` from the error (or from `fields.reference`) when one
+is known, so a credit can be joined to the error and the spend record. The reference is a hash
+of the signed payload, not a chain signature; an unknown reference is left off the row.
 
 Both ledgers are in memory, scoped to one process, and reset on restart. Credits record
 signed attempts, not confirmed settlement or redeemable balances. There is no refund, chain

package/dist/index.d.ts

@@ -1,9 +1,126 @@
 import { Account } from 'viem';
-import { SpendControl, PayFetch, SpendRecord } from '@twzrd1111/clawrouter';
+import { PayFetch, SpendControl, SpendRecord } from '@twzrd1111/clawrouter';
 export { PayFetch } from '@twzrd1111/clawrouter';
 import { KeyPairSigner } from '@solana/kit';
 
-declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v1";
+/** A blockhash stays valid for about 150 slots, roughly 60-90 s. */
+declare const LANDING_WINDOW_SECONDS = 90;
+declare const CLUSTER_IDS: {
+    readonly mainnet: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    readonly devnet: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+};
+type SolanaCluster = keyof typeof CLUSTER_IDS;
+type TrustedMint = {
+    decimals: number;
+    tokenPrograms: readonly string[];
+};
+/** Classic SPL Token USD mints with 6 decimals: USDC mainnet, USDC devnet, USDT mainnet. */
+declare const DEFAULT_TRUSTED_USD_MINTS: Readonly<Record<string, TrustedMint>>;
+type ChainMismatch = "bad_reference_format" | "wrong_network" | "signature_mismatch" | "message_mismatch" | "buyer_signature_missing" | "untrusted_token_program" | "untrusted_mint" | "decimals_mismatch" | "tx_failed" | "no_matching_transfer" | "multiple_matching_transfers" | "amount_mismatch" | "mint_mismatch" | "payee_mismatch" | "payer_mismatch";
+type ChainUnverifiedReason = "rpc_unavailable" | "not_finalized" | "no_fetcher" | "non_solana" | "no_signed_transaction" | "splits_unsupported" | "unnormalized_terms" | "unsupported_message_format"
+/** The verifier itself threw; recorded by the fulfillment hook, never returned by `verify`. */
+ | "verifier_error";
+type ReceiptChainVerification = {
+    receipt_reference_chain_verified: boolean | null;
+    receipt_reference_finalized_slot: number | null;
+    receipt_reference_mismatch: ChainMismatch | null;
+    receipt_reference_unverified_reason: ChainUnverifiedReason | null;
+    receipt_reference_purchase_bound: boolean | null;
+    receipt_reference_purchase_bound_reason: "nonce_mismatch" | "no_buyer_nonce" | "chain_unverified" | null;
+    receipt_reference_local_acceptance: "accepted" | "refused" | null;
+    receipt_reference_refusal_reason: "reference_reused" | "stale_by_local_clock" | null;
+};
+/** Compiled inner instruction as returned by getTransaction with `encoding: "base64"`. */
+type RpcInnerInstruction = {
+    programIdIndex: number;
+    accounts: number[];
+    data: string;
+};
+/** The subset of a `getTransaction` (`encoding: "base64"`, finalized) result this verifier reads. */
+type RpcTransaction = {
+    slot: number;
+    blockTime: number | null;
+    meta: {
+        err: unknown;
+        innerInstructions?: {
+            index: number;
+            instructions: RpcInnerInstruction[];
+        }[] | null;
+    } | null;
+    transaction: [string, "base64"] | readonly [string, string];
+};
+/**
+ * Must call getTransaction(signature, {commitment: "finalized", encoding: "base64",
+ * maxSupportedTransactionVersion: 0}) on the configured cluster and return its result (null when
+ * not found or not finalized). Throw on transport failure. `signal` aborts when the verifier's
+ * `rpcTimeoutMs` deadline passes; pass it to fetch() so the request is cancelled, not abandoned.
+ */
+type GetFinalizedTransaction = (signature: string, options?: {
+    signal?: AbortSignal;
+}) => Promise<RpcTransaction | null>;
+/**
+ * Durable, atomic reference -> purchase_id index. `bind` returns true when this purchase owns the
+ * reference (newly bound or already bound to the same purchase) and false when another purchase
+ * holds it; exactly one concurrent binder may win. `owner` reads without binding.
+ */
+type ReceiptReferenceIndex = {
+    bind(reference: string, purchaseId: string): Promise<boolean>;
+    owner(reference: string): Promise<string | undefined>;
+};
+/** In-memory index for tests and single-process demos. It forgets on restart, so it is not durable. */
+declare class InMemoryReceiptReferenceIndex implements ReceiptReferenceIndex {
+    #private;
+    bind(reference: string, purchaseId: string): Promise<boolean>;
+    owner(reference: string): Promise<string | undefined>;
+}
+type ReceiptChainVerifierConfig = {
+    cluster: SolanaCluster;
+    getTransaction?: GetFinalizedTransaction;
+    index: ReceiptReferenceIndex;
+    /** Trusted mint -> decimals and token programs. Defaults to DEFAULT_TRUSTED_USD_MINTS. */
+    trustedMints?: Readonly<Record<string, TrustedMint>>;
+    /** Default 600. Must exceed maxClockSkewSeconds + LANDING_WINDOW_SECONDS. */
+    maxAgeSeconds?: number;
+    /** Default 60. */
+    maxClockSkewSeconds?: number;
+    /**
+     * Deadline for one getTransaction call, in ms. Default 10000. When it passes, the fetcher's
+     * signal aborts and the reference is recorded as null/rpc_unavailable. The reference index is
+     * not covered: a durable index must bound its own calls.
+     */
+    rpcTimeoutMs?: number;
+};
+/** Default deadline for one getTransaction call. */
+declare const DEFAULT_RPC_TIMEOUT_MS = 10000;
+type ReceiptChainVerifyInput = {
+    /** Seller's receipt reference: the settled transaction signature. */
+    reference: string;
+    /** MPP payment method; only "solana" is verified. */
+    method: string;
+    /** Challenge terms as the seller sent them. */
+    network: string | null;
+    asset: string | null;
+    payTo: string | null;
+    amountAtomic: string | null;
+    /** True when the challenge carried split recipients. */
+    hasSplits?: boolean;
+    /** The buyer's own address. */
+    payer: string;
+    /** Base64 wire transaction from the rail's `signed` event, or null when not retained. */
+    signedTransaction: string | null;
+    /** Buyer clock (unix seconds) when the signed event fired. */
+    signedAtUnix: number | null;
+    /** Buyer-generated id of the logical purchase (not the seller's challenge id). */
+    purchaseId: string;
+};
+/** A built verifier. `cluster` lets a rail refuse a verifier configured for another cluster. */
+type ReceiptChainVerify = ((input: ReceiptChainVerifyInput) => Promise<ReceiptChainVerification>) & {
+    readonly cluster: SolanaCluster;
+};
+/** Build a verifier. Throws when the age policy cannot hold an honest payment. */
+declare function createReceiptChainVerifier(config: ReceiptChainVerifierConfig): ReceiptChainVerify;
+
+declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v3";
 declare const MPP_FULFILLMENT_MAX_BODY_BYTES: number;
 type MppPaymentFacts = {
     challengeId: string;
@@ -14,7 +131,14 @@ type MppPaymentFacts = {
     asset: string | null;
     amountAtomic: string | null;
 };
-type MppFulfillmentRecord = {
+/**
+ * Chain verification of the seller's receipt reference. Every field is null when no verifier ran
+ * (none configured, a non-Solana rail, or no valid-format receipt): null means "not evaluated",
+ * never "clean". See docs/receipt-chain-verify.md for each field.
+ */
+type MppReceiptReferenceVerification = ReceiptChainVerification;
+declare const RECEIPT_REFERENCE_NOT_EVALUATED: Readonly<MppReceiptReferenceVerification>;
+type MppFulfillmentRecord = MppReceiptReferenceVerification & {
     schema: typeof MPP_FULFILLMENT_RECORD_SCHEMA;
     at_unix_ms: number;
     resource_origin: string | null;
@@ -29,7 +153,10 @@ type MppFulfillmentRecord = {
     receipt_state: "valid_format" | "missing" | "invalid_format" | "unavailable";
     receipt_status: string | null;
     receipt_method: string | null;
-    /** Seller-supplied MPP receipt reference (EVM hash or Solana signature); not chain-verified here. */
+    /**
+     * Seller-supplied MPP receipt reference (EVM hash or Solana signature). Chain-verified only when
+     * the rail was given a verifier; see the receipt_reference_* verification fields.
+     */
     receipt_reference: string | null;
     receipt_timestamp: string | null;
     requested_model: string | null;
@@ -38,6 +165,18 @@ type MppFulfillmentRecord = {
     /** Equality of seller-reported and requested labels only; this does not verify the served model. */
     seller_reported_model_matches_request: boolean | null;
     gate: MppGateDecision | null;
+    /**
+     * Byte length of the complete response body as received. null when the recorder did not read
+     * the body, it exceeded MPP_FULFILLMENT_MAX_BODY_BYTES, or it was cancelled or errored first.
+     */
+    response_bytes: number | null;
+    /** Lowercase hex SHA-256 of the same complete body; null under the same conditions. */
+    body_sha256: string | null;
+};
+/** Size and digest of a complete response body, or null fields when it was not fully read. */
+type MppBodyDigest = {
+    response_bytes: number | null;
+    body_sha256: string | null;
 };
 type MppFulfillmentSink = (record: MppFulfillmentRecord) => void | Promise<void>;
 
@@ -75,6 +214,27 @@ declare class MppGateError extends Error {
     constructor(code: MppGateError["code"], challengeId: string, message: string, decision?: MppGateDecision);
 }
 
+type MppFlushOptions = {
+    /**
+     * Bound the entire wait for fulfillment records and ledger persistence. At the deadline,
+     * ledger flushing is still attempted in the background; neither writes nor response bodies
+     * are cancelled. Late ledger failures are retained for the next flush(). Omit to wait forever.
+     * Valid range: 0 through 2_147_483_647 milliseconds (Node's maximum timer delay).
+     */
+    timeoutMs?: number;
+};
+/** A rail fetch whose flush() accepts an optional deadline. Assignable to PayFetch. */
+type MppPayFetch = PayFetch & {
+    flush: (options?: MppFlushOptions) => Promise<void>;
+};
+/** The deadline elapsed; persistence may still be running and response bodies remain caller-owned. */
+declare class MppFlushTimeoutError extends Error {
+    readonly pending: number;
+    readonly timeoutMs: number;
+    readonly ledgerPending: boolean;
+    constructor(pending: number, timeoutMs: number, ledgerPending?: boolean);
+}
+
 /**
  * Tempo TIP-20 USD stablecoins priced here, lower-case, all 6 decimals (the challenge carries no
  * `decimals`). Any other asset cannot be priced, so it is refused while amount limits are set.
@@ -108,7 +268,7 @@ declare function quoteFromChallenge(challenge: ChallengeLike, usdAssets?: Readon
     amount: string | undefined;
     priceable: boolean;
 };
-declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): PayFetch;
+declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): MppPayFetch;
 
 declare const DEFAULT_SOLANA_USD_MINTS: ReadonlySet<string>;
 type SolanaNetwork = "mainnet" | "devnet" | "localnet";
@@ -122,8 +282,25 @@ type SolanaMppFetchOptions = {
     integration: MppIntegration;
     /** Injectable transport; defaults to fetch. The SDK's RPC transport is separate. */
     fetch?: typeof fetch;
+    /**
+     * Chain-verify each seller receipt reference before its fulfillment row is written. Off when
+     * omitted (the row's receipt_reference_* verification fields stay null). Never delays the response.
+     */
+    receiptVerification?: SolanaReceiptVerificationOptions;
+};
+type SolanaReceiptVerificationOptions = {
+    /** From createReceiptChainVerifier, built for the same cluster as `network`. */
+    verify: ReceiptChainVerify;
+    /**
+     * How long to keep re-checking a reference that is not finalized yet, in ms. Default 0: one check,
+     * and a not-yet-finalized reference is recorded as null/not_finalized. This delays only the row
+     * (and flush()), never the response.
+     */
+    finalityWaitMs?: number;
+    /** Delay between finality re-checks, in ms. Default 2000. */
+    finalityPollMs?: number;
 };
-declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<PayFetch>;
+declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<MppPayFetch>;
 
 /** In-memory credit row. No chain write and no signer. */
 type CreditEntry = Readonly<{
@@ -131,6 +308,11 @@ type CreditEntry = Readonly<{
     amount: string;
     challengeId: string;
     reason: string;
+    /**
+     * Payment reference from MppPaidNoCompletionError, when one is known: `mpp-` plus a short hash of
+     * the signed payload. Joins the row to the error and the spend record. Not a chain tx signature.
+     */
+    reference?: string;
 }>;
 declare class CreditLedger {
     private readonly rows;
@@ -149,6 +331,7 @@ declare class MppPaidNoCompletionError extends Error {
 /**
  * Record one credit for a paid call that returned no completion.
  * A retry of the same payer and challenge returns the first row.
+ * The row carries `fields.reference`, else the error's reference when one is known.
  * `sign`, when passed, is never called.
  */
 declare function creditPaidNoCompletion(ledger: CreditLedger, err: MppPaidNoCompletionError, fields: CreditEntry, hooks?: {
@@ -206,5 +389,5 @@ declare function fulfillPaidProof<T>(opts: {
     upstream: () => Promise<T>;
 }): Promise<T>;
 
-export { CreditLedger, DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, MPP_FULFILLMENT_MAX_BODY_BYTES, MPP_FULFILLMENT_RECORD_SCHEMA, MppGateError, MppPaidNoCompletionError, ReplayRejectedError, SpentProofLedger, createMppFetch, createSolanaMppFetch, creditPaidNoCompletion, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
-export type { CreditEntry, MppFetchOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPaymentFacts, SolanaMppFetchOptions };
+export { CreditLedger, DEFAULT_RPC_TIMEOUT_MS, DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, DEFAULT_TRUSTED_USD_MINTS, InMemoryReceiptReferenceIndex, LANDING_WINDOW_SECONDS, MPP_FULFILLMENT_MAX_BODY_BYTES, MPP_FULFILLMENT_RECORD_SCHEMA, MppFlushTimeoutError, MppGateError, MppPaidNoCompletionError, RECEIPT_REFERENCE_NOT_EVALUATED, ReplayRejectedError, SpentProofLedger, createMppFetch, createReceiptChainVerifier, createSolanaMppFetch, creditPaidNoCompletion, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
+export type { ChainMismatch, ChainUnverifiedReason, CreditEntry, GetFinalizedTransaction, MppBodyDigest, MppFetchOptions, MppFlushOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPayFetch, MppPaymentFacts, MppReceiptReferenceVerification, ReceiptChainVerification, ReceiptChainVerifierConfig, ReceiptChainVerify, ReceiptChainVerifyInput, ReceiptReferenceIndex, RpcTransaction, SolanaCluster, SolanaMppFetchOptions, SolanaReceiptVerificationOptions, TrustedMint };

package/dist/index.js

@@ -41,12 +41,18 @@ var MppPaidNoCompletionError = class extends Error {
     this.status = status;
   }
 };
+var UNKNOWN_REFERENCE = "mpp-unknown";
 function creditPaidNoCompletion(ledger, err, fields, hooks) {
   if (!(err instanceof MppPaidNoCompletionError)) {
     throw new TypeError("credit requires MppPaidNoCompletionError");
   }
   void hooks;
-  return ledger.recordOnce(fields);
+  const reference = [fields.reference, err.reference].find(
+    (value) => typeof value === "string" && value !== "" && value !== UNKNOWN_REFERENCE
+  );
+  const { reference: _dropped, ...rest } = fields;
+  void _dropped;
+  return ledger.recordOnce(reference ? { ...rest, reference } : rest);
 }
 var credits = new CreditLedger();
 function creditFromChallenge(challenge, payer) {
@@ -160,7 +166,7 @@ async function boundedSnippet(response, timeoutMs = SNIPPET_TIMEOUT_MS) {
   }
 }
 function fail(spend, call, status, detail, cause) {
-  const reference = call.reference ?? "mpp-unknown";
+  const reference = call.reference ?? UNKNOWN_REFERENCE;
   const why = status !== void 0 ? `HTTP ${status}` : "request failed";
   if (spend && call.record) {
     spend.annotateRecord(call.record, `signed, no completion (${why}) ref ${reference}`);
@@ -273,8 +279,24 @@ async function evaluateMppGate(evaluator, challenge) {
 }
 
 // src/mpp-fulfillment-record.ts
-var MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v1";
+import { createHash as createHash2 } from "crypto";
+var MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v3";
 var MPP_FULFILLMENT_MAX_BODY_BYTES = 1024 * 1024;
+var RECEIPT_REFERENCE_NOT_EVALUATED = Object.freeze({
+  receipt_reference_chain_verified: null,
+  receipt_reference_finalized_slot: null,
+  receipt_reference_mismatch: null,
+  receipt_reference_unverified_reason: null,
+  receipt_reference_purchase_bound: null,
+  receipt_reference_purchase_bound_reason: null,
+  receipt_reference_local_acceptance: null,
+  receipt_reference_refusal_reason: null
+});
+var VERIFIER_ERROR = Object.freeze({
+  ...RECEIPT_REFERENCE_NOT_EVALUATED,
+  receipt_reference_unverified_reason: "verifier_error"
+});
+var NO_BODY_DIGEST = { response_bytes: null, body_sha256: null };
 function asRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -324,6 +346,7 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
   let unavailable = false;
   let receipt;
   let sellerReportedModel = null;
+  const hash = createHash2("sha256");
   const finishEvent = () => {
     if (data.length && eventName === "payment-receipt" && !receipt) {
       try {
@@ -359,6 +382,7 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
   return {
     push(chunk) {
       totalBytes += chunk.byteLength;
+      if (totalBytes <= MPP_FULFILLMENT_MAX_BODY_BYTES) hash.update(chunk);
       if (totalBytes > MPP_FULFILLMENT_MAX_BODY_BYTES) {
         unavailable = true;
         buffer = "";
@@ -378,6 +402,10 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
         buffer = "";
       }
     },
+    /** Digest of every pushed byte; call only after the source stream reported done. */
+    digest() {
+      return totalBytes > MPP_FULFILLMENT_MAX_BODY_BYTES ? NO_BODY_DIGEST : { response_bytes: totalBytes, body_sha256: hash.digest("hex") };
+    },
     finish() {
       if (!unavailable && !receipt) {
         buffer += decoder.decode();
@@ -391,8 +419,8 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
     }
   };
 }
-async function readJsonCapped(body) {
-  if (!body) return void 0;
+async function readBodyCapped(body) {
+  if (!body) return null;
   const reader = body.getReader();
   const chunks = [];
   let size = 0;
@@ -403,15 +431,32 @@ async function readJsonCapped(body) {
       size += value.byteLength;
       if (size > MPP_FULFILLMENT_MAX_BODY_BYTES) {
         await reader.cancel().catch(() => void 0);
-        return void 0;
+        return null;
       }
       chunks.push(value);
     }
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return Buffer.concat(chunks);
+  } catch {
+    return null;
+  }
+}
+function parseJson(bytes) {
+  if (!bytes) return void 0;
+  try {
+    return JSON.parse(bytes.toString("utf8"));
   } catch {
     return void 0;
   }
 }
+function digestOf(bytes) {
+  return bytes ? {
+    response_bytes: bytes.byteLength,
+    body_sha256: createHash2("sha256").update(bytes).digest("hex")
+  } : NO_BODY_DIGEST;
+}
+async function readJsonCapped(body) {
+  return parseJson(await readBodyCapped(body));
+}
 function bodyIsJson(headers) {
   return (headers.get("content-type") ?? "").toLowerCase().includes("json");
 }
@@ -449,11 +494,20 @@ function wrappedResponse(response, body) {
   });
   return wrapped;
 }
-async function emitRecord(input, receipt, requestValue, responseValue, sink, sellerModelOverride) {
+async function emitRecord(input, receipt, requestValue, responseValue, sink, digest, sellerModelOverride) {
   const req = asRecord(requestValue);
   const res = asRecord(responseValue);
   const requestedModel = string(req?.model);
   const sellerReportedModel = string(sellerModelOverride) ?? string(res?.model);
+  const reference = string(receipt.value?.reference);
+  let verification = RECEIPT_REFERENCE_NOT_EVALUATED;
+  if (receipt.state === "valid_format" && reference && input.verifyReceiptReference) {
+    try {
+      verification = await input.verifyReceiptReference(reference);
+    } catch {
+      verification = VERIFIER_ERROR;
+    }
+  }
   const row = {
     schema: MPP_FULFILLMENT_RECORD_SCHEMA,
     at_unix_ms: Date.now(),
@@ -469,12 +523,22 @@ async function emitRecord(input, receipt, requestValue, responseValue, sink, sel
     receipt_state: receipt.state,
     receipt_status: string(receipt.value?.status),
     receipt_method: string(receipt.value?.method),
-    receipt_reference: string(receipt.value?.reference),
+    receipt_reference: reference,
     receipt_timestamp: string(receipt.value?.timestamp),
     requested_model: requestedModel,
     seller_reported_model: sellerReportedModel,
     seller_reported_model_matches_request: requestedModel && sellerReportedModel ? requestedModel.toLowerCase() === sellerReportedModel.toLowerCase() : null,
-    gate: input.gate ?? null
+    gate: input.gate ?? null,
+    response_bytes: digest.response_bytes,
+    body_sha256: digest.body_sha256,
+    receipt_reference_chain_verified: verification.receipt_reference_chain_verified,
+    receipt_reference_finalized_slot: verification.receipt_reference_finalized_slot,
+    receipt_reference_mismatch: verification.receipt_reference_mismatch,
+    receipt_reference_unverified_reason: verification.receipt_reference_unverified_reason,
+    receipt_reference_purchase_bound: verification.receipt_reference_purchase_bound,
+    receipt_reference_purchase_bound_reason: verification.receipt_reference_purchase_bound_reason,
+    receipt_reference_local_acceptance: verification.receipt_reference_local_acceptance,
+    receipt_reference_refusal_reason: verification.receipt_reference_refusal_reason
   };
   await sink(row);
 }
@@ -507,11 +571,11 @@ function recordMppFulfillment(input, sink, onPending) {
     });
     track(recording2);
     let recordingStarted = false;
-    const finishRecord = (receipt2, sellerReportedModel) => {
+    const finishRecord = (receipt2, sellerReportedModel, digest) => {
       if (recordingStarted) return;
       recordingStarted = true;
       const write = requestBody.then(
-        (request) => emitRecord(input, receipt2, request, void 0, sink, sellerReportedModel)
+        (request) => emitRecord(input, receipt2, request, void 0, sink, digest, sellerReportedModel)
       );
       void write.then(resolveRecording, rejectRecording);
       void write.catch(() => {
@@ -526,7 +590,7 @@ function recordMppFulfillment(input, sink, onPending) {
           const { done, value } = await reader.read();
           if (done) {
             const parsed = parser.finish();
-            finishRecord(parsed.receipt, parsed.sellerReportedModel);
+            finishRecord(parsed.receipt, parsed.sellerReportedModel, parser.digest());
             controller.close();
             reader.releaseLock();
             return;
@@ -534,7 +598,7 @@ function recordMppFulfillment(input, sink, onPending) {
           parser.push(value);
           controller.enqueue(value);
         } catch (error) {
-          finishRecord({ state: "unavailable", value: null }, null);
+          finishRecord({ state: "unavailable", value: null }, null, NO_BODY_DIGEST);
           controller.error(error);
         }
       },
@@ -542,14 +606,14 @@ function recordMppFulfillment(input, sink, onPending) {
         await reader.cancel(reason).catch(() => void 0);
         const parsed = parser.finish();
         const receipt2 = parsed.receipt.state === "missing" ? { state: "unavailable", value: null } : parsed.receipt;
-        finishRecord(receipt2, parsed.sellerReportedModel);
+        finishRecord(receipt2, parsed.sellerReportedModel, NO_BODY_DIGEST);
       }
     });
     return wrappedResponse(input.response, tapped);
   }
-  const responseBody = bodyIsJson(input.response.headers) ? readJsonCapped(input.response.clone().body) : Promise.resolve(void 0);
+  const responseBody = bodyIsJson(input.response.headers) ? readBodyCapped(input.response.clone().body) : Promise.resolve(null);
   const recording = Promise.all([requestBody, responseBody]).then(
-    ([request, response]) => emitRecord(input, receipt, request, response, sink)
+    ([request, bytes]) => emitRecord(input, receipt, request, parseJson(bytes), sink, digestOf(bytes))
   );
   track(recording);
   void recording.catch(() => {
@@ -583,6 +647,102 @@ function runWithMppPaymentBudget(context, run) {
   return contextStorage.run(context, run);
 }
 
+// src/mpp-flush.ts
+var MppFlushTimeoutError = class extends Error {
+  pending;
+  timeoutMs;
+  ledgerPending;
+  constructor(pending, timeoutMs, ledgerPending = false) {
+    super(
+      `MPP flush deadline reached after ${timeoutMs} ms: ${pending} fulfillment record(s) pending; ledger flush ${ledgerPending ? "still pending" : "finished"}`
+    );
+    this.name = "MppFlushTimeoutError";
+    this.pending = pending;
+    this.timeoutMs = timeoutMs;
+    this.ledgerPending = ledgerPending;
+  }
+};
+var MAX_TIMER_MS = 2147483647;
+function deadlineOf(options) {
+  const value = options?.timeoutMs;
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_TIMER_MS) {
+    throw new TypeError(`flush timeoutMs must be a number from 0 to ${MAX_TIMER_MS}`);
+  }
+  return value;
+}
+var ownership = /* @__PURE__ */ new WeakMap();
+function ownershipFor(failures) {
+  let entry = ownership.get(failures);
+  if (!entry) {
+    entry = { waiters: /* @__PURE__ */ new Map(), claimed: /* @__PURE__ */ new WeakSet() };
+    ownership.set(failures, entry);
+  }
+  return entry;
+}
+var isObject = (value) => typeof value === "object" && value !== null || typeof value === "function";
+async function flushFulfillments(pending, failures, integrationFlush, options) {
+  const timeoutMs = deadlineOf(options);
+  let timer;
+  let expired = false;
+  const deadline = timeoutMs === void 0 ? void 0 : new Promise((resolve) => {
+    timer = setTimeout(() => {
+      expired = true;
+      resolve();
+    }, timeoutMs);
+  });
+  const wait = (task) => deadline ? Promise.race([task, deadline]) : task;
+  try {
+    await wait(Promise.all([...pending]).then(() => void 0));
+    const owners = ownershipFor(failures);
+    const ownErrors = [];
+    let ledgerPending = true;
+    let waiting = true;
+    let source;
+    try {
+      source = Promise.resolve(integrationFlush());
+    } catch (error) {
+      ownErrors.push(error);
+      ledgerPending = false;
+    }
+    const release = () => {
+      if (!waiting) return;
+      waiting = false;
+      if (!source) return;
+      const left = (owners.waiters.get(source) ?? 1) - 1;
+      if (left > 0) owners.waiters.set(source, left);
+      else owners.waiters.delete(source);
+    };
+    let ledger = Promise.resolve();
+    if (source) {
+      const observed = source;
+      owners.waiters.set(observed, (owners.waiters.get(observed) ?? 0) + 1);
+      ledger = observed.catch((error) => {
+        if (waiting) {
+          ownErrors.push(error);
+          if (isObject(error)) owners.claimed.add(error);
+          const queued = failures.indexOf(error);
+          if (queued >= 0) failures.splice(queued, 1);
+        } else if (!owners.waiters.get(observed) && !(isObject(error) && owners.claimed.has(error)) && !failures.includes(error)) {
+          failures.push(error);
+        }
+      }).finally(() => {
+        ledgerPending = false;
+      });
+    }
+    try {
+      await wait(ledger);
+    } finally {
+      release();
+    }
+    const errors = [.../* @__PURE__ */ new Set([...failures.splice(0), ...ownErrors])];
+    if (expired) errors.push(new MppFlushTimeoutError(pending.size, timeoutMs, ledgerPending));
+    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/mpp-fetch.ts
 var mppxClientDeps = {
   load: () => loadOptional("mppx", MPPX_RANGE, () => import("mppx/client"))
@@ -747,20 +907,12 @@ function createMppFetch(account, base = fetch, opts) {
   payFetch.supportsNativeStreaming = true;
   payFetch.onNoCompletion = rejectPaidNoCompletion;
   payFetch.isPaidResponse = isPaidResponse;
-  payFetch.flush = async () => {
-    await Promise.all([...pendingFulfillments]);
-    const errors = fulfillmentFailures.splice(0);
-    try {
-      await integration.flush();
-    } catch (error) {
-      errors.push(error);
-    }
-    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
-  };
+  payFetch.flush = (options) => flushFulfillments(pendingFulfillments, fulfillmentFailures, () => integration.flush(), options);
   return payFetch;
 }
 
 // src/mpp-solana-fetch.ts
+import { randomUUID } from "crypto";
 import {
   assertSpendPolicyAllows as assertSpendPolicyAllows2,
   SpendPolicyError as SpendPolicyError3
@@ -775,12 +927,46 @@ var CAIP2 = {
   devnet: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
   localnet: "solana:localnet"
 };
+var MAX_TIMER_MS2 = 2147483647;
+function verificationSettings(options, network) {
+  if (options === void 0) return void 0;
+  if (typeof options?.verify !== "function") {
+    throw new TypeError("receiptVerification.verify must come from createReceiptChainVerifier");
+  }
+  if (options.verify.cluster !== network) {
+    throw new TypeError(
+      `receiptVerification is built for ${String(options.verify.cluster)}, but the rail network is ${network}`
+    );
+  }
+  const waitMs = options.finalityWaitMs ?? 0;
+  const pollMs = options.finalityPollMs ?? 2e3;
+  for (const [name, value, min] of [
+    ["finalityWaitMs", waitMs, 0],
+    ["finalityPollMs", pollMs, 1]
+  ]) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > MAX_TIMER_MS2)
+      throw new TypeError(
+        `receiptVerification.${name} must be a number from ${min} to ${MAX_TIMER_MS2}`
+      );
+  }
+  return { verify: options.verify, waitMs, pollMs };
+}
+async function verifyUntilFinal(verify, waitMs, pollMs) {
+  const deadline = Date.now() + waitMs;
+  for (; ; ) {
+    const result = await verify();
+    if (result.receipt_reference_unverified_reason !== "not_finalized") return result;
+    if (Date.now() + pollMs > deadline) return result;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
 var solanaChargeDeps = {
   load: () => loadOptional("@solana/mpp", SOLANA_MPP_RANGE, () => import("@solana/mpp/client"))
 };
 async function createSolanaMppFetch(opts) {
   assertMppIntegration(opts?.integration, "Solana");
   const integration = Object.freeze({ ...opts.integration });
+  const verification = verificationSettings(opts.receiptVerification, opts.network);
   const { charge, selectSolanaChargeChallengeFromResponse, resolveStablecoinMint } = await solanaChargeDeps.load();
   const base = opts.fetch ?? fetch;
   const usd = /* @__PURE__ */ new Set([...DEFAULT_SOLANA_USD_MINTS, ...opts.usdMints ?? []]);
@@ -877,6 +1063,8 @@ async function createSolanaMppFetch(opts) {
               let sessionSpendRecorded = false;
               let record;
               let payload = "";
+              let signedTransaction = null;
+              let signedAtUnix = null;
               try {
                 const method = charge({
                   signer: opts.signer,
@@ -887,6 +1075,8 @@ async function createSolanaMppFetch(opts) {
                     if (event.type !== "signed") return;
                     signed = true;
                     payload = event.transaction;
+                    signedTransaction = event.transaction;
+                    signedAtUnix = Math.floor(Date.now() / 1e3);
                     if (!sessionSpendRecorded) {
                       budgetContext?.recordSigned(budgetQuoteMicros);
                       sessionSpendRecorded = true;
@@ -912,12 +1102,17 @@ async function createSolanaMppFetch(opts) {
                     });
                   }
                 }
+                const splits = challenge.request.methodDetails.splits;
                 return {
                   credential,
                   payload,
                   record,
                   gate: gateDecision,
-                  payment
+                  payment,
+                  signedTransaction,
+                  signedAtUnix,
+                  purchaseId: randomUUID(),
+                  hasSplits: Array.isArray(splits) && splits.length > 0
                 };
               } catch (err) {
                 if (signed) {
@@ -951,8 +1146,32 @@ async function createSolanaMppFetch(opts) {
           const response = await base(new Request(request, { headers }));
           const paid = currentPaidCall();
           if (response.status !== 402 && paid?.signed && paid.payment) {
+            const terms = paid.payment;
+            const verifyReceiptReference = verification ? (reference) => verifyUntilFinal(
+              () => verification.verify({
+                reference,
+                method: terms.method,
+                network: terms.network,
+                asset: terms.asset,
+                payTo: terms.payTo,
+                amountAtomic: terms.amountAtomic,
+                hasSplits: result.hasSplits,
+                payer: opts.signer.address,
+                signedTransaction: result.signedTransaction,
+                signedAtUnix: result.signedAtUnix,
+                purchaseId: result.purchaseId
+              }),
+              verification.waitMs,
+              verification.pollMs
+            ) : void 0;
             return recordMppFulfillment(
-              { input: requestForRecord, response, payment: paid.payment, gate: paid.gate },
+              {
+                input: requestForRecord,
+                response,
+                payment: terms,
+                gate: paid.gate,
+                verifyReceiptReference
+              },
               integration.onFulfillment,
               trackFulfillment
             );
@@ -968,16 +1187,7 @@ async function createSolanaMppFetch(opts) {
   payFetch.supportsNativeStreaming = true;
   payFetch.onNoCompletion = rejectPaidNoCompletion;
   payFetch.isPaidResponse = isPaidResponse;
-  payFetch.flush = async () => {
-    await Promise.all([...pendingFulfillments]);
-    const errors = fulfillmentFailures.splice(0);
-    try {
-      await integration.flush();
-    } catch (error) {
-      errors.push(error);
-    }
-    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
-  };
+  payFetch.flush = (options) => flushFulfillments(pendingFulfillments, fulfillmentFailures, () => integration.flush(), options);
   return payFetch;
 }
 function solanaNetworkId(value) {
@@ -1035,17 +1245,293 @@ async function fulfillPaidProof(opts) {
   if (!won) throw new ReplayRejectedError(opts.networkId, opts.txSignature, opts.challengeId);
   return opts.upstream();
 }
+
+// src/receipt-chain-verify.ts
+var SOLANA_KIT_RANGE = "~6.10.0";
+var TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+var TOKEN_2022_PROGRAM = "TokenzQdBNbLqP7VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+var ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+var KNOWN_TOKEN_PROGRAMS = /* @__PURE__ */ new Set([TOKEN_PROGRAM, TOKEN_2022_PROGRAM]);
+var IX_TRANSFER = 3;
+var IX_TRANSFER_CHECKED = 12;
+var LANDING_WINDOW_SECONDS = 90;
+var CLUSTER_IDS = {
+  mainnet: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  devnet: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
+};
+var SYMBOL_MINTS = {
+  mainnet: { USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
+  devnet: { USDC: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU" }
+};
+var DEFAULT_TRUSTED_USD_MINTS = Object.freeze({
+  EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: { decimals: 6, tokenPrograms: [TOKEN_PROGRAM] },
+  "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU": { decimals: 6, tokenPrograms: [TOKEN_PROGRAM] },
+  Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB: { decimals: 6, tokenPrograms: [TOKEN_PROGRAM] }
+});
+var InMemoryReceiptReferenceIndex = class {
+  #owners = /* @__PURE__ */ new Map();
+  async bind(reference, purchaseId) {
+    const current = this.#owners.get(reference);
+    if (current === void 0) {
+      this.#owners.set(reference, purchaseId);
+      return true;
+    }
+    return current === purchaseId;
+  }
+  async owner(reference) {
+    return this.#owners.get(reference);
+  }
+};
+var DEFAULT_RPC_TIMEOUT_MS = 1e4;
+var MAX_TIMER_MS3 = 2147483647;
+var loadKit = () => loadOptional("@solana/kit", SOLANA_KIT_RANGE, () => import("@solana/kit"));
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+function readU64(data, offset) {
+  let value = 0n;
+  for (let i = 7; i >= 0; i--) value = value << 8n | BigInt(data[offset + i]);
+  return value;
+}
+function clusterOf(network) {
+  if (network === "mainnet" || network === "mainnet-beta" || network === CLUSTER_IDS.mainnet)
+    return "mainnet";
+  if (network === "devnet" || network === CLUSTER_IDS.devnet) return "devnet";
+  return void 0;
+}
+function createReceiptChainVerifier(config) {
+  const maxAge = config.maxAgeSeconds ?? 600;
+  const skew = config.maxClockSkewSeconds ?? 60;
+  if (!Number.isFinite(maxAge) || !Number.isFinite(skew) || skew < 0) {
+    throw new TypeError("maxAgeSeconds and maxClockSkewSeconds must be finite; skew must be >= 0");
+  }
+  if (maxAge <= skew + LANDING_WINDOW_SECONDS) {
+    throw new RangeError(
+      `maxAgeSeconds (${maxAge}) must exceed maxClockSkewSeconds (${skew}) + the ${LANDING_WINDOW_SECONDS} s landing window`
+    );
+  }
+  if (!config.index) throw new TypeError("a ReceiptReferenceIndex is required");
+  const rpcTimeoutMs = config.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+  if (typeof rpcTimeoutMs !== "number" || !Number.isFinite(rpcTimeoutMs) || rpcTimeoutMs < 1 || rpcTimeoutMs > MAX_TIMER_MS3) {
+    throw new TypeError(`rpcTimeoutMs must be a number from 1 to ${MAX_TIMER_MS3}`);
+  }
+  const trusted = config.trustedMints ?? DEFAULT_TRUSTED_USD_MINTS;
+  const cluster = config.cluster;
+  if (!(cluster in CLUSTER_IDS)) throw new TypeError(`unknown cluster ${String(cluster)}`);
+  async function fetchWithDeadline(getTransaction, reference) {
+    const controller = new AbortController();
+    let timer;
+    const expired = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const reason = new Error(`getTransaction exceeded rpcTimeoutMs (${rpcTimeoutMs} ms)`);
+        controller.abort(reason);
+        reject(reason);
+      }, rpcTimeoutMs);
+    });
+    try {
+      return await Promise.race([
+        getTransaction(reference, { signal: controller.signal }),
+        expired
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function verify(input) {
+    const chain = await chainFacts(input);
+    const verified = chain.receipt_reference_chain_verified;
+    const purchase = verified === true ? {
+      receipt_reference_purchase_bound: null,
+      receipt_reference_purchase_bound_reason: "no_buyer_nonce"
+    } : {
+      receipt_reference_purchase_bound: null,
+      receipt_reference_purchase_bound_reason: "chain_unverified"
+    };
+    let refusal = null;
+    if (chain.blockTime !== null && input.signedAtUnix !== null && Number.isFinite(input.signedAtUnix) && input.signedAtUnix - chain.blockTime > maxAge) {
+      refusal = "stale_by_local_clock";
+    }
+    if (verified === true && refusal === null) {
+      const owns = await config.index.bind(input.reference, input.purchaseId);
+      if (!owns) refusal = "reference_reused";
+    } else {
+      const owner = await config.index.owner(input.reference);
+      if (owner !== void 0 && owner !== input.purchaseId) refusal = "reference_reused";
+    }
+    const acceptance = refusal ? "refused" : verified === true ? "accepted" : null;
+    return {
+      receipt_reference_chain_verified: verified,
+      receipt_reference_finalized_slot: chain.receipt_reference_finalized_slot,
+      receipt_reference_mismatch: chain.receipt_reference_mismatch,
+      receipt_reference_unverified_reason: chain.receipt_reference_unverified_reason,
+      ...purchase,
+      receipt_reference_local_acceptance: acceptance,
+      receipt_reference_refusal_reason: refusal
+    };
+  }
+  function result(verified, code, slot = null, blockTime = null) {
+    return {
+      receipt_reference_chain_verified: verified,
+      receipt_reference_finalized_slot: slot,
+      receipt_reference_mismatch: verified === false ? code : null,
+      receipt_reference_unverified_reason: verified === null ? code : null,
+      blockTime
+    };
+  }
+  async function chainFacts(input) {
+    if (input.method !== "solana") return result(null, "non_solana");
+    const kit = await loadKit();
+    const base58 = kit.getBase58Encoder();
+    let referenceBytes;
+    try {
+      referenceBytes = new Uint8Array(base58.encode(input.reference));
+    } catch {
+      return result(false, "bad_reference_format");
+    }
+    if (referenceBytes.length !== 64) return result(false, "bad_reference_format");
+    const challengeCluster = input.network ? clusterOf(input.network) : void 0;
+    if (challengeCluster !== cluster) return result(false, "wrong_network");
+    if (input.hasSplits) return result(null, "splits_unsupported");
+    if (!input.signedTransaction) return result(null, "no_signed_transaction");
+    const symbols = SYMBOL_MINTS[cluster];
+    const asset = input.asset ? Object.prototype.hasOwnProperty.call(symbols, input.asset) ? symbols[input.asset] : input.asset : null;
+    if (!asset || !kit.isAddress(asset)) return result(null, "unnormalized_terms");
+    if (!input.payTo || !kit.isAddress(input.payTo)) return result(null, "unnormalized_terms");
+    if (!kit.isAddress(input.payer)) return result(null, "unnormalized_terms");
+    if (!input.amountAtomic || !/^\d+$/.test(input.amountAtomic))
+      return result(null, "unnormalized_terms");
+    let retained;
+    try {
+      retained = decodeWire(kit, input.signedTransaction);
+    } catch {
+      return result(null, "no_signed_transaction");
+    }
+    if (!config.getTransaction) return result(null, "no_fetcher");
+    let tx;
+    try {
+      tx = await fetchWithDeadline(config.getTransaction, input.reference);
+    } catch {
+      return result(null, "rpc_unavailable");
+    }
+    if (!tx) return result(null, "not_finalized");
+    const slot = typeof tx.slot === "number" ? tx.slot : null;
+    const blockTime = typeof tx.blockTime === "number" ? tx.blockTime : null;
+    const at = (verified, code) => result(verified, code, slot, blockTime);
+    if (!tx.meta) return at(null, "rpc_unavailable");
+    if (tx.meta.err !== null && tx.meta.err !== void 0) return at(false, "tx_failed");
+    let onChain;
+    try {
+      onChain = decodeWire(kit, tx.transaction[0]);
+    } catch {
+      return at(null, "rpc_unavailable");
+    }
+    const firstSignature = Object.values(onChain.signatures)[0];
+    if (!firstSignature || !bytesEqual(firstSignature, referenceBytes))
+      return at(false, "signature_mismatch");
+    if (!bytesEqual(onChain.messageBytes, retained.messageBytes))
+      return at(false, "message_mismatch");
+    const buyerRetained = retained.signatures[input.payer];
+    const buyerOnChain = onChain.signatures[input.payer];
+    if (!buyerRetained || !buyerOnChain || !bytesEqual(buyerRetained, buyerOnChain)) {
+      return at(false, "buyer_signature_missing");
+    }
+    const message = kit.getCompiledTransactionMessageDecoder().decode(onChain.messageBytes);
+    if (message.version !== "legacy" && message.version !== 0) {
+      return at(null, "unsupported_message_format");
+    }
+    const lookups = message.addressTableLookups;
+    if (lookups && lookups.length > 0) return at(null, "unsupported_message_format");
+    const keys = message.staticAccounts.map(String);
+    const transfers = [];
+    const consider = (programIndex, accountIndexes, data) => {
+      const program = keys[programIndex];
+      if (!program || !KNOWN_TOKEN_PROGRAMS.has(program) || data.length === 0) return;
+      if (data[0] !== IX_TRANSFER && data[0] !== IX_TRANSFER_CHECKED) return;
+      transfers.push({ program, tag: data[0], accounts: accountIndexes.map((i) => keys[i]), data });
+    };
+    for (const ix of message.instructions) {
+      consider(ix.programAddressIndex, ix.accountIndices ?? [], new Uint8Array(ix.data ?? []));
+    }
+    const base58Bytes = kit.getBase58Encoder();
+    if (!Array.isArray(tx.meta.innerInstructions)) return at(null, "rpc_unavailable");
+    for (const group of tx.meta.innerInstructions) {
+      for (const ix of group.instructions) {
+        let data;
+        try {
+          data = new Uint8Array(base58Bytes.encode(ix.data));
+        } catch {
+          return at(null, "rpc_unavailable");
+        }
+        consider(ix.programIdIndex, ix.accounts, data);
+      }
+    }
+    const checked = transfers.filter((t) => t.tag === IX_TRANSFER_CHECKED);
+    if (checked.length === 0) return at(false, "no_matching_transfer");
+    if (checked.length > 1 || transfers.length > 1) return at(false, "multiple_matching_transfers");
+    const [transfer] = checked;
+    if (transfer.data.length < 10 || transfer.accounts.length < 4)
+      return at(false, "no_matching_transfer");
+    const [source, mint, destination, authority] = transfer.accounts;
+    const trust = Object.prototype.hasOwnProperty.call(trusted, asset) ? trusted[asset] : void 0;
+    if (!trust) return at(false, "untrusted_mint");
+    if (!trust.tokenPrograms.includes(transfer.program))
+      return at(false, "untrusted_token_program");
+    if (mint !== asset) return at(false, "mint_mismatch");
+    if (transfer.data[9] !== trust.decimals) return at(false, "decimals_mismatch");
+    const [expectedDestination] = await kit.getProgramDerivedAddress({
+      programAddress: kit.address(ASSOCIATED_TOKEN_PROGRAM),
+      seeds: [
+        kit.getAddressEncoder().encode(kit.address(input.payTo)),
+        kit.getAddressEncoder().encode(kit.address(transfer.program)),
+        kit.getAddressEncoder().encode(kit.address(asset))
+      ]
+    });
+    if (destination !== expectedDestination) return at(false, "payee_mismatch");
+    if (readU64(transfer.data, 1) !== BigInt(input.amountAtomic))
+      return at(false, "amount_mismatch");
+    if (authority !== input.payer) return at(false, "payer_mismatch");
+    const [expectedSource] = await kit.getProgramDerivedAddress({
+      programAddress: kit.address(ASSOCIATED_TOKEN_PROGRAM),
+      seeds: [
+        kit.getAddressEncoder().encode(kit.address(input.payer)),
+        kit.getAddressEncoder().encode(kit.address(transfer.program)),
+        kit.getAddressEncoder().encode(kit.address(asset))
+      ]
+    });
+    if (source !== expectedSource) return at(false, "payer_mismatch");
+    return at(true, null);
+  }
+  return Object.freeze(Object.assign(verify, { cluster }));
+}
+function decodeWire(kit, base64) {
+  const bytes = kit.getBase64Encoder().encode(base64);
+  const decoded = kit.getTransactionDecoder().decode(bytes);
+  const signatures = {};
+  for (const [addr, sig] of Object.entries(decoded.signatures)) {
+    signatures[addr] = sig ? new Uint8Array(sig) : null;
+  }
+  return { messageBytes: new Uint8Array(decoded.messageBytes), signatures };
+}
 export {
   CreditLedger,
+  DEFAULT_RPC_TIMEOUT_MS,
   DEFAULT_SOLANA_USD_MINTS,
   DEFAULT_TEMPO_USD_ASSETS,
+  DEFAULT_TRUSTED_USD_MINTS,
+  InMemoryReceiptReferenceIndex,
+  LANDING_WINDOW_SECONDS,
   MPP_FULFILLMENT_MAX_BODY_BYTES,
   MPP_FULFILLMENT_RECORD_SCHEMA,
+  MppFlushTimeoutError,
   MppGateError,
   MppPaidNoCompletionError,
+  RECEIPT_REFERENCE_NOT_EVALUATED,
   ReplayRejectedError,
   SpentProofLedger,
   createMppFetch,
+  createReceiptChainVerifier,
   createSolanaMppFetch,
   creditPaidNoCompletion,
   fulfillPaidProof,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twzrd1111/clawrouter-mpp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MPP (Machine Payments Protocol) payment rails for ClawRouter: Tempo and Solana charge, with spend limits and paid-failure handling",
   "type": "module",
   "main": "dist/index.js",