@twzrd1111/clawrouter-mpp 0.0.0-stage → 0.2.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,172 @@
-# 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";
+import { createTwzrdMppIntegration, createLocalDecisionSigner } from "twzrd-x402-gate";
+
+const spend = new SpendControl({ storage: new FileSpendControlStorage() });
+const twzrdMpp = createTwzrdMppIntegration({
+  signer: createLocalDecisionSigner(),
+  policy: { maxAmountUsd: "1.00" },
+});
+
+// Tempo (needs `mppx`); alternatively use createSolanaMppFetch with the same hooks.
+const payFetch = createMppFetch(account, fetch, { spend, integration: twzrdMpp });
+const proxy = await startProxy({ spendControl: spend, payFetch /* ... */ });
+
+// proxy.close() closes the listener, then drains the rail's pending ledger writes.
+await proxy.close();
+```
+
+The supported setup uses the integration helper returned by `createTwzrdMppIntegration`.
+The `twzrdMppIntegration` marker is a wiring check only; it is forgeable and does not authenticate
+the origin of the hooks. Its gate receives the full MPP charge challenge before credential
+creation and returns
+`{ disposition: "allow" | "warn" | "block" }`; `block` and callback errors refuse payment before
+signing, while `warn` proceeds. The MPP rail rejects integrations without the marker or required
+hooks before loading payment SDKs.
+
+The integration writes the pre-sign decision durably to `.twzrd/decisions.jsonl` before allowing
+credential creation, then appends the projected MPP receipt to that same file. Fulfillment writes
+run asynchronously so they do not hold the response stream. `payFetch.flush?.()` waits for pending
+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
+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
+`reputation_unchecked` as a warning; warnings proceed unless `treatWarnAsBlock` is set. The
+fulfillment row omits prompts, responses, credentials, and raw receipt headers; its seller model
+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.
+
+Receipt-safe payment metadata is available through `readPaidCallEvidence(response)` for a paid
+response from this rail. The
+fulfillment hook records the decoded receipt reference, never the raw base64 receipt or payment
+credential. Tempo session receipts emitted in an SSE `payment-receipt` event are captured when the
+response stream completes; the stream bytes are forwarded unchanged, including the seller-reported
+model label from its first JSON data event. A `valid_format` receipt means its structure, method, and
+intent match the challenge; it is not an on-chain verification. `seller_reported_model_matches_request`
+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.
+
+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.
+
+For Tempo install the optional peer `mppx@~0.17.0`. For Solana install `@solana/mpp@~0.7.0`,
+`mppx@~0.17.0`, and `@solana/kit@~6.10.0`. Solana now uses the official charge method
+directly, replacing the pay-kit client wrapper. That wrapper's progress events omit the
+challenge ID; the direct method lets policy checks and credits use the full challenge
+before signing. `@solana/pay-kit` is used only by development tests as a fixture seller.
+
+## What it guarantees
+
+- **Spend limits apply.** The amount, network, asset and payee are checked, and budget reserved, _before_
+  anything is signed. Solana checks the complete challenge before transaction construction
+  and pins the configured network even when no spend control is supplied.
+  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.
+- **Streaming receipts.** Both factories set `deferStreamingHeaders`. The proxy holds final
+  headers while paying, sends informational HTTP 102 responses, and forwards the seller's
+  exact `Payment-Receipt` on the final streaming response. It does not fabricate a missing receipt.
+  Both also set `supportsNativeStreaming`: streaming chat requests retain `stream: true`
+  upstream and request usage chunks. Native SSE flows incrementally, including structured
+  tool calls, with reasoning filtered and token/cost accounting retained.
+  Ambiguous text-encoded calls wait for the choice to finish so recovery matches the existing
+  whole-message parser; structured tool deltas and ordinary text flow incrementally.
+  JSON-only replies use the existing simulated stream. In-flight coalesced callers receive live chunks from
+  one paid attempt; completed cache replays do not claim a new receipt.
+  HTTP 102 does not extend OpenClaw's deadline. Real content/tool deltas reset client activity
+  timers as the model streams. Payment/header wait and stalled output still have deadlines.
+- **Optional peers.** Importing this package does not load payment SDKs. Tempo loads `mppx` on
+  first use; the asynchronous Solana factory loads `@solana/mpp`. Missing peers produce an
+  install instruction.
+
+"Signed" is not "settled": on Solana the seller submits the transaction. Seller-side refunds
+remain outside this package.
+
+## Replay protection at a seller
+
+```ts
+import { SpentProofLedger, fulfillPaidProof, ReplayRejectedError } from "@twzrd1111/clawrouter-mpp";
+
+const proofs = new SpentProofLedger(); // share across requests in this process
+
+// First authenticate the challenge and independently verify its payment on chain.
+// Pass a canonical network ID plus verified transaction and challenge IDs,
+// never untrusted body fields. Example IDs: "solana:mainnet-beta", "eip155:4217".
+const completion = await fulfillPaidProof({
+  ledger: proofs,
+  networkId: verifiedNetworkId,
+  txSignature: verifiedSignature,
+  challengeId: verifiedChallengeId,
+  upstream: () => runModel(),
+});
+```
+
+A reused transaction or challenge on the same network throws `ReplayRejectedError` with
+`status: 409` and `code: "proof_replayed"` before invoking `upstream`. Network scope allows
+the same signature text or challenge ID to exist independently on another chain. The
+synchronous claim gives concurrent duplicates one winner. The claim remains spent if the
+model fails. This helper does not verify a payment itself,
+and installing a buyer rail cannot add replay protection to a remote seller.
+
+## Credits for signed calls with no completion
+
+```ts
+import { MppPaidNoCompletionError, readCredits } from "@twzrd1111/clawrouter-mpp";
+
+try {
+  await payFetch(url, init);
+} catch (error) {
+  if (error instanceof MppPaidNoCompletionError) {
+    console.log(readCredits()); // immutable snapshots; do not log credentials
+  }
+  throw error;
+}
+```
+
+Both rails record `{ payer, amount, challengeId, reason }` on a signed call's HTTP error or
+transport failure. Payer comes from the supplied account/signer, never the seller's recipient.
+Amount is the original integer base-unit string. Repeating a payer/challenge records one row.
+
+When the proxy detects a provider error hidden inside HTTP 200, it calls the rail's
+`onNoCompletion(response, reason)` hook. For a signed response this records the credit and
+throws the same terminal error before any fallback model is paid. Unsigned responses retain
+the ordinary provider fallback behavior. A custom host using these rails can invoke that
+hook after its own completion validation; the response must be the one returned by the rail.
+
+For a broken or unfinished native body the proxy invokes that same hook, records one credit,
+and ends the existing SSE response with `payment_settled_no_completion`. Its HTTP 200 and
+receipt have already been sent, so this is an in-stream error rather than a new HTTP 502.
+The proxy never retries a model or pays a fallback after committing that stream. Disconnects
+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.
+
+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
+write, cross-process exclusion, persistence, or automatic reconciliation in these helpers.
+
+## Develop
+
+```
+npm install   # from the ClawRouter repo root
+# Before the candidate core is published, install rails development dependencies:
+npm install --legacy-peer-deps   # in packages/clawrouter-mpp
+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,210 @@
+import { Account } from 'viem';
+import { SpendControl, PayFetch, SpendRecord } from '@twzrd1111/clawrouter';
+export { PayFetch } from '@twzrd1111/clawrouter';
+import { KeyPairSigner } from '@solana/kit';
+
+declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v1";
+declare const MPP_FULFILLMENT_MAX_BODY_BYTES: number;
+type MppPaymentFacts = {
+    challengeId: string;
+    method: string;
+    intent: string;
+    payTo: string | null;
+    network: string | null;
+    asset: string | null;
+    amountAtomic: string | null;
+};
+type MppFulfillmentRecord = {
+    schema: typeof MPP_FULFILLMENT_RECORD_SCHEMA;
+    at_unix_ms: number;
+    resource_origin: string | null;
+    http_status: number;
+    payment_method: string;
+    payment_intent: string;
+    challenge_id: string;
+    paid_to: string | null;
+    network: string | null;
+    asset: string | null;
+    amount_atomic: string | null;
+    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. */
+    receipt_reference: string | null;
+    receipt_timestamp: string | null;
+    requested_model: string | null;
+    /** Model label reported by the seller. This is not an attestation of model identity. */
+    seller_reported_model: string | null;
+    /** 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;
+};
+type MppFulfillmentSink = (record: MppFulfillmentRecord) => void | Promise<void>;
+
+/** Optional buyer-side policy hook evaluated on the exact MPP challenge before signing. */
+type MppGateChallenge = {
+    id: string;
+    realm?: string;
+    method: string;
+    intent: string;
+    request: Record<string, unknown>;
+    expires?: string;
+    description?: string;
+};
+/** Safe decision metadata retained with the paid response for receipt verification. */
+type MppGateDecision = {
+    disposition: "allow" | "warn" | "block";
+    decisionId?: string;
+    intentHash?: string;
+    reasonCodes?: readonly string[];
+};
+/** Return the TWZRD gate's result. Throwing or returning an invalid result fails closed. */
+type MppGateEvaluator = (challenge: MppGateChallenge) => MppGateDecision | Promise<MppGateDecision>;
+/** Integration contract accepted by the MPP factories. The marker is not an authenticity proof. */
+type MppIntegration = Readonly<{
+    twzrdMppIntegration: true;
+    gate: MppGateEvaluator;
+    onFulfillment: MppFulfillmentSink;
+    flush: () => Promise<void>;
+}>;
+declare class MppGateError extends Error {
+    readonly code: "MPP_GATE_BLOCKED" | "MPP_GATE_INVALID_RESULT";
+    readonly challengeId: string;
+    readonly decisionId?: string;
+    readonly reasonCodes?: readonly string[];
+    constructor(code: MppGateError["code"], challengeId: string, message: string, decision?: MppGateDecision);
+}
+
+/**
+ * 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   fee token a Tempo-run MPP proxy quoted on mainnet 4217 (2026-11-03)
+ *  - 0x20c0…f37de3740adec032   charge currency on that same OpenRouter challenge (6 decimals, 750 = 0.00075 USD)
+ */
+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>;
+    /** Required branded object from createTwzrdMppIntegration. */
+    integration: MppIntegration;
+};
+type ChallengeLike = {
+    id: string;
+    realm?: string;
+    method: string;
+    intent: string;
+    request: Record<string, unknown>;
+    expires?: string;
+    description?: string;
+};
+/** 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;
+};
+declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): PayFetch;
+
+declare const DEFAULT_SOLANA_USD_MINTS: ReadonlySet<string>;
+type SolanaNetwork = "mainnet" | "devnet" | "localnet";
+type SolanaMppFetchOptions = {
+    signer: KeyPairSigner;
+    rpcUrl: string;
+    network: SolanaNetwork;
+    spend?: SpendControl;
+    usdMints?: Iterable<string>;
+    /** Required branded object from createTwzrdMppIntegration. */
+    integration: MppIntegration;
+    /** Injectable transport; defaults to fetch. The SDK's RPC transport is separate. */
+    fetch?: typeof fetch;
+};
+declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<PayFetch>;
+
+/** In-memory credit row. No chain write and no signer. */
+type CreditEntry = Readonly<{
+    payer: string;
+    amount: string;
+    challengeId: string;
+    reason: string;
+}>;
+declare class CreditLedger {
+    private readonly rows;
+    /** One row per payer and challenge. A retry returns the first row. */
+    recordOnce(entry: CreditEntry): CreditEntry;
+    read(): readonly CreditEntry[];
+}
+
+declare class MppPaidNoCompletionError extends Error {
+    readonly reference: string;
+    readonly status?: number;
+    constructor(message: string, reference: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Record one credit for a paid call that returned no completion.
+ * A retry of the same payer and challenge returns the first row.
+ * `sign`, when passed, is never called.
+ */
+declare function creditPaidNoCompletion(ledger: CreditLedger, err: MppPaidNoCompletionError, fields: CreditEntry, hooks?: {
+    sign?: () => Promise<unknown>;
+}): CreditEntry;
+type PaidCall = {
+    /** The paying account supplied to the rail, never the challenge recipient. */
+    payer: string;
+    /** A credential or transaction was produced for this call. */
+    signed: boolean;
+    /** Stable, non-secret handle for the payment (hash of what was sent), for disputes. */
+    reference?: string;
+    /** The ledger entry written when the payment was signed, if limits made one. */
+    record?: SpendRecord;
+    /** Payer, amount, and challenge known before the model runs. Reason is filled on failure. */
+    credit?: Pick<CreditEntry, "payer" | "amount" | "challengeId">;
+    /** Optional pre-sign policy decision; no raw challenge or signed token is retained. */
+    gate?: MppGateDecision;
+    payment?: MppPaymentFacts;
+};
+/** Rows written by `fail` when a signed call returns no completion. */
+declare function readCredits(ledger?: CreditLedger): readonly CreditEntry[];
+/** Safe payment facts associated with this exact response, if it was paid by this rail. */
+declare function readPaidCallEvidence(response: Response): Pick<PaidCall, "payer" | "reference" | "credit" | "gate" | "payment"> | undefined;
+
+/**
+ * Seller-side spent-proof ledger. In memory only.
+ *
+ * A proof is one payment transaction signature plus one challenge id.
+ * The buyer's 402 followed by the authorized retry is one proof: the 402
+ * carries no transaction signature, so it never claims a slot.
+ */
+declare class ReplayRejectedError extends Error {
+    readonly networkId: string;
+    readonly txSignature: string;
+    readonly challengeId: string;
+    readonly status = 409;
+    readonly code = "proof_replayed";
+    constructor(networkId: string, txSignature: string, challengeId: string);
+}
+declare class SpentProofLedger {
+    private readonly transactions;
+    private readonly challenges;
+    claim(networkId: string, txSignature: string, challengeId: string): boolean;
+}
+/**
+ * Accept one paid proof and call the model at most once.
+ * The claim is synchronous, so two overlapping calls yield one winner.
+ */
+declare function fulfillPaidProof<T>(opts: {
+    ledger: SpentProofLedger;
+    networkId: string;
+    txSignature: string;
+    challengeId: string;
+    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 };