@black-market/sdk 0.12.0 → 0.13.0

package/examples/launch-example-support.ts

@@ -607,9 +607,7 @@ export function createLocalLaunchWallet({ privateKey, creator, chainId, orchestr
           if (request[field] < 0n) throw exampleError("INVALID_ENVELOPE", `${field} must be unsigned`);
         }
       }
-      request.nonce = envelope.nonce === undefined
-        ? exactNumber(await client.request({ method: "eth_getTransactionCount", params: [creator, "pending"] }), "nonce")
-        : exactNumber(envelope.nonce, "nonce");
+      if (envelope.nonce !== undefined) request.nonce = exactNumber(envelope.nonce, "nonce");
       if (request.type !== undefined) {
         request.type = transactionTypes[request.type];
         if (!request.type) throw exampleError("INVALID_ENVELOPE", "Only legacy/EIP-2930/EIP-1559 envelopes are supported");
@@ -622,6 +620,16 @@ export function createLocalLaunchWallet({ privateKey, creator, chainId, orchestr
         request.maxFeePerGas ??= fees.maxFeePerGas;
         request.maxPriorityFeePerGas ??= fees.maxPriorityFeePerGas;
       }
+      const [nonceValue, balanceValue] = await Promise.all([
+        client.request({ method: "eth_getTransactionCount", params: [creator, "pending"] }),
+        client.request({ method: "eth_getBalance", params: [creator, "pending"] }),
+      ]);
+      const pendingNonce = exactNumber(nonceValue, "pending nonce");
+      if (request.nonce !== undefined && request.nonce !== pendingNonce) throw exampleError("PENDING_NONCE_CHANGED", "Pending account nonce differs from the exact reviewed envelope");
+      request.nonce = pendingNonce;
+      const maximumFee = request.gas * (request.gasPrice ?? request.maxFeePerGas);
+      if (BigInt(balanceValue) < request.value + maximumFee) throw exampleError("INSUFFICIENT_PENDING_BALANCE", "Pending balance cannot fund the exact transaction value and maximum gas envelope");
+      await assertChain();
       const rawTransaction = await account.signTransaction(request);
       redactor.addSecret(rawTransaction);
       const wire = { ...envelope, chainId: toHex(id), nonce: toHex(request.nonce) };

package/examples/launch-example.ts

@@ -494,7 +494,7 @@ async function executePlan({ client, fixture, planned, sdk, artifacts, signal, l
     const next = await sdk.buildNextTransaction({ client, planned, receipts: references, limits, submissionClient: client, reviewedTransaction, signal });
     if (!next) return { references, activation };
     assert.ok(reviewedTransaction, "No transaction outside the saved review may be submitted");
-    for (const field of ["id", "kind", "chainId", "from", "to", "data", "value", "gas", "gasPrice"]) assert.equal(next[field], reviewedTransaction[field], `Fresh ${field} must match the saved review`);
+    for (const field of ["id", "kind", "chainId", "from", "to", "data", "value", "nonce", "gas", "gasPrice"]) assert.equal(next[field], reviewedTransaction[field], `Fresh ${field} must match the saved review`);
     if (retainedReferences.length) {
       const progress = await sdk.readLaunchProgress({ client, planned, receipts: references, confirmations: planned.confirmations, signal });
       assertRetainedExampleReceipts({ progress, references, artifacts });

package/examples/launch-lifecycle-smoke.ts

@@ -46,7 +46,7 @@ async function send(transaction) {
   const gasPrice = transaction.gasPrice ?? BigInt(await client.request({ method: "eth_gasPrice" }));
   const head = await client.request({ method: "eth_getBlockByNumber", params: ["latest", false] });
   const ceiling = [BigInt(head.gasLimit), BigInt(policy.chainTransactionGasLimit), BigInt(policy.rpcTransactionGasLimit), BigInt(policy.accountTransactionGasLimit)].reduce((a, b) => a < b ? a : b);
-  const wire = { from: transaction.from, to: transaction.to, data: transaction.data, value: toHex(transaction.value), gasPrice: toHex(gasPrice) };
+  const wire = { from: transaction.from, to: transaction.to, data: transaction.data, value: toHex(transaction.value), gasPrice: toHex(gasPrice), ...(transaction.nonce === undefined ? {} : { nonce: toHex(transaction.nonce) }) };
   const estimated = transaction.gas ?? ((BigInt(await client.request({ method: "eth_estimateGas", params: [{ ...wire, gas: toHex(ceiling) }] })) * BigInt(10000 + Number(policy.headroomBps)) + 9999n) / 10000n);
   assert.ok(estimated <= ceiling, "Unsigned helper must still fit explicit local execution admission");
   const transactionHash = await client.request({ method: "eth_sendTransaction", params: [{ ...wire, gas: toHex(estimated) }] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {

package/src/lifecycle/planner.ts

@@ -3,9 +3,9 @@ import { ABYSS_FEE_TIERS } from "../abyss.js";
 import { assertLaunchTopologyCoverage, getTickAtSqrtRatio } from "../launch.js";
 import { launchLifecycleAbi, lifecycleAdapterAbi, lifecycleErc20Abi } from "./abi.js";
 import { hashLaunchIdentity, hashLaunchPlan, LifecycleFundingKind, LifecyclePhase, LifecycleRewardMode, LifecycleTokenKind, LIFECYCLE_MAX_REWARD_ERC20_SUPPLY, LIFECYCLE_MAX_ERC404_SUPPLY, parseLaunchPlan, serializeLaunchPlan, type LaunchPlanV1 } from "./schema.js";
-import { readLaunchProgress, readLifecycleProfiles, readLifecycleTokenAtBlock, readPoolBoundHookDeployment } from "./progress.js";
+import { readLaunchProgress, readLifecycleHeadProgress, readLifecycleProfiles, readLifecycleTokenAtBlock, readPoolBoundHookDeployment } from "./progress.js";
 import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig, decodeV4LifecycleMarketConfig, encodePoolBoundV4LifecycleMarketConfig, isPoolBoundV4ConfigVersion, minePoolBoundHookSalt, type AbyssLifecycleMarketConfig, type V4LifecycleMarketConfig, type V4PoolBoundLifecycleMarketConfig } from "./markets.js";
-import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, resolveLifecycleLimits, rpcHex, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
+import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, readLifecycleGasPrice, resolveLifecycleLimits, rpcHex, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
 import { prepareLaunchSimulation, simulateLaunchTransactions, type NextTransactionEnvelope } from "./simulation.js";
 import { LifecyclePlanningError, type BuildNextTransactionOptions, type CanonicalLaunchProgress, type LifecycleBlock, type LifecycleConstructionProfile, type LifecycleFundingPrerequisite, type LifecyclePoolBoundHookDeployment, type LifecycleProfile, type LifecycleRpcClient, type LifecycleSimulation, type LifecycleTransaction, type PlannedLaunch, type PlanLaunchOptions, type PrepareAndPlanLifecycleLaunchOptions, type SimulateLaunchPlanOptions } from "./types.js";
 import { deriveKnownPoolBoundHookDeployment, protectOrderedBuyMinimums, validateBuySlippageBps } from "./calibration.js";
@@ -144,7 +144,7 @@ function orderedTransactions(plan: LaunchPlanV1, mode: "atomic" | "staged", prog
     (transaction.kind !== "begin" && transaction.kind !== "atomic" || progress.canonical.phase === LifecyclePhase.None) &&
     (transaction.kind !== "prepare" || (transaction.marketStart ?? 0) >= prepared));
   const transactions = progress.canonical.phase === LifecyclePhase.None ? [...approvals, ...commands] : commands;
-  return transactions.map((transaction, index) => ({ ...transaction, calldataBytes: (transaction.data.length - 2) / 2, dependencies: index === 0 ? [] : [transactions[index - 1]!.id] }));
+  return transactions.map((transaction, index) => ({ ...transaction, nonce: progress.pendingAccountNonce + BigInt(index), calldataBytes: (transaction.data.length - 2) / 2, dependencies: index === 0 ? [] : [transactions[index - 1]!.id] }));
 }
 
 function attachEstimates(transactions: readonly LifecycleTransaction[], simulation: LifecycleSimulation): LifecycleTransaction[] {
@@ -154,7 +154,7 @@ function attachEstimates(transactions: readonly LifecycleTransaction[], simulati
       admission: estimate === undefined ? undefined : { admitted: simulation.admitted, confidence: simulation.confidence, executionProof: simulation.executionProof, protocolFit: simulation.protocolFit, transportPreflight: simulation.transportPreflight, blockNumber: simulation.blockNumber, blockHash: simulation.blockHash, account: simulation.account, chainId: simulation.chainId, reason: simulation.reason, limits: simulation.limits } };
   });
 }
-type ReviewedNextTransaction = Pick<LifecycleTransaction, "id" | "kind" | "chainId" | "from" | "to" | "data" | "value"> & NextTransactionEnvelope;
+type ReviewedNextTransaction = Pick<LifecycleTransaction, "id" | "kind" | "chainId" | "from" | "to" | "data" | "value" | "nonce"> & NextTransactionEnvelope;
 const reviewedTransactionKinds = ["approve-reset", "approve", "atomic", "begin", "prepare", "activate", "cancel"] as const;
 
 function readReviewedNextTransaction(transaction: LifecycleTransaction | undefined): ReviewedNextTransaction | undefined {
@@ -167,7 +167,8 @@ function readReviewedNextTransaction(transaction: LifecycleTransaction | undefin
     typeof transaction.data !== "string" || !/^0x(?:[\da-fA-F]{2})*$/.test(transaction.data) ||
     typeof transaction.value !== "bigint" || transaction.value < 0n || transaction.value >= 1n << 256n ||
     typeof transaction.gas !== "bigint" || transaction.gas <= 0n || transaction.gas >= 1n << 64n ||
-    typeof transaction.gasPrice !== "bigint" || transaction.gasPrice < 0n || transaction.gasPrice >= 1n << 256n) {
+    typeof transaction.gasPrice !== "bigint" || transaction.gasPrice < 0n || transaction.gasPrice >= 1n << 256n ||
+    transaction.nonce !== undefined && (typeof transaction.nonce !== "bigint" || transaction.nonce < 0n || transaction.nonce >= 1n << 64n)) {
     throw new LifecyclePlanningError("INVALID_REVIEWED_TRANSACTION", "Reviewed transaction must contain a well-formed exact chain/account/target/calldata/value and uint64 gas/uint256 price envelope");
   }
   return transaction as ReviewedNextTransaction;
@@ -176,7 +177,8 @@ function readReviewedNextTransaction(transaction: LifecycleTransaction | undefin
 function matchesReviewedNextTransaction(next: LifecycleTransaction | ReviewedNextTransaction | undefined, reviewed: ReviewedNextTransaction): boolean {
   return next !== undefined && next.id === reviewed.id && next.kind === reviewed.kind && next.chainId === reviewed.chainId &&
     next.from.toLowerCase() === reviewed.from.toLowerCase() && next.to.toLowerCase() === reviewed.to.toLowerCase() &&
-    next.data.toLowerCase() === reviewed.data.toLowerCase() && next.value === reviewed.value;
+    next.data.toLowerCase() === reviewed.data.toLowerCase() && next.value === reviewed.value &&
+    (reviewed.nonce === undefined || next.nonce === reviewed.nonce);
 }
 
 function assertReviewedTransactionUnchanged(options: BuildNextTransactionOptions, reviewed: ReviewedNextTransaction | undefined, next: LifecycleTransaction): void {
@@ -273,16 +275,24 @@ function assertFinalPlan(planned: PlannedLaunch, signal?: AbortSignal): void {
 export async function prepareAndPlanLifecycleLaunch(options: PrepareAndPlanLifecycleLaunchOptions): Promise<PlannedLaunch> {
   const { commitment, ufgConfigHash } = validatePlanningIntent(options);
   if (options.buySlippageBps !== undefined) validateBuySlippageBps(options.buySlippageBps);
+  const fixed = options.fixedFinalEnvelope;
+  if (fixed !== undefined && (fixed === null || typeof fixed !== "object" || options.mode !== "atomic" || typeof fixed.gas !== "bigint" || fixed.gas <= 0n || fixed.gas >= 1n << 64n ||
+    fixed.gasPrice !== undefined && (typeof fixed.gasPrice !== "bigint" || fixed.gasPrice < 0n || fixed.gasPrice >= 1n << 256n))) {
+    throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope requires atomic mode, exact positive uint64 gas and optional uint256 price");
+  }
+  const heldEnvelope = fixed === undefined ? undefined : Object.freeze({ ...fixed });
   const needsMining = options.plan.markets.some((market) => isPoolBoundV4ConfigVersion(market.configVersion));
   const needsProtection = options.buySlippageBps !== undefined && options.plan.buys.length !== 0;
-  if (!needsMining && !needsProtection) return planLaunch(options);
+  if (!needsMining && !needsProtection && fixed === undefined) return planLaunch(options);
   const draft = parseLaunchPlan(serializeLaunchPlan(options.plan));
   const assertDraft = () => {
     assertPlanningActive(options.signal);
     if (hashLaunchPlan(options.plan).toLowerCase() !== commitment.toLowerCase()) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed during asynchronous preparation; previous construction is invalid");
     if ((options.ufg === undefined ? undefined : hashUfgLaunchConfig(options.ufg.config)) !== ufgConfigHash) throw new LifecyclePlanningError("PLAN_MUTATED", "UFG config changed during asynchronous preparation");
+    if (fixed === undefined ? options.fixedFinalEnvelope !== undefined : options.fixedFinalEnvelope !== fixed ||
+      fixed.gas !== heldEnvelope!.gas || fixed.gasPrice !== heldEnvelope!.gasPrice) throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope changed during preparation");
   };
-  return withLifecycleReadClient(options.client, async (client) => {
+  const result = await withLifecycleReadClient(options.client, async (client) => {
     const [block, chainId] = await Promise.all([readLifecycleBlock(client), readLifecycleChainId(client)]);
     if (chainId !== draft.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain differs from the economic plan being finalized");
     const metadata = needsMining ? await Promise.all(draft.markets.map((market, marketIndex) => isPoolBoundV4ConfigVersion(market.configVersion)
@@ -307,13 +317,19 @@ export async function prepareAndPlanLifecycleLaunch(options: PrepareAndPlanLifec
     // start at a fresh post-mining snapshot and share it through final protection.
     const executionBlock = needsMining ? await readLifecycleBlock(client) : block;
     assertDraft();
+    const price = heldEnvelope === undefined ? undefined : heldEnvelope.gasPrice ?? rpcQuantity(await readLifecycleGasPrice(client), "gas price");
+    const baseFeeEnvelope = (executionBlock.baseFeePerGas ?? 0n) * 2n;
+    const finalEnvelope = heldEnvelope === undefined ? undefined : Object.freeze({
+      gas: heldEnvelope.gas,
+      gasPrice: heldEnvelope.gasPrice ?? (price! > baseFeeEnvelope ? price! : baseFeeEnvelope),
+    });
     let plan: LaunchPlanV1 = { ...draft, markets };
     let ownedProgress: CanonicalLaunchProgress | undefined;
     if (needsProtection) {
       // A diagnostic minimum is never returned as an admitted or executable plan.
       // Price guards, funding minima, recipients and all ordered budgets stay exact.
       const diagnosticPlan = { ...plan, buys: plan.buys.map((buy) => ({ ...buy, minTokenOut: 1n })) };
-      const diagnostic = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan: diagnosticPlan }, client, executionBlock, undefined, true));
+      const diagnostic = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan: diagnosticPlan }, client, executionBlock, undefined, true, undefined, finalEnvelope));
       assertDraft();
       if (diagnostic.progress.canonical.phase !== LifecyclePhase.None || diagnostic.progress.head.phase !== LifecyclePhase.None) throw new LifecyclePlanningError("LAUNCH_ALREADY_STARTED", "Buy protection cannot replace an already committed launch plan");
       plan = protectOrderedBuyMinimums(diagnostic, options.buySlippageBps!);
@@ -321,7 +337,7 @@ export async function prepareAndPlanLifecycleLaunch(options: PrepareAndPlanLifec
       // state. No onchain commitment existed at this exact snapshot to replace.
       ownedProgress = { ...diagnostic.progress, planHash: hashLaunchPlan(plan) };
     }
-    const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan }, client, executionBlock, ownedProgress));
+    const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan }, client, executionBlock, ownedProgress, false, undefined, finalEnvelope));
     assertDraft();
     assertFinalPlan(planned, options.signal);
     if (planned.progress.canonical.phase !== LifecyclePhase.Active && planned.progress.canonical.phase !== LifecyclePhase.Cancelled) {
@@ -333,18 +349,23 @@ export async function prepareAndPlanLifecycleLaunch(options: PrepareAndPlanLifec
     if (needsProtection && !planned.simulation.admitted) throw new LifecyclePlanningError("PROTECTED_PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The final protected launch did not establish exact execution proof", planned.simulation);
     return planned;
   });
+  assertDraft();
+  assertFinalPlan(result, options.signal);
+  return result;
 }
 
 /** Independently fresh current-state admission of an already finalized commitment. No broadcasts. */
 export async function planLaunch(options: PlanLaunchOptions): Promise<PlannedLaunch> {
-  return withLifecycleReadClient(options.client, async (client) => {
+  const result = await withLifecycleReadClient(options.client, async (client) => {
     const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads(options, client));
     assertFinalPlan(planned, options.signal);
     return planned;
   });
+  assertFinalPlan(result, options.signal);
+  return result;
 }
 
-async function planLaunchWithReads(options: PlanLaunchOptions, client: LifecycleRpcClient, pinnedBlock?: LifecycleBlock, ownedProgress?: CanonicalLaunchProgress, diagnostic = false, reviewed?: ReviewedNextTransaction): Promise<PlannedLaunch> {
+async function planLaunchWithReads(options: PlanLaunchOptions, client: LifecycleRpcClient, pinnedBlock?: LifecycleBlock, ownedProgress?: CanonicalLaunchProgress, diagnostic = false, reviewed?: ReviewedNextTransaction, fixedFinalEnvelope?: NextTransactionEnvelope): Promise<PlannedLaunch> {
   const { plan, account, mode, ufg } = options;
   const { commitment: planHash, marketConfigs, ufgConfigHash } = validatePlanningIntent(options);
   const launchId = hashLaunchIdentity(plan);
@@ -366,7 +387,10 @@ async function planLaunchWithReads(options: PlanLaunchOptions, client: Lifecycle
     preset ?? readTokenFactoryBinding(client, plan.orchestrator, block),
     resolveLifecycleLimits({ client, account, orchestrator: plan.orchestrator, block, chainId: plan.chainId }, options.limits),
     lifecycleStage(client, "plan.progress", async () => {
-      const predictedToken = await readLifecycleTokenAtBlock(client, plan, block);
+      const [predictedToken] = await Promise.all([
+        readLifecycleTokenAtBlock(client, plan, block),
+        ownedProgress === undefined ? readLifecycleHeadProgress(client, plan, account, block) : undefined,
+      ]);
       const identity = { plan, planHash, launchId, predictedToken, account, mode, confirmations: options.confirmations ?? 1,
         ...(ufg === undefined ? {} : { ufg: { config: ufg.config, configHash: ufgConfigHash! } }) };
       if (ufg !== undefined) validateUfgLaunchPlan(plan, ufg.config, predictedToken);
@@ -419,6 +443,9 @@ async function planLaunchWithReads(options: PlanLaunchOptions, client: Lifecycle
     batches = [...(prepared > 0 ? [prepared] : []), count, ...(start + count < plan.markets.length ? [plan.markets.length - start - count] : [])];
   }
   let transactions = orderedTransactions(plan, mode, progress, funding.approvals, batches, ufg);
+  if (fixedFinalEnvelope !== undefined && (transactions.length !== 1 || transactions[0]!.kind !== "atomic")) {
+    throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope requires one immediate atomic launch with no preceding approvals");
+  }
   if (reviewed !== undefined) {
     if (!matchesReviewedNextTransaction(transactions[0], reviewed)) throw new LifecyclePlanningError("REVIEWED_TRANSACTION_MISMATCH", "Reviewed transaction differs from the current canonical unfinished next step");
     transactions = transactions.slice(0, 1);
@@ -427,9 +454,10 @@ async function planLaunchWithReads(options: PlanLaunchOptions, client: Lifecycle
     await assertLifecycleBlock(client, block, plan.chainId);
     return { ...planned, simulation: { ...placeholder, confidence: "stateful", reason: metadata.reasons.join("; "), failureCategory: "semantic" }, transactions, totalCalldataBytes: transactions.reduce((total, transaction) => total + (transaction.data.length - 2) / 2, 0) };
   }
-  const preparedSimulation = prepareLaunchSimulation({ client, planned, limits: options.limits, fork: options.fork, signal: options.signal }, block, true, reviewed);
+  const envelope = diagnostic ? undefined : reviewed ?? fixedFinalEnvelope;
+  const preparedSimulation = prepareLaunchSimulation({ client, planned, limits: options.limits, fork: options.fork, signal: options.signal }, block, true, envelope, fixedFinalEnvelope?.gasPrice);
   try {
-    const execute = diagnostic ? preparedSimulation.measure : (candidate: readonly LifecycleTransaction[]) => preparedSimulation(candidate, reviewed);
+    const execute = diagnostic ? preparedSimulation.measure : (candidate: readonly LifecycleTransaction[]) => preparedSimulation(candidate, envelope);
     let simulation = await execute(transactions);
     assertFinalPlan(planned, options.signal);
     if (mode === "staged") {
@@ -475,6 +503,7 @@ async function preflightNextTransaction(options: BuildNextTransactionOptions, ne
     if (rpcQuantity(await lifecycleRpc(submissionClient, "eth_chainId"), "submission chain ID") !== simulation.chainId) throw new Error("Active submission RPC chain differs from the reviewed transaction");
     const estimated = rpcQuantity(await lifecycleRpc(submissionClient, "eth_estimateGas", [{
       from: next.from, to: next.to, data: next.data, value: toHex(next.value), gas: toHex(next.gas), gasPrice: toHex(next.gasPrice),
+      ...(next.nonce === undefined ? {} : { nonce: toHex(next.nonce) }),
     }, "latest"]), "submission gas estimate");
     if (estimated <= 0n || estimated > next.gas) throw new Error("Submission RPC gas estimate exceeds the exact reviewed envelope or is zero");
     if (rpcQuantity(await lifecycleRpc(submissionClient, "eth_chainId"), "submission chain ID") !== simulation.chainId) throw new Error("Active submission RPC chain changed during preflight");
@@ -484,12 +513,6 @@ async function preflightNextTransaction(options: BuildNextTransactionOptions, ne
     const reason = `Exact next-transaction submission preflight failed: ${lifecycleFailureReason(failure)}`;
     throw new LifecyclePlanningError("SUBMISSION_PREFLIGHT_FAILED", reason, { ...simulation, transportPreflight: "failed", reason });
   }
-  const [canonical, chainId] = await Promise.all([
-    readLifecycleBlock(options.client, toHex(simulation.blockNumber)),
-    lifecycleRpc(options.client, "eth_chainId"),
-  ]);
-  if (canonical.hash.toLowerCase() !== simulation.blockHash.toLowerCase()) throw new LifecyclePlanningError("STATE_REORGED", "Pinned launch proof changed during submission preflight; rebuild from canonical progress");
-  if (rpcQuantity(chainId, "chain ID") !== simulation.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during submission preflight");
   if (next.admission === undefined) throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Next transaction omitted its exact simulation admission", simulation);
   assertPlanningActive(options.signal);
   assertReviewedTransactionUnchanged(options, reviewed, next);
@@ -503,9 +526,17 @@ export async function buildNextTransaction(options: BuildNextTransactionOptions)
   // Snapshot only the reviewed wire fields; caller proofs and commands are never
   // reused, and final checks compare the mutable input with this one local copy.
   const reviewed = supplied === undefined ? undefined : Object.freeze({ id: supplied.id, kind: supplied.kind, chainId: supplied.chainId,
-    from: supplied.from, to: supplied.to, data: supplied.data, value: supplied.value, gas: supplied.gas, gasPrice: supplied.gasPrice });
-  return withLifecycleReadClient(options.client, async (client) => {
+    from: supplied.from, to: supplied.to, data: supplied.data, value: supplied.value, gas: supplied.gas, gasPrice: supplied.gasPrice, nonce: supplied.nonce });
+  const result = await withLifecycleReadClient(options.client, async (client) => {
     const block = await readLifecycleBlock(client);
+    const limitSource = options.limits === undefined ? options.planned.limits : options.limits;
+    if (getKnownLifecycleDeployment({ chainId: options.planned.chainId, orchestrator: options.planned.plan.orchestrator }) !== undefined && typeof limitSource !== "function") {
+      await Promise.all([
+        readLifecycleTokenAtBlock(client, options.planned.plan, block),
+        readLifecycleHeadProgress(client, options.planned.plan, options.planned.account, block),
+        resolveLifecycleLimits({ client, account: options.planned.account, orchestrator: options.planned.plan.orchestrator, block, chainId: options.planned.chainId }, limitSource),
+      ]);
+    }
     const progress = await readLaunchProgress({ ...options, client }, block);
     if (progress.canonical.phase === LifecyclePhase.Active || progress.canonical.phase === LifecyclePhase.Cancelled) {
       // Only the confirmed canonical terminal phase is terminal; a head-only
@@ -523,6 +554,7 @@ export async function buildNextTransaction(options: BuildNextTransactionOptions)
       assertFinalPlan(planned, options.signal);
       const transaction: LifecycleTransaction = planned.ufg !== undefined ? buildUfgCancelTransaction({ plan: planned.plan, preparedMarkets: progress.canonical.preparedMarkets })
         : { id: "cancel", kind: "cancel", chainId: Number(planned.chainId), from: planned.account, to: planned.plan.orchestrator, data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "cancelLaunch", args: [planned.plan] }), value: 0n, dependencies: [], postconditions: [{ kind: "launch", phase: "Cancelled", preparedMarkets: progress.canonical.preparedMarkets }] };
+      transaction.nonce = progress.pendingAccountNonce;
       if (reviewed !== undefined && !matchesReviewedNextTransaction(transaction, reviewed)) throw new LifecyclePlanningError("REVIEWED_TRANSACTION_MISMATCH", "Reviewed transaction differs from the current canonical cancellation");
       const simulation = await simulateLaunchTransactions({ client, planned, limits: options.limits === undefined ? planned.limits : options.limits, fork: options.fork, signal: options.signal }, [transaction], block, reviewed);
       if (!simulation.admitted) throw new LifecyclePlanningError("CANCEL_NOT_ADMITTED", simulation.reason ?? "Cancellation could not be proved against current canonical state", simulation);
@@ -539,6 +571,9 @@ export async function buildNextTransaction(options: BuildNextTransactionOptions)
     if (next === undefined) return undefined;
     return preflightNextTransaction(options, next, refreshed.simulation, reviewed);
   });
+  assertFinalPlan(options.planned, options.signal);
+  if (result !== undefined) assertReviewedTransactionUnchanged(options, reviewed, result);
+  return result;
 }
 
 /** Re-simulates only canonical unfinished work with the same submitted receipt

package/src/lifecycle/progress.ts

@@ -2,7 +2,7 @@ import { concatHex, decodeFunctionData, encodeAbiParameters, encodeFunctionData,
 import { launchLifecycleAbi, lifecycleAdapterAbi, lifecycleDirectoryAbi, lifecycleErc20Abi, lifecycleOracleFactoryAbi, lifecycleRegistryAbi, poolFeeCollectorFactoryV1Abi, poolFeeCollectorFactoryConfigV6Abi, lifecycleV4HookAbi, lifecycleV4LockerAbi, poolHookDeployerV1Abi, poolHookDeployerConfigV6Abi, sharedHookDeployerV1Abi, fixedFeePoolHookV1Abi, fixedFeePoolHookConfigV6Abi, poolMarketAdapterV1Abi, sharedMarketAdapterV1Abi } from "./abi.js";
 import { buildPoolBoundHookParameters, decodePoolBoundV4LifecycleMarketConfig, encodePoolBoundHookParameters, hasLifecycleV4HookPermissions, isPoolBoundV4ConfigVersion, poolBoundHookInitCodeHash, predictPoolBoundHookAddress, validateV4LifecycleMarket, V4_LIFECYCLE_CONFIG_SCHEMA, V4_POOL_BOUND_LIFECYCLE_CONFIG_SCHEMA_V5, V4_POOL_BOUND_LIFECYCLE_CONFIG_SCHEMA_V6, type PoolBoundHookParameters, type PoolBoundLifecycleConfigVersion } from "./markets.js";
 import { hashLaunchIdentity, hashLaunchPlan, hashLaunchBounds, hashLaunchDependencies, hashLifecycleProfile, lifecycleTokenComponents, launchProgressV1Components, LifecycleMode, LifecyclePhase, LifecycleVenue, LIFECYCLE_REQUIRED_CAPABILITIES, LIFECYCLE_ERC404_CAPABILITY, LIFECYCLE_MULTI_POSITION_CAPABILITY, type AdapterRegistrationV1, type LaunchPlanV1, type LaunchProgressV1, type MarketIdentityV1, type MarketLiveStateV1, type PreparedMarketV1, type ProfileRegistrationV1, type ProfileTopologyV1, type LaunchEnvelopeV2, type LifecycleDeveloperTerms } from "./schema.js";
-import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, readLifecycleStaticContract, readLifecycleProfileTopology, rpcHex, rpcObject, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
+import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, readLifecycleImmutable, readLifecycleStaticContract, readLifecycleProfileTopology, rpcHex, rpcObject, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
 import { LifecyclePlanningError, type CanonicalLaunchProgress, type LifecycleBlock, type LifecycleMarketProgress, type LifecycleProfile, type LifecycleReceiptReference, type LifecycleReceiptStatus, type LifecycleRpcClient, type PoolBoundHookDeployment, type ReadLaunchProgressOptions } from "./types.js";
 import { deriveKnownPoolBoundHookDeployment } from "./calibration.js";
 import { getKnownLifecycleDeployment, getKnownLifecycleProfile } from "./presets.js";
@@ -21,9 +21,18 @@ const lifecycleTokenPredictionAbi = [{
  * avoiding full-plan prediction reads after salts or buy minima change. */
 export async function readLifecycleTokenAtBlock(client: LifecycleRpcClient, plan: LaunchPlanV1, block: LifecycleBlock): Promise<Address> {
   const deployment = getKnownLifecycleDeployment({ chainId: plan.chainId, orchestrator: plan.orchestrator });
-  return deployment === undefined
-    ? readLifecycleContract<Address>(client, plan.orchestrator, launchLifecycleAbi, "predictToken", [plan], block)
-    : readLifecycleContract<Address>(client, deployment.tokenFactory, lifecycleTokenPredictionAbi, "predictToken", [hashLaunchIdentity(plan), plan.token], block);
+  if (deployment === undefined) return readLifecycleContract<Address>(client, plan.orchestrator, launchLifecycleAbi, "predictToken", [plan], block);
+  const launchId = hashLaunchIdentity(plan);
+  const data = encodeFunctionData({ abi: lifecycleTokenPredictionAbi, functionName: "predictToken", args: [launchId, plan.token] });
+  const key = `${plan.chainId}:${plan.orchestrator.toLowerCase()}:${deployment.tokenFactory.toLowerCase()}:${deployment.tokenFactoryCodeHash}:${data}`;
+  return readLifecycleImmutable(client, key, () =>
+    readLifecycleContract<Address>(client, deployment.tokenFactory, lifecycleTokenPredictionAbi, "predictToken", [launchId, plan.token], block, undefined, false, true));
+}
+
+/** Internal pinned head observation. Known cores do not inspect msg.sender. */
+export function readLifecycleHeadProgress(client: LifecycleRpcClient, plan: LaunchPlanV1, account: Address, block: LifecycleBlock): Promise<LaunchProgressV1> {
+  const known = getKnownLifecycleDeployment({ chainId: plan.chainId, orchestrator: plan.orchestrator }) !== undefined;
+  return readLifecycleContract<LaunchProgressV1>(client, plan.orchestrator, launchLifecycleAbi, "readLaunchProgress", [hashLaunchIdentity(plan)], block, account, false, known);
 }
 
 export async function predictLifecycleToken(options: { client: LifecycleRpcClient; plan: LaunchPlanV1 }): Promise<Address> {
@@ -224,7 +233,7 @@ export async function validateV4LifecycleOracle(options: {
 
 export async function readLifecycleProfiles(options: { client: LifecycleRpcClient; orchestrator: Address; profileIds?: readonly Hex[]; offset?: bigint; limit?: bigint }, pinnedBlock?: LifecycleBlock): Promise<LifecycleProfile[]> {
   return withLifecycleReadClient(options.client, (client) => lifecycleStage(client, "profile.certification", async () => {
-    const chainIdPromise = lifecycleRpc(client, "eth_chainId").then((value) => rpcQuantity(value, "chain ID"));
+    const chainIdPromise = readLifecycleChainId(client);
     // Block-bound discovery does not depend on chain identity. Join both branches
     // immediately so a failed chain read cannot become detached or a profile refusal.
     const [chainId, { block, profiles }] = await Promise.all([
@@ -303,7 +312,7 @@ async function readPoolBoundHookDeploymentDetails(options: { client: LifecycleRp
   const market = plan.markets[marketIndex];
   if (market === undefined || !isPoolBoundV4ConfigVersion(market.configVersion)) throw new LifecyclePlanningError("INVALID_BOUND_MARKET", "Market index must select explicit pool-bound config version 5 or 6");
   let chainId: bigint;
-  try { chainId = rpcQuantity(await lifecycleRpc(client, "eth_chainId"), "chain ID"); }
+  try { chainId = await readLifecycleChainId(client); }
   finally { assertDerivedReadClientOpen(client); }
   if (hashLaunchPlan(plan) !== commitment) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed while observing the hook deployment chain");
   if (chainId !== plan.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain differs from the committed plan");
@@ -419,19 +428,21 @@ async function readPoolBoundHookDeploymentDetailsFresh(options: { client: Lifecy
 export async function readPoolBoundHookDeployment(options: { client: LifecycleRpcClient; plan: LaunchPlanV1; marketIndex: number }, pinnedBlock?: LifecycleBlock): Promise<PoolBoundHookDeployment> {
   const commitment = hashLaunchPlan(options.plan);
   const block = pinnedBlock ?? await readLifecycleBlock(options.client);
-  return withLifecycleReadClient(options.client, async (client) => {
+  const result = await withLifecycleReadClient(options.client, async (client) => {
     const { deployment } = await readPoolBoundHookDeploymentDetails({ ...options, client }, block, commitment);
     if (hashLaunchPlan(options.plan) !== commitment) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed while reading hook deployment metadata");
     if (pinnedBlock === undefined) await assertLifecycleBlock(client, block, options.plan.chainId);
     return { ...deployment };
   });
+  if (hashLaunchPlan(options.plan) !== commitment) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed during the final hook deployment guard");
+  return result;
 }
 
 /** Optional permissionless predeployment calldata; no token deployment, pool registration or wallet broadcast. */
 export async function buildPoolBoundHookDeploymentTransaction(options: { client: LifecycleRpcClient; plan: LaunchPlanV1; marketIndex: number }): Promise<{ to: Address; data: Hex; value: bigint; deployment: PoolBoundHookDeployment }> {
   const commitment = hashLaunchPlan(options.plan);
   const block = await readLifecycleBlock(options.client);
-  return withLifecycleReadClient(options.client, async (client) => {
+  const result = await withLifecycleReadClient(options.client, async (client) => {
     const { deployment, parameters, configVersion } = await readPoolBoundHookDeploymentDetails({ ...options, client }, block, commitment);
     if (!hasLifecycleV4HookPermissions(deployment.predictedHook)) throw new LifecyclePlanningError("INVALID_HOOK_BITS", "Finalize a salt with the exact lifecycle hook permissions before predeployment");
     if (hashLaunchPlan(options.plan) !== commitment) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed while constructing hook deployment calldata");
@@ -439,6 +450,8 @@ export async function buildPoolBoundHookDeploymentTransaction(options: { client:
     const abi = configVersion === 5 ? poolHookDeployerV1Abi : poolHookDeployerConfigV6Abi;
     return { to: deployment.deployer, data: encodeFunctionData({ abi, functionName: "deploy", args: [parameters, deployment.salt] }), value: 0n, deployment: { ...deployment } };
   });
+  if (hashLaunchPlan(options.plan) !== commitment) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed during the final hook transaction guard");
+  return result;
 }
 
 export function validateLifecycleMarketIdentity(identity: MarketIdentityV1, plan: LaunchPlanV1, token: Address, marketIndex: number): void {
@@ -455,7 +468,7 @@ export function validateLifecycleMarketIdentity(identity: MarketIdentityV1, plan
   } else if (identity.venue !== LifecycleVenue.Abyss || identity.pool === zeroAddress || identity.factory === zeroAddress) throw new LifecyclePlanningError("MARKET_IDENTITY", "Abyss canonical factory/pool identity is missing");
 }
 
-async function transactionMatchesLaunch(transaction: Record<string, unknown>, options: ReadLaunchProgressOptions, block: LifecycleBlock): Promise<boolean> {
+async function transactionMatchesLaunch(transaction: Record<string, unknown>, options: ReadLaunchProgressOptions, readBlock: () => Promise<LifecycleBlock>): Promise<boolean> {
   const { planned } = options;
   const from = rpcHex(transaction.from, "receipt transaction account");
   if (from.toLowerCase() !== planned.account.toLowerCase()) throw new LifecyclePlanningError("RECEIPT_ACCOUNT", "Receipt transaction belongs to a different account");
@@ -484,53 +497,103 @@ async function transactionMatchesLaunch(transaction: Record<string, unknown>, op
     if (decoded.functionName !== "approve" || rpcQuantity(transaction.value ?? "0x0", "approval native value") !== 0n) return false;
     spender = decoded.args[0];
   } catch { return false; }
-  const escrow = planned.ufg !== undefined ? UFG_LAUNCH_PROXY_ADDRESS : await readLifecycleContract<Address>(options.client, planned.plan.orchestrator, launchLifecycleAbi, "fundingEscrow", [], block);
+  const known = getKnownLifecycleDeployment({ chainId: planned.plan.chainId, orchestrator: planned.plan.orchestrator });
+  const escrow = planned.ufg !== undefined ? UFG_LAUNCH_PROXY_ADDRESS : known?.fundingEscrow ??
+    await readLifecycleContract<Address>(options.client, planned.plan.orchestrator, launchLifecycleAbi, "fundingEscrow", [], await readBlock());
   return spender.toLowerCase() === escrow.toLowerCase();
 }
 
-async function readReceipt(reference: LifecycleReceiptReference, options: ReadLaunchProgressOptions, block: LifecycleBlock): Promise<LifecycleReceiptStatus> {
+type ReceiptObservation = {
+  pins: readonly { number: bigint; hash: Hex }[];
+  finish(headers: ReadonlyMap<bigint, Hex | undefined>): LifecycleReceiptStatus;
+};
+
+async function readReceipt(reference: LifecycleReceiptReference, options: ReadLaunchProgressOptions, block: LifecycleBlock, readIdentityBlock: (number: bigint) => Promise<LifecycleBlock>): Promise<ReceiptObservation> {
   const effectiveHash = reference.replacementHash ?? reference.transactionHash;
   const base = { transactionHash: reference.transactionHash, effectiveHash, replaced: reference.replacementHash !== undefined && reference.replacementHash.toLowerCase() !== reference.transactionHash.toLowerCase() };
-  const observedNumber = reference.observedBlockNumber;
-  if (observedNumber !== undefined && reference.observedBlockHash !== undefined) {
-    const observed = await lifecycleRpc(options.client, "eth_getBlockByNumber", [toHex(observedNumber), false]);
-    if (observed === null || rpcHex(rpcObject(observed, "observed receipt block").hash, "observed receipt block hash").toLowerCase() !== reference.observedBlockHash.toLowerCase()) return { ...base, status: "reorged", blockNumber: observedNumber, blockHash: reference.observedBlockHash };
-  }
-  const [receiptValue, transactionValue] = await Promise.all([
-    lifecycleRpc(options.client, "eth_getTransactionReceipt", [effectiveHash]),
-    lifecycleRpc(options.client, "eth_getTransactionByHash", [effectiveHash]),
-  ]);
-  if (receiptValue === null) {
-    // An absent receipt with an unchanged canonical observed block is not a
-    // reorg: the transaction is simply not (yet) mined. A missing/changed
-    // canonical block above already reported the real reorg.
-    if (reference.observedBlockHash !== undefined) return { ...base, status: "pending", blockNumber: observedNumber, blockHash: reference.observedBlockHash };
-    return { ...base, status: "pending" };
+  const pins: { number: bigint; hash: Hex }[] = [];
+  const observedNumber = reference.observedBlockNumber, observedHash = reference.observedBlockHash;
+  if (observedNumber !== undefined && observedHash !== undefined) pins.push({ number: observedNumber, hash: observedHash });
+  const finish = (result: LifecycleReceiptStatus, failure?: { error: unknown }): ReceiptObservation => ({
+    pins,
+    finish(headers) {
+      for (const pin of pins) {
+        if (failure !== undefined && (pin.number !== observedNumber || pin.hash !== observedHash)) continue;
+        if (headers.get(pin.number)?.toLowerCase() !== pin.hash.toLowerCase()) return { ...base, status: "reorged", blockNumber: pin.number, blockHash: pin.hash };
+      }
+      if (failure !== undefined) throw failure.error;
+      return result;
+    },
+  });
+  try {
+    const [receiptValue, transactionValue] = await Promise.all([
+      lifecycleRpc(options.client, "eth_getTransactionReceipt", [effectiveHash]),
+      lifecycleRpc(options.client, "eth_getTransactionByHash", [effectiveHash]),
+    ]);
+    if (receiptValue === null) return finish({ ...base, status: "pending", blockNumber: observedNumber, blockHash: observedHash });
+    if (transactionValue === null) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Receipt exists without its canonical transaction");
+    const receipt = rpcObject(receiptValue, "receipt");
+    const blockNumber = rpcQuantity(receipt.blockNumber, "receipt block number");
+    const blockHash = rpcHex(receipt.blockHash, "receipt block hash");
+    pins.push({ number: blockNumber, hash: blockHash });
+    const matches = await transactionMatchesLaunch(rpcObject(transactionValue, "receipt transaction"), options,
+      () => readIdentityBlock(blockNumber));
+    const confirmations = block.number >= blockNumber ? block.number - blockNumber + 1n : 0n;
+    const required = reference.confirmations ?? 1;
+    if (!Number.isSafeInteger(required) || required < 1) throw new LifecyclePlanningError("INVALID_CONFIRMATIONS", "Receipt confirmations must be a positive integer");
+    const observation = finish({
+      ...base, blockNumber, blockHash, confirmations,
+      status: confirmations < BigInt(required) ? "unconfirmed" : !matches ? "replacement-cancelled" :
+        rpcQuantity(receipt.status, "receipt status") !== 1n ? "reverted" : "confirmed",
+    });
+    return {
+      pins,
+      finish(headers) {
+        const result = observation.finish(headers);
+        if (result.status !== "reorged" && !matches && !base.replaced) throw new LifecyclePlanningError("RECEIPT_IDENTITY", "Receipt calldata does not belong to the exact committed launch");
+        return result;
+      },
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") throw error;
+    // A changed retained observation is a reorg even if the orphan's transaction
+    // or identity read is now unavailable. Otherwise preserve the original error.
+    return finish({ ...base, status: "pending" }, { error });
   }
-  if (transactionValue === null) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Receipt exists without its canonical transaction");
-  const transaction = rpcObject(transactionValue, "receipt transaction");
-  const receiptBlock = await readLifecycleBlock(options.client, toHex(rpcQuantity(rpcObject(receiptValue, "receipt").blockNumber, "receipt block number")));
-  const matches = await transactionMatchesLaunch(transaction, options, receiptBlock);
-  if (!matches && !base.replaced) throw new LifecyclePlanningError("RECEIPT_IDENTITY", "Receipt calldata does not belong to the exact committed launch");
-  const receipt = rpcObject(receiptValue, "receipt");
-  const blockNumber = rpcQuantity(receipt.blockNumber, "receipt block number");
-  const blockHash = rpcHex(receipt.blockHash, "receipt block hash");
-  const canonicalBlockValue = await lifecycleRpc(options.client, "eth_getBlockByNumber", [toHex(blockNumber), false]);
-  if (canonicalBlockValue === null || rpcHex(rpcObject(canonicalBlockValue, "receipt canonical block").hash, "receipt canonical hash").toLowerCase() !== blockHash.toLowerCase()) return { ...base, status: "reorged", blockNumber, blockHash };
-  const confirmations = block.number >= blockNumber ? block.number - blockNumber + 1n : 0n;
-  const required = reference.confirmations ?? 1;
-  if (!Number.isSafeInteger(required) || required < 1) throw new LifecyclePlanningError("INVALID_CONFIRMATIONS", "Receipt confirmations must be a positive integer");
-  if (confirmations < BigInt(required)) return { ...base, status: "unconfirmed", blockNumber, blockHash, confirmations };
-  if (!matches) return { ...base, status: "replacement-cancelled", blockNumber, blockHash, confirmations };
-  if (rpcQuantity(receipt.status, "receipt status") !== 1n) return { ...base, status: "reverted", blockNumber, blockHash, confirmations };
-  return { ...base, status: "confirmed", blockNumber, blockHash, confirmations };
+}
+
+async function readReceipts(options: ReadLaunchProgressOptions, block: LifecycleBlock, confirmationDepth: number): Promise<LifecycleReceiptStatus[]> {
+  if (options.receipts === undefined || options.receipts.length === 0) return [];
+  const identityBlocks = new Map<bigint, Promise<LifecycleBlock>>();
+  const readIdentityBlock = (number: bigint) => {
+    let pending = identityBlocks.get(number);
+    if (pending === undefined) { pending = readLifecycleBlock(options.client, toHex(number)); identityBlocks.set(number, pending); }
+    return pending;
+  };
+  const observations = await Promise.all((options.receipts ?? []).map((reference) =>
+    readReceipt({ ...reference, confirmations: Math.max(reference.confirmations ?? 1, confirmationDepth) }, options, block, readIdentityBlock)));
+  const headers = new Map<bigint, Hex | undefined>();
+  for (const observation of observations) for (const pin of observation.pins) headers.set(pin.number, undefined);
+  // All asynchronous identity reads have settled. Equal observed/inclusion blocks
+  // and multiple receipts now share one fresh canonical header, never a stale cache.
+  await Promise.all([...headers.keys()].map(async (number) => {
+    const value = await lifecycleRpc(options.client, "eth_getBlockByNumber", [toHex(number), false]);
+    const hash = value === null ? undefined : rpcHex(rpcObject(value, "receipt canonical block").hash, "receipt canonical hash");
+    if (hash !== undefined && hash.length !== 66) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Receipt canonical block hash must have 32 bytes");
+    headers.set(number, hash);
+  }));
+  return observations.map((observation) => observation.finish(headers));
 }
 
 /** Reads confirmation-bound canonical state and receipt provenance; local step counters are never used. */
 export async function readLaunchProgress(options: ReadLaunchProgressOptions, pinnedBlock?: LifecycleBlock): Promise<CanonicalLaunchProgress> {
   if (options.signal?.aborted) throw Object.assign(new Error("Lifecycle progress read cancelled"), { name: "AbortError" });
-  const block = pinnedBlock ?? await readLifecycleBlock(options.client);
-  return withLifecycleReadClient(options.client, (client) => readLaunchProgressAtBlock(options, client, block, pinnedBlock === undefined));
+  const planHash = options.planned.planHash, launchId = options.planned.launchId;
+  const result = await withLifecycleReadClient(options.client, async (client) =>
+    readLaunchProgressAtBlock(options, client, pinnedBlock ?? await readLifecycleBlock(client), pinnedBlock === undefined));
+  if (hashLaunchPlan(options.planned.plan) !== planHash || hashLaunchIdentity(options.planned.plan) !== launchId) throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed during the final canonical progress guard");
+  if (options.signal?.aborted) throw Object.assign(new Error("Lifecycle progress read cancelled"), { name: "AbortError" });
+  return result;
 }
 
 async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, client: LifecycleRpcClient, block: LifecycleBlock, checkBlock: boolean): Promise<CanonicalLaunchProgress> {
@@ -555,7 +618,7 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
   } else if (planned.account.toLowerCase() !== planned.plan.creator.toLowerCase()) throw new LifecyclePlanningError("ACCOUNT_MISMATCH", "Execution account must be the committed creator/payer/refund account");
   if (hashLaunchPlan(planned.plan).toLowerCase() !== planned.planHash.toLowerCase() || hashLaunchIdentity(planned.plan).toLowerCase() !== planned.launchId.toLowerCase()) throw new LifecyclePlanningError("PLAN_MUTATED", "Stored economic plan no longer matches its commitment");
   const [head, confirmedProgress, token, confirmedNonce, headNonce, pendingNonce] = await Promise.all([
-    readLifecycleContract<LaunchProgressV1>(client, planned.plan.orchestrator, launchLifecycleAbi, "readLaunchProgress", [planned.launchId], block, planned.account),
+    readLifecycleHeadProgress(client, planned.plan, planned.account, block),
     confirmedNumber === block.number ? undefined : readLifecycleContract<LaunchProgressV1>(client, planned.plan.orchestrator, launchLifecycleAbi, "readLaunchProgress", [planned.launchId], confirmedBlock, planned.account),
     readLifecycleTokenAtBlock(client, planned.plan, block),
     lifecycleRpc(client, "eth_getTransactionCount", [planned.account, toHex(confirmedBlock.number)]),
@@ -582,7 +645,7 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
   const pendingAccountNonce = rpcQuantity(pendingNonce, "pending account nonce");
   const progressParameters = [{ type: "tuple", components: launchProgressV1Components }] as const;
   const confirmationSafe = confirmedAccountNonce === headAccountNonce && pendingAccountNonce === headAccountNonce && keccak256(encodeAbiParameters(progressParameters, [canonical])) === keccak256(encodeAbiParameters(progressParameters, [head]));
-  const receipts = await Promise.all((options.receipts ?? []).map((reference) => readReceipt({ ...reference, confirmations: Math.max(reference.confirmations ?? 1, confirmationDepth) }, { ...options, client }, block)));
+  const receipts = await readReceipts({ ...options, client }, block, confirmationDepth);
   assertActive();
   let markets: LifecycleMarketProgress[] = [];
   if (canonical.preparedMarkets > 0) {