@twzrd1111/clawrouter-mpp 0.1.0 → 0.3.0

package/README.md

@@ -3,45 +3,202 @@
 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 from 0.2.0
+
+- Fulfillment rows now use `twzrd.mpp.fulfillment.v2`. Readers must accept the new schema to retain
+  `response_bytes` and `body_sha256`; these fields are null when the recorder does not read a complete
+  body within its 1 MiB cap.
+- Credit rows carry an optional `reference` matching the error and spend record. It is a local
+  signed-payload hash, not a settlement signature.
+- `payFetch.flush({ timeoutMs })` bounds waiting for both records and ledger persistence. A timeout
+  leaves the paid response and background writes intact; an omitted timeout keeps the previous
+  unbounded wait. Values above 2,147,483,647 ms are rejected.
+
 ```ts
 import { startProxy, SpendControl, FileSpendControlStorage } from "@twzrd1111/clawrouter";
 import { createMppFetch, createSolanaMppFetch } from "@twzrd1111/clawrouter-mpp";
+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`)
-const payFetch = createMppFetch(account, fetch, { spend });
-// or Solana (needs `@solana/pay-kit`)
-// const payFetch = await createSolanaMppFetch({ signer, rpcUrl, network: "devnet", spend });
+// 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 /* ... */ });
 
-await startProxy({ spendControl: spend, payFetch /* ... */ });
+// proxy.close() closes the listener, then drains the rail's pending ledger writes.
+await proxy.close();
 ```
 
-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`.
+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. `payFetch.flush({ timeoutMs })` bounds the entire wait for records and ledger persistence
+(0 through 2,147,483,647 ms). At the deadline it still attempts the ledger flush in the background,
+then rejects with an `AggregateError` holding an `MppFlushTimeoutError`. Its `pending` field counts
+unfinished records; `ledgerPending` indicates whether ledger flushing is still in progress.
+A late ledger failure is reported once: by a flush still waiting on that ledger, otherwise by the next explicit flush. (Ownership is tracked per ledger promise; an integration that returns a fresh wrapper promise for the same failure to each caller can still see it twice.) A timeout does not confirm durability.
+It never cancels or reads a response body, so a late reader still gets the whole paid response,
+and its record lands when that body is drained. Network contribution remains off unless separately enabled. It blocks unscored
+networks by default, including Tempo mainnet and Moderato, until TWZRD has a reputation corpus for
+them. The default provider also fails closed on outages; the ledger sink itself makes no network
+call. An explicit `allowUnscoredNetwork: true` requires `policy.maxAmountUsd` and returns
+`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.2` does not include Tempo charge evaluation or the shared-ledger adapter.
+
+Receipt-safe payment metadata is available through `readPaidCallEvidence(response)` for a paid
+response from this rail. The
+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.
+
+Rows use schema `twzrd.mpp.fulfillment.v2`. `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.
+
+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. Payee lists on Solana are checked at the challenge event and fail closed.
+  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.
-- **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.
+- **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.
+
+`SpentProofLedger` keeps claims in memory, so a restart or a second process forgets spent
+proofs, and a proof can be redeemed again while its challenge is still valid. A seller with
+more than one process, or one that restarts, needs a durable, atomic uniqueness check shared by
+every worker (for example a unique key on network plus transaction signature, as an
+authoritative settlement table provides). Rejecting expired challenges narrows the window but
+does not close it on its own.
+
+## Credits for signed calls with no completion
+
+```ts
+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.
+Each row carries the payment `reference` from the error (or from `fields.reference`) when one
+is known, so a credit can be joined to the error and the spend record. The reference is a hash
+of the signed payload, not a chain signature; an unknown reference is left off the row.
 
-"Signed" is not "settled": on Solana the seller submits the transaction. Not covered: failures that happen
-mid-stream, and seller-side refunds.
+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
 ```
 

package/dist/index.d.ts

@@ -1,14 +1,119 @@
 import { Account } from 'viem';
-import { SpendControl, PayFetch } from '@twzrd1111/clawrouter';
+import { PayFetch, SpendControl, SpendRecord } from '@twzrd1111/clawrouter';
 export { PayFetch } from '@twzrd1111/clawrouter';
-import { SolanaNetwork } from '@solana/pay-kit/client';
 import { KeyPairSigner } from '@solana/kit';
 
+declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v2";
+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;
+    /**
+     * Byte length of the complete response body as received. null when the recorder did not read
+     * the body, it exceeded MPP_FULFILLMENT_MAX_BODY_BYTES, or it was cancelled or errored first.
+     */
+    response_bytes: number | null;
+    /** Lowercase hex SHA-256 of the same complete body; null under the same conditions. */
+    body_sha256: string | null;
+};
+/** Size and digest of a complete response body, or null fields when it was not fully read. */
+type MppBodyDigest = {
+    response_bytes: number | null;
+    body_sha256: string | null;
+};
+type MppFulfillmentSink = (record: MppFulfillmentRecord) => void | Promise<void>;
+
+/** 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);
+}
+
+type MppFlushOptions = {
+    /**
+     * Bound the entire wait for fulfillment records and ledger persistence. At the deadline,
+     * ledger flushing is still attempted in the background; neither writes nor response bodies
+     * are cancelled. Late ledger failures are retained for the next flush(). Omit to wait forever.
+     * Valid range: 0 through 2_147_483_647 milliseconds (Node's maximum timer delay).
+     */
+    timeoutMs?: number;
+};
+/** A rail fetch whose flush() accepts an optional deadline. Assignable to PayFetch. */
+type MppPayFetch = PayFetch & {
+    flush: (options?: MppFlushOptions) => Promise<void>;
+};
+/** The deadline elapsed; persistence may still be running and response bodies remain caller-owned. */
+declare class MppFlushTimeoutError extends Error {
+    readonly pending: number;
+    readonly timeoutMs: number;
+    readonly ledgerPending: boolean;
+    constructor(pending: number, timeoutMs: number, ledgerPending?: boolean);
+}
+
 /**
  * Tempo TIP-20 USD stablecoins priced here, lower-case, all 6 decimals (the challenge carries no
  * `decimals`). Any other asset cannot be priced, so it is refused while amount limits are set.
  *  - 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)
+ *  - 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 = {
@@ -16,10 +121,17 @@ type MppFetchOptions = {
     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;
-    request?: Record<string, unknown>;
+    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>): {
@@ -29,36 +141,41 @@ declare function quoteFromChallenge(challenge: ChallengeLike, usdAssets?: Readon
     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;
+declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): MppPayFetch;
 
-/**
- * 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 SolanaNetwork = "mainnet" | "devnet" | "localnet";
 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>;
+    /** 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>;
+declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<MppPayFetch>;
+
+/** In-memory credit row. No chain write and no signer. */
+type CreditEntry = Readonly<{
+    payer: string;
+    amount: string;
+    challengeId: string;
+    reason: string;
+    /**
+     * Payment reference from MppPaidNoCompletionError, when one is known: `mpp-` plus a short hash of
+     * the signed payload. Joins the row to the error and the spend record. Not a chain tx signature.
+     */
+    reference?: string;
+}>;
+declare class CreditLedger {
+    private readonly rows;
+    /** 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;
@@ -67,6 +184,66 @@ declare class MppPaidNoCompletionError extends Error {
         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.
+ * The row carries `fields.reference`, else the error's reference when one is known.
+ * `sign`, when passed, is never called.
+ */
+declare function creditPaidNoCompletion(ledger: CreditLedger, err: MppPaidNoCompletionError, fields: CreditEntry, hooks?: {
+    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 { DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, MppPaidNoCompletionError, createMppFetch, createSolanaMppFetch, guardMethod, quoteFromChallenge };
-export type { MppFetchOptions, SolanaMppFetchOptions };
+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 };