@black-market/sdk 0.11.0 → 0.13.0

package/src/lifecycle/progress.ts

@@ -2,10 +2,12 @@ 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";
+import { ufgLaunchProxyV1Abi } from "./ufg-abi.js";
+import { assertUfgLaunchAccount, hashUfgLaunchConfig, UFG_LAUNCH_PROXY_ADDRESS, type UfgLaunchConfig } from "./ufg-config.js";
 
 export const ABYSS_LIFECYCLE_CONFIG_SCHEMA = keccak256(stringToHex("(uint8,uint24,bytes32,uint160,(int24,int24,uint128,uint256)[])"));
 
@@ -19,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> {
@@ -222,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([
@@ -301,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");
@@ -417,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");
@@ -437,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 {
@@ -453,19 +468,24 @@ 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");
   if (transaction.chainId !== undefined && rpcQuantity(transaction.chainId, "receipt transaction chain") !== planned.plan.chainId) throw new LifecyclePlanningError("RECEIPT_CHAIN", "Receipt transaction belongs to a different chain");
   const to = transaction.to === null ? zeroAddress : rpcHex(transaction.to, "receipt transaction target");
   const input = rpcHex(transaction.input ?? transaction.data, "receipt transaction calldata");
-  if (to.toLowerCase() === planned.plan.orchestrator.toLowerCase()) {
+  const target = planned.ufg === undefined ? planned.plan.orchestrator : UFG_LAUNCH_PROXY_ADDRESS;
+  if (to.toLowerCase() === target.toLowerCase()) {
     try {
-      const decoded = decodeFunctionData({ abi: launchLifecycleAbi, data: input });
+      const decoded = decodeFunctionData({ abi: planned.ufg === undefined ? launchLifecycleAbi : ufgLaunchProxyV1Abi, data: input });
       if (!["launchAtomic", "beginLaunch", "prepareMarkets", "activateLaunch", "cancelLaunch"].includes(decoded.functionName) || !Array.isArray(decoded.args)) return false;
       // Decoded plan layout is validated by the exact ABI, not trusted raw RPC JSON.
       const plan = decoded.args[0] as LaunchPlanV1;
+      if (planned.ufg !== undefined && (decoded.functionName === "launchAtomic" || decoded.functionName === "beginLaunch")) {
+        const config = decoded.args[decoded.functionName === "launchAtomic" ? 1 : 2] as UfgLaunchConfig;
+        if (hashUfgLaunchConfig(config) !== planned.ufg.configHash) return false;
+      }
       return hashLaunchPlan(plan).toLowerCase() === planned.planHash.toLowerCase();
     } catch { return false; }
   }
@@ -477,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 = 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> {
@@ -542,10 +612,13 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
   assertActive();
   const chainId = chainIdValue;
   if (chainId !== planned.plan.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain differs from the committed launch");
-  if (planned.account.toLowerCase() !== planned.plan.creator.toLowerCase()) throw new LifecyclePlanningError("ACCOUNT_MISMATCH", "Execution account must be the committed creator/payer/refund account");
+  if (planned.ufg !== undefined) {
+    assertUfgLaunchAccount(planned.plan, planned.account);
+    if (hashUfgLaunchConfig(planned.ufg.config) !== planned.ufg.configHash) throw new LifecyclePlanningError("PLAN_MUTATED", "UFG config differs from its finalized commitment");
+  } 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)]),
@@ -556,16 +629,23 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
   const canonical = confirmedProgress ?? head;
   if (token.toLowerCase() !== planned.predictedToken.toLowerCase()) throw new LifecyclePlanningError("TOKEN_IDENTITY", "Predicted token changed for the committed token configuration");
   for (const progress of [canonical, head]) if (progress.phase !== LifecyclePhase.None) {
-    if (progress.planHash.toLowerCase() !== planned.planHash.toLowerCase() || progress.launchId.toLowerCase() !== planned.launchId.toLowerCase() || progress.creator.toLowerCase() !== planned.account.toLowerCase() || progress.nonce !== planned.plan.nonce || progress.token.toLowerCase() !== token.toLowerCase() || progress.marketCount !== planned.plan.markets.length || progress.buyCount !== planned.plan.buys.length || progress.deadline !== planned.plan.deadline) throw new LifecyclePlanningError("PLAN_REPLAY", "This creator nonce is already bound to a different economic launch");
+    if (progress.planHash.toLowerCase() !== planned.planHash.toLowerCase() || progress.launchId.toLowerCase() !== planned.launchId.toLowerCase() || progress.creator.toLowerCase() !== planned.plan.creator.toLowerCase() || progress.nonce !== planned.plan.nonce || progress.token.toLowerCase() !== token.toLowerCase() || progress.marketCount !== planned.plan.markets.length || progress.buyCount !== planned.plan.buys.length || progress.deadline !== planned.plan.deadline) throw new LifecyclePlanningError("PLAN_REPLAY", "This creator nonce is already bound to a different economic launch");
     if (progress.mode !== (planned.mode === "atomic" ? LifecycleMode.Atomic : LifecycleMode.Staged)) throw new LifecyclePlanningError("MODE_MISMATCH", "Execution mode differs from the already recorded launch");
     if (progress.preparedMarkets > progress.marketCount || progress.phase === LifecyclePhase.Activating || (progress.phase === LifecyclePhase.Ready && progress.preparedMarkets !== progress.marketCount)) throw new LifecyclePlanningError("INVALID_PROGRESS", "Canonical progress violates the committed ordered state machine");
   }
+  if (planned.ufg !== undefined && head.phase !== LifecyclePhase.None) {
+    const [principal, configHash] = await Promise.all([
+      readLifecycleContract<Address>(client, UFG_LAUNCH_PROXY_ADDRESS, ufgLaunchProxyV1Abi, "principalOf", [planned.launchId], block),
+      readLifecycleContract<Hash>(client, UFG_LAUNCH_PROXY_ADDRESS, ufgLaunchProxyV1Abi, "launchConfigHash", [planned.launchId], block),
+    ]);
+    if (principal.toLowerCase() !== planned.account.toLowerCase() || configHash.toLowerCase() !== planned.ufg.configHash.toLowerCase()) throw new LifecyclePlanningError("PLAN_REPLAY", "UFG proxy principal or launch config differs from the stored launch");
+  }
   const confirmedAccountNonce = rpcQuantity(confirmedNonce, "confirmed account nonce");
   const headAccountNonce = headNonce === undefined ? confirmedAccountNonce : rpcQuantity(headNonce, "head account nonce");
   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) {

package/src/lifecycle/rpc.ts

@@ -1,7 +1,12 @@
-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";
+type IndependentRead = { params: readonly unknown[]; resolve: (value: unknown) => void; reject: (failure: unknown) => void };
 
 const lifecycleReadConcurrency = 8;
 const diagnosticRpcMethods: Record<string, true> = {
@@ -67,6 +72,11 @@ 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 canonicalPins = new Map<string, { block: Pick<LifecycleBlock, "number" | "hash">; chainId?: bigint }>();
+  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 +155,103 @@ 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; });
+  }
+
+  deferCanonicalCheck(block: Pick<LifecycleBlock, "number" | "hash">, chainId?: bigint): void {
+    this.assertOpen();
+    const key = block.number.toString();
+    const existing = this.canonicalPins.get(key);
+    if (existing !== undefined && (existing.block.hash.toLowerCase() !== block.hash.toLowerCase() ||
+      existing.chainId !== undefined && chainId !== undefined && existing.chainId !== chainId)) {
+      this.invalidateSession();
+      throw new LifecyclePlanningError("STATE_REORGED", "One lifecycle invocation observed incompatible canonical pins");
+    }
+    this.canonicalPins.set(key, { block: { ...block }, chainId: chainId ?? existing?.chainId });
+  }
+
+  async finalize(): Promise<void> {
+    this.assertOpen();
+    const pins = [...this.canonicalPins.values()];
+    if (pins.length === 0) return;
+    const [chainId, current] = await Promise.all([
+      pins.some((pin) => pin.chainId !== undefined) ? this.run("eth_chainId", []).then((value) => rpcQuantity(value, "chain ID")) : undefined,
+      Promise.all(pins.map((pin) => readLifecycleBlock(this, toHex(pin.block.number)))),
+    ]);
+    for (let index = 0; index < pins.length; index += 1) {
+      const pin = pins[index]!;
+      if (pin.chainId !== undefined && chainId !== pin.chainId) {
+        this.invalidateSession();
+        throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during the pinned operation");
+      }
+      if (current[index]!.hash.toLowerCase() !== pin.block.hash.toLowerCase()) {
+        this.invalidateSession();
+        throw new LifecyclePlanningError("STATE_REORGED", "Pinned launch state changed during the operation; read canonical progress again");
+      }
+    }
+    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 {
+      // Two cold reads cannot beat two direct calls after code attestation.
+      if (reads.length < 3 || 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;
+      const code = rpcHex(await this.read("eth_getCode", [to, toHex(block.number)], block, true), "Multicall3 code");
+      if (keccak256(code) !== multicall3CodeHash) throw new LifecyclePlanningError("MULTICALL_CODE_MISMATCH", "Pinned Multicall3 runtime differs from the reviewed chain4663 deployment");
+      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,7 +275,7 @@ 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.
@@ -189,7 +296,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.
@@ -207,6 +314,11 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     this.reads.clear();
     this.chainId = undefined;
     this.limitObservations.clear();
+    this.gasPrice = undefined;
+    this.immutableReads.clear();
+    this.canonicalPins.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 +333,15 @@ 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) {
+      // Refused simulations still report a changed canonical source, not a
+      // misleading economic refusal derived from an orphaned observation.
+      await client.finalize();
+      throw failure;
+    }
+    await client.finalize();
     success = true;
     return result;
   } finally { client.close(success); }
@@ -285,6 +405,28 @@ export function readLifecycleChainId(client: LifecycleRpcClient): Promise<bigint
     ? 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>;
+}
+
+/** 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 +467,11 @@ 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) {
+    client.deferCanonicalCheck(block, expectedChainId);
+    return;
+  }
   const [chainId, current] = await Promise.all([
     expectedChainId === undefined ? undefined : lifecycleRpc(client, "eth_chainId"),
     readLifecycleBlock(client, toHex(block.number)),
@@ -339,13 +485,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 +530,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;
 }