@black-market/sdk 0.15.0 → 0.16.0

package/src/lifecycle/raeto-abi.ts

@@ -0,0 +1,223 @@
+// Generated from the verified RaetoFeeCollectorV1 ABI by scripts/generate-raeto-presets.mjs.
+// Provenance: test/fixtures/raeto-registry-readback.json, abiProvenance.
+export const raetoFeeCollectorV1Abi = [
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "launchToken",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "poolId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "asset",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint256",
+        "name": "grossQuoteCollected",
+        "type": "uint256"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint256",
+        "name": "raetoAmount",
+        "type": "uint256"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint256",
+        "name": "forwardedQuote",
+        "type": "uint256"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint16",
+        "name": "shareBps",
+        "type": "uint16"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint256",
+        "name": "owedAfter",
+        "type": "uint256"
+      }
+    ],
+    "name": "RaetoFeesBooked",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "launchToken",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "poolId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "payout",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "address",
+        "name": "asset",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint256",
+        "name": "amount",
+        "type": "uint256"
+      }
+    ],
+    "name": "RaetoFeesClaimed",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "launchToken",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "poolId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "operator",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint16",
+        "name": "previousShareBps",
+        "type": "uint16"
+      },
+      {
+        "indexed": false,
+        "internalType": "uint16",
+        "name": "newShareBps",
+        "type": "uint16"
+      }
+    ],
+    "name": "RaetoShareUpdated",
+    "type": "event"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "asset",
+        "type": "address"
+      }
+    ],
+    "name": "claimRaeto",
+    "outputs": [
+      {
+        "internalType": "uint256",
+        "name": "amount",
+        "type": "uint256"
+      }
+    ],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "launchToken",
+    "outputs": [
+      {
+        "internalType": "address",
+        "name": "",
+        "type": "address"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "asset",
+        "type": "address"
+      }
+    ],
+    "name": "owed",
+    "outputs": [
+      {
+        "internalType": "uint256",
+        "name": "amount",
+        "type": "uint256"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "quoteAsset",
+    "outputs": [
+      {
+        "internalType": "address",
+        "name": "",
+        "type": "address"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "uint16",
+        "name": "newShareBps",
+        "type": "uint16"
+      }
+    ],
+    "name": "setShareBps",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "shareBps",
+    "outputs": [
+      {
+        "internalType": "uint16",
+        "name": "",
+        "type": "uint16"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  }
+] as const;

package/src/lifecycle/raeto.ts

@@ -0,0 +1,61 @@
+import { encodeAbiParameters, type Hex } from "viem";
+import { decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
+import type { LaunchPlanV1 } from "./schema.js";
+import { LifecyclePlanningError } from "./types.js";
+
+export const RAETO_FIXED_PROFILE_ID: Hex = "0x9161833b162e7ca8160b11c64aedb307561e19a9136fd32f99cd797aab6da3ca";
+export const RAETO_DYNAMIC_PROFILE_ID: Hex = "0x08387d00ee4f75f860810cc8fb434087328592c2f39ea3321109e589039f80e1";
+export const RAETO_FIXED_ADAPTER_ID: Hex = "0x911d7ecefe56489d329235e3484829717dc00400d4181902f0f2de45f9338615";
+export const RAETO_DYNAMIC_ADAPTER_ID: Hex = "0x8ab9c8c9b8fd4c8bbf12b780d9474463fa0fa52e3b450f0d5f68fd067dc1674d";
+export const RAETO_PAYOUT_REGISTRY_ADDRESS = "0xBEC2C0e91612090F82df6743F31CDF18B4386b50";
+/** The deployed collectors accept this menu, not the wider range in later source. */
+export const RAETO_SHARE_BPS_OPTIONS = Object.freeze([500, 1000, 2500, 5000, 7500] as const);
+export const RAETO_QUOTE_ASSETS = Object.freeze([
+  "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
+  "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+] as const);
+export type RaetoLaunchConfigV1 = { shareBps: number };
+
+export function isRaetoProfile(profileId: Hex): boolean {
+  const id = profileId.toLowerCase();
+  return id === RAETO_FIXED_PROFILE_ID || id === RAETO_DYNAMIC_PROFILE_ID;
+}
+
+export function validateRaetoLaunchConfig(config: RaetoLaunchConfigV1): void {
+  if (!RAETO_SHARE_BPS_OPTIONS.some((share) => share === config.shareBps)) {
+    throw new LifecyclePlanningError("INVALID_RAETO_CONFIG", "Raeto shareBps must be one of 500, 1000, 2500, 5000 or 7500");
+  }
+}
+
+/** Exactly abi.encode(RaetoLaunchConfigV1): one static uint16 word. */
+export function encodeRaetoLaunchTail(config: RaetoLaunchConfigV1): Hex {
+  validateRaetoLaunchConfig(config);
+  return encodeAbiParameters([{ type: "uint16" }], [config.shareBps]);
+}
+
+export function decodeRaetoLaunchTail(encoded: Hex): RaetoLaunchConfigV1 {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(encoded)) throw new LifecyclePlanningError("INVALID_RAETO_CONFIG", "Raeto tail must be exactly one ABI word");
+  const share = BigInt(encoded);
+  if (share > 65535n) throw new LifecyclePlanningError("INVALID_RAETO_CONFIG", "Raeto tail must contain a canonical uint16");
+  const config = { shareBps: Number(share) };
+  validateRaetoLaunchConfig(config);
+  return config;
+}
+
+/** Raeto uses the normal lifecycle creator/funding route, not the UFG proxy. */
+export function validateRaetoLaunchPlan(plan: LaunchPlanV1): void {
+  try {
+    if (plan.markets.length === 0) throw new Error("A Raeto plan requires at least one market");
+    for (const market of plan.markets) {
+      if (!isRaetoProfile(market.profileId) || market.configVersion !== 6 ||
+        !RAETO_QUOTE_ASSETS.some((quote) => quote.toLowerCase() === market.quoteAsset.toLowerCase()) ||
+        market.adapterId.toLowerCase() !== (market.profileId.toLowerCase() === RAETO_FIXED_PROFILE_ID ? RAETO_FIXED_ADAPTER_ID : RAETO_DYNAMIC_ADAPTER_ID)) {
+        throw new Error("Every Raeto market requires its Raeto config6 profile/adapter and a WETH or USDG quote");
+      }
+      const config = decodePoolBoundV4LifecycleMarketConfig(market.config, 6);
+      if (config.profileId.toLowerCase() !== market.profileId.toLowerCase()) throw new Error("Raeto config profile differs from its market");
+    }
+  } catch (error) {
+    throw new LifecyclePlanningError("INVALID_RAETO_PLAN", error instanceof Error ? error.message : "Invalid Raeto launch plan");
+  }
+}

package/src/lifecycle/rpc.ts

@@ -22,8 +22,8 @@ type IndependentRead = { params: readonly unknown[]; resolve: (value: unknown) =
 const lifecycleReadConcurrency = 8;
 const diagnosticRpcMethods: Record<string, true> = {
   eth_chainId: true, eth_getBlockByNumber: true, eth_getBlockByHash: true, eth_getCode: true,
-  eth_getBalance: true, eth_call: true, eth_estimateGas: true, eth_gasPrice: true,
-  eth_simulateV1: true, eth_getTransactionCount: true, eth_getTransactionReceipt: true, eth_getTransactionByHash: true,
+  eth_getBalance: true, eth_call: true, eth_gasPrice: true,
+  eth_getTransactionReceipt: true, eth_getTransactionByHash: true,
 };
 
 type SessionReadGroup = {
@@ -70,7 +70,7 @@ class SessionLifecycleCache implements LifecycleSessionCache {
   }
 }
 
-/** Opt-in pinned read reuse; client-bound identity/capability facts are separate. */
+/** Opt-in pinned read reuse; client-bound identity/deployment facts are separate. */
 export function createLifecycleSessionCache(): LifecycleSessionCache {
   return new SessionLifecycleCache();
 }
@@ -410,7 +410,7 @@ 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. */
+/** Successful deployment 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;
@@ -524,9 +524,7 @@ export async function readLifecycleProfileTopology(client: LifecycleRpcClient, r
   if (topology.hookTopology !== 0 && topology.hookTopology !== 1 && topology.hookTopology !== 2) throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Registry returned an unsupported hook topology");
   return { ...topology, hookTopology: topology.hookTopology };
 }
-export const nitroArbSys = "0x0000000000000000000000000000000000000064";
 export const nitroGasInfo = "0x000000000000000000000000000000000000006c";
-export const nitroArbSysAbi = parseAbi(["function arbOSVersion() view returns (uint256)"]);
 export const nitroGasInfoAbi = parseAbi([
   // Transaction ceilings are release preset metadata, not guard-only getter reads.
   "function getPricesInWei() view returns (uint256,uint256,uint256,uint256,uint256,uint256)",
@@ -534,7 +532,7 @@ export const nitroGasInfoAbi = parseAbi([
 export type LifecycleNitroPrices = readonly [bigint, bigint, bigint, bigint, bigint, bigint];
 const maxUint64 = (1n << 64n) - 1n;
 
-/** Seeded by the planning aggregate; standalone simulation batches this with limits. */
+/** Seeded by the explicitly pinned planning aggregate. */
 export function readNitroPrices(client: LifecycleRpcClient, block: LifecycleBlock): Promise<LifecycleNitroPrices> {
   return readLifecycleContract(client, nitroGasInfo, nitroGasInfoAbi, "getPricesInWei", [], block, undefined, true, true);
 }
@@ -551,12 +549,6 @@ export function nitroPosterGasBound(transaction: Pick<LifecycleTransaction, "dat
   return { posterGas: 2n * ((feeBound + prices[5] - 1n) / prices[5]), feeBound };
 }
 
-async function readNitroScalar(context: LifecycleLimitContext, to: Address, abi: Abi, functionName: string): Promise<bigint> {
-  const data = encodeFunctionData({ abi, 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;
-}
 
 export type LifecycleLimitObservation = {
   limits: ResolvedLifecycleLimits;
@@ -591,7 +583,7 @@ async function resolveLifecycleLimitsFresh(context: LifecycleLimitContext, sourc
   };
   const headroomBps = configuration.headroomBps === undefined ? 1500 : configuration.headroomBps;
   if (!Number.isSafeInteger(headroomBps) || headroomBps < 0 || headroomBps > 10000) throw new LifecyclePlanningError("INVALID_LIMITS", "Headroom must be between zero and 10000 basis points");
-  for (const limit of [context.block.gasLimit, configuration.chainGasLimit, configuration.rpcGasLimit, configuration.accountGasLimit, configuration.maxSimulationGas]) {
+  for (const limit of [context.block.gasLimit, configuration.chainGasLimit, configuration.rpcGasLimit, configuration.accountGasLimit]) {
     if (limit !== undefined && (typeof limit !== "bigint" || limit <= 0n || limit > maxUint64)) throw new LifecyclePlanningError("INVALID_LIMITS", "Gas caps must be positive exact uint64 bigint values");
   }
   if (configuration.maxCalldataBytes !== undefined && (!Number.isSafeInteger(configuration.maxCalldataBytes) || configuration.maxCalldataBytes <= 0)) throw new LifecyclePlanningError("INVALID_LIMITS", "Calldata cap must be a positive byte count");
@@ -604,37 +596,23 @@ async function resolveLifecycleLimitsFresh(context: LifecycleLimitContext, sourc
     throw new LifecyclePlanningError("LIMIT_CONTEXT_MISMATCH", "Supplied execution policy provenance differs from the canonical chain/account/core/block context");
   }
   const protocol = context.chainId === 4663n ? "nitro" : "evm";
-  const maxSimulationGas = configuration.maxSimulationGas;
-  let arbOSVersion: bigint | undefined;
-  if (protocol === "nitro") {
-    try {
-      const rawVersion = await readNitroScalar(context, nitroArbSys, nitroArbSysAbi, "arbOSVersion");
-      // ArbSys alone adds 55 to the logical Nitro ArbOS version.
-      if (typeof rawVersion !== "bigint" || rawVersion < 105n) throw new Error("ArbOS version 50 or newer is required (ArbSys raw version >= 105)");
-      arbOSVersion = rawVersion - 55n;
-    } catch (failure) {
-      if (failure instanceof Error && failure.name === "AbortError") throw failure;
-      throw new LifecyclePlanningError("NITRO_LIMITS_UNAVAILABLE", `Pinned Nitro version could not be established: ${lifecycleFailureReason(failure)}`);
-    }
-    if (configuration.estimateDataFee !== undefined) throw new LifecyclePlanningError("INVALID_LIMITS", "Nitro poster fees are already included in gas; an external data-fee estimator would double-charge them");
-  }
+  if (protocol === "nitro" && configuration.estimateDataFee !== undefined) throw new LifecyclePlanningError("INVALID_LIMITS", "Nitro poster fees are already included in gas; an external data-fee estimator would double-charge them");
   const envelopeCaps = [configuration.chainGasLimit, configuration.rpcGasLimit, configuration.accountGasLimit].filter((limit): limit is bigint => limit !== undefined);
   if (protocol === "evm") envelopeCaps.push(context.block.gasLimit);
   const transactionGasCeiling = envelopeCaps.length === 0 ? undefined : envelopeCaps.reduce((minimum, limit) => limit < minimum ? limit : minimum);
   const executionGasCeiling = protocol === "nitro" ? ROBINHOOD_NATIVE_TRANSACTION_GAS_LIMIT : transactionGasCeiling ?? context.block.gasLimit;
   const unknownExecutionConstraints = [
-    ...(protocol === "evm" && configuration.chainGasLimit === undefined ? ["Independent chain per-transaction execution cap is unknown; proof is bounded by the pinned header and validated backend"] : []),
+    ...(protocol === "evm" && configuration.chainGasLimit === undefined ? ["Independent chain per-transaction cap is unknown; the budget is bounded by the pinned header"] : []),
     ...(configuration.rpcGasLimit === undefined ? ["RPC transaction gas-envelope cap is unknown"] : []),
     ...(configuration.accountGasLimit === undefined ? ["Current account/wallet transaction gas-envelope cap is unknown"] : []),
     ...(configuration.maxCalldataBytes === undefined ? ["Applicable chain/account/RPC calldata byte cap is unknown"] : []),
-    ...(maxSimulationGas === undefined ? ["RPC aggregate simulation gas cap is unknown"] : []),
   ];
   assertCurrent();
   return {
     configuration, assertCurrent,
     limits: Object.freeze({
-      protocol, executionGasCeiling, transactionGasCeiling, arbOSVersion, headroomBps,
-      maxCalldataBytes: configuration.maxCalldataBytes, maxSimulationGas,
+      protocol, executionGasCeiling, transactionGasCeiling, headroomBps,
+      maxCalldataBytes: configuration.maxCalldataBytes,
       blockGasLimit: context.block.gasLimit, chainGasLimit: configuration.chainGasLimit,
       rpcGasLimit: configuration.rpcGasLimit, accountGasLimit: configuration.accountGasLimit,
       unknownExecutionConstraints: Object.freeze(unknownExecutionConstraints),

package/src/lifecycle/snapshot.ts

@@ -5,7 +5,7 @@ import { getKnownLifecycleDeployment, type LifecycleDeploymentPreset } from "./p
 import { lifecycleTokenPredictionAbi } from "./progress.js";
 import { launchLensAbi, observeLifecycleLens, type LifecycleLensSnapshot } from "./lens.js";
 import { hashLaunchIdentity, LifecycleFundingKind, type LaunchPlanV1 } from "./schema.js";
-import { attestLifecycleMulticall, lifecycleRpc, nitroArbSys, nitroArbSysAbi, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readLifecycleChainId, rpcHex, seedLifecycleRead } from "./rpc.js";
+import { attestLifecycleMulticall, lifecycleRpc, nitroGasInfo, nitroGasInfoAbi, readLifecycleBlock, readLifecycleChainId, rpcHex, seedLifecycleRead } from "./rpc.js";
 import { LifecyclePlanningError, type LifecycleBlock, type LifecycleRpcClient } from "./types.js";
 import { UFG_LAUNCH_PROXY_ADDRESS } from "./ufg-config.js";
 
@@ -36,7 +36,6 @@ export async function readLifecyclePlanningBlock(client: LifecycleRpcClient, pla
       if (escrow !== undefined) add(asset, lifecycleErc20Abi, "allowance", [account, escrow]);
     }
   }
-  add(nitroArbSys, nitroArbSysAbi, "arbOSVersion", []);
   add(nitroGasInfo, nitroGasInfoAbi, "getPricesInWei", []);
   await attestLifecycleMulticall(client, block);
   const calls = reads.map((read) => ({ target: read.to, allowFailure: true, callData: encodeFunctionData({ abi: read.abi, functionName: read.functionName, args: read.args }) }));

package/src/lifecycle/transactions.ts

@@ -3,27 +3,64 @@ import { launchLifecycleAbi } from "./abi.js";
 import { LifecycleFundingKind, LifecycleMode, type LaunchPlanV1 } from "./schema.js";
 import { LifecyclePlanningError, type BuildLaunchTransactionsOptions, type LifecycleTransaction } from "./types.js";
 import { assertLifecycleTokenAllocation } from "./allocations.js";
-import { HMM_V2_PREPARE_GAS } from "./presets.js";
-import { isHmmProfile } from "./hmm.js";
 import { ufgLaunchProxyV1Abi } from "./ufg-abi.js";
-import { UFG_LAUNCH_PROXY_ADDRESS } from "./ufg-config.js";
+import { UFG_LAUNCH_PROXY_ADDRESS, isUfgProfile } from "./ufg-config.js";
+import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig, decodeV4LifecycleMarketConfig, isPoolBoundV4ConfigVersion } from "./markets.js";
+import { isHmmProfile } from "./hmm.js";
+import { isRaetoProfile } from "./raeto.js";
+import { isAutoCompoundProfile } from "./auto-compound.js";
 import type { UfgLaunchConfig } from "./ufg-config.js";
 
-const OTHER_MARKET_PREPARE_GAS = 16_000_000n;
+// Native9,723,187 Abyss3 (0x679d…e77), fork32-position10,900,786;
+// fork V4 fixed/dynamic8-position8,804,466; UFG9,896,176; native HMM8-position14,676,638 (0x459c…5b7).
+const preparationCosts = {
+  abyss: { market: 9_800_000n, position: 70_000n },
+  v4: { market: 9_000_000n, position: 40_000n },
+  ufg: { market: 10_000_000n, position: 70_000n },
+  hmm: { market: 15_000_000n, position: 50_000n },
+  // template-gas-matrix.json: Raeto1 <=9.13M,32 <=11.23M.
+  raeto: { market: 9_300_000n, position: 70_000n },
+  // Same matrix: auto-compound1 <=8.71M,32 <=10.76M.
+  autoCompound: { market: 8_900_000n, position: 70_000n },
+} as const;
+export const LIFECYCLE_CAPACITY_PADDING_BPS = 2500;
+/** Full single-market observations include call overhead. Add conservative full
+ * calldata/hash processing (16 intrinsic gas per nonzero byte plus8 for copying). */
+export function preparationCalldataGas(data: `0x${string}`): bigint { return 24n * BigInt((data.length - 2) / 2); }
 
 export function preparationGasEstimate(plan: LaunchPlanV1, first: number, count: number): bigint {
   let gas = 0n;
-  for (let index = first; index < first + count; index += 1) gas += isHmmProfile(plan.markets[index]!.profileId) ? HMM_V2_PREPARE_GAS : OTHER_MARKET_PREPARE_GAS;
+  for (let index = first; index < first + count; index += 1) {
+    const market = plan.markets[index]!;
+    const positions = market.configVersion === 1 ? decodeAbyssLifecycleMarketConfig(market.config).positions.length
+      : isPoolBoundV4ConfigVersion(market.configVersion) ? decodePoolBoundV4LifecycleMarketConfig(market.config, market.configVersion).positions.length
+      : decodeV4LifecycleMarketConfig(market.config).positions.length;
+    const cost = market.configVersion === 1 ? preparationCosts.abyss : isHmmProfile(market.profileId) ? preparationCosts.hmm
+      : isUfgProfile(market.profileId) ? preparationCosts.ufg : isRaetoProfile(market.profileId) ? preparationCosts.raeto
+      : isAutoCompoundProfile(market.profileId) ? preparationCosts.autoCompound : preparationCosts.v4;
+    gas += cost.market + cost.position * BigInt(positions - 1);
+  }
   return gas;
 }
 
-/** Contiguous cost packing preserves committed market order and recovery progress. */
-export function packPreparationBatches(plan: LaunchPlanV1, prepared: number, computeCap: bigint): number[] {
+/** Contiguous deterministic packing with compute headroom. The caller reserves
+ * poster allocation separately from computeCap; neither resizes transaction gas. */
+export function packPreparationBatches(plan: LaunchPlanV1, prepared: number, computeCap: bigint, headroomBps = 1500): number[] {
+  const data = buildLifecycleCommand(plan, { kind: "prepare", first: prepared, count: 1 }).data;
+  return packLifecyclePreparationBatches(plan, prepared, computeCap, headroomBps, preparationCalldataGas(data));
+}
+
+/** Internal path reuses the command already encoded for poster allocation. */
+export function packLifecyclePreparationBatches(plan: LaunchPlanV1, prepared: number, computeCap: bigint, headroomBps: number, calldataGas: bigint): number[] {
+  if (!Number.isSafeInteger(headroomBps) || headroomBps < 0 || headroomBps > 10000) throw new LifecyclePlanningError("INVALID_LIMITS", "Headroom must be between zero and10000 basis points");
+  const padding = BigInt(10000 + Math.max(LIFECYCLE_CAPACITY_PADDING_BPS, headroomBps));
+  const fits = (gas: bigint) => ((gas + calldataGas) * padding + 9999n) / 10000n <= computeCap;
   const batches = prepared > 0 ? [prepared] : [];
   let count = 0, gas = 0n;
   for (let index = prepared; index < plan.markets.length; index += 1) {
     const estimate = preparationGasEstimate(plan, index, 1);
-    if (count > 0 && gas + estimate > computeCap) { batches.push(count); count = 0; gas = 0n; }
+    if (!fits(estimate)) throw new LifecyclePlanningError("PREPARATION_GAS_LIMIT", "A market exceeds the preparation gas budget. Reduce its positions before launching.");
+    if (count > 0 && !fits(gas + estimate)) { batches.push(count); count = 0; gas = 0n; }
     count += 1;
     gas += estimate;
   }
@@ -53,7 +90,7 @@ export function buildLifecycleCommand(plan: LaunchPlanV1, command: LifecycleComm
 
 /** Pure unsigned launch commands. Every command carries the complete commitment;
  * preparation splits only empty markets, never positions, buys or public opening.
- * Allowance discovery, recovery and execution proof belong to the planner. */
+ * Allowance discovery, recovery and gas-budget checks belong to the planner. */
 export function buildLifecycleCommands({ plan, mode, preparationBatches }: BuildLaunchTransactionsOptions, ufg?: LifecycleUfgRoute): LifecycleTransaction[] {
   if (mode !== "atomic" && mode !== "staged") throw new LifecyclePlanningError("EXPLICIT_MODE_REQUIRED", "Choose atomic or staged explicitly; staged is never silently substituted");
   if (plan.chainId <= 0n || plan.chainId > BigInt(Number.MAX_SAFE_INTEGER)) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Chain ID must be a positive exact JavaScript integer");