@black-market/sdk 0.6.0 → 0.6.2

package/src/lifecycle/rpc.ts

@@ -1,10 +1,133 @@
 import { decodeFunctionResult, encodeFunctionData, isAddress, isHex, parseAbi, toHex, type Abi, type Address, type Hex } from "viem";
-import { LifecyclePlanningError, type LifecycleBlock, type LifecycleLimitContext, type LifecycleLimitSource, type LifecycleLimits, type LifecycleRpcClient, type LifecycleTransaction, type ResolvedLifecycleLimits } from "./types.js";
+import { LifecyclePlanningError, type LifecycleBlock, type LifecycleDiagnosticEvent, type LifecycleDiagnosticListener, type LifecycleDiagnosticStage, type LifecycleLimitContext, type LifecycleLimitSource, type LifecycleLimits, type LifecycleRpcClient, type LifecycleTransaction, type ResolvedLifecycleLimits } from "./types.js";
 import { lifecycleRegistryAbi } from "./abi.js";
 import type { ProfileTopologyV1 } from "./schema.js";
 
+const lifecycleReadConcurrency = 8;
+const diagnosticRpcMethods: Record<string, true> = {
+  eth_chainId: true, eth_getBlockByNumber: true, eth_getBlockByHash: true, eth_getCode: true,
+  eth_getBalance: true, eth_call: true, eth_estimateGas: true, eth_gasPrice: true,
+  eth_simulateV1: true, eth_getTransactionCount: true, eth_getTransactionReceipt: true, eth_getTransactionByHash: true,
+};
+
+/** Owns only one invocation's immutable RPC observations, never live checks or writes. */
+class InvocationLifecycleClient implements LifecycleRpcClient {
+  private readonly reads = new Map<string, Promise<unknown>>();
+  private readonly active = new Set<Promise<void>>();
+  private closed = false;
+  private readonly concurrency: number;
+  private diagnosticSequence = 0;
+  constructor(readonly source: LifecycleRpcClient) {
+    this.concurrency = source.supportsReadBatching === true ? lifecycleReadConcurrency : 1;
+  }
+
+  async request(args: { method: string; params?: readonly unknown[] }): Promise<unknown> {
+    this.assertOpen();
+    const result = await this.source.request(args);
+    this.assertOpen();
+    return result;
+  }
+
+  private assertOpen(): void {
+    if (this.closed) throw new LifecyclePlanningError("READ_SCOPE_CLOSED", "Lifecycle read invocation has already settled");
+  }
+
+  async run(method: string, params: readonly unknown[]): Promise<unknown> {
+    this.assertOpen();
+    const listener = this.source.onDiagnostic;
+    const observedMethod = listener === undefined ? undefined : diagnosticRpcMethods[method] === true ? method : "other";
+    const queuedAt = listener === undefined ? 0 : performance.now();
+    const requestId = listener === undefined ? 0 : ++this.diagnosticSequence;
+    if (listener !== undefined) emitLifecycleDiagnostic(listener, { stage: "rpc", phase: "queued", requestId, method: observedMethod });
+    while (this.active.size >= this.concurrency) await Promise.race(this.active);
+    this.assertOpen();
+    const started = listener === undefined ? 0 : performance.now();
+    if (listener !== undefined) emitLifecycleDiagnostic(listener, { stage: "rpc", phase: "start", requestId, method: observedMethod, queueMs: started - queuedAt });
+    const pending = this.request({ method, params });
+    const settled = pending.then(
+      () => { this.active.delete(settled); },
+      () => { this.active.delete(settled); },
+    );
+    this.active.add(settled);
+    try {
+      const result = await pending;
+      if (listener !== undefined) emitLifecycleDiagnostic(listener, { stage: "rpc", phase: "success", requestId, method: observedMethod, durationMs: performance.now() - started });
+      return result;
+    } catch (error) {
+      if (listener !== undefined) emitLifecycleDiagnostic(listener, { stage: "rpc", phase: "failure", requestId, method: observedMethod, durationMs: performance.now() - started });
+      throw error;
+    }
+  }
+
+  read(method: string, params: readonly unknown[], block: LifecycleBlock): Promise<unknown> {
+    this.assertOpen();
+    // Source identity is this scope's original client. The complete wire call includes
+    // caller, value, gas and any other call fields; no selector-only/ABI-name aliasing.
+    const key = JSON.stringify([block.number.toString(), block.hash.toLowerCase(), method, params]);
+    const existing = this.reads.get(key);
+    if (existing !== undefined) {
+      const listener = this.source.onDiagnostic;
+      if (listener !== undefined) emitLifecycleDiagnostic(listener, { stage: "rpc", phase: "reuse", method: diagnosticRpcMethods[method] === true ? method : "other" });
+      return existing;
+    }
+    const pending = this.run(method, params);
+    this.reads.set(key, pending);
+    void pending.catch(() => { if (this.reads.get(key) === pending) this.reads.delete(key); });
+    return pending;
+  }
+
+  close(): void {
+    this.closed = true;
+    this.reads.clear();
+  }
+}
+
+/** Internal callers join the same invocation; no process-wide/source-wide read cache. */
+export async function withLifecycleReadClient<T>(source: LifecycleRpcClient, work: (client: LifecycleRpcClient) => Promise<T>): Promise<T> {
+  if (source instanceof InvocationLifecycleClient) return work(source);
+  const client = new InvocationLifecycleClient(source);
+  try { return await work(client); }
+  finally { client.close(); }
+}
+
+export function lifecycleSourceClient(client: LifecycleRpcClient): LifecycleRpcClient {
+  return client instanceof InvocationLifecycleClient ? client.source : client;
+}
+
+function emitLifecycleDiagnostic(listener: LifecycleDiagnosticListener, event: LifecycleDiagnosticEvent): void {
+  try {
+    const pending = listener(event);
+    if (pending !== undefined) void pending.catch(() => {});
+  } catch { /* Observers cannot change financial behavior. */ }
+}
+
+/** No clock, event allocation or extra promise when diagnostics are disabled. */
+export function lifecycleStage<T>(client: LifecycleRpcClient, stage: LifecycleDiagnosticStage, work: () => Promise<T>): Promise<T> {
+  const listener = lifecycleSourceClient(client).onDiagnostic;
+  return listener === undefined ? work() : observedLifecycleStage(listener, stage, work);
+}
+
+async function observedLifecycleStage<T>(listener: LifecycleDiagnosticListener, stage: LifecycleDiagnosticStage, work: () => Promise<T>): Promise<T> {
+  const started = performance.now();
+  emitLifecycleDiagnostic(listener, { stage, phase: "start" });
+  try {
+    const result = await work();
+    emitLifecycleDiagnostic(listener, { stage, phase: "success", durationMs: performance.now() - started });
+    return result;
+  } catch (error) {
+    emitLifecycleDiagnostic(listener, { stage, phase: "failure", durationMs: performance.now() - started });
+    throw error;
+  }
+}
+
+/** Only explicitly pinned fixed-state reads may participate in invocation reuse. */
+export async function lifecyclePinnedRpc(client: LifecycleRpcClient, method: "eth_call" | "eth_getCode" | "eth_getBalance", params: readonly unknown[], block: LifecycleBlock): Promise<unknown> {
+  if (params.length !== 2 || params[1] !== toHex(block.number)) throw new LifecyclePlanningError("INVALID_READ_CONTEXT", "Reusable lifecycle reads require the exact pinned block and no state overrides");
+  return client instanceof InvocationLifecycleClient ? client.read(method, params, block) : lifecycleRpc(client, method, params);
+}
+
 export async function lifecycleRpc(client: LifecycleRpcClient, method: string, params: readonly unknown[] = []): Promise<unknown> {
-  return client.request({ method, params });
+  return client instanceof InvocationLifecycleClient ? client.run(method, params) : client.request({ method, params });
 }
 export function rpcObject(value: unknown, label: string): Record<string, unknown> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", `${label} must be an object`);
