@blockrun/llm 3.24.9 → 3.25.0

package/README.md

@@ -635,7 +635,10 @@ console.log(res.costUsd, res.settlement);        // what you paid, and the tx
 ```
 
 `costUsd`, `settlement` and the per-call `timeout` work the same on `LLMClient`
-(Base / Arc). `costUsd` is what the call added to `getSpending()`: the signed
+(Base / Arc). Both clients default to a 600 s request timeout
+(`BLOCKRUN_CHAT_TIMEOUT`, in seconds, overrides it; the `timeout` option, in
+ms, overrides both): a call aborted after its payment was sent may already be
+charged, so a batch payment ends unresolved rather than paid again. `costUsd` is what the call added to `getSpending()`: the signed
 price under `exact`, the metered `extra.chargedAmount` under batch settlement,
 `0` for a free model; it is undefined in API-key mode (billed to the account).
 When the gateway answers a paid request from a free fallback model it skips
@@ -720,6 +723,7 @@ await client.closeBatchChannel();
 - **Never pays twice.** Anything that goes wrong before a batch payment is sent falls back to `exact`. Once one is sent, a call whose payment may have been charged throws `BatchPaymentUnresolvedError` and is never paid again (no new payment, no `exact`, no fallback model).
 - **Non-streaming chat only.** `chat`, `chatCompletion`, `smartChat` and `smartChatCompletion` use batch; `stream()` and media jobs pay `exact`.
 - **One channel per wallet.** All clients for a wallet share one channel, saved to `~/.blockrun/solana-batch/<wallet>.json` (mode `0600`) so a restart reuses it.
+- **One process per wallet.** The process that opens the channel holds its store's lock until it exits. Other processes on that wallet (worker pools, PM2/cluster workers, parallel runs) pay `exact`, reported as `channel_store_locked`. Give each worker its own wallet, or route calls through one process. `batch.onLocked: "wait"` waits up to `batch.lockWaitMs` (default 60 s) for the lock, and `"throw"` raises `BatchChannelLockedError` (unpaid, nothing signed) instead of paying `exact`.
 - **Observable.** Every fallback, backoff, recovery and re-read writes one stderr line; `batch.onEvent` and `client.getBatchStats()` expose the same events and counters.
 
 The full runtime contract (the answer-by-answer table, payment-identifier
@@ -1695,7 +1699,7 @@ const configured = new LLMClient({
 | `SOLANA_RPC_URL` | Solana RPC for payments and balance (also `rpcUrl`) |
 | `SOLANA_RPC_API_KEY` / `SOLANA_RPC_HEADERS` | Header auth for that RPC (also `rpcHeaders`) |
 | `BASE_RPC_URL` | Base RPC tried first by `LLMClient.getBalance()` |
-| `BLOCKRUN_CHAT_TIMEOUT` | `LLMClient` default timeout, in **seconds** (default 600) |
+| `BLOCKRUN_CHAT_TIMEOUT` | `LLMClient` and `SolanaLLMClient` default timeout, in **seconds** (default 600) |
 | `BLOCKRUN_HOME` | Base directory for the Base wallet files (security-sensitive, see [Wallets](#one-wallet-across-every-blockrun-product)) |
 
 `BLOCKRUN_SOL_OPERATOR` is **not** an environment variable or a secret. It is

package/dist/index.cjs

@@ -36,11 +36,13 @@ __export(index_exports, {
   AnthropicClient: () => AnthropicClient,
   BASE_CHAIN_ID: () => BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR: () => BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError: () => BatchChannelLockedError,
   BatchCloseDeferredError: () => BatchCloseDeferredError,
   BatchPaymentUnresolvedError: () => BatchPaymentUnresolvedError,
   BlockrunClient: () => BlockrunClient,
   BlockrunError: () => BlockrunError,
   DEFAULT_BATCH_IN_DOUBT: () => DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS: () => DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT: () => DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS: () => EVM_NETWORKS,
   ImageClient: () => ImageClient,
@@ -5120,7 +5122,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.24.9";
+var SDK_VERSION = "3.25.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -10222,6 +10224,8 @@ var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
 var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
 var DEFAULT_BATCH_IN_DOUBT = { maxWaitMs: 3e5 };
+var DEFAULT_BATCH_LOCK_WAIT_MS = 6e4;
+var LOCK_POLL_MS = 500;
 var BatchPaymentUnresolvedError = class extends PaymentError {
   /** The {@link SolanaBatchEvent.reason} of the `unresolved` event reported with it. */
   reason;
@@ -10267,6 +10271,22 @@ var BatchCloseDeferredError = class extends BlockrunError {
     this.channelIds = init.channelIds ?? [];
   }
 };
+var BatchChannelLockedError = class extends BlockrunError {
+  /** The paying wallet's address. */
+  wallet;
+  /** The live owner's pid, when the SDK knows it. */
+  ownerPid;
+  /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+  waitedMs;
+  constructor(init) {
+    super(`batch-settlement unavailable for wallet ${init.wallet}: ${init.detail}`);
+    this.name = "BatchChannelLockedError";
+    this.wallet = init.wallet;
+    if (init.ownerPid !== void 0) this.ownerPid = init.ownerPid;
+    this.waitedMs = init.waitedMs;
+    withDisposition(this, "unpaid");
+  }
+};
 var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
 async function load(pkg, importer) {
   try {
@@ -10902,6 +10922,38 @@ function withoutClientSignedBatch(paymentRequired) {
   const accepts = paymentRequired.accepts ?? [];
   return accepts.some(clientSignedBatch) ? { ...paymentRequired, accepts: accepts.filter((accept) => !clientSignedBatch(accept)) } : paymentRequired;
 }
+var DEPOSIT_BLOCKHASH_TTL_MS = 1e4;
+var MAX_DEPOSIT_BLOCKHASH_ENDPOINTS = 8;
+var depositBlockhashes = /* @__PURE__ */ new Map();
+async function finalizedBlockhash(rpcUrl, rpcHeaders) {
+  const cached = depositBlockhashes.get(rpcUrl);
+  if (cached && Date.now() - cached.fetchedAt < DEPOSIT_BLOCKHASH_TTL_MS) return cached;
+  const result = await rpcRequest(rpcUrl, "getLatestBlockhash", [{ commitment: "finalized" }], rpcHeaders);
+  const blockhash = result.value?.blockhash;
+  if (typeof blockhash !== "string" || !blockhash) throw new Error("getLatestBlockhash returned no blockhash");
+  const entry = {
+    blockhash,
+    lastValidBlockHeight: rpcInteger(result.value?.lastValidBlockHeight, "getLatestBlockhash lastValidBlockHeight"),
+    fetchedAt: Date.now()
+  };
+  depositBlockhashes.delete(rpcUrl);
+  depositBlockhashes.set(rpcUrl, entry);
+  while (depositBlockhashes.size > MAX_DEPOSIT_BLOCKHASH_ENDPOINTS) {
+    depositBlockhashes.delete(depositBlockhashes.keys().next().value);
+  }
+  return entry;
+}
+function withDepositBlockhash(paymentRequired, blockhash) {
+  const accepts = paymentRequired.accepts ?? [];
+  const lacking = (accept) => accept.scheme === BATCH_SCHEME && !accept.extra?.recentBlockhash;
+  if (!accepts.some(lacking)) return paymentRequired;
+  return {
+    ...paymentRequired,
+    accepts: accepts.map(
+      (accept) => lacking(accept) ? { ...accept, extra: { ...accept.extra, recentBlockhash: blockhash.blockhash, lastValidBlockHeight: blockhash.lastValidBlockHeight } } : accept
+    )
+  };
+}
 var PAYMENT_IDENTIFIER = "payment-identifier";
 function withPaymentIdentifier(paymentRequired) {
   const declared = paymentRequired.extensions?.[PAYMENT_IDENTIFIER];
@@ -11299,12 +11351,22 @@ var SolanaBatchPayer = class {
     if (!Number.isFinite(this.inDoubtMaxWaitMs) || this.inDoubtMaxWaitMs < 0) {
       throw new Error("batch.inDoubt.maxWaitMs must be a finite number of ms >= 0");
     }
+    this.onLocked = init.options.onLocked ?? "exact";
+    if (this.onLocked !== "exact" && this.onLocked !== "wait" && this.onLocked !== "throw") {
+      throw new Error('batch.onLocked must be "exact", "wait" or "throw"');
+    }
+    this.lockWaitMs = init.options.lockWaitMs ?? DEFAULT_BATCH_LOCK_WAIT_MS;
+    if (!Number.isFinite(this.lockWaitMs) || this.lockWaitMs < 0) {
+      throw new Error("batch.lockWaitMs must be a finite number of ms >= 0");
+    }
   }
   init;
   state;
   maxAttempts;
   maxWaitMs;
   inDoubtMaxWaitMs;
+  onLocked;
+  lockWaitMs;
   counters = {
     fallbacks: 0,
     fallbacksByReason: {},
@@ -11353,6 +11415,7 @@ var SolanaBatchPayer = class {
         if (owner !== void 0) {
           return {
             reason: "channel_store_locked",
+            ownerPid: owner,
             detail: owner === process.pid ? `channel store ${file} is in use by another copy of @blockrun/llm in this process (or by a process that had this pid and died: remove ${file}.lock if nothing uses it)` : `channel store ${file} is in use by process ${owner}`
           };
         }
@@ -11698,12 +11761,23 @@ var SolanaBatchPayer = class {
     const unavailable = batchUnavailable(paymentRequired);
     if (unavailable) return this.fallback(unavailable);
     let wallet;
+    let waitedMs = 0;
     try {
       wallet = await this.wallet();
+      if ("reason" in wallet && wallet.reason === "channel_store_locked" && this.onLocked === "wait") {
+        const started = Date.now();
+        wallet = await this.waitForLock(wallet);
+        waitedMs = Date.now() - started;
+      }
     } catch (err) {
       return this.fallback(creationFailure(err));
     }
-    if ("reason" in wallet) return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    if ("reason" in wallet) {
+      if (wallet.reason === "channel_store_locked" && this.onLocked !== "exact") {
+        return this.lockedOut(wallet.detail, wallet.ownerPid, waitedMs);
+      }
+      return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    }
     if (closesAtStart !== void 0 && wallet.closes !== closesAtStart) {
       return this.fallback({
         reason: "closed_during_call",
@@ -11720,6 +11794,40 @@ var SolanaBatchPayer = class {
       wallet.active -= 1;
     }
   }
+  /**
+   * `onLocked: "wait"`: try the wallet's channel store again every
+   * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+   * out. Reported once as a `backoff` event (`channel_store_locked`).
+   */
+  async waitForLock(refusal) {
+    const deadline = Date.now() + this.lockWaitMs;
+    let current = refusal;
+    if (this.lockWaitMs > 0) {
+      await this.report({
+        type: "backoff",
+        reason: "channel_store_locked",
+        retryAfterMs: this.lockWaitMs,
+        detail: refusal.detail
+      });
+    }
+    while ("reason" in current && current.reason === "channel_store_locked") {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await sleep2(Math.min(LOCK_POLL_MS, left));
+      current = await this.wallet();
+    }
+    return current;
+  }
+  /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+  async lockedOut(detail, ownerPid, waitedMs) {
+    const error = new BatchChannelLockedError({
+      wallet: await this.init.address(),
+      detail,
+      waitedMs,
+      ...ownerPid !== void 0 ? { ownerPid } : {}
+    });
+    return { kind: "failed", error };
+  }
   /**
    * The close fence for a call about to send its first request: how many
    * closes this wallet has completed so far, to hand to {@link pay}.
@@ -11810,11 +11918,9 @@ var SolanaBatchPayer = class {
         }
         if (wallet.busy) return fallback({ reason: "channel_busy", attempt: budget.attempt });
         if (wallet.file && !holdsChannelFile(wallet.file)) {
-          return fallback({
-            reason: "channel_store_locked",
-            attempt: budget.attempt,
-            detail: `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`
-          });
+          const detail = `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`;
+          if (this.onLocked !== "exact") return this.lockedOut(detail, void 0, 0);
+          return fallback({ reason: "channel_store_locked", attempt: budget.attempt, detail });
         }
         wallet.busy = true;
         holding = true;
@@ -12391,7 +12497,8 @@ var SolanaBatchPayer = class {
       const http = (await this.build(wallet)).http;
       try {
         await this.prepareTopUp(wallet, paymentRequired);
-        return { http, payload: await http.createPaymentPayload(withPaymentIdentifier(withoutClientSignedBatch(paymentRequired))) };
+        const required = await this.withDepositBlockhash(wallet, withoutClientSignedBatch(paymentRequired));
+        return { http, payload: await http.createPaymentPayload(withPaymentIdentifier(required)) };
       } catch (err) {
         if (pass > 0 || !isResyncRequired(err) || wallet.resyncs.size === 0) throw err;
       } finally {
@@ -12399,6 +12506,34 @@ var SolanaBatchPayer = class {
       }
     }
   }
+  /**
+   * The 402 to build this payment from: with a finalized blockhash
+   * ({@link withDepositBlockhash}) when the payment will likely carry a
+   * deposit (no usable record for the trusted accept's channel, so an open,
+   * or a top-up {@link prepareTopUp} just sized). An authorization signs no
+   * transaction and costs no RPC read. Best effort: a failed read leaves the
+   * 402 as it is, and `@x402/svm` fetches its own blockhash.
+   */
+  async withDepositBlockhash(wallet, paymentRequired) {
+    const accept = trustedBatchAccept(paymentRequired, this.init.options.operators);
+    const key = accept ? channelKeyOf(accept) : void 0;
+    if (!accept || accept.extra?.recentBlockhash) return paymentRequired;
+    let deposit = wallet.topUp !== void 0;
+    if (!deposit) {
+      try {
+        const record = key ? await wallet.book.base.get(key) : void 0;
+        deposit = !record || typeof record.channelId !== "string" || record.pending !== void 0;
+      } catch {
+        deposit = true;
+      }
+    }
+    if (!deposit) return paymentRequired;
+    try {
+      return withDepositBlockhash(paymentRequired, await finalizedBlockhash(this.init.rpcUrl, this.init.rpcHeaders));
+    } catch {
+      return paymentRequired;
+    }
+  }
   /**
    * Queue a re-read of a stored channel whose account is gone at finalized
    * and at confirmed commitment (closed, its account reclaimed), anchored at
@@ -12705,7 +12840,6 @@ var SolanaBatchPayer = class {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT14 = 6e4;
 var STALE_BLOCKHASH_RETRY_BACKOFFS_MS = [500, 2e3];
 var MAX_PAYMENT_FAILURE_BYTES = 64 * 1024;
 var DEFAULT_VIDEO_MODEL = "xai/grok-imagine-video";
@@ -12873,7 +13007,7 @@ var SolanaLLMClient = class {
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
-    this.timeout = options.timeout || DEFAULT_TIMEOUT14;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
     if (options.batch && !this.apiAuth) {
       this.batchPayer = new SolanaBatchPayer({
         options: options.batch,
@@ -14641,11 +14775,13 @@ var AnthropicClient = class {
   AnthropicClient,
   BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError,
   BatchCloseDeferredError,
   BatchPaymentUnresolvedError,
   BlockrunClient,
   BlockrunError,
   DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS,
   ImageClient,

package/dist/index.d.cts

@@ -2923,6 +2923,27 @@ interface SolanaBatchOptions {
      *   by scanning the chain for it.
      */
     channelStore?: string | false;
+    /**
+     * What a call does when another live process owns this wallet's channel
+     * store (`channel_store_locked`). One process per wallet pays with batch:
+     * it holds the store's lock until it exits, so worker pools, PM2/cluster
+     * workers or parallel runs on one wallet must each use their own wallet
+     * (or route their calls through one process).
+     * - `"exact"` (default): the call pays with `exact`, as before.
+     * - `"wait"`: the call waits up to {@link lockWaitMs} for the lock (the
+     *   owner has to exit), then pays with batch, or raises
+     *   {@link BatchChannelLockedError} once the wait runs out.
+     * - `"throw"`: the call raises {@link BatchChannelLockedError} at once.
+     *
+     * The error is raised before anything is signed, so it is `"unpaid"`:
+     * `fallbackModels` (and `smartChat()`'s chain) may move on, and will meet
+     * the same lock. A process that loses its lock to another owner raises it
+     * too unless `onLocked` is `"exact"` (waiting cannot give it back).
+     * Locks between clients of one process do not apply: they share a channel.
+     */
+    onLocked?: "exact" | "wait" | "throw";
+    /** Most time, in ms, one call waits for the lock under `onLocked: "wait"`. Default 60000. */
+    lockWaitMs?: number;
     /**
      * How a call rides out an HTTP 429 (rate limited, or channel capacity
      * exhausted) on a batch payment before it pays with `exact`. The call waits
@@ -2982,6 +3003,8 @@ declare const DEFAULT_BATCH_RATE_LIMIT: {
 declare const DEFAULT_BATCH_IN_DOUBT: {
     readonly maxWaitMs: 300000;
 };
+/** Default {@link SolanaBatchOptions.lockWaitMs}. */
+declare const DEFAULT_BATCH_LOCK_WAIT_MS = 60000;
 /**
  * One observable batch-settlement event.
  *
@@ -2996,7 +3019,10 @@ declare const DEFAULT_BATCH_IN_DOUBT: {
  *   (`reason: "rate_limited"`) or because another call for the wallet hit one
  *   (`reason: "cooldown"`), or before each replay of a payment in doubt that
  *   carries a payment identifier (`reason: "in_doubt"`, or `rate_limited`
- *   after a 429), with the answer's `status` and the wait in `retryAfterMs`.
+ *   after a 429), with the answer's `status` and the wait in `retryAfterMs`;
+ *   or, once, when a call starts waiting up to `lockWaitMs` for another
+ *   process's channel store lock (`reason: "channel_store_locked"`,
+ *   `onLocked: "wait"`).
  * - `recovered`: a call that backed off was then paid with batch (`reason:
  *   "in_doubt"` when the replay of a payment in doubt resolved it), or its
  *   fresh challenge after the wait was served without a payment (`reason:
