@black-market/sdk 0.12.0 → 0.14.0

package/src/lifecycle/presets.ts

@@ -61,6 +61,9 @@ export type LifecycleDeploymentPreset = {
   readonly tokenFactory: Address;
   readonly tokenFactoryCodeHash: Hex;
   readonly fundingEscrow: Address;
+  /** Optional read-only acceleration contracts. An unset lens is not a deployed feature. */
+  readonly hookSaltMiner?: Address;
+  readonly launchLens?: Address;
   readonly profiles: readonly LifecycleProfilePreset[];
   readonly provenance: {
     readonly sourceCommit: string;
@@ -325,6 +328,7 @@ const knownDeployment: LifecycleDeploymentPreset = Object.freeze({
   tokenFactory: "0xd3cE64E49224a9a96075633f63761FE6BE22FE30",
   tokenFactoryCodeHash: "0x6bbbdfe93ec615b7f1e70bac5e69aa890eba5e5f248f25e7022e866b4064d541",
   fundingEscrow: "0x7bc77946CeF52A178583FCe1EEB7751983cEC703",
+  hookSaltMiner: "0x2f06176ba739b609b6a7334e2e6647558ba78ad5",
   profiles: Object.freeze([
     abyssPreset(KnownLifecycleProfile.Abyss0, "0x49b2ed65e2021247951193dd2c671b40867b6e064af65a2d98a70f57556412fc"),
     abyssPreset(KnownLifecycleProfile.Abyss1, "0x2f6f494f8810473b3c0ac6b03b1a1353d067ffa5c86d3cba16b04c6b61f73c05"),

package/src/lifecycle/progress.ts

@@ -2,16 +2,17 @@ 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 { 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";
 import { ufgLaunchProxyV1Abi } from "./ufg-abi.js";
 import { assertUfgLaunchAccount, hashUfgLaunchConfig, UFG_LAUNCH_PROXY_ADDRESS, type UfgLaunchConfig } from "./ufg-config.js";
+import { lifecycleLensSnapshot } from "./lens.js";
 
 export const ABYSS_LIFECYCLE_CONFIG_SCHEMA = keccak256(stringToHex("(uint8,uint24,bytes32,uint160,(int24,int24,uint128,uint256)[])"));
 
-const lifecycleTokenPredictionAbi = [{
+export const lifecycleTokenPredictionAbi = [{
   type: "function", name: "predictToken", stateMutability: "view",
   inputs: [{ name: "launchId", type: "bytes32" }, { name: "config", type: "tuple", components: lifecycleTokenComponents }],
   outputs: [{ type: "address" }],
@@ -21,16 +22,24 @@ 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> {
   return withLifecycleReadClient(options.client, async (client) => {
     const block = await readLifecycleBlock(client);
     const token = await readLifecycleTokenAtBlock(client, options.plan, block);
-    await assertLifecycleBlock(client, block, options.plan.chainId);
     return token;
   });
 }
@@ -224,10 +233,10 @@ 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([
+    const [, { profiles }] = await Promise.all([
       chainIdPromise,
       (async () => {
         const block = pinnedBlock ?? await readLifecycleBlock(client);
@@ -293,7 +302,6 @@ export async function readLifecycleProfiles(options: { client: LifecycleRpcClien
         return { block, profiles };
       })(),
     ]);
-    if (pinnedBlock === undefined) await assertLifecycleBlock(client, block, chainId);
     return profiles;
   }));
 }
@@ -303,7 +311,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,26 +427,28 @@ 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");
-    await assertLifecycleBlock(client, block, options.plan.chainId);
     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 +465,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,56 +494,114 @@ 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) => {
+    if (number === block.number) return Promise.resolve(block);
+    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);
+  // Reuse this invocation's authoritative L2 head header. Older receipt blocks
+  // share one canonical read after their asynchronous identity observations.
+  await Promise.all([...headers.keys()].map(async (number) => {
+    if (number === block.number) { headers.set(number, block.hash); return; }
+    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)));
+  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> {
+/** Build-next needs the state machine, receipts and nonce, not display-only live markets. */
+export async function readLifecycleExecutionProgress(options: ReadLaunchProgressOptions, block: LifecycleBlock): Promise<CanonicalLaunchProgress> {
+  if (!assertLifecycleReadClientOpen(options.client)) throw new LifecyclePlanningError("INVALID_READ_CONTEXT", "Execution progress requires an invocation owner");
+  return readLaunchProgressAtBlock(options, options.client, block, false);
+}
+
+async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, client: LifecycleRpcClient, block: LifecycleBlock, readMarkets = true): Promise<CanonicalLaunchProgress> {
   const { planned } = options;
   const assertActive = () => {
     if (options.signal?.aborted) throw Object.assign(new Error("Lifecycle progress read cancelled"), { name: "AbortError" });
@@ -555,7 +623,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,16 +650,23 @@ 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) {
+  const lens = lifecycleLensSnapshot(client, confirmedBlock);
+  if (readMarkets && lens !== undefined) {
+    markets = lens.preparedMarkets.map((market) => {
+      validateLifecycleMarketIdentity(market.prepared.identity, planned.plan, token, market.index);
+      return { index: market.index, prepared: market.prepared,
+        ...(market.liveStateSuccess ? { live: market.live } : { error: "Prepared market live-state read failed" }) };
+    });
+  } else if (readMarkets && canonical.preparedMarkets > 0) {
     const directory = await readLifecycleContract<Address>(client, planned.plan.orchestrator, launchLifecycleAbi, "directory", [], confirmedBlock);
     markets = await Promise.all(Array.from({ length: canonical.preparedMarkets }, async (_, index): Promise<LifecycleMarketProgress> => {
-      const [adapter, prepared] = await readLifecycleContract<readonly [Address, PreparedMarketV1]>(client, directory, lifecycleDirectoryAbi, "market", [planned.launchId, index], confirmedBlock);
+      const [adapter, prepared] = await readLifecycleContract<readonly [Address, PreparedMarketV1]>(client, directory, lifecycleDirectoryAbi, "market", [planned.launchId, index], confirmedBlock, undefined, false, true);
       validateLifecycleMarketIdentity(prepared.identity, planned.plan, token, index);
       try {
-        const live = await readLifecycleContract<MarketLiveStateV1>(client, adapter, lifecycleAdapterAbi, "readMarket", [planned.launchId, index], confirmedBlock);
+        const live = await readLifecycleContract<MarketLiveStateV1>(client, adapter, lifecycleAdapterAbi, "readMarket", [planned.launchId, index], confirmedBlock, undefined, false, true);
         return { index, prepared, live };
       } catch (failure) {
         if (failure instanceof Error && failure.name === "AbortError") throw failure;
@@ -599,8 +674,6 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
       }
     }));
   }
-  if (checkBlock) await assertLifecycleBlock(client, block, chainId);
-  if (confirmedNumber !== block.number) await assertLifecycleBlock(client, confirmedBlock, chainId);
   if (hashLaunchPlan(planned.plan).toLowerCase() !== planned.planHash.toLowerCase() || hashLaunchIdentity(planned.plan).toLowerCase() !== planned.launchId.toLowerCase()) throw new LifecyclePlanningError("PLAN_MUTATED", "Stored economic plan changed during asynchronous progress reads");
   assertActive();
   return { canonical, head, confirmationDepth, confirmedBlockNumber: confirmedBlock.number, confirmedBlockHash: confirmedBlock.hash, confirmedAccountNonce, headAccountNonce, pendingAccountNonce, confirmationSafe, token, planHash: planned.planHash, launchId: planned.launchId, chainId, blockNumber: block.number, blockHash: block.hash, markets, receipts };

package/src/lifecycle/rpc.ts

@@ -1,7 +1,14 @@
-import { decodeFunctionResult, encodeFunctionData, isAddress, isHex, parseAbi, toHex, type Abi, type Address, type Hex } from "viem";
+import { decodeFunctionResult, encodeFunctionData, isAddress, isHex, keccak256, multicall3Abi, parseAbi, toHex, type Abi, type Address, type Hex } from "viem";
 import { LifecyclePlanningError, type LifecycleBlock, type LifecycleDiagnosticEvent, type LifecycleDiagnosticListener, type LifecycleDiagnosticStage, type LifecycleLimitContext, type LifecycleLimitSource, type LifecycleLimits, type LifecycleRpcClient, type LifecycleSessionCache, type LifecycleTransaction, type ResolvedLifecycleLimits } from "./types.js";
 import { lifecycleRegistryAbi } from "./abi.js";
 import type { ProfileTopologyV1 } from "./schema.js";
+import { robinhoodMainnet } from "../addresses.js";
+
+// Reviewed chain4663 deployment, independently observed at block 98,136,655.
+const multicall3CodeHash = "0xd5c15df687b16f2ff992fc8d767b4216323184a2bbc6ee2f9c398c318e770891";
+const sessionObservations = new WeakMap<object, Map<string, Promise<unknown>>>();
+const canonicalWireValue = (_key: string, value: unknown): unknown => typeof value === "string" && value.startsWith("0x") ? value.toLowerCase() : value;
+type IndependentRead = { params: readonly unknown[]; resolve: (value: unknown) => void; reject: (failure: unknown) => void };
 
 const lifecycleReadConcurrency = 8;
 const diagnosticRpcMethods: Record<string, true> = {
@@ -67,6 +74,10 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
   private readonly concurrency: number;
   private diagnosticSequence = 0;
   private chainId?: Promise<bigint>;
+  private gasPrice?: Promise<unknown>;
+  private readonly immutableReads = new Map<string, Promise<unknown>>();
+  private readonly independentReads = new Map<string, { block: LifecycleBlock; reads: IndependentRead[] }>();
+  readonly finalChecks = new Set<() => void>();
   private readonly limitObservations = new Map<LifecycleLimitSource | undefined, Map<string, Promise<LifecycleLimitObservation>>>();
   private readonly session?: SessionLifecycleCache;
   private sessionGroup?: SessionReadGroup;
@@ -145,6 +156,73 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     return this.chainId ??= this.run("eth_chainId", []).then((value) => rpcQuantity(value, "chain ID"));
   }
 
+  observeGasPrice(): Promise<unknown> {
+    this.assertOpen();
+    return this.gasPrice ??= this.run("eth_gasPrice", []);
+  }
+
+  immutableRead(key: string, work: () => Promise<unknown>): Promise<unknown> {
+    this.assertOpen();
+    let pending = this.immutableReads.get(key);
+    if (pending === undefined) {
+      pending = work();
+      this.immutableReads.set(key, pending);
+      const owned = pending;
+      void pending.catch(() => { if (this.immutableReads.get(key) === owned) this.immutableReads.delete(key); });
+    }
+    return pending.then((value) => { this.assertOpen(); return value; });
+  }
+
+
+  async finalize(): Promise<void> {
+    this.assertOpen();
+    for (const check of this.finalChecks) check();
+  }
+
+  independentRead(params: readonly unknown[], block: LifecycleBlock, staticRead: boolean): Promise<unknown> {
+    return this.read("eth_call", params, block, staticRead, () => new Promise((resolve, reject) => {
+      const key = `${block.number}:${block.hash.toLowerCase()}`;
+      let group = this.independentReads.get(key);
+      if (group === undefined) {
+        group = { block, reads: [] };
+        this.independentReads.set(key, group);
+        queueMicrotask(() => {
+          this.independentReads.delete(key);
+          void this.flushIndependentReads(group!);
+        });
+      }
+      group.reads.push({ params, resolve, reject });
+    }));
+  }
+
+  private async flushIndependentReads(group: { block: LifecycleBlock; reads: IndependentRead[] }): Promise<void> {
+    const { block, reads } = group;
+    try {
+      if (await this.observeChainId() !== 4663n) {
+        await Promise.all(reads.map(async (read) => {
+          try { read.resolve(await this.run("eth_call", read.params)); }
+          catch (failure) { read.reject(failure); }
+        }));
+        return;
+      }
+      const to = robinhoodMainnet.contracts.multicall3.address;
+      await attestLifecycleMulticall(this, block);
+      const calls = reads.map((read) => {
+        const request = read.params[0] as { to: Address; data: Hex };
+        return { target: request.to, allowFailure: true, callData: request.data };
+      });
+      const data = encodeFunctionData({ abi: multicall3Abi, functionName: "aggregate3", args: [calls] });
+      const raw = rpcHex(await this.run("eth_call", [{ to, data }, toHex(block.number)]), "Multicall3 result");
+      const results = decodeFunctionResult({ abi: multicall3Abi, functionName: "aggregate3", data: raw });
+      if (results.length !== reads.length) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Multicall3 omitted independent pinned results");
+      for (let index = 0; index < reads.length; index += 1) {
+        const result = results[index]!;
+        if (result.success) reads[index]!.resolve(result.returnData);
+        else reads[index]!.reject(new LifecyclePlanningError("MULTICALL_READ_FAILED", "An independent pinned getter reverted"));
+      }
+    } catch (failure) { for (const read of reads) read.reject(failure); }
+  }
+
   observeLimits(context: LifecycleLimitContext, source?: LifecycleLimitSource): Promise<LifecycleLimitObservation> {
     this.assertOpen();
     // A caller callback is live policy, not an immutable pinned observation.
@@ -168,11 +246,11 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     return observation.then((result) => { this.assertOpen(); result.assertCurrent(); return result; });
   }
 
-  read(method: string, params: readonly unknown[], block: LifecycleBlock, staticRead = false): Promise<unknown> {
+  read(method: string, params: readonly unknown[], block: LifecycleBlock, staticRead = false, load?: () => Promise<unknown>): 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 key = JSON.stringify([block.number.toString(), block.hash, method, params], canonicalWireValue);
     const existing = this.reads.get(key);
     if (existing !== undefined) {
       if (staticRead && this.session !== undefined) this.sessionReuses += 1;
@@ -189,7 +267,7 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
       pending = Promise.resolve(cached);
     } else {
       if (staticRead && this.session !== undefined) this.sessionMisses += 1;
-      pending = this.run(method, params);
+      pending = load === undefined ? this.run(method, params) : load();
       if (group !== undefined) pending = pending.then((value) => {
         // Never share in-flight work or install late results after invalidation/closure.
         // Only wire hex is retained, so public decoded DTOs cannot mutate authority.
@@ -202,11 +280,21 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     return pending;
   }
 
+  seed(method: string, params: readonly unknown[], block: LifecycleBlock, value: unknown): void {
+    this.assertOpen();
+    const key = JSON.stringify([block.number.toString(), block.hash, method, params], canonicalWireValue);
+    this.reads.set(key, Promise.resolve(value));
+  }
+
   close(success: boolean): void {
     this.closed = true;
     this.reads.clear();
     this.chainId = undefined;
     this.limitObservations.clear();
+    this.gasPrice = undefined;
+    this.immutableReads.clear();
+    this.independentReads.clear();
+    this.finalChecks.clear();
     const listener = this.source.onDiagnostic;
     if (this.session !== undefined && listener !== undefined) emitLifecycleDiagnostic(listener, {
       stage: "session-cache", phase: success ? "success" : "failure",
@@ -221,7 +309,14 @@ export async function withLifecycleReadClient<T>(source: LifecycleRpcClient, wor
   const client = new InvocationLifecycleClient(source);
   let success = false;
   try {
-    const result = await work(client);
+    let result: T;
+    try { result = await work(client); }
+    catch (failure) {
+      // Live policy is rechecked even when exact execution or a source read refuses.
+      await client.finalize();
+      throw failure;
+    }
+    await client.finalize();
     success = true;
     return result;
   } finally { client.close(success); }
@@ -278,13 +373,65 @@ export function lifecycleStaticRpc(client: LifecycleRpcClient, method: "eth_call
 export async function lifecycleRpc(client: LifecycleRpcClient, method: string, params: readonly unknown[] = []): Promise<unknown> {
   return client instanceof InvocationLifecycleClient ? client.run(method, params) : client.request({ method, params });
 }
-/** One invocation's observed identity. End-of-operation and submission checks
- * deliberately use uncached eth_chainId so a switched provider cannot retain proof. */
+/** One invocation's observed identity; wallet submission owns its final chain check. */
 export function readLifecycleChainId(client: LifecycleRpcClient): Promise<bigint> {
   return client instanceof InvocationLifecycleClient
     ? client.observeChainId()
     : lifecycleRpc(client, "eth_chainId").then((value) => rpcQuantity(value, "chain ID"));
 }
+
+/** A single operation-local recommendation, never a session or cross-head quote. */
+export function readLifecycleGasPrice(client: LifecycleRpcClient): Promise<unknown> {
+  return client instanceof InvocationLifecycleClient ? client.observeGasPrice() : lifecycleRpc(client, "eth_gasPrice");
+}
+
+/** Only the reviewed immutable factory identity may use an invocation-wide key. */
+export function readLifecycleImmutable<T>(client: LifecycleRpcClient, key: string, work: () => Promise<T>): Promise<T> {
+  return (client instanceof InvocationLifecycleClient ? client.immutableRead(key, work) : work()) as Promise<T>;
+}
+
+/** Successful deployment/backend observations live for the caller's session, not one block. */
+export function lifecycleSessionRead<T>(client: LifecycleRpcClient, key: string, work: () => Promise<T>): Promise<T> {
+  const source = lifecycleSourceClient(client);
+  const owner = source.sessionCache ?? source;
+  let values = sessionObservations.get(owner);
+  if (values === undefined) { values = new Map(); sessionObservations.set(owner, values); }
+  let pending = values.get(key);
+  if (pending === undefined) {
+    pending = work();
+    values.set(key, pending);
+    const owned = pending;
+    void pending.catch(() => { if (values.get(key) === owned) values.delete(key); });
+  }
+  return pending as Promise<T>;
+}
+
+export async function attestLifecycleMulticall(client: LifecycleRpcClient, block?: LifecycleBlock): Promise<void> {
+  const to = robinhoodMainnet.contracts.multicall3.address;
+  await lifecycleSessionRead(client, `4663:multicall:${to}`, async () => {
+    const code = rpcHex(await lifecycleRpc(client, "eth_getCode", [to, block === undefined ? "latest" : toHex(block.number)]), "Multicall3 code");
+    if (keccak256(code) !== multicall3CodeHash) throw new LifecyclePlanningError("MULTICALL_CODE_MISMATCH", "Multicall3 runtime differs from the reviewed chain4663 deployment");
+  });
+}
+
+/** Installs only SDK-observed wire results from this invocation's aggregate/lens. */
+export function seedLifecycleRead(client: LifecycleRpcClient, method: string, params: readonly unknown[], block: LifecycleBlock, value: unknown): void {
+  if (!(client instanceof InvocationLifecycleClient)) throw new LifecyclePlanningError("INVALID_READ_CONTEXT", "Snapshot reads require an invocation owner");
+  client.observeBlock(block, true);
+  client.seed(method, params, block, value);
+}
+
+/** Recheck live policy after the owner's final asynchronous canonical guards. */
+export function registerLifecycleFinalCheck(client: LifecycleRpcClient, check: () => void): void {
+  if (client instanceof InvocationLifecycleClient) { client.assertOpen(); client.finalChecks.add(check); }
+}
+
+/** SDK-selected caller-independent getters only; never poster quotes or execution. */
+function lifecycleIndependentRpc(client: LifecycleRpcClient, params: readonly unknown[], block: LifecycleBlock, staticRead: boolean): Promise<unknown> {
+  return client instanceof InvocationLifecycleClient
+    ? client.independentRead(params, block, staticRead)
+    : lifecyclePinnedRpc(client, "eth_call", params, block, staticRead);
+}
 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`);
   // The object guard establishes the RPC record boundary; fields remain untrusted unknowns.
@@ -325,7 +472,8 @@ export async function readLifecycleBlock(client: LifecycleRpcClient, tag: Hex |
   if (client instanceof InvocationLifecycleClient) client.observeBlock(block, tag === "latest");
   return block;
 }
-export async function assertLifecycleBlock(client: LifecycleRpcClient, block: LifecycleBlock, expectedChainId?: bigint): Promise<void> {
+export async function assertLifecycleBlock(client: LifecycleRpcClient, block: Pick<LifecycleBlock, "number" | "hash">, expectedChainId?: bigint): Promise<void> {
+  if (client instanceof InvocationLifecycleClient) return;
   const [chainId, current] = await Promise.all([
     expectedChainId === undefined ? undefined : lifecycleRpc(client, "eth_chainId"),
     readLifecycleBlock(client, toHex(block.number)),
@@ -339,13 +487,15 @@ export async function assertLifecycleBlock(client: LifecycleRpcClient, block: Li
     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, staticRead = false): Promise<T> {
+export async function readLifecycleContract<T>(client: LifecycleRpcClient, to: Address, abi: Abi, functionName: string, args: readonly unknown[], block: LifecycleBlock, from?: Address, staticRead = false, independent = false): Promise<T> {
   const data = encodeFunctionData({ abi, functionName, args });
   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"
-    ? staticRead ? lifecycleStaticRpc(client, "eth_call", request, block) : lifecyclePinnedRpc(client, "eth_call", request, block)
-    : lifecycleRpc(client, "eth_call", request)), functionName);
+  const result = rpcHex(await (independent
+    ? lifecycleIndependentRpc(client, request, block, staticRead)
+    : getter
+      ? staticRead ? lifecycleStaticRpc(client, "eth_call", request, block) : 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;
@@ -382,7 +532,7 @@ 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 lifecycleStaticRpc(context.client, "eth_call", [{ to, data }, toHex(context.block.number)], context.block), functionName);
+  const result = rpcHex(await lifecycleIndependentRpc(context.client, [{ to, data }, toHex(context.block.number)], context.block, true), 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;
 }