@twzrd1111/clawrouter-mpp 0.4.0 → 0.5.0

package/README.md

@@ -3,6 +3,28 @@
 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),
@@ -126,8 +148,10 @@ 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_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.

package/dist/index.d.ts

@@ -3,6 +3,18 @@ import { PayFetch, SpendControl, SpendRecord } from '@twzrd1111/clawrouter';
 export { PayFetch } from '@twzrd1111/clawrouter';
 import { KeyPairSigner } from '@solana/kit';
 
+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: {
@@ -112,6 +124,8 @@ type ReceiptChainVerifyInput = {
     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>) & {
@@ -272,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;
@@ -287,6 +310,8 @@ type SolanaMppFetchOptions = {
      * 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`. */
@@ -389,5 +414,5 @@ declare function fulfillPaidProof<T>(opts: {
     upstream: () => Promise<T>;
 }): Promise<T>;
 
-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 };
+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

@@ -912,7 +912,7 @@ function createMppFetch(account, base = fetch, opts) {
 }
 
 // src/mpp-solana-fetch.ts
-import { randomUUID } from "crypto";
+import { randomBytes, randomUUID } from "crypto";
 import {
   assertSpendPolicyAllows as assertSpendPolicyAllows2,
   SpendPolicyError as SpendPolicyError3
@@ -922,6 +922,23 @@ 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",
@@ -997,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;
@@ -1024,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,
@@ -1112,7 +1132,8 @@ async function createSolanaMppFetch(opts) {
                   signedTransaction,
                   signedAtUnix,
                   purchaseId: randomUUID(),
-                  hasSplits: Array.isArray(splits) && splits.length > 0
+                  hasSplits: Array.isArray(splits) && splits.length > 0,
+                  expectedExternalId
                 };
               } catch (err) {
                 if (signed) {
@@ -1159,7 +1180,9 @@ async function createSolanaMppFetch(opts) {
                 payer: opts.signer.address,
                 signedTransaction: result.signedTransaction,
                 signedAtUnix: result.signedAtUnix,
-                purchaseId: result.purchaseId
+                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
@@ -1248,6 +1271,23 @@ async function fulfillPaidProof(opts) {
 
 // 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";
@@ -1342,12 +1382,10 @@ function createReceiptChainVerifier(config) {
   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"
+    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) {
@@ -1501,7 +1539,13 @@ function createReceiptChainVerifier(config) {
       ]
     });
     if (source !== expectedSource) return at(false, "payer_mismatch");
-    return at(true, null);
+    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 }));
 }
@@ -1522,6 +1566,8 @@ export {
   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,
@@ -1530,10 +1576,13 @@ export {
   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.4.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",