feat(solana): opt-in batch-settlement through @blockrun/llm's SolanaBatchPayer

[VickyXAI]

Opt-in Solana x402 batch-settlement for chat calls. One deposit opens a channel with BlockRun; after that, each call carries an authorization for its ceiling and the gateway charges what the call actually cost. It is off by default; turn it on with CLAWROUTER_SOLANA_BATCH=1 or startProxy({ solanaBatch }).

This replaces #435 (SkinGem). ClawRouter no longer implements the protocol itself: it drives @blockrun/llm's SolanaBatchPayer (3.23.1), the same payer SolanaLLMClient ships. That payer never replaces an in-doubt payment, locks the channel file across processes, cools down after a 429, and parks a wallet on exact after a refused deposit. BlockRun's operator key is pinned as the only trusted operator.

Commits

1. chore(deps): @x402/* 2.21 → 2.28 and @blockrun/llm 3.10 → 3.23.1.
   • 2.28's default SDK spend controls ($1 per payment, default assets only) are switched off, which keeps the old behaviour.
   • An override points svm's @solana/program-client-core at kit 8.4. svm only uses getAccountMetaFactory, whose signature is identical, and this keeps a single @solana/* family in the tree.
   • viem is pinned to ~2.56.9.
2. feat(solana): the integration.
   • Spend rules. The payer's client gets ClawRouter's own hooks: the strict cap, SpendControl and the signing recorders. Batch payments are checked at their ceiling like exact ones, and only if the user set limits. The session cap then books the receipt's charge, not the ceiling.
   • Routing. Non-streaming chat completions on Solana go to the payer:
     • paid → the response is returned;
     • fallback → exact, against the freshest challenge;
     • served or failed → returned unpaid;
     • in doubt → thrown and never paid again.
   • Anthropic SDK. @anthropic-ai/sdk (lazy-imported by @blockrun/llm and unused here) stays external, which saves 0.65MB and removes child_process from dist.
3. Three rounds of Codex review fixes:
   • In doubt is final. "Payment in doubt" is a hard stop on every retry path: the per-model timeout, explicit-pin and rate-limit retries, and the global deadline.
   • Receipts. Only a parsed receipt charge settles the ceiling down; without one, the ceiling stays booked.
   • Zero charges. A receipt that states a zero charge stays at zero.
   • Unpaid 429 retries. When the payer re-signs after a 429 that charged nothing, the earlier signature is voided first.
   • Balance preflight. It defers to the channel, which holds escrow the wallet balance does not show.
   • Notifications. onPayment fires for batch charges.
   • Replay budget. Bounded at 20s.

Tests (1197 pass; typecheck, lint, prettier and dist smoke are clean):

• payment-preauth.batch.test.ts: every pay() outcome, receipt parsing (missing, malformed or zero), and an abort after the send counting as in doubt.
• proxy.solana-batch.test.ts: runs end to end through startProxy with the real payer and the real @x402/svm scheme against a local gateway and RPC. It covers:
  • the strict cap counting the charge, not the ceiling;
  • no receipt keeping the ceiling;
  • in doubt never repaid, for both explicit and routed models;
  • the low liquid-balance preflight;
  • the global deadline while a payment is in flight.
• Mutation-checked. Each of these changes makes a test fail:
  • booking the ceiling instead of the charge;
  • removing the in-doubt chain stop;
  • restoring the balance downgrade;
  • putting the old order back around the global deadline.

Review

• Codex rounds 1–2: FAIL, with findings fixed.
• Round 3: gate PASS; its two P2s are fixed.
• Round 4 could not run (the Codex workspace is out of credits).
• llm-ts side: blockrun-llm-ts Venice Ai APi #72 and fix: resolve @solana/kit version split causing Solana payment simulation failures #74, Codex-reviewed and published as 3.23.1.

Summary by CodeRabbit

• New Features

  • Added optional Solana batch payments for eligible, non-streaming wallet-based chat requests. The feature is off by default and supports configurable deposit limits, including a default cap of $1, and programmatic setup.
  • Added safeguards against duplicate payments when an outcome is uncertain, plus session accounting based on confirmed charges.

• Bug Fixes

  • Improved payment-limit enforcement and handling of payment challenges and failures. Exact-payment fallback occurs only when the gateway confirms that no batch payment was charged.

• Documentation

  • Documented Solana batch settings, payment behavior, configuration options, and automatic closure of idle deposits after three days.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: BlockRunAI/ClawRouter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9a0318d4-4470-41d3-b857-aa5404323bc3

---

📥 Commits

Reviewing files that changed from the base of the PR and between 415490b and 756d072.

---

📒 Files selected for processing (1)

• docs/configuration.md

---

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The proxy adds opt-in Solana batch settlement for eligible wallet-mode chat requests. It records confirmed charges, distinguishes unresolved payments, and stops retries when payment status is unknown. Configuration, dependency updates, and tests support the new settlement path.

Changes

Solana Batch Settlement

Layer / File(s)	Summary
Batch configuration and payer setup src/config.ts, src/solana-batch.ts, src/proxy.ts, package.json, docs/configuration.md	The environment setting and ProxyOptions configure batch settlement. The payer resolves wallet and settlement settings. Documentation describes eligibility and configuration. Dependency ranges and an override are updated.
Eligible request settlement src/payment-preauth.ts, src/payment-preauth.batch.test.ts, src/payment-preauth.test.ts	The pre-auth route attempts batch settlement for eligible non-streaming chat requests. It uses valid receipt amounts, returns served responses, and uses a fresh challenge for exact-payment fallback. Tests cover outcomes, errors, receipts, and excluded endpoints.
Proxy accounting and unresolved-payment handling src/session-spend.ts, src/session-spend.test.ts, src/proxy.ts	The proxy records settled charges and tracks signed payments. Unknown payment outcomes stop model fallback and retry paths.
Settlement tests and policy-client configuration src/proxy.solana-batch.test.ts, src/commands/policy.test.ts, src/doctor.ts, src/polymarket/spend-policy.test.ts, src/spend-control.test.ts	Tests cover spending limits, missing receipts, low liquid balance, and in-doubt payments. Policy clients disable SDK spend controls before registering policy hooks.
Externalize Anthropic SDK tsup.config.ts	The build configuration adds @anthropic-ai/sdk to the external list.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant createPayFetchWithPreAuth
  participant Gateway
  participant SolanaBatchPayer
  Client->>createPayFetchWithPreAuth: Send eligible chat request
  createPayFetchWithPreAuth->>Gateway: Fetch unpaid request
  Gateway->>createPayFetchWithPreAuth: Return payment challenge
  createPayFetchWithPreAuth->>SolanaBatchPayer: Attempt batch payment
  SolanaBatchPayer->>Gateway: Send batch authorization
  Gateway->>SolanaBatchPayer: Return settlement response and receipt
  SolanaBatchPayer->>createPayFetchWithPreAuth: Return batch outcome
  createPayFetchWithPreAuth->>Client: Return response or continue exact-payment fallback

Loading

---

Merge Risk: ⚪ Minimal · up to 756d0

The reviewed documentation describes the opt-in settlement behavior and idle closure without an established contradiction; no actionable merge risk is identified in this change.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 47.37% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 14 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: opt-in Solana batch settlement through @blockrun/llm's SolanaBatchPayer.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 47.37% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 14 files. (1 skipped: 1 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}