@twzrd1111/clawrouter-mpp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 BlockRunAI
+Copyright (c) 2026 TWZRD (MPP rails)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @twzrd1111/clawrouter-mpp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```ts
+import { startProxy, SpendControl, FileSpendControlStorage } from "@twzrd1111/clawrouter";
+import { createMppFetch, createSolanaMppFetch } from "@twzrd1111/clawrouter-mpp";
+
+const spend = new SpendControl({ storage: new FileSpendControlStorage() });
+
+// Tempo (needs `mppx`)
+const payFetch = createMppFetch(account, fetch, { spend });
+// or Solana (needs `@solana/pay-kit`)
+// const payFetch = await createSolanaMppFetch({ signer, rpcUrl, network: "devnet", spend });
+
+await startProxy({ spendControl: spend, payFetch /* ... */ });
+```
+
+Requires ClawRouter with the `payFetch` seam. Until that ships upstream
+([BlockRunAI/ClawRouter#546](https://github.com/BlockRunAI/ClawRouter/pull/546)), install the
+`@twzrd1111/clawrouter` distribution: upstream ClawRouter plus that seam, nothing else, with version numbers
+mirroring upstream. When the seam is released upstream, switch the import and peer dependency back to
+`@blockrun/clawrouter`.
+
+## What it guarantees
+
+- **Spend limits apply.** The amount, network, asset and payee are checked, and budget reserved, _before_
+  anything is signed. Payee lists on Solana are checked at the challenge event and fail closed.
+  The proxy refuses to start a rail that does not set `enforcesSpend` while amount limits are configured.
+- **A signed payment is never paid twice.** If a call fails after a credential or transaction was signed, it
+  ends in `MppPaidNoCompletionError`: the proxy answers 502 `payment_settled_no_completion` and does not
+  retry or fall back. The spend ledger keeps the spend with a note, and the error carries a payment
+  reference (`mpp-<16 hex>`, a hash of the signed payload) for disputes.
+- **Optional peers.** `mppx` and `@solana/pay-kit` are loaded on the first paid call; a missing one produces an
+  install instruction, not a crash at import.
+
+"Signed" is not "settled": on Solana the seller submits the transaction. Not covered: failures that happen
+mid-stream, and seller-side refunds.
+
+## Develop
+
+```
+npm install   # from the ClawRouter repo root
+npm run typecheck && npm test && npm run build   # in packages/clawrouter-mpp
+```
+
+Tests resolve `@twzrd1111/clawrouter` to the repo source until the seam is released.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { Account } from 'viem';
+import { SpendControl, PayFetch } from '@twzrd1111/clawrouter';
+export { PayFetch } from '@twzrd1111/clawrouter';
+import { SolanaNetwork } from '@solana/pay-kit/client';
+import { KeyPairSigner } from '@solana/kit';
+
+/**
+ * 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.
+ *  - 0x20c0…0000   pathUSD (Moderato testnet 42431, also on mainnet 4217)
+ *  - 0x20c0…b9537d11c60e8b50   the USD token a Tempo-run MPP proxy quoted on mainnet 4217 (2026-11-03)
+ */
+declare const DEFAULT_TEMPO_USD_ASSETS: ReadonlySet<string>;
+type MppFetchOptions = {
+    /** When set, every challenge is checked against these limits before a credential is created. */
+    spend?: SpendControl;
+    /** Override the assets treated as 6-decimal USD (lower-case addresses). */
+    usdAssets?: ReadonlySet<string>;
+};
+type ChallengeLike = {
+    id: string;
+    request?: Record<string, unknown>;
+};
+/** The quote as the spend-control layer understands it. `amount` stays undefined if unpriceable. */
+declare function quoteFromChallenge(challenge: ChallengeLike, usdAssets?: ReadonlySet<string>): {
+    payTo: string | undefined;
+    network: string | undefined;
+    asset: string | undefined;
+    amount: string | undefined;
+    priceable: boolean;
+};
+type MethodLike = {
+    createCredential: (options: any) => Promise<string>;
+};
+/**
+ * Put the spend policy in the signing path of an mppx method.
+ *
+ * mppx's `challenge.received` event is an observer: it runs each handler inside try/catch and goes on to
+ * sign, so a handler cannot veto a payment by throwing (verified against mppx 0.17.0 and live, 2026-11-03).
+ * `createCredential` is the one place a throw really aborts: reserve (fail-closed) -> sign -> settle,
+ * and release the reservation if signing fails. A signed credential counts as spend even if the request
+ * then fails, because MPP settles before the upstream responds.
+ */
+declare function guardMethod<M extends MethodLike>(method: M, control: SpendControl | undefined, usdAssets?: ReadonlySet<string>): M;
+declare function createMppFetch(account: Account, base?: typeof fetch, opts?: MppFetchOptions): PayFetch;
+
+/**
+ * 6-decimal USD stablecoin mints priced here (from pay-kit 0.13.1's own tables). Any other mint cannot be
+ * priced, so it is refused while amount limits are set. Pass `usdMints` to add e.g. a localnet test mint.
+ */
+declare const DEFAULT_SOLANA_USD_MINTS: ReadonlySet<string>;
+type SolanaMppFetchOptions = {
+    signer: KeyPairSigner;
+    rpcUrl: string;
+    network: SolanaNetwork;
+    /** When set, every payment is checked against these limits before it is signed. */
+    spend?: SpendControl;
+    /** Extra mints to treat as 6-decimal USD (e.g. a localnet test mint). */
+    usdMints?: Iterable<string>;
+};
+declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<PayFetch>;
+
+declare class MppPaidNoCompletionError extends Error {
+    readonly reference: string;
+    readonly status?: number;
+    constructor(message: string, reference: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+
+export { DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, MppPaidNoCompletionError, createMppFetch, createSolanaMppFetch, guardMethod, quoteFromChallenge };
+export type { MppFetchOptions, SolanaMppFetchOptions };

package/dist/index.js

@@ -0,0 +1,313 @@
+// src/mpp-fetch.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+import {
+  assertSpendPolicyAllows,
+  SpendPolicyError as SpendPolicyError2
+} from "@twzrd1111/clawrouter";
+
+// src/mpp-paid-failure.ts
+import { createHash } from "crypto";
+import { AsyncLocalStorage } from "async_hooks";
+import {
+  PAYMENT_SETTLED_NO_COMPLETION,
+  SpendPolicyError
+} from "@twzrd1111/clawrouter";
+var MppPaidNoCompletionError = class extends Error {
+  reference;
+  status;
+  constructor(message, reference, status, options) {
+    super(message, options);
+    this.name = PAYMENT_SETTLED_NO_COMPLETION;
+    this.reference = reference;
+    this.status = status;
+  }
+};
+var storage = new AsyncLocalStorage();
+function paymentReference(payload) {
+  return `mpp-${createHash("sha256").update(payload).digest("hex").slice(0, 16)}`;
+}
+function markSigned(payload, record) {
+  const call = storage.getStore();
+  if (!call || call.signed) return;
+  call.signed = true;
+  call.reference = paymentReference(payload);
+  call.record = record;
+}
+async function guardPaid(spend, run) {
+  const call = { signed: false };
+  let response;
+  try {
+    response = await storage.run(call, run);
+  } catch (err) {
+    if (!call.signed || err instanceof SpendPolicyError) throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw fail(spend, call, void 0, detail, err);
+  }
+  if (call.signed && response.status >= 400) {
+    throw fail(spend, call, response.status, await boundedSnippet(response));
+  }
+  return response;
+}
+var SNIPPET_CHARS = 200;
+var SNIPPET_MAX_BYTES = 1024;
+var SNIPPET_TIMEOUT_MS = 1e3;
+async function boundedSnippet(response, timeoutMs = SNIPPET_TIMEOUT_MS) {
+  let reader;
+  let timer;
+  try {
+    const body = response.clone().body;
+    if (!body) return "";
+    reader = body.getReader();
+    const r = reader;
+    const chunks = [];
+    let total = 0;
+    const read = (async () => {
+      while (total < SNIPPET_MAX_BYTES) {
+        const { done, value } = await r.read();
+        if (done || !value) break;
+        chunks.push(value);
+        total += value.byteLength;
+      }
+    })();
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+    });
+    await Promise.race([read, timeout]);
+    const bytes = new Uint8Array(Math.min(total, SNIPPET_MAX_BYTES));
+    let at = 0;
+    for (const c of chunks) {
+      const n = Math.min(c.byteLength, bytes.byteLength - at);
+      bytes.set(c.subarray(0, n), at);
+      at += n;
+    }
+    return new TextDecoder().decode(bytes).slice(0, SNIPPET_CHARS);
+  } catch {
+    return "";
+  } finally {
+    if (timer) clearTimeout(timer);
+    reader?.cancel().catch(() => {
+    });
+  }
+}
+function fail(spend, call, status, detail, cause) {
+  const reference = call.reference ?? "mpp-unknown";
+  const why = status !== void 0 ? `HTTP ${status}` : "request failed";
+  if (spend && call.record) {
+    spend.annotateRecord(call.record, `signed, no completion (${why}) ref ${reference}`);
+  }
+  return new MppPaidNoCompletionError(
+    `MPP payment was signed and sent but no completion came back (${why}${detail ? `: ${detail}` : ""}). Not retrying, to avoid paying twice. Payment reference: ${reference}`,
+    reference,
+    status,
+    { cause }
+  );
+}
+
+// src/mpp-optional.ts
+async function loadOptional(name, range, importer) {
+  try {
+    return await importer();
+  } catch (err) {
+    const code = err?.code;
+    const message = err instanceof Error ? err.message : String(err);
+    const missing = code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find (package|module)/.test(message);
+    if (!missing || !message.includes(name)) throw err;
+    throw new Error(
+      `ClawRouter's MPP payment rail needs the optional package "${name}", which is not installed. Install it next to ClawRouter: npm install ${name}@${range}`,
+      { cause: err }
+    );
+  }
+}
+var MPPX_RANGE = "~0.17.0";
+var PAY_KIT_RANGE = "~0.13.1";
+
+// src/mpp-fetch.ts
+var DEFAULT_TEMPO_USD_ASSETS = /* @__PURE__ */ new Set([
+  "0x20c0000000000000000000000000000000000000",
+  "0x20c000000000000000000000b9537d11c60e8b50"
+]);
+function quoteFromChallenge(challenge, usdAssets = DEFAULT_TEMPO_USD_ASSETS) {
+  const req = challenge.request ?? {};
+  const asset = typeof req.currency === "string" ? req.currency : void 0;
+  const chainId = req.methodDetails?.chainId;
+  const priceable = asset !== void 0 && usdAssets.has(asset.toLowerCase()) && typeof req.amount === "string";
+  return {
+    payTo: typeof req.recipient === "string" ? req.recipient : void 0,
+    network: typeof chainId === "number" ? `eip155:${chainId}` : void 0,
+    asset,
+    amount: priceable ? req.amount : void 0,
+    priceable
+  };
+}
+function guardMethod(method, control, usdAssets = DEFAULT_TEMPO_USD_ASSETS) {
+  const guarded = {
+    createCredential: async (options) => {
+      let reservationId;
+      if (control) {
+        const quote = quoteFromChallenge(options.challenge, usdAssets);
+        if (!quote.priceable && control.hasAmountLimits()) {
+          throw new SpendPolicyError2(
+            `MPP quote is in an asset or shape ClawRouter cannot price (${quote.asset ?? "none"}); refusing to pay against a configured spend limit`
+          );
+        }
+        reservationId = assertSpendPolicyAllows(control, quote);
+      }
+      let credential;
+      try {
+        credential = await method.createCredential(options);
+      } catch (err) {
+        if (control && reservationId !== void 0) control.releaseReservation(reservationId);
+        throw err;
+      }
+      const record = control && reservationId !== void 0 ? control.settleReservation(reservationId, { action: "mpp tempo charge" }) : void 0;
+      markSigned(credential, record);
+      return credential;
+    }
+  };
+  return { ...method, ...guarded };
+}
+function createMppFetch(account, base = fetch, opts = {}) {
+  const calls = new AsyncLocalStorage2();
+  const recording = async (input, init) => {
+    const res = await base(input, init);
+    const call = calls.getStore();
+    if (call) call.last402 = res.status === 402 ? res.clone() : void 0;
+    return res;
+  };
+  const { spend, usdAssets } = opts;
+  let mppxPromise;
+  const getMppx = () => mppxPromise ??= loadOptional("mppx", MPPX_RANGE, () => import("mppx/client")).then(
+    ({ Mppx, tempo }) => Mppx.create({
+      methods: tempo({ account }).map((m) => guardMethod(m, spend, usdAssets)),
+      polyfill: false,
+      fetch: recording
+    })
+  );
+  const payFetch = async (input, init) => {
+    const call = {};
+    const mppx = await getMppx();
+    try {
+      return await calls.run(call, () => guardPaid(spend, () => mppx.fetch(input, init)));
+    } catch (e) {
+      if (call.last402 && /No method found for challenges/.test(e.message)) {
+        return call.last402;
+      }
+      throw e;
+    }
+  };
+  payFetch.enforcesSpend = opts.spend !== void 0;
+  return payFetch;
+}
+
+// src/mpp-solana-fetch.ts
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
+import {
+  assertSpendPolicyAllows as assertSpendPolicyAllows2,
+  SpendPolicyError as SpendPolicyError3
+} from "@twzrd1111/clawrouter";
+var DEFAULT_SOLANA_USD_MINTS = /* @__PURE__ */ new Set([
+  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  // USDC mainnet
+  "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+  // USDC devnet
+  "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
+  // USDT mainnet
+]);
+var CAIP2 = {
+  mainnet: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  devnet: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+  localnet: "solana:localnet"
+};
+async function createSolanaMppFetch(opts) {
+  const { spend, network } = opts;
+  const usd = /* @__PURE__ */ new Set([...DEFAULT_SOLANA_USD_MINTS, ...opts.usdMints ?? []]);
+  const calls = new AsyncLocalStorage3();
+  const permissions = spend ? {
+    authorize(candidate) {
+      const call = calls.getStore();
+      if (!call)
+        throw new SpendPolicyError3("Solana MPP payment attempted outside a guarded call");
+      const priceable = usd.has(candidate.mint);
+      if (!priceable && spend.hasAmountLimits()) {
+        throw new SpendPolicyError3(
+          `MPP quote is in a mint ClawRouter cannot price (${candidate.mint}); refusing to pay against a configured spend limit`
+        );
+      }
+      const amount = priceable ? candidate.amount.toString() : void 0;
+      call.quote = {
+        network: CAIP2[candidate.network],
+        asset: candidate.mint,
+        amount,
+        priceable
+      };
+      call.reservationId = assertSpendPolicyAllows2(spend, {
+        network: call.quote.network,
+        asset: candidate.mint,
+        amount,
+        payeeDeferred: true
+      });
+      return { maxAmountAtomic: candidate.amount };
+    }
+  } : void 0;
+  const { PayKitClient } = await loadOptional(
+    "@solana/pay-kit",
+    PAY_KIT_RANGE,
+    () => import("@solana/pay-kit/client")
+  );
+  const client = await PayKitClient.builder().signer(opts.signer).rpcUrl(opts.rpcUrl).network(network).accept(["mpp"]).permissions(permissions).onProgress((event) => {
+    const call = calls.getStore();
+    const e = event;
+    if (!call) return;
+    if (!spend) {
+      if (e.type === "signed" && typeof e.transaction === "string") markSigned(e.transaction);
+      return;
+    }
+    if (e.type === "challenge" && call.quote) {
+      const result = spend.check(0, {
+        payTo: e.recipient,
+        network: call.quote.network,
+        asset: call.quote.asset
+      });
+      if (!result.allowed) {
+        throw new SpendPolicyError3(result.reason ?? "blocked by spend policy", {
+          blockedBy: result.blockedBy,
+          blockedByPolicy: result.blockedByPolicy
+        });
+      }
+      call.payeeChecked = true;
+    } else if (e.type === "signing") {
+      if (!call.payeeChecked) {
+        throw new SpendPolicyError3("payee was never checked before signing; refusing to sign");
+      }
+    } else if (e.type === "signed" || e.type === "paid") {
+      let record;
+      if (call.reservationId !== void 0 && !call.settled) {
+        call.settled = true;
+        record = spend.settleReservation(call.reservationId, { action: "mpp solana charge" });
+      }
+      if (e.type === "signed" && typeof e.transaction === "string")
+        markSigned(e.transaction, record);
+    }
+  }).build();
+  const payFetch = async (input, init) => {
+    const call = { settled: false, payeeChecked: false };
+    try {
+      return await guardPaid(spend, () => calls.run(call, () => client.fetch(input, init, "mpp")));
+    } finally {
+      if (spend && call.reservationId !== void 0 && !call.settled) {
+        spend.releaseReservation(call.reservationId);
+      }
+    }
+  };
+  payFetch.enforcesSpend = spend !== void 0;
+  return payFetch;
+}
+export {
+  DEFAULT_SOLANA_USD_MINTS,
+  DEFAULT_TEMPO_USD_ASSETS,
+  MppPaidNoCompletionError,
+  createMppFetch,
+  createSolanaMppFetch,
+  guardMethod,
+  quoteFromChallenge
+};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@twzrd1111/clawrouter-mpp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@twzrd1111/clawrouter": ">=0.12.306",
+    "@solana/kit": "*",
+    "@solana/pay-kit": "~0.13.1",
+    "mppx": "~0.17.0",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/kit": {
+      "optional": true
+    },
+    "@solana/pay-kit": {
+      "optional": true
+    },
+    "mppx": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}