@@ -3167,6 +3193,26 @@ declare class BatchCloseDeferredError extends BlockrunError {
         detail: string;
     });
 }
+/**
+ * Batch is on, another owner holds this wallet's channel store, and the
+ * client's `batch.onLocked` is `"wait"` (the wait ran out) or `"throw"`.
+ * Raised before anything is signed: nothing was paid for the call, and its
+ * {@link RetryDisposition} is `"unpaid"`.
+ */
+declare class BatchChannelLockedError extends BlockrunError {
+    /** The paying wallet's address. */
+    readonly wallet: string;
+    /** The live owner's pid, when the SDK knows it. */
+    readonly ownerPid?: number;
+    /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+    readonly waitedMs: number;
+    constructor(init: {
+        wallet: string;
+        detail: string;
+        ownerPid?: number;
+        waitedMs: number;
+    });
+}
 /**
  * The outcome of one batch attempt.
  *
@@ -3270,6 +3316,8 @@ declare class SolanaBatchPayer {
     private readonly maxAttempts;
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
+    private readonly onLocked;
+    private readonly lockWaitMs;
     private readonly counters;
     private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
@@ -3387,6 +3435,14 @@ declare class SolanaBatchPayer {
      *   open a channel the caller believes is closed.
      */
     pay(paymentRequired: PaymentRequired, send: (headers: Record<string, string>) => Promise<Response>, rechallenge: () => Promise<Rechallenge>, closesAtStart?: number): Promise<BatchAttempt>;
+    /**
+     * `onLocked: "wait"`: try the wallet's channel store again every
+     * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+     * out. Reported once as a `backoff` event (`channel_store_locked`).
+     */
+    private waitForLock;
+    /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+    private lockedOut;
     /**
      * The close fence for a call about to send its first request: how many
      * closes this wallet has completed so far, to hand to {@link pay}.
@@ -3508,6 +3564,15 @@ declare class SolanaBatchPayer {
      * once.
      */
     private createPayload;
+    /**
+     * The 402 to build this payment from: with a finalized blockhash
+     * ({@link withDepositBlockhash}) when the payment will likely carry a
+     * deposit (no usable record for the trusted accept's channel, so an open,
+     * or a top-up {@link prepareTopUp} just sized). An authorization signs no
+     * transaction and costs no RPC read. Best effort: a failed read leaves the
+     * 402 as it is, and `@x402/svm` fetches its own blockhash.
+     */
+    private withDepositBlockhash;
     /**
      * Queue a re-read of a stored channel whose account is gone at finalized
      * and at confirmed commitment (closed, its account reclaimed), anchored at
@@ -3647,7 +3712,12 @@ interface SolanaLLMClientOptions extends ApiKeyOptions {
      * (shortcut for `{ "x-api-key": "..." }`) env vars when omitted.
      */
     rpcHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds (default: 60000) */
+    /**
+     * Request timeout in milliseconds. Default: `BLOCKRUN_CHAT_TIMEOUT` (in
+     * seconds) when set, else 600000, the same as `LLMClient`: a reasoning
+     * model's long turn can take minutes, and a batch payment whose call is
+     * aborted after it was sent ends unresolved.
+     */
     timeout?: number;
     /**
      * Opt in to x402 batch-settlement (metered billing) for chat completions.
@@ -4476,4 +4546,4 @@ declare function readSettlement(response: Response, quotedUsd: number, scheme: S
     settlement: Settlement;
 };
 
-export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchChannelLockedError, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_LOCK_WAIT_MS, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -2923,6 +2923,27 @@ interface SolanaBatchOptions {
      *   by scanning the chain for it.
      */
     channelStore?: string | false;
+    /**
+     * What a call does when another live process owns this wallet's channel
+     * store (`channel_store_locked`). One process per wallet pays with batch:
+     * it holds the store's lock until it exits, so worker pools, PM2/cluster
+     * workers or parallel runs on one wallet must each use their own wallet
+     * (or route their calls through one process).
+     * - `"exact"` (default): the call pays with `exact`, as before.
+     * - `"wait"`: the call waits up to {@link lockWaitMs} for the lock (the
+     *   owner has to exit), then pays with batch, or raises
+     *   {@link BatchChannelLockedError} once the wait runs out.
+     * - `"throw"`: the call raises {@link BatchChannelLockedError} at once.
+     *
+     * The error is raised before anything is signed, so it is `"unpaid"`:
+     * `fallbackModels` (and `smartChat()`'s chain) may move on, and will meet
+     * the same lock. A process that loses its lock to another owner raises it
+     * too unless `onLocked` is `"exact"` (waiting cannot give it back).
+     * Locks between clients of one process do not apply: they share a channel.
+     */
+    onLocked?: "exact" | "wait" | "throw";
+    /** Most time, in ms, one call waits for the lock under `onLocked: "wait"`. Default 60000. */
+    lockWaitMs?: number;
     /**
      * How a call rides out an HTTP 429 (rate limited, or channel capacity
      * exhausted) on a batch payment before it pays with `exact`. The call waits
@@ -2982,6 +3003,8 @@ declare const DEFAULT_BATCH_RATE_LIMIT: {
 declare const DEFAULT_BATCH_IN_DOUBT: {
     readonly maxWaitMs: 300000;
 };
+/** Default {@link SolanaBatchOptions.lockWaitMs}. */
+declare const DEFAULT_BATCH_LOCK_WAIT_MS = 60000;
 /**
  * One observable batch-settlement event.
  *
@@ -2996,7 +3019,10 @@ declare const DEFAULT_BATCH_IN_DOUBT: {
  *   (`reason: "rate_limited"`) or because another call for the wallet hit one
  *   (`reason: "cooldown"`), or before each replay of a payment in doubt that
  *   carries a payment identifier (`reason: "in_doubt"`, or `rate_limited`
- *   after a 429), with the answer's `status` and the wait in `retryAfterMs`.
+ *   after a 429), with the answer's `status` and the wait in `retryAfterMs`;
+ *   or, once, when a call starts waiting up to `lockWaitMs` for another
+ *   process's channel store lock (`reason: "channel_store_locked"`,
+ *   `onLocked: "wait"`).
  * - `recovered`: a call that backed off was then paid with batch (`reason:
  *   "in_doubt"` when the replay of a payment in doubt resolved it), or its
  *   fresh challenge after the wait was served without a payment (`reason:
@@ -3167,6 +3193,26 @@ declare class BatchCloseDeferredError extends BlockrunError {
         detail: string;
     });
 }
+/**
+ * Batch is on, another owner holds this wallet's channel store, and the
+ * client's `batch.onLocked` is `"wait"` (the wait ran out) or `"throw"`.
+ * Raised before anything is signed: nothing was paid for the call, and its
+ * {@link RetryDisposition} is `"unpaid"`.
+ */
+declare class BatchChannelLockedError extends BlockrunError {
+    /** The paying wallet's address. */
+    readonly wallet: string;
+    /** The live owner's pid, when the SDK knows it. */
+    readonly ownerPid?: number;
+    /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+    readonly waitedMs: number;
+    constructor(init: {
+        wallet: string;
+        detail: string;
+        ownerPid?: number;
+        waitedMs: number;
+    });
+}
 /**
  * The outcome of one batch attempt.
  *
@@ -3270,6 +3316,8 @@ declare class SolanaBatchPayer {
     private readonly maxAttempts;
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
+    private readonly onLocked;
+    private readonly lockWaitMs;
     private readonly counters;
     private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
@@ -3387,6 +3435,14 @@ declare class SolanaBatchPayer {
      *   open a channel the caller believes is closed.
      */
     pay(paymentRequired: PaymentRequired, send: (headers: Record<string, string>) => Promise<Response>, rechallenge: () => Promise<Rechallenge>, closesAtStart?: number): Promise<BatchAttempt>;
+    /**
+     * `onLocked: "wait"`: try the wallet's channel store again every
+     * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+     * out. Reported once as a `backoff` event (`channel_store_locked`).
+     */
+    private waitForLock;
+    /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+    private lockedOut;
     /**
      * The close fence for a call about to send its first request: how many
      * closes this wallet has completed so far, to hand to {@link pay}.
@@ -3508,6 +3564,15 @@ declare class SolanaBatchPayer {
      * once.
      */
     private createPayload;
+    /**
+     * The 402 to build this payment from: with a finalized blockhash
+     * ({@link withDepositBlockhash}) when the payment will likely carry a
+     * deposit (no usable record for the trusted accept's channel, so an open,
+     * or a top-up {@link prepareTopUp} just sized). An authorization signs no
+     * transaction and costs no RPC read. Best effort: a failed read leaves the
+     * 402 as it is, and `@x402/svm` fetches its own blockhash.
+     */
+    private withDepositBlockhash;
     /**
      * Queue a re-read of a stored channel whose account is gone at finalized
      * and at confirmed commitment (closed, its account reclaimed), anchored at
@@ -3647,7 +3712,12 @@ interface SolanaLLMClientOptions extends ApiKeyOptions {
      * (shortcut for `{ "x-api-key": "..." }`) env vars when omitted.
      */
     rpcHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds (default: 60000) */
+    /**
+     * Request timeout in milliseconds. Default: `BLOCKRUN_CHAT_TIMEOUT` (in
+     * seconds) when set, else 600000, the same as `LLMClient`: a reasoning
+     * model's long turn can take minutes, and a batch payment whose call is
+     * aborted after it was sent ends unresolved.
+     */
     timeout?: number;
     /**
      * Opt in to x402 batch-settlement (metered billing) for chat completions.
@@ -4476,4 +4546,4 @@ declare function readSettlement(response: Response, quotedUsd: number, scheme: S
     settlement: Settlement;
 };
 
-export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchChannelLockedError, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_LOCK_WAIT_MS, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -4989,7 +4989,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.24.9";
+var SDK_VERSION = "3.25.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -10091,6 +10091,8 @@ var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
 var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
 var DEFAULT_BATCH_IN_DOUBT = { maxWaitMs: 3e5 };
+var DEFAULT_BATCH_LOCK_WAIT_MS = 6e4;
+var LOCK_POLL_MS = 500;
 var BatchPaymentUnresolvedError = class extends PaymentError {
   /** The {@link SolanaBatchEvent.reason} of the `unresolved` event reported with it. */
   reason;
@@ -10136,6 +10138,22 @@ var BatchCloseDeferredError = class extends BlockrunError {
     this.channelIds = init.channelIds ?? [];
   }
 };
+var BatchChannelLockedError = class extends BlockrunError {
+  /** The paying wallet's address. */
+  wallet;
+  /** The live owner's pid, when the SDK knows it. */
+  ownerPid;
+  /** How long this call waited for the lock, in ms (0 unless `onLocked` is `"wait"`). */
+  waitedMs;
+  constructor(init) {
+    super(`batch-settlement unavailable for wallet ${init.wallet}: ${init.detail}`);
+    this.name = "BatchChannelLockedError";
+    this.wallet = init.wallet;
+    if (init.ownerPid !== void 0) this.ownerPid = init.ownerPid;
+    this.waitedMs = init.waitedMs;
+    withDisposition(this, "unpaid");
+  }
+};
 var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
 async function load(pkg, importer) {
   try {
@@ -10771,6 +10789,38 @@ function withoutClientSignedBatch(paymentRequired) {
   const accepts = paymentRequired.accepts ?? [];
   return accepts.some(clientSignedBatch) ? { ...paymentRequired, accepts: accepts.filter((accept) => !clientSignedBatch(accept)) } : paymentRequired;
 }
+var DEPOSIT_BLOCKHASH_TTL_MS = 1e4;
+var MAX_DEPOSIT_BLOCKHASH_ENDPOINTS = 8;
+var depositBlockhashes = /* @__PURE__ */ new Map();
+async function finalizedBlockhash(rpcUrl, rpcHeaders) {
+  const cached = depositBlockhashes.get(rpcUrl);
+  if (cached && Date.now() - cached.fetchedAt < DEPOSIT_BLOCKHASH_TTL_MS) return cached;
+  const result = await rpcRequest(rpcUrl, "getLatestBlockhash", [{ commitment: "finalized" }], rpcHeaders);
+  const blockhash = result.value?.blockhash;
+  if (typeof blockhash !== "string" || !blockhash) throw new Error("getLatestBlockhash returned no blockhash");
+  const entry = {
+    blockhash,
+    lastValidBlockHeight: rpcInteger(result.value?.lastValidBlockHeight, "getLatestBlockhash lastValidBlockHeight"),
+    fetchedAt: Date.now()
+  };
+  depositBlockhashes.delete(rpcUrl);
+  depositBlockhashes.set(rpcUrl, entry);
+  while (depositBlockhashes.size > MAX_DEPOSIT_BLOCKHASH_ENDPOINTS) {
+    depositBlockhashes.delete(depositBlockhashes.keys().next().value);
+  }
+  return entry;
+}
+function withDepositBlockhash(paymentRequired, blockhash) {
+  const accepts = paymentRequired.accepts ?? [];
+  const lacking = (accept) => accept.scheme === BATCH_SCHEME && !accept.extra?.recentBlockhash;
+  if (!accepts.some(lacking)) return paymentRequired;
+  return {
+    ...paymentRequired,
+    accepts: accepts.map(
+      (accept) => lacking(accept) ? { ...accept, extra: { ...accept.extra, recentBlockhash: blockhash.blockhash, lastValidBlockHeight: blockhash.lastValidBlockHeight } } : accept
+    )
+  };
+}
 var PAYMENT_IDENTIFIER = "payment-identifier";
 function withPaymentIdentifier(paymentRequired) {
   const declared = paymentRequired.extensions?.[PAYMENT_IDENTIFIER];
@@ -11168,12 +11218,22 @@ var SolanaBatchPayer = class {
     if (!Number.isFinite(this.inDoubtMaxWaitMs) || this.inDoubtMaxWaitMs < 0) {
       throw new Error("batch.inDoubt.maxWaitMs must be a finite number of ms >= 0");
     }
+    this.onLocked = init.options.onLocked ?? "exact";
+    if (this.onLocked !== "exact" && this.onLocked !== "wait" && this.onLocked !== "throw") {
+      throw new Error('batch.onLocked must be "exact", "wait" or "throw"');
+    }
+    this.lockWaitMs = init.options.lockWaitMs ?? DEFAULT_BATCH_LOCK_WAIT_MS;
+    if (!Number.isFinite(this.lockWaitMs) || this.lockWaitMs < 0) {
+      throw new Error("batch.lockWaitMs must be a finite number of ms >= 0");
+    }
   }
   init;
   state;
   maxAttempts;
   maxWaitMs;
   inDoubtMaxWaitMs;
+  onLocked;
+  lockWaitMs;
   counters = {
     fallbacks: 0,
     fallbacksByReason: {},
@@ -11222,6 +11282,7 @@ var SolanaBatchPayer = class {
         if (owner !== void 0) {
           return {
             reason: "channel_store_locked",
+            ownerPid: owner,
             detail: owner === process.pid ? `channel store ${file} is in use by another copy of @blockrun/llm in this process (or by a process that had this pid and died: remove ${file}.lock if nothing uses it)` : `channel store ${file} is in use by process ${owner}`
           };
         }
@@ -11567,12 +11628,23 @@ var SolanaBatchPayer = class {
     const unavailable = batchUnavailable(paymentRequired);
     if (unavailable) return this.fallback(unavailable);
     let wallet;
+    let waitedMs = 0;
     try {
       wallet = await this.wallet();
+      if ("reason" in wallet && wallet.reason === "channel_store_locked" && this.onLocked === "wait") {
+        const started = Date.now();
+        wallet = await this.waitForLock(wallet);
+        waitedMs = Date.now() - started;
+      }
     } catch (err) {
       return this.fallback(creationFailure(err));
     }
-    if ("reason" in wallet) return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    if ("reason" in wallet) {
+      if (wallet.reason === "channel_store_locked" && this.onLocked !== "exact") {
+        return this.lockedOut(wallet.detail, wallet.ownerPid, waitedMs);
+      }
+      return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    }
     if (closesAtStart !== void 0 && wallet.closes !== closesAtStart) {
       return this.fallback({
         reason: "closed_during_call",
@@ -11589,6 +11661,40 @@ var SolanaBatchPayer = class {
       wallet.active -= 1;
     }
   }
+  /**
+   * `onLocked: "wait"`: try the wallet's channel store again every
+   * {@link LOCK_POLL_MS} until its owner lets go of it or `lockWaitMs` runs
+   * out. Reported once as a `backoff` event (`channel_store_locked`).
+   */
+  async waitForLock(refusal) {
+    const deadline = Date.now() + this.lockWaitMs;
+    let current = refusal;
+    if (this.lockWaitMs > 0) {
+      await this.report({
+        type: "backoff",
+        reason: "channel_store_locked",
+        retryAfterMs: this.lockWaitMs,
+        detail: refusal.detail
+      });
+    }
+    while ("reason" in current && current.reason === "channel_store_locked") {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await sleep2(Math.min(LOCK_POLL_MS, left));
+      current = await this.wallet();
+    }
+    return current;
+  }
+  /** `onLocked` other than `"exact"`: the call's `"unpaid"` error, nothing signed. */
+  async lockedOut(detail, ownerPid, waitedMs) {
+    const error = new BatchChannelLockedError({
+      wallet: await this.init.address(),
+      detail,
+      waitedMs,
+      ...ownerPid !== void 0 ? { ownerPid } : {}
+    });
+    return { kind: "failed", error };
+  }
   /**
    * The close fence for a call about to send its first request: how many
    * closes this wallet has completed so far, to hand to {@link pay}.
@@ -11679,11 +11785,9 @@ var SolanaBatchPayer = class {
         }
         if (wallet.busy) return fallback({ reason: "channel_busy", attempt: budget.attempt });
         if (wallet.file && !holdsChannelFile(wallet.file)) {
-          return fallback({
-            reason: "channel_store_locked",
-            attempt: budget.attempt,
-            detail: `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`
-          });
+          const detail = `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`;
+          if (this.onLocked !== "exact") return this.lockedOut(detail, void 0, 0);
+          return fallback({ reason: "channel_store_locked", attempt: budget.attempt, detail });
         }
         wallet.busy = true;
         holding = true;
@@ -12260,7 +12364,8 @@ var SolanaBatchPayer = class {
       const http = (await this.build(wallet)).http;
       try {
         await this.prepareTopUp(wallet, paymentRequired);
-        return { http, payload: await http.createPaymentPayload(withPaymentIdentifier(withoutClientSignedBatch(paymentRequired))) };
+        const required = await this.withDepositBlockhash(wallet, withoutClientSignedBatch(paymentRequired));
+        return { http, payload: await http.createPaymentPayload(withPaymentIdentifier(required)) };
       } catch (err) {
         if (pass > 0 || !isResyncRequired(err) || wallet.resyncs.size === 0) throw err;
       } finally {
@@ -12268,6 +12373,34 @@ var SolanaBatchPayer = class {
       }
     }
   }
+  /**
+   * The 402 to build this payment from: with a finalized blockhash
+   * ({@link withDepositBlockhash}) when the payment will likely carry a
+   * deposit (no usable record for the trusted accept's channel, so an open,
+   * or a top-up {@link prepareTopUp} just sized). An authorization signs no
+   * transaction and costs no RPC read. Best effort: a failed read leaves the
+   * 402 as it is, and `@x402/svm` fetches its own blockhash.
+   */
+  async withDepositBlockhash(wallet, paymentRequired) {
+    const accept = trustedBatchAccept(paymentRequired, this.init.options.operators);
+    const key = accept ? channelKeyOf(accept) : void 0;
+    if (!accept || accept.extra?.recentBlockhash) return paymentRequired;
+    let deposit = wallet.topUp !== void 0;
+    if (!deposit) {
+      try {
+        const record = key ? await wallet.book.base.get(key) : void 0;
+        deposit = !record || typeof record.channelId !== "string" || record.pending !== void 0;
+      } catch {
+        deposit = true;
+      }
+    }
+    if (!deposit) return paymentRequired;
+    try {
+      return withDepositBlockhash(paymentRequired, await finalizedBlockhash(this.init.rpcUrl, this.init.rpcHeaders));
+    } catch {
+      return paymentRequired;
+    }
+  }
   /**
    * Queue a re-read of a stored channel whose account is gone at finalized
    * and at confirmed commitment (closed, its account reclaimed), anchored at
@@ -12574,7 +12707,6 @@ var SolanaBatchPayer = class {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT14 = 6e4;
 var STALE_BLOCKHASH_RETRY_BACKOFFS_MS = [500, 2e3];
 var MAX_PAYMENT_FAILURE_BYTES = 64 * 1024;
 var DEFAULT_VIDEO_MODEL = "xai/grok-imagine-video";
@@ -12742,7 +12874,7 @@ var SolanaLLMClient = class {
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
-    this.timeout = options.timeout || DEFAULT_TIMEOUT14;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
     if (options.batch && !this.apiAuth) {
       this.batchPayer = new SolanaBatchPayer({
         options: options.batch,
@@ -14509,11 +14641,13 @@ export {
   AnthropicClient,
   BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR,
+  BatchChannelLockedError,
   BatchCloseDeferredError,
   BatchPaymentUnresolvedError,
   BlockrunClient,
   BlockrunError,
   DEFAULT_BATCH_IN_DOUBT,
+  DEFAULT_BATCH_LOCK_WAIT_MS,
   DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS,
   ImageClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.24.9",
+  "version": "3.25.0",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",