@twzrd1111/clawrouter-mpp 0.3.0 → 0.5.0

package/README.md

@@ -3,6 +3,45 @@
 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.5.0 from 0.4.0
+
+This release adds opt-in Solana Echo purchase binding (#21). Omit `echo` to preserve existing
+behavior. `echo: {}` offers binding and pays unbound when a seller omits or changes the reflected
+ID; `echo: { requireBinding: true }` refuses those challenges before signing.
+
+- Each call sends fresh 16-byte buyer entropy as `X-Buyer-Nonce: <32 hex>`. A cooperating seller
+  reflects it as `request.externalId: "twzrd:p:<nonce>"`, which the existing SDK writes as a memo.
+- With `receiptVerification` enabled, a finalized payment passing all chain checks can set
+  `receipt_reference_purchase_bound: true` only when exactly one SPL Memo (v1 and v2 counted
+  together) matches the retained buyer expectation byte for byte. Malformed UTF-8, a leading BOM,
+  or multiple memos cannot silently match.
+- Identical complete challenges share one credential and one spend record; binding remains per
+  call. The local nonce is not part of the shared-signing cache key.
+- Fulfillment schema stays `twzrd.mpp.fulfillment.v3`; core peer floor stays `>=0.12.309`.
+  `response_bytes` and `body_sha256` are existing fields, first shipped in 0.3.0.
+
+Seller reflection is a separate integration. This release does not deploy a seller, verify Tempo
+receipts, prove model execution, or supply a durable replay index. The existing in-memory indexes
+forget on restart; cross-worker uniqueness requires caller-supplied durable, atomic storage.
+See the [seller wire contract](https://github.com/twzrd-sol/ClawRouter-1/blob/899295ef627032260dbff363bbb012d446c9ecc6/docs/echo-protocol.md).
+
+## 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
@@ -74,12 +113,60 @@ 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.v2`. `response_bytes` and `body_sha256` (lowercase hex
+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. With opt-in `echo: { requireBinding: true }`
+  and a cooperating seller, one exactly matching buyer memo can establish binding after chain
+  verification. Otherwise it remains unbound; see `docs/echo-protocol.md`. Chain verification alone
+  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.
 

package/dist/index.d.ts

@@ -3,7 +3,138 @@ 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.v2";
+declare const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+declare const MEMO_V1_PROGRAM_ID = "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo";
+type BindingInstruction = {
+    program: string;
+    data: Uint8Array;
+};
+type PurchaseBoundOutcome = {
+    purchase_bound: boolean | null;
+    purchase_bound_reason: "no_buyer_nonce" | "nonce_mismatch" | "chain_unverified" | null;
+};
+/** An expected buyer nonce binds only through one exactly matching, valid UTF-8 SPL Memo. */
+declare function evaluatePurchaseBinding(instructions: readonly BindingInstruction[], expectedExternalId: string | null | undefined): PurchaseBoundOutcome;
+/** 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;
+    /** Buyer-generated Echo expectation, retained only after exact pre-sign reflection. */
+    expectedExternalId?: string | null;
+};
+/** 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 +145,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 +167,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;
@@ -145,6 +286,15 @@ declare function createMppFetch(account: Account, base: typeof fetch | undefined
 
 declare const DEFAULT_SOLANA_USD_MINTS: ReadonlySet<string>;
 type SolanaNetwork = "mainnet" | "devnet" | "localnet";
+type EchoPolicy = {
+    requireBinding?: boolean;
+};
+type EchoBindingContext = {
+    buyerNonce: string;
+    expectedExternalId: string;
+};
+declare function createEchoContext(): EchoBindingContext;
+declare function assertEchoPreSign(challengeExternalId: unknown, context: EchoBindingContext, policy?: EchoPolicy): "bound" | "unbound";
 type SolanaMppFetchOptions = {
     signer: KeyPairSigner;
     rpcUrl: string;
@@ -155,6 +305,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;
+    /** Opt in to buyer nonce reflection. Omit to preserve existing seller externalId behavior. */
+    echo?: EchoPolicy;
+};
+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<MppPayFetch>;
 
@@ -245,5 +414,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, MppFlushTimeoutError, MppGateError, MppPaidNoCompletionError, ReplayRejectedError, SpentProofLedger, createMppFetch, createSolanaMppFetch, creditPaidNoCompletion, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
-export type { CreditEntry, MppBodyDigest, MppFetchOptions, MppFlushOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPayFetch, MppPaymentFacts, SolanaMppFetchOptions };
+export { CreditLedger, DEFAULT_RPC_TIMEOUT_MS, DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, DEFAULT_TRUSTED_USD_MINTS, InMemoryReceiptReferenceIndex, LANDING_WINDOW_SECONDS, MEMO_PROGRAM_ID, MEMO_V1_PROGRAM_ID, MPP_FULFILLMENT_MAX_BODY_BYTES, MPP_FULFILLMENT_RECORD_SCHEMA, MppFlushTimeoutError, MppGateError, MppPaidNoCompletionError, RECEIPT_REFERENCE_NOT_EVALUATED, ReplayRejectedError, SpentProofLedger, assertEchoPreSign, createEchoContext, createMppFetch, createReceiptChainVerifier, createSolanaMppFetch, creditPaidNoCompletion, evaluatePurchaseBinding, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
+export type { ChainMismatch, ChainUnverifiedReason, CreditEntry, EchoBindingContext, EchoPolicy, GetFinalizedTransaction, MppBodyDigest, MppFetchOptions, MppFlushOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPayFetch, MppPaymentFacts, MppReceiptReferenceVerification, PurchaseBoundOutcome, ReceiptChainVerification, ReceiptChainVerifierConfig, ReceiptChainVerify, ReceiptChainVerifyInput, ReceiptReferenceIndex, RpcTransaction, SolanaCluster, SolanaMppFetchOptions, SolanaReceiptVerificationOptions, TrustedMint };

package/dist/index.js

@@ -280,8 +280,22 @@ async function evaluateMppGate(evaluator, challenge) {
 
 // src/mpp-fulfillment-record.ts
 import { createHash as createHash2 } from "crypto";
-var MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v2";
+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;
@@ -485,6 +499,15 @@ async function emitRecord(input, receipt, requestValue, responseValue, sink, dig
   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(),
@@ -500,14 +523,22 @@ async function emitRecord(input, receipt, requestValue, responseValue, sink, dig
     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,
     response_bytes: digest.response_bytes,
-    body_sha256: digest.body_sha256
+    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);
 }
@@ -881,6 +912,7 @@ function createMppFetch(account, base = fetch, opts) {
 }
 
 // src/mpp-solana-fetch.ts
+import { randomBytes, randomUUID } from "crypto";
 import {
   assertSpendPolicyAllows as assertSpendPolicyAllows2,
   SpendPolicyError as SpendPolicyError3
@@ -890,17 +922,68 @@ var DEFAULT_SOLANA_USD_MINTS = /* @__PURE__ */ new Set([
   "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
   "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
 ]);
+function createEchoContext() {
+  const buyerNonce = randomBytes(16).toString("hex");
+  return { buyerNonce, expectedExternalId: `twzrd:p:${buyerNonce}` };
+}
+function assertEchoPreSign(challengeExternalId, context, policy = {}) {
+  if (challengeExternalId === void 0 || challengeExternalId === null) {
+    if (policy.requireBinding)
+      throw new SpendPolicyError3("REJECTED_UNBOUND_CHALLENGE: Seller failed to echo buyer nonce");
+    return "unbound";
+  }
+  if (challengeExternalId !== context.expectedExternalId) {
+    if (policy.requireBinding)
+      throw new SpendPolicyError3("SECURITY_VIOLATION: Challenge externalId mismatch");
+    return "unbound";
+  }
+  return "bound";
+}
 var CAIP2 = {
   mainnet: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   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 ?? []]);
@@ -931,6 +1014,8 @@ async function createSolanaMppFetch(opts) {
         opts.spend,
         async () => {
           const request = new Request(input, cleanInit);
+          const echoContext = opts.echo === void 0 ? void 0 : createEchoContext();
+          if (echoContext) request.headers.set("X-Buyer-Nonce", echoContext.buyerNonce);
           const requestForRecord = request.clone();
           const probe = await base(request.clone());
           if (probe.status !== 402) return probe;
@@ -958,6 +1043,7 @@ async function createSolanaMppFetch(opts) {
           );
           const payment = paymentFactsFromMppChallenge(challenge);
           markPaymentChallenge(payment);
+          const expectedExternalId = echoContext && assertEchoPreSign(challenge.request.externalId, echoContext, opts.echo) === "bound" ? echoContext.expectedExternalId : null;
           const key = JSON.stringify([
             challenge.id,
             challenge.realm,
@@ -997,6 +1083,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,
@@ -1007,6 +1095,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;
@@ -1032,12 +1122,18 @@ 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,
+                  expectedExternalId
                 };
               } catch (err) {
                 if (signed) {
@@ -1071,8 +1167,34 @@ 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,
+                // Binding belongs to this call, not merely a cached credential.
+                expectedExternalId: result.expectedExternalId === echoContext?.expectedExternalId ? result.expectedExternalId : null
+              }),
+              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
             );
@@ -1146,20 +1268,321 @@ 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 MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+var MEMO_V1_PROGRAM_ID = "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo";
+var MEMO_PROGRAMS = /* @__PURE__ */ new Set([MEMO_PROGRAM_ID, MEMO_V1_PROGRAM_ID]);
+function evaluatePurchaseBinding(instructions, expectedExternalId) {
+  const unbound = { purchase_bound: null, purchase_bound_reason: "no_buyer_nonce" };
+  const mismatch = { purchase_bound: false, purchase_bound_reason: "nonce_mismatch" };
+  if (!expectedExternalId) return unbound;
+  const memos = instructions.filter((ix) => MEMO_PROGRAMS.has(ix.program));
+  if (memos.length === 0) return unbound;
+  if (memos.length !== 1) return mismatch;
+  try {
+    new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(memos[0].data);
+  } catch {
+    return mismatch;
+  }
+  return bytesEqual(memos[0].data, new TextEncoder().encode(expectedExternalId)) ? { purchase_bound: true, purchase_bound_reason: null } : mismatch;
+}
+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 binding = verified === true ? evaluatePurchaseBinding(chain.instructions ?? [], input.expectedExternalId) : { purchase_bound: null, purchase_bound_reason: "chain_unverified" };
+    const purchase = {
+      receipt_reference_purchase_bound: binding.purchase_bound,
+      receipt_reference_purchase_bound_reason: binding.purchase_bound_reason
+    };
+    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),
+      instructions: message.instructions.map((ix) => ({
+        program: keys[ix.programAddressIndex],
+        data: new Uint8Array(ix.data ?? [])
+      }))
+    };
+  }
+  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,
+  MEMO_PROGRAM_ID,
+  MEMO_V1_PROGRAM_ID,
   MPP_FULFILLMENT_MAX_BODY_BYTES,
   MPP_FULFILLMENT_RECORD_SCHEMA,
   MppFlushTimeoutError,
   MppGateError,
   MppPaidNoCompletionError,
+  RECEIPT_REFERENCE_NOT_EVALUATED,
   ReplayRejectedError,
   SpentProofLedger,
+  assertEchoPreSign,
+  createEchoContext,
   createMppFetch,
+  createReceiptChainVerifier,
   createSolanaMppFetch,
   creditPaidNoCompletion,
+  evaluatePurchaseBinding,
   fulfillPaidProof,
   quoteFromChallenge,
   readCredits,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twzrd1111/clawrouter-mpp",
-  "version": "0.3.0",
+  "version": "0.5.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",