@black-market/sdk 0.13.0 → 0.14.1

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, readLifecycleImmutable, 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" }],
@@ -39,7 +40,6 @@ export async function predictLifecycleToken(options: { client: LifecycleRpcClien
   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;
   });
 }
@@ -236,7 +236,7 @@ export async function readLifecycleProfiles(options: { client: LifecycleRpcClien
     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);
@@ -302,7 +302,6 @@ export async function readLifecycleProfiles(options: { client: LifecycleRpcClien
         return { block, profiles };
       })(),
     ]);
-    if (pinnedBlock === undefined) await assertLifecycleBlock(client, block, chainId);
     return profiles;
   }));
 }
@@ -431,7 +430,6 @@ export async function readPoolBoundHookDeployment(options: { client: LifecycleRp
   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");
@@ -446,7 +444,6 @@ export async function buildPoolBoundHookDeploymentTransaction(options: { 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 } };
   });
@@ -566,6 +563,7 @@ async function readReceipts(options: ReadLaunchProgressOptions, block: Lifecycle
   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;
@@ -574,9 +572,10 @@ async function readReceipts(options: ReadLaunchProgressOptions, block: Lifecycle
     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.
+  // 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");
@@ -590,13 +589,19 @@ export async function readLaunchProgress(options: ReadLaunchProgressOptions, pin
   if (options.signal?.aborted) throw Object.assign(new Error("Lifecycle progress read cancelled"), { name: "AbortError" });
   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));
+    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" });
@@ -648,13 +653,20 @@ async function readLaunchProgressAtBlock(options: ReadLaunchProgressOptions, cli
   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;
@@ -662,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

@@ -6,6 +6,8 @@ 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;
@@ -74,7 +76,6 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
   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>>>();
@@ -172,37 +173,9 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     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();
   }
 
@@ -225,8 +198,7 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
   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) {
+      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); }
@@ -234,8 +206,7 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
         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");
+      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 };
@@ -279,7 +250,7 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     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;
@@ -309,6 +280,12 @@ 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();
@@ -316,7 +293,6 @@ class InvocationLifecycleClient implements LifecycleRpcClient {
     this.limitObservations.clear();
     this.gasPrice = undefined;
     this.immutableReads.clear();
-    this.canonicalPins.clear();
     this.independentReads.clear();
     this.finalChecks.clear();
     const listener = this.source.onDiagnostic;
@@ -336,8 +312,7 @@ export async function withLifecycleReadClient<T>(source: LifecycleRpcClient, wor
     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.
+      // Live policy is rechecked even when exact execution or a source read refuses.
       await client.finalize();
       throw failure;
     }
@@ -398,8 +373,7 @@ 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()
@@ -416,6 +390,37 @@ export function readLifecycleImmutable<T>(client: LifecycleRpcClient, key: strin
   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); }
@@ -468,10 +473,7 @@ export async function readLifecycleBlock(client: LifecycleRpcClient, tag: Hex |
   return block;
 }
 export async function assertLifecycleBlock(client: LifecycleRpcClient, block: Pick<LifecycleBlock, "number" | "hash">, expectedChainId?: bigint): Promise<void> {
-  if (client instanceof InvocationLifecycleClient) {
-    client.deferCanonicalCheck(block, expectedChainId);
-    return;
-  }
+  if (client instanceof InvocationLifecycleClient) return;
   const [chainId, current] = await Promise.all([
     expectedChainId === undefined ? undefined : lifecycleRpc(client, "eth_chainId"),
     readLifecycleBlock(client, toHex(block.number)),