@@ -32,13 +155,20 @@ export async function readLifecycleBlock(client: LifecycleRpcClient, tag: Hex |
   };
 }
 export async function assertLifecycleBlock(client: LifecycleRpcClient, block: LifecycleBlock, expectedChainId?: bigint): Promise<void> {
-  if (expectedChainId !== undefined && rpcQuantity(await lifecycleRpc(client, "eth_chainId"), "chain ID") !== expectedChainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during the pinned operation");
-  const current = await readLifecycleBlock(client, toHex(block.number));
+  const [chainId, current] = await Promise.all([
+    expectedChainId === undefined ? undefined : lifecycleRpc(client, "eth_chainId"),
+    readLifecycleBlock(client, toHex(block.number)),
+  ]);
+  if (expectedChainId !== undefined && rpcQuantity(chainId, "chain ID") !== expectedChainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during the pinned operation");
   if (current.hash.toLowerCase() !== block.hash.toLowerCase()) throw new LifecyclePlanningError("STATE_REORGED", "Pinned launch state changed during the operation; read canonical progress again");
 }
 export async function readLifecycleContract<T>(client: LifecycleRpcClient, to: Address, abi: Abi, functionName: string, args: readonly unknown[], block: LifecycleBlock, from?: Address): Promise<T> {
   const data = encodeFunctionData({ abi, functionName, args });
-  const result = rpcHex(await lifecycleRpc(client, "eth_call", [{ to, from, data }, toHex(block.number)]), functionName);
+  const request = [{ to, from, data }, toHex(block.number)];
+  const getter = abi.some((item) => item.type === "function" && item.name === functionName && (item.stateMutability === "view" || item.stateMutability === "pure"));
+  const result = rpcHex(await (getter && functionName !== "readLaunchProgress"
+    ? lifecyclePinnedRpc(client, "eth_call", request, block)
+    : lifecycleRpc(client, "eth_call", request)), functionName);
   // ABI decoding validates scalar widths and tuple layout; T names that exact frozen ABI result.
   const decoded = decodeFunctionResult({ abi, functionName, data: result }) as T;
   return decoded;
@@ -61,7 +191,7 @@ const maxUint64 = (1n << 64n) - 1n;
 /** A poster quote is an envelope budget, never an execution/compute proof. */
 export async function readNitroPosterGas(transaction: LifecycleTransaction, context: LifecycleLimitContext): Promise<{ posterGas: bigint; baseFee: bigint; l1BaseFeeEstimate: bigint }> {
   const data = encodeFunctionData({ abi: nitroNodeInterfaceAbi, functionName: "gasEstimateL1Component", args: [transaction.to, false, transaction.data] });
-  const result = rpcHex(await lifecycleRpc(context.client, "eth_call", [{ from: transaction.from, to: nitroNodeInterface, data, value: toHex(transaction.value) }, toHex(context.block.number)]), "Nitro poster estimate");
+  const result = rpcHex(await lifecyclePinnedRpc(context.client, "eth_call", [{ from: transaction.from, to: nitroNodeInterface, data, value: toHex(transaction.value) }, toHex(context.block.number)], context.block), "Nitro poster estimate");
   if (result.length !== 194) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Nitro poster estimate must contain exactly three ABI words");
   const [posterGas, baseFee, l1BaseFeeEstimate] = decodeFunctionResult({ abi: nitroNodeInterfaceAbi, functionName: "gasEstimateL1Component", data: result });
   if (posterGas < 0n || posterGas > maxUint64 || baseFee <= 0n || l1BaseFeeEstimate < 0n) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Nitro poster estimate has invalid gas or fee values");
@@ -70,14 +200,15 @@ export async function readNitroPosterGas(transaction: LifecycleTransaction, cont
 
 async function readNitroScalar(context: LifecycleLimitContext, to: Address, abi: Abi, functionName: string): Promise<bigint> {
   const data = encodeFunctionData({ abi, functionName });
-  const result = rpcHex(await lifecycleRpc(context.client, "eth_call", [{ to, data }, toHex(context.block.number)]), functionName);
+  const result = rpcHex(await lifecyclePinnedRpc(context.client, "eth_call", [{ to, data }, toHex(context.block.number)], context.block), functionName);
   if (result.length !== 66) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", `${functionName} must return exactly one ABI word`);
   return decodeFunctionResult({ abi, functionName, data: result }) as bigint;
 }
 
 export async function resolveLifecycleLimits(context: LifecycleLimitContext, source?: LifecycleLimitSource): Promise<{ limits: ResolvedLifecycleLimits; configuration: LifecycleLimits }> {
   let configuration: LifecycleLimits;
-  try { configuration = source === undefined ? {} : typeof source === "function" ? await source(context) : source; }
+  const policyContext = typeof source === "function" && context.client instanceof InvocationLifecycleClient ? { ...context, client: context.client.source } : context;
+  try { configuration = source === undefined ? {} : typeof source === "function" ? await source(policyContext) : source; }
   catch (failure) { throw new LifecyclePlanningError("LIMIT_SOURCE_FAILED", `Supplied execution policy could not be resolved: ${failure instanceof Error ? failure.message : String(failure)}`); }
   if (configuration === null || typeof configuration !== "object" || Array.isArray(configuration)) throw new LifecyclePlanningError("INVALID_LIMITS", "Supplied execution policy must be an object");
   const headroomBps = configuration.headroomBps === undefined ? 1500 : configuration.headroomBps;
@@ -98,12 +229,16 @@ export async function resolveLifecycleLimits(context: LifecycleLimitContext, sou
   let arbOSVersion: bigint | undefined; let maxTxComputeGas: bigint | undefined; let maxBlockComputeGas: bigint | undefined;
   if (protocol === "nitro") {
     try {
-      const rawVersion = await readNitroScalar(context, nitroArbSys, nitroArbSysAbi, "arbOSVersion");
+      const [rawVersion, txComputeGas, blockComputeGas] = await Promise.all([
+        readNitroScalar(context, nitroArbSys, nitroArbSysAbi, "arbOSVersion"),
+        readNitroScalar(context, nitroGasInfo, nitroGasInfoAbi, "getMaxTxGasLimit"),
+        readNitroScalar(context, nitroGasInfo, nitroGasInfoAbi, "getMaxBlockGasLimit"),
+      ]);
       // ArbSys alone adds 55 to the logical Nitro ArbOS version.
       if (typeof rawVersion !== "bigint" || rawVersion < 105n) throw new Error("ArbOS version 50 or newer is required (ArbSys raw version >= 105)");
       arbOSVersion = rawVersion - 55n;
-      maxTxComputeGas = await readNitroScalar(context, nitroGasInfo, nitroGasInfoAbi, "getMaxTxGasLimit");
-      maxBlockComputeGas = await readNitroScalar(context, nitroGasInfo, nitroGasInfoAbi, "getMaxBlockGasLimit");
+      maxTxComputeGas = txComputeGas;
+      maxBlockComputeGas = blockComputeGas;
       if ([maxTxComputeGas, maxBlockComputeGas].some((limit) => typeof limit !== "bigint" || limit <= 0n || limit > maxUint64)) throw new Error("Nitro compute getters must be positive uint64 values");
     } catch (failure) { throw new LifecyclePlanningError("NITRO_LIMITS_UNAVAILABLE", `Pinned Nitro compute limits could not be established: ${failure instanceof Error ? failure.message : String(failure)}; header gasLimit is not a fallback`); }
     if (configuration.estimateDataFee !== undefined) throw new LifecyclePlanningError("INVALID_LIMITS", "Nitro poster fees are already included in gas; an external data-fee estimator would double-charge them");

package/src/lifecycle/simulation.ts

@@ -1,7 +1,7 @@
 import { decodeEventLog, decodeFunctionResult, encodeFunctionData, encodeFunctionResult, toHex, type Hex } from "viem";
 import { launchLifecycleAbi, lifecycleErc20Abi } from "./abi.js";
 import { LifecyclePhase, type LaunchProgressV1, type LaunchReceiptV1 } from "./schema.js";
-import { assertLifecycleBlock, lifecycleRpc, nitroArbSys, nitroArbSysAbi, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readNitroPosterGas, resolveLifecycleLimits, rpcHex, rpcObject, rpcQuantity } from "./rpc.js";
+import { assertLifecycleBlock, lifecyclePinnedRpc, lifecycleRpc, lifecycleSourceClient, lifecycleStage, nitroArbSys, nitroArbSysAbi, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readNitroPosterGas, resolveLifecycleLimits, rpcHex, rpcObject, rpcQuantity } from "./rpc.js";
 import { LifecyclePlanningError, type ControlledLifecycleFork, type LifecycleBlock, type LifecyclePostcondition, type LifecycleRpcClient, type LifecycleSimulation, type LifecycleSimulationStep, type LifecycleTransaction, type PlannedLaunch, type ResolvedLifecycleLimits, type SimulateLaunchPlanOptions } from "./types.js";
 
 function conditionRequest(condition: LifecyclePostcondition, planned: PlannedLaunch): { to: Hex; data: Hex } {
@@ -234,27 +234,36 @@ async function simulateForkPass(fork: ControlledLifecycleFork, planned: PlannedL
 
 export async function simulateLaunchTransactions(options: SimulateLaunchPlanOptions, transactions: readonly LifecycleTransaction[], pinnedBlock?: LifecycleBlock): Promise<LifecycleSimulation> {
   const { client, planned } = options;
-  if (options.fork?.client === client) throw new LifecyclePlanningError("UNSAFE_FORK", "Source RPC must never receive controlled simulation transactions/snapshots/resets");
+  const sourceClient = lifecycleSourceClient(client);
+  if (options.fork !== undefined && lifecycleSourceClient(options.fork.client) === sourceClient) throw new LifecyclePlanningError("UNSAFE_FORK", "Source RPC must never receive controlled simulation transactions/snapshots/resets");
   const block = pinnedBlock ?? await readLifecycleBlock(client);
   const context = { client, account: planned.account, orchestrator: planned.plan.orchestrator, block, chainId: planned.chainId };
-  const { limits, configuration } = await resolveLifecycleLimits(context, options.limits === undefined ? planned.limits : options.limits);
+  const [{ limits, configuration }, chainId, accountCodeValue, gasPriceValue] = await lifecycleStage(client, "simulation.context", () => Promise.all([
+    resolveLifecycleLimits(context, options.limits === undefined ? planned.limits : options.limits),
+    lifecycleRpc(client, "eth_chainId"),
+    lifecyclePinnedRpc(client, "eth_getCode", [planned.account, toHex(block.number)], block),
+    transactions.length === 0 ? undefined : lifecycleRpc(client, "eth_gasPrice"),
+  ]));
   const base = { confidence: "stateful" as const, executionProof: "failed" as const, protocolFit: "unknown" as const, transportPreflight: "not-requested" as const, blockNumber: block.number, blockHash: block.hash, account: planned.account, chainId: planned.chainId, limits };
-  if (rpcQuantity(await lifecycleRpc(client, "eth_chainId"), "chain ID") !== planned.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain changed before sequential simulation");
-  const accountCode = rpcHex(await lifecycleRpc(client, "eth_getCode", [planned.account, toHex(block.number)]), "account code");
+  if (rpcQuantity(chainId, "chain ID") !== planned.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain changed before sequential simulation");
+  const accountCode = rpcHex(accountCodeValue, "account code");
   if (accountCode !== "0x") return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: "Direct EOA transaction simulation cannot prove smart-account signature/execution behavior" };
   for (const transaction of transactions) {
     if (transaction.from.toLowerCase() !== planned.account.toLowerCase() || BigInt(transaction.chainId) !== planned.chainId) throw new LifecyclePlanningError("ACCOUNT_MISMATCH", "Simulation transaction differs from the committed chain/account");
     if (limits.maxCalldataBytes !== undefined && (transaction.data.length - 2) / 2 > limits.maxCalldataBytes) return { ...base, executionProof: "unavailable", protocolFit: "failed", backend: "unavailable", admitted: false, steps: [], failedTransactionId: transaction.id, reason: "Exact calldata exceeds the supplied chain/account/RPC byte cap" };
   }
   if (transactions.length === 0) { await assertLifecycleBlock(client, block, planned.chainId); return { ...base, executionProof: "proved", protocolFit: "proved", backend: "unavailable", admitted: true, steps: [] }; }
-  const gasPrice = rpcQuantity(await lifecycleRpc(client, "eth_gasPrice"), "gas price");
+  const gasPrice = rpcQuantity(gasPriceValue, "gas price");
   if (gasPrice >= 1n << 256n) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Gas price must be a uint256 quantity");
   const buffer = (gas: bigint) => (gas * BigInt(10000 + limits.headroomBps) + 9999n) / 10000n;
   const posterGas: bigint[] = [];
   if (limits.protocol === "nitro") {
     try {
-      await proveNitroBackend(client, planned, block, limits, gasPrice);
-      for (const transaction of transactions) posterGas.push(buffer((await readNitroPosterGas(transaction, context)).posterGas));
+      const [, estimates] = await Promise.all([
+        lifecycleStage(client, "simulation.nitro", () => proveNitroBackend(client, planned, block, limits, gasPrice)),
+        lifecycleStage(client, "simulation.poster", () => Promise.all(transactions.map(async (transaction) => buffer((await readNitroPosterGas(transaction, context)).posterGas)))),
+      ]);
+      posterGas.push(...estimates);
     } catch (failure) {
       await assertLifecycleBlock(client, block, planned.chainId);
       return { ...base, confidence: "provisional", executionProof: "unavailable", backend: "unavailable", admitted: false, steps: [], reason: `Native Nitro compute/poster proof unavailable: ${failure instanceof Error ? failure.message : String(failure)}. Generic Anvil/Hardhat forks cannot prove ArbOS metering.` };
@@ -273,7 +282,7 @@ export async function simulateLaunchTransactions(options: SimulateLaunchPlanOpti
   let backend: "eth_simulateV1" | "controlled-fork" = "eth_simulateV1";
   let measured: LifecycleSimulationStep[];
   // Permissive cap measurement is not proof; only the exact-gas validated replay admits a plan.
-  try { measured = await simulateRpcPass(client, planned, block, transactions, capGas, limits, gasPrice, false); }
+  try { measured = await lifecycleStage(client, "simulation.measure", () => simulateRpcPass(client, planned, block, transactions, capGas, limits, gasPrice, false)); }
   catch (failure) {
     if (options.fork === undefined || limits.protocol === "nitro") {
       await assertLifecycleBlock(client, block, planned.chainId);
@@ -300,7 +309,7 @@ export async function simulateLaunchTransactions(options: SimulateLaunchPlanOpti
   let verified: LifecycleSimulationStep[];
   let validatedReplayError: string | undefined;
   try {
-    if (backend === "eth_simulateV1") verified = await simulateRpcPass(client, planned, block, transactions, gasLimits, limits, gasPrice, true);
+    if (backend === "eth_simulateV1") verified = await lifecycleStage(client, "simulation.replay", () => simulateRpcPass(client, planned, block, transactions, gasLimits, limits, gasPrice, true));
     else {
       if (options.fork === undefined) throw new LifecyclePlanningError("INVALID_SIMULATION", "Controlled fork is missing for the exact-gas replay");
       verified = await simulateForkPass(options.fork, planned, block, transactions, gasLimits, gasPrice, false, limits.headroomBps);
@@ -325,7 +334,7 @@ export async function simulateLaunchTransactions(options: SimulateLaunchPlanOpti
     try {
       const ceilingLimits = discoveryGas;
       const retried = backend === "eth_simulateV1"
-        ? await simulateRpcPass(client, planned, block, transactions, ceilingLimits, limits, gasPrice, true)
+        ? await lifecycleStage(client, "simulation.envelope", () => simulateRpcPass(client, planned, block, transactions, ceilingLimits, limits, gasPrice, true))
         : options.fork === undefined ? undefined : await simulateForkPass(options.fork, planned, block, transactions, ceilingLimits, gasPrice, false, limits.headroomBps);
       if (retried === undefined || retried.some((step) => !step.success)) {
         await assertLifecycleBlock(client, block, planned.chainId);
@@ -368,13 +377,14 @@ export async function simulateLaunchTransactions(options: SimulateLaunchPlanOpti
     }
   }
   const estimates: LifecycleSimulationStep[] = [];
-  const balance = rpcQuantity(await lifecycleRpc(client, "eth_getBalance", [planned.account, toHex(block.number)]), "creator native balance");
+  const balance = rpcQuantity(await lifecyclePinnedRpc(client, "eth_getBalance", [planned.account, toHex(block.number)], block), "creator native balance");
   let remainingBalance = balance;
   let affordabilityFailure: string | undefined;
+  const feeContext = configuration.estimateDataFee === undefined || sourceClient === client ? context : { ...context, client: sourceClient };
   for (let index = 0; index < verifiedSteps.length; index += 1) {
     const step = verifiedSteps[index]; const transaction = transactions[index]; const gasLimit = admittedGasLimits[index];
     if (step === undefined || transaction === undefined || gasLimit === undefined) throw new LifecyclePlanningError("INVALID_SIMULATION", "Missing verified fee context");
-    const dataFee = limits.protocol === "nitro" ? 0n : configuration.estimateDataFee === undefined ? undefined : await configuration.estimateDataFee({ ...transaction, gas: gasLimit }, context);
+    const dataFee = limits.protocol === "nitro" ? 0n : configuration.estimateDataFee === undefined ? undefined : await configuration.estimateDataFee({ ...transaction, gas: gasLimit }, feeContext);
     if (dataFee !== undefined && (typeof dataFee !== "bigint" || dataFee < 0n || dataFee >= 1n << 256n)) throw new LifecyclePlanningError("INVALID_DATA_FEE", "Data-fee oracle must return a nonnegative uint256 bigint amount");
     // Nitro gas includes poster charges. Never add the quoted poster fee again.
     const executionFee = gasLimit * gasPrice;

package/src/lifecycle/types.ts

@@ -4,9 +4,28 @@ import type {
   MarketLiveStateV1, PreparedMarketV1, ProfileRegistrationV1, ProfileTopologyV1, LaunchEnvelopeV2, LifecycleDeveloperTerms,
 } from "./schema.js";
 
+/** Local opt-in timing only: never contains request arguments, addresses, results or errors. */
+export type LifecycleDiagnosticStage =
+  | "plan" | "plan.context" | "plan.domain" | "plan.progress" | "plan.inputs" | "rpc"
+  | "profile.certification" | "simulation.context" | "simulation.nitro"
+  | "simulation.poster" | "simulation.measure" | "simulation.replay" | "simulation.envelope";
+export type LifecycleDiagnosticEvent = {
+  stage: LifecycleDiagnosticStage;
+  phase: "queued" | "start" | "success" | "failure" | "reuse";
+  durationMs?: number;
+  queueMs?: number;
+  requestId?: number;
+  method?: string;
+};
+export type LifecycleDiagnosticListener = (event: LifecycleDiagnosticEvent) => void | Promise<void>;
+
 /** viem public clients or a raw JSON-RPC client; neither selects a transport. */
 export type LifecycleRpcClient = {
   request(args: { method: string; params?: readonly unknown[] }): Promise<unknown>;
+  /** Opt in to bounded parallel reads only when the supplied transport batches concurrent requests. */
+  supportsReadBatching?: boolean;
+  /** Optional local observer. Listener failures cannot change execution or admission. */
+  onDiagnostic?: LifecycleDiagnosticListener;
 };
 export type LifecycleBlock = { number: bigint; hash: Hash; timestamp: bigint; gasLimit: bigint; baseFeePerGas?: bigint };
 export type LifecycleLimitContext = { client: LifecycleRpcClient; account: Address; orchestrator: Address; block: LifecycleBlock; chainId: bigint };