@black-market/sdk 0.14.1 → 0.15.1

package/src/lifecycle/gas-profile.ts

@@ -0,0 +1,186 @@
+import { toHex, type Address } from "viem";
+import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
+import { computeLifecycleOpeningBuys, hasProfiledOpeningMath } from "./opening-buys.js";
+import { hmmV2ForwardingReserve } from "./presets.js";
+import { lifecyclePinnedRpc, lifecycleSourceClient, nitroPosterGasBound, readLifecycleGasPrice, readNitroPrices, registerLifecycleFinalCheck, resolveLifecycleLimits, rpcQuantity } from "./rpc.js";
+import { LifecycleFundingKind, LifecycleRewardMode, LifecycleTokenKind, type LaunchPlanV1 } from "./schema.js";
+import { isAutoCompoundProfile } from "./auto-compound.js";
+import { buildLifecycleCommand, LIFECYCLE_CAPACITY_PADDING_BPS, preparationCalldataGas, preparationGasEstimate } from "./transactions.js";
+import { UFG_LAUNCH_PROXY_ADDRESS, isUfgProfile, ufgPlanPrincipal, type UfgLaunchConfig } from "./ufg-config.js";
+import { LifecyclePlanningError, type LifecycleBlock, type LifecycleLaunchGasBounds, type LifecycleLimitSource, type LifecycleOpeningBuyQuote, type LifecyclePlanningAssessment, type LifecycleRpcClient, type LifecycleTransaction, type PlannedLaunch } from "./types.js";
+import { isHmmProfile } from "./hmm.js";
+
+export const LIFECYCLE_GAS_PROFILE_VERSION = "robinhood-4663-capacity-v3";
+export type NextTransactionEnvelope = Readonly<{ gas: bigint; gasPrice: bigint }>;
+const ceil = (value: bigint, divisor: bigint) => (value + divisor - 1n) / divisor;
+const approval = (transaction: LifecycleTransaction) => transaction.kind === "approve" || transaction.kind === "approve-reset";
+type MarketGas = { abyss: boolean; hmm: boolean; ufgHook: boolean; positions: number };
+
+function marketGas(plan: LaunchPlanV1): MarketGas[] {
+  return plan.markets.map((market) => {
+    const abyss = market.configVersion === 1;
+    const config = abyss ? decodeAbyssLifecycleMarketConfig(market.config) : decodePoolBoundV4LifecycleMarketConfig(market.config, 6);
+    return { abyss, hmm: isHmmProfile(market.profileId), ufgHook: isUfgProfile(market.profileId), positions: config.positions.length };
+  });
+}
+
+function utf8Bytes(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length && value.charCodeAt(index + 1) >= 0xdc00 && value.charCodeAt(index + 1) <= 0xdfff) { bytes += 4; index += 1; }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+function tokenCreationGas(token: LaunchPlanV1["token"]): bigint {
+  return (token.kind === LifecycleTokenKind.ERC404 ? 2_500_000n : 0n) +
+    (token.rewardMode === LifecycleRewardMode.Staking ? 2_500_000n : token.rewardMode === LifecycleRewardMode.Dividends ? 500_000n : 0n) +
+    25_000n * BigInt(Math.ceil(utf8Bytes(token.name) / 32) + Math.ceil(utf8Bytes(token.symbol) / 32) + Math.ceil(utf8Bytes(token.metadataURI) / 32));
+}
+
+// Max observed compute: native Abyss atomic21,584,262; V4 fixed20,833,003;
+// HMM26,395,772; UFG27,941,420 (historical-receipts.json,195 transactions).
+// fork-matrix.json: Abyss activation8 positions11.08M/32 positions39.72M;
+// fork-v4-matrix.json: dynamic V4 eight positions5,906,285.
+// Native mixed HMM8/Abyss8/HMM8 activation23,883,893 (0xf05e…fe98).
+const activationCosts = {
+  call: 1_500_000n,
+  abyss: { market: 500_000n, position: 1_250_000n },
+  v4: { market: 250_000n, position: 500_000n },
+  hmm: 1_000_000n,
+  ufg: 250_000n,
+  // Fork Abyss32: 64 buys78.44M minimum versus one buy47.49M;
+  // max observed marginal is below0.5M/buy. ERC404 pairs add below0.1M/NFT.
+  buy: 500_000n,
+  nft: 100_000n,
+} as const;
+
+/** Measured-max template budgets, never gas-limit sizing or execution evidence. */
+function capacityBasis(plan: LaunchPlanV1, transaction: LifecycleTransaction, markets: readonly MarketGas[], quotes: readonly LifecycleOpeningBuyQuote[], ufgRoute: boolean): bigint {
+  const atomic = transaction.kind === "atomic";
+  let gas = atomic ? 22_000_000n + tokenCreationGas(plan.token) + (ufgRoute ? 6_500_000n : 0n)
+    : activationCosts.call + (ufgRoute ? activationCosts.ufg : 0n);
+  for (const market of markets) {
+    if (atomic) gas += (market.hmm ? 7_000_000n : market.ufgHook ? 1_000_000n : market.abyss ? 500_000n : 0n) +
+      (market.abyss ? 1_500_000n : 600_000n) * BigInt(market.positions - 1);
+    else {
+      const cost = market.abyss ? activationCosts.abyss : activationCosts.v4;
+      gas += cost.market + cost.position * BigInt(market.positions) + (market.hmm ? activationCosts.hmm : market.ufgHook ? activationCosts.ufg : 0n);
+    }
+  }
+  gas += activationCosts.buy * BigInt(quotes.length);
+  if (plan.token.kind === LifecycleTokenKind.ERC404) for (const quote of quotes) gas += activationCosts.nft * ceil(quote.tokenOut, plan.token.nftUnit);
+  return gas + 24n * BigInt((transaction.data.length - 2) / 2) + 100_000n * BigInt(plan.feeAssets.length);
+}
+
+type CapacityOptions = { plan: LaunchPlanV1; predictedToken: Address; ufg?: { config: UfgLaunchConfig }; headroomBps?: number };
+export type ProfiledLaunchCapacity = {
+  bounds: LifecycleLaunchGasBounds; initialBuys: readonly LifecycleOpeningBuyQuote[]; headroomBps: number;
+  atomic?: LifecycleTransaction; activation: LifecycleTransaction;
+};
+
+/** No quote-token allowlist: costs and exact curve math belong to the release template. */
+export function deriveLifecycleLaunchCapacity(options: CapacityOptions, openingBuys?: readonly LifecycleOpeningBuyQuote[]): ProfiledLaunchCapacity | undefined {
+  const { plan, ufg } = options;
+  if (!hasProfiledOpeningMath(plan) || (plan.creator.toLowerCase() === UFG_LAUNCH_PROXY_ADDRESS.toLowerCase()) !== (ufg !== undefined)) return undefined;
+  // Auto-compounding templates have no measured gas yet; never invent their budgets.
+  if (plan.markets.some((market) => isAutoCompoundProfile(market.profileId))) return undefined;
+  const headroomBps = options.headroomBps ?? 1500;
+  if (!Number.isSafeInteger(headroomBps) || headroomBps < 0 || headroomBps > 10000) throw new LifecyclePlanningError("INVALID_LIMITS", "Headroom must be between zero and 10000 basis points");
+  const initialBuys = openingBuys ?? computeLifecycleOpeningBuys(options);
+  const route = ufg === undefined ? undefined : { account: ufgPlanPrincipal(plan), config: ufg.config };
+  const atomic = plan.markets.length === 1 && !plan.funding.some((funding) => funding.kind === LifecycleFundingKind.Swap)
+    ? buildLifecycleCommand(plan, { kind: "atomic" }, route) : undefined;
+  const activation = buildLifecycleCommand(plan, { kind: "activate" }, route);
+  const markets = marketGas(plan), reserve = hmmV2ForwardingReserve(plan);
+  const bound = (transaction: LifecycleTransaction) => {
+    const basis = capacityBasis(plan, transaction, markets, initialBuys, ufg !== undefined);
+    const buffered = ceil(basis * BigInt(10000 + Math.max(LIFECYCLE_CAPACITY_PADDING_BPS, headroomBps)), 10000n);
+    return buffered > basis + reserve ? buffered : basis + reserve;
+  };
+  return { bounds: { ...(atomic === undefined ? {} : { atomicComputeGasUpperBound: bound(atomic) }), activationComputeGasUpperBound: bound(activation) }, initialBuys, headroomBps, atomic, activation };
+}
+
+/** Pure release-template budgets with headroom, excluding poster allocation.
+ * Missing coverage refuses planning; there is no execution fallback. */
+export function computeLifecycleLaunchGasBounds(options: CapacityOptions): LifecycleLaunchGasBounds | undefined {
+  return deriveLifecycleLaunchCapacity(options)?.bounds;
+}
+
+export type LifecycleBudgetOptions = { client: LifecycleRpcClient; planned: PlannedLaunch; limits?: LifecycleLimitSource; signal?: AbortSignal };
+
+/** Checks pinned inputs and deterministic capacity only. Never executes launch calldata. */
+export async function assessLifecycleTransactions(options: LifecycleBudgetOptions, transactions: readonly LifecycleTransaction[], block: LifecycleBlock,
+  reviewed?: NextTransactionEnvelope, openingBuys?: readonly LifecycleOpeningBuyQuote[], capacity?: ProfiledLaunchCapacity): Promise<LifecyclePlanningAssessment> {
+  const { client, planned } = options, plan = planned.plan;
+  const context = { client, account: planned.account, orchestrator: plan.orchestrator, block, chainId: planned.chainId };
+  const observed = await resolveLifecycleLimits(context, options.limits === undefined ? planned.limits : options.limits);
+  const [recommendation, balanceValue, prices] = await Promise.all([
+    readLifecycleGasPrice(client, block, planned.chainId),
+    lifecyclePinnedRpc(client, "eth_getBalance", [planned.account, toHex(block.number)], block),
+    observed.limits.protocol === "nitro" ? readNitroPrices(client, block) : undefined,
+  ]);
+  options.signal?.throwIfAborted(); observed.assertCurrent(); registerLifecycleFinalCheck(client, observed.assertCurrent);
+  const { limits } = observed, baseFee = block.baseFeePerGas ?? 0n, gasLimit = limits.executionGasCeiling;
+  const requiredGasPrice = limits.protocol === "nitro" && recommendation > baseFee ? recommendation : baseFee;
+  const gasPrice = reviewed?.gasPrice ?? (recommendation > baseFee * 2n ? recommendation : baseFee * 2n);
+  if (reviewed !== undefined && reviewed.gas !== gasLimit) throw new LifecyclePlanningError("STALE_REVIEWED_GAS", "Reviewed gas differs from the native transaction ceiling. Refresh the review before continuing.");
+  const cancelOnly = transactions.every((transaction) => transaction.kind === "cancel");
+  const currentCapacity = cancelOnly ? undefined : capacity?.headroomBps === limits.headroomBps ? capacity
+    : deriveLifecycleLaunchCapacity({ plan, predictedToken: planned.predictedToken, ufg: planned.ufg, headroomBps: limits.headroomBps }, openingBuys);
+  const immediate = transactions[0], launch = transactions.find((transaction) => !approval(transaction));
+  const poster = (transaction: LifecycleTransaction) => prices === undefined ? 0n : nitroPosterGasBound(transaction, prices).posterGas;
+  const assessment: LifecyclePlanningAssessment = { ready: true, blockNumber: block.number, blockHash: block.hash,
+    account: planned.account, chainId: planned.chainId, limits,
+    ...(currentCapacity === undefined ? {} : { gasProfile: { version: LIFECYCLE_GAS_PROFILE_VERSION, bounds: currentCapacity.bounds, initialBuys: currentCapacity.initialBuys } }) };
+  const refuse = (code: string, reason: string, failureCategory: LifecyclePlanningAssessment["failureCategory"], capacityConstraint?: LifecyclePlanningAssessment["capacityConstraint"], failedTransactionId?: string): LifecyclePlanningAssessment =>
+    ({ ...assessment, ready: false, code, reason, failureCategory, capacityConstraint, failedTransactionId });
+  if (!cancelOnly && currentCapacity === undefined) return refuse("UNKNOWN_GAS_PROFILE", "Gas budgets are unavailable for this launch profile. Use a supported profile or update the SDK.", "capacity");
+  if (!cancelOnly && currentCapacity!.bounds.activationComputeGasUpperBound + poster(currentCapacity!.activation) > gasLimit) {
+    return refuse("ACTIVATION_GAS_LIMIT", "Too many positions or pools for one activation. Reduce them to fit the native transaction ceiling.", "capacity", "activation", "activate");
+  }
+  for (const transaction of transactions) {
+    if (transaction.kind === "atomic" && (currentCapacity?.bounds.atomicComputeGasUpperBound === undefined || currentCapacity.bounds.atomicComputeGasUpperBound + poster(transaction) > gasLimit))
+      return refuse("STAGED_EXECUTION_REQUIRED", "This launch requires staged execution. Refresh the review before continuing.", "capacity", "gas-envelope", transaction.id);
+    if (transaction.kind === "prepare" && ceil((preparationGasEstimate(plan, transaction.marketStart!, transaction.marketCount!) + preparationCalldataGas(transaction.data)) * BigInt(10000 + Math.max(LIFECYCLE_CAPACITY_PADDING_BPS, limits.headroomBps)), 10000n) + poster(transaction) > gasLimit)
+      return refuse("PREPARATION_GAS_LIMIT", "This preparation batch exceeds the gas budget. Refresh the review to split it.", "capacity", "preparation", transaction.id);
+    if (limits.maxCalldataBytes !== undefined && (transaction.data.length - 2) / 2 > limits.maxCalldataBytes)
+      return refuse("CALLDATA_LIMIT", "The launch exceeds the transaction data limit. Reduce its positions or pools.", "capacity", "calldata", transaction.id);
+  }
+  if (launch !== undefined && limits.transactionGasCeiling !== undefined && gasLimit > limits.transactionGasCeiling)
+    return refuse("GAS_POLICY_LIMIT", "The configured gas limit is below the chain's native transaction ceiling.", "capacity", "gas-envelope", launch.id);
+  if (reviewed !== undefined && gasPrice < requiredGasPrice) return refuse("REVIEWED_FEE_TOO_LOW", "The reviewed gas price is below the current required fee. Refresh the review before continuing.", "semantic", undefined, immediate?.id);
+  const quotes = currentCapacity?.initialBuys ?? [];
+  if (quotes.some((quote) => quote.tokenOut < plan.buys[quote.buyIndex]!.minTokenOut))
+    return refuse("BUY_MINIMUM_NOT_MET", "An opening buy is below its minimum output. Refresh the review before continuing.", "semantic");
+  if (block.timestamp > plan.deadline && !cancelOnly) return refuse("PLAN_EXPIRED", "The launch deadline has passed. Cancel an unfinished launch to recover its funds.", "semantic");
+  const inputs = new Map<string, { required: bigint; balance: bigint }>();
+  for (const prerequisite of planned.prerequisites) {
+    if (prerequisite.allowance === undefined) continue;
+    const key = prerequisite.funding.inputAsset.toLowerCase(), total = inputs.get(key) ?? { required: 0n, balance: prerequisite.inputBalance };
+    total.required += prerequisite.requiredInput; inputs.set(key, total);
+  }
+  if ([...inputs.values()].some((input) => input.required > input.balance)) return refuse("INSUFFICIENT_FUNDING_BALANCE", "There are not enough tokens to fund this launch. Add funds or reduce the purchase.", "affordability");
+  const balance = rpcQuantity(balanceValue, "creator native balance");
+  if (gasPrice >= 1n << 256n || launch !== undefined && launch.value + gasLimit * gasPrice >= 1n << 256n) throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Transaction value and native-ceiling fee must fit uint256");
+  if (launch !== undefined && launch.value + gasLimit * gasPrice > balance) return refuse("INSUFFICIENT_NATIVE_BALANCE", "There is not enough native currency for the launch amount and gas budget. Add funds or reduce the purchase.", "affordability", undefined, launch.id);
+  if (immediate !== undefined && !approval(immediate)) {
+    const source = lifecycleSourceClient(client);
+    const dataFee = limits.protocol === "nitro" ? 0n : observed.configuration.estimateDataFee === undefined ? undefined
+      : await observed.configuration.estimateDataFee({ ...immediate, gas: gasLimit, gasPrice }, source === client ? context : { ...context, client: source });
+    if (dataFee !== undefined && (typeof dataFee !== "bigint" || dataFee < 0n || dataFee >= 1n << 256n)) throw new LifecyclePlanningError("INVALID_DATA_FEE", "Data-fee estimate must be a nonnegative uint256 amount");
+    const executionFee = gasLimit * gasPrice, required = immediate.value + executionFee + (dataFee ?? 0n);
+    if (required >= 1n << 256n) throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Transaction value and gas/data fee budget must fit uint256");
+    if (required > balance) return refuse("INSUFFICIENT_NATIVE_BALANCE", "There is not enough native currency for the launch amount and gas budget. Add funds or reduce the purchase.", "affordability", undefined, immediate.id);
+    const posterGas = prices === undefined ? undefined : poster(immediate);
+    assessment.estimate = { gasLimit, gasPrice, executionFee, dataFee, totalFee: dataFee === undefined ? undefined : executionFee + dataFee,
+      posterGas, posterFee: posterGas === undefined ? undefined : posterGas * gasPrice, dataFeeIncludedInGas: limits.protocol === "nitro",
+      feeConfidence: dataFee === undefined ? "native-ceiling-only" : "native-ceiling-and-data" };
+  }
+  options.signal?.throwIfAborted(); observed.assertCurrent();
+  return assessment;
+}

package/src/lifecycle/index.ts

@@ -1,19 +1,21 @@
-/** Versioned construction metadata and live launch execution calibration. */
+/** Versioned construction metadata, exact local curve math and launch budgets. */
 export * from "./schema.js";
 export * from "./types.js";
 export * from "./abi.js";
 export * from "./markets.js";
 export * from "./hmm.js";
 export * from "./ufg.js";
+export * from "./auto-compound.js";
 export { ABYSS_LIFECYCLE_CONFIG_SCHEMA, readLifecycleTokenAtBlock, readLifecycleHeadProgress, predictLifecycleToken,
   validateV4LifecycleOracle, readLifecycleProfiles, readPoolBoundHookDeployment,
   buildPoolBoundHookDeploymentTransaction, validateLifecycleMarketIdentity, readLaunchProgress } from "./progress.js";
-export * from "./fork.js";
 export * from "./authors.js";
 export * from "./presets.js";
-export * from "./transactions.js";
+export { preparationGasEstimate, packPreparationBatches, buildLaunchTransactions, LIFECYCLE_CAPACITY_PADDING_BPS } from "./transactions.js";
 export { createLifecycleSessionCache } from "./rpc.js";
 export { launchLensAbi } from "./lens.js";
 export { hookSaltMinerAbi } from "./mining.js";
-export { planLaunch, simulateLaunchPlan, buildNextTransaction, prepareAndPlanLifecycleLaunch } from "./planner.js";
+export { planLaunch, buildNextTransaction, prepareAndPlanLifecycleLaunch } from "./planner.js";
+export { computeLifecycleOpeningBuys } from "./opening-buys.js";
+export { computeLifecycleLaunchGasBounds } from "./gas-profile.js";
 export { assertLaunchTopologyCoverage, getTickAtSqrtRatio, type LaunchTopologyCoverageInput, type LaunchTopologyPosition } from "../launch.js";

package/src/lifecycle/markets.ts

@@ -3,6 +3,7 @@ import type { MarketConfigV1 } from "./schema.js";
 import { LifecyclePlanningError, type LifecycleProfile, type PoolBoundHookSaltProgress } from "./types.js";
 import { decodeHmmLaunchTail, encodeHmmLaunchTail, isHmmProfile, type HmmLaunchConfig } from "./hmm.js";
 import { decodeUfgLaunchConfig, encodeUfgLaunchConfig, isUfgProfile, type UfgLaunchConfig } from "./ufg-config.js";
+import { decodeAutoCompoundTail, encodeAutoCompoundTail, isAutoCompoundProfile, validateAutoCompoundConfig, type AutoCompoundConfigV1 } from "./auto-compound.js";
 
 export type V4LifecyclePositionConfig = {
   tickLower: number; tickUpper: number; liquidity: bigint; salt: Hex; maxTokenAmount: bigint;
@@ -46,6 +47,7 @@ export type V4PoolBoundLifecycleMarketConfigV6 = Omit<V4LifecycleMarketConfig, "
   version: 6; minimumHookFeePips: number; feeSensitivityPipsSecondsPerTick: number; hookSalt: Hex;
   hmmLaunchConfig?: HmmLaunchConfig;
   ufgLaunchConfig?: UfgLaunchConfig;
+  autoCompoundConfig?: AutoCompoundConfigV1;
 };
 export type V4PoolBoundLifecycleMarketConfig = V4PoolBoundLifecycleMarketConfigV5 | V4PoolBoundLifecycleMarketConfigV6;
 export const V4_LIFECYCLE_CONFIG_SCHEMA = keccak256(stringToHex("(uint16,uint24,int24,uint160,uint24,uint8,uint8,address,bool,bytes32,bytes32,bytes32,address,uint16,(int24,int24,uint128,bytes32,uint256)[])"));
@@ -92,9 +94,22 @@ function assertV1HookFeeShape(config: object): void {
   }
 }
 
+function validateAutoCompoundMarket(config: V4LifecycleMarketConfig | V4PoolBoundLifecycleMarketConfig): asserts config is V4PoolBoundLifecycleMarketConfigV6 & { autoCompoundConfig: AutoCompoundConfigV1 } {
+  if (config.version !== 6 || config.autoCompoundConfig === undefined) throw new LifecyclePlanningError("INVALID_AUTO_COMPOUND_CONFIG", "Auto-compounding profiles require config6 and an explicit autoCompoundConfig");
+  if (config.hmmLaunchConfig !== undefined || config.ufgLaunchConfig !== undefined) throw new LifecyclePlanningError("INVALID_AUTO_COMPOUND_CONFIG", "Auto-compounding profiles cannot carry HMM or UFG tails");
+  if (config.lpFeePips !== 0) throw new LifecyclePlanningError("INVALID_HOOK_FEES", "Auto-compounding profiles require zero LP fee");
+  if (config.developerFeeBps !== 0) throw new LifecyclePlanningError("DEVELOPER_FEE_CEILING", "Auto-compounding profiles require zero developer fee");
+  validateAutoCompoundConfig(config.autoCompoundConfig);
+}
+
 /** Auxiliary launch profiles require their typed tail and append it automatically. */
 export function encodePoolBoundV4LifecycleMarketConfig(config: V4PoolBoundLifecycleMarketConfig): Hex {
   const prefix = encodePoolBoundV4Prefix(config);
+  if (isAutoCompoundProfile(config.profileId)) {
+    validateAutoCompoundMarket(config);
+    return concatHex([prefix, encodeAutoCompoundTail(config.autoCompoundConfig)]);
+  }
+  if (config.version === 6 && config.autoCompoundConfig !== undefined) throw new LifecyclePlanningError("INVALID_AUTO_COMPOUND_CONFIG", "An auto-compounding tail requires an auto-compounding profile");
   if (isUfgProfile(config.profileId)) {
     if (config.version !== 6 || config.ufgLaunchConfig === undefined) throw new LifecyclePlanningError("INVALID_UFG_CONFIG", "UFG profiles require config6 and an explicit ufgLaunchConfig");
     if (config.hmmLaunchConfig !== undefined) throw new LifecyclePlanningError("INVALID_UFG_CONFIG", "UFG profiles cannot carry an HMM tail");
@@ -130,6 +145,10 @@ export function decodePoolBoundV4LifecycleMarketConfig(encoded: Hex, expectedVer
   const config = version === 5
     ? decodeAbiParameters([{ type: "tuple", components: poolBoundV4LifecycleMarketComponentsV5 }], encoded)[0] as V4PoolBoundLifecycleMarketConfigV5
     : decodeAbiParameters([{ type: "tuple", components: poolBoundV4LifecycleMarketComponentsV6 }], encoded)[0] as V4PoolBoundLifecycleMarketConfigV6;
+  if (isAutoCompoundProfile(config.profileId)) {
+    if (config.version !== 6) throw new LifecyclePlanningError("INVALID_AUTO_COMPOUND_CONFIG", "Auto-compounding profiles require config6");
+    config.autoCompoundConfig = decodeAutoCompoundTail(`0x${encoded.slice(encodePoolBoundV4Prefix(config).length)}`);
+  }
   if (isHmmProfile(config.profileId)) {
     if (config.version !== 6) throw new LifecyclePlanningError("INVALID_HMM_CONFIG", "HMM profiles require config6");
     const prefixLength = encodePoolBoundV4Prefix(config).length;
@@ -160,6 +179,7 @@ export function validateV4LifecycleMarket(options: {
   if (config.version !== 4 && !isPoolBoundV4ConfigVersion(config.version)) throw new LifecyclePlanningError("UNSUPPORTED_CONFIG_VERSION", "Reviewed V4 config version must be 4, 5 or 6");
   if (config.version === 6) validatePoolBoundHookFees(config);
   else if (config.version === 5) assertV1HookFeeShape(config);
+  if (isAutoCompoundProfile(config.profileId)) validateAutoCompoundMarket(config);
   const { envelope, developerTerms: terms, protocolMaximumDeveloperFeeBps: protocolCeiling } = profile;
   if (envelope === undefined || terms === undefined || protocolCeiling === undefined || !terms.enabled ||
     profile.topology.hookTopology !== (config.version === 4 ? 1 : 2) || market.configVersion !== config.version ||
@@ -258,9 +278,11 @@ export function hashPoolBoundV4MarketCommitment(options: { chainId: bigint; core
   if (!isPoolBoundV4ConfigVersion(market.configVersion)) throw new LifecyclePlanningError("INVALID_BOUND_MARKET", "Pool-bound V4 market requires explicit config version 5 or 6");
   const config = decodePoolBoundV4LifecycleMarketConfig(market.config, market.configVersion);
   if (config.profileId.toLowerCase() !== market.profileId.toLowerCase()) throw new LifecyclePlanningError("INVALID_BOUND_MARKET", "Config profile differs from the committed market profile");
-  // Collector factories commit only the V6 prefix, not auxiliary launch tails.
-  // The full plan commitment separately binds every byte of those tails.
-  const configHash = keccak256(encodePoolBoundV4Prefix({ ...config, hookSalt: zeroHash }));
+  // Auto-compounding binds its tail into constructor economics; older factories
+  // bind only the prefix. Every full plan commitment also binds every tail byte.
+  const normalized = { ...config, hookSalt: zeroHash };
+  const configHash = keccak256(isAutoCompoundProfile(config.profileId)
+    ? encodePoolBoundV4LifecycleMarketConfig(normalized) : encodePoolBoundV4Prefix(normalized));
   return keccak256(encodeAbiParameters([
     { type: "bytes32" }, { type: "uint256" }, { type: "address" }, { type: "address" }, { type: "address" },
     { type: "bytes32" }, { type: "bytes32" }, { type: "address" }, { type: "uint256" }, { type: "uint32" }, { type: "bytes32" },

package/src/lifecycle/opening-buys.ts

@@ -0,0 +1,157 @@
+import type { Address } from "viem";
+import { ABYSS_FEE_TIERS } from "../abyss.js";
+import { getSqrtRatioAtTick, getTickAtSqrtRatio } from "../launch.js";
+import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
+import { getKnownLifecycleProfile, KnownLifecycleProfile } from "./presets.js";
+import type { LaunchPlanV1 } from "./schema.js";
+import { LifecyclePlanningError, type LifecycleOpeningBuyQuote } from "./types.js";
+
+// Independent integer model of the reviewed openings. Mathematical rounding and
+// uint256 overflow branches match Uniswap v4 SqrtPriceMath/SwapMath (MIT) and
+// the corresponding Abyss libraries. Bitmap word boundaries cannot be skipped:
+// each step rounds input/fees up and output down, in the pool's favor.
+const Q96 = 1n << 96n;
+const PIPS = 1_000_000n;
+const MAX_UINT256 = (1n << 256n) - 1n;
+const MIN_PRICE = 4_295_128_739n;
+const MAX_PRICE = 1_461_446_703_485_210_103_287_273_052_203_988_822_378_723_970_342n;
+const ceil = (numerator: bigint, denominator: bigint): bigint => (numerator + denominator - 1n) / denominator;
+
+type OpeningState = {
+  price: bigint; tick: number; liquidity: bigint; spacing: number;
+  lpFee: bigint; hookFee: bigint;
+  liquidityNet: Map<number, bigint>; ticks: number[];
+};
+
+/** Only the exact release-owned schemas/hooks have profiled opening behavior. */
+export function hasProfiledOpeningMath(plan: LaunchPlanV1): boolean {
+  return plan.markets.every((market) => {
+    const preset = getKnownLifecycleProfile({ chainId: plan.chainId, orchestrator: plan.orchestrator, profileId: market.profileId });
+    return preset?.supported === true && preset.profile.topology.configVersion === market.configVersion &&
+      preset.profile.registration.adapterId.toLowerCase() === market.adapterId.toLowerCase();
+  });
+}
+
+function openingState(plan: LaunchPlanV1, marketIndex: number): OpeningState {
+  const market = plan.markets[marketIndex];
+  if (market === undefined) throw new LifecyclePlanningError("INVALID_BUY", "Opening buy market index is outside the plan");
+  const preset = getKnownLifecycleProfile({ chainId: plan.chainId, orchestrator: plan.orchestrator, profileId: market.profileId });
+  if (preset?.supported !== true || preset.profile.topology.configVersion !== market.configVersion ||
+    preset.profile.registration.adapterId.toLowerCase() !== market.adapterId.toLowerCase()) throw new LifecyclePlanningError("OPENING_BUY_NOT_PROFILED", "Opening buy math requires the exact release-owned profile and schema");
+  let price: bigint, spacing: number, lpFee: bigint, hookFee = 0n;
+  let positions: readonly { tickLower: number; tickUpper: number; liquidity: bigint }[];
+  if (market.configVersion === 1) {
+    const config = decodeAbyssLifecycleMarketConfig(market.config);
+    const tier = ABYSS_FEE_TIERS.find((candidate) => candidate.feePips === config.fee);
+    if (tier === undefined || preset.key !== `abyss-${config.profile}`) throw new LifecyclePlanningError("INVALID_MARKET", "Abyss opening must use its committed profile and canonical fee tier");
+    price = config.openingSqrtPriceX96; spacing = tier.tickSpacing; lpFee = BigInt(config.fee); positions = config.positions;
+  } else {
+    // All current release-owned V4 offerings use config6. Dynamic first buys
+    // share the opening block's minimum fee; HMM strategy work starts onOpened,
+    // after the ordered initial buys, never during this unopened curve.
+    const config = decodePoolBoundV4LifecycleMarketConfig(market.config, 6);
+    if (config.profileId.toLowerCase() !== market.profileId.toLowerCase()) throw new LifecyclePlanningError("INVALID_MARKET", "V4 opening config differs from the selected profile");
+    price = config.sqrtPriceX96; spacing = config.tickSpacing; lpFee = BigInt(config.lpFeePips); positions = config.positions;
+    const dynamic = preset.key === KnownLifecycleProfile.V4DynamicFeePool || preset.key === KnownLifecycleProfile.V4HmmDynamicPool || preset.key === KnownLifecycleProfile.V4UfgDynamicPool || preset.key === KnownLifecycleProfile.V4AutoCompoundDynamicPool;
+    hookFee = BigInt(dynamic ? config.minimumHookFeePips! : config.hookFeePips);
+  }
+  const tick = getTickAtSqrtRatio(price), liquidityNet = new Map<number, bigint>();
+  let liquidity = 0n;
+  for (const position of positions) {
+    liquidityNet.set(position.tickLower, (liquidityNet.get(position.tickLower) ?? 0n) + position.liquidity);
+    liquidityNet.set(position.tickUpper, (liquidityNet.get(position.tickUpper) ?? 0n) - position.liquidity);
+    if (position.tickLower <= tick && tick < position.tickUpper) liquidity += position.liquidity;
+  }
+  return { price, tick, liquidity, spacing, lpFee, hookFee, liquidityNet, ticks: [...liquidityNet.keys()].sort((a, b) => a - b) };
+}
+
+function lowerBound(ticks: readonly number[], value: number): number {
+  let left = 0, right = ticks.length;
+  while (left < right) {
+    const middle = (left + right) >>> 1;
+    if (ticks[middle]! < value) left = middle + 1; else right = middle;
+  }
+  return left;
+}
+
+function nextTick(state: OpeningState, zeroForOne: boolean): number {
+  const compressed = Math.floor(state.tick / state.spacing) + (zeroForOne ? 0 : 1);
+  const first = Math.floor(compressed / 256) * 256, last = first + 255;
+  const index = lowerBound(state.ticks, (compressed + (zeroForOne ? 1 : 0)) * state.spacing) - (zeroForOne ? 1 : 0);
+  const initialized = state.ticks[index];
+  const selected = initialized !== undefined && initialized >= first * state.spacing && initialized <= last * state.spacing
+    ? initialized : (zeroForOne ? first : last) * state.spacing;
+  return Math.max(-887272, Math.min(887272, selected));
+}
+
+function amount0(a: bigint, b: bigint, liquidity: bigint, roundUp: boolean): bigint {
+  if (a > b) [a, b] = [b, a];
+  const numerator = liquidity * Q96 * (b - a), denominator = a * b;
+  return roundUp ? ceil(numerator, denominator) : numerator / denominator;
+}
+function amount1(a: bigint, b: bigint, liquidity: bigint, roundUp: boolean): bigint {
+  const numerator = liquidity * (a > b ? a - b : b - a);
+  return roundUp ? ceil(numerator, Q96) : numerator / Q96;
+}
+function inputPrice(price: bigint, liquidity: bigint, input: bigint, zeroForOne: boolean): bigint {
+  if (input === 0n) return price;
+  if (!zeroForOne) return price + input * Q96 / liquidity;
+  const numerator = liquidity * Q96, product = input * price, denominator = numerator + product;
+  return product <= MAX_UINT256 && denominator <= MAX_UINT256
+    ? ceil(numerator * price, denominator)
+    : ceil(numerator, numerator / price + input);
+}
+
+function swap(state: OpeningState, amount: bigint, limit: bigint, zeroForOne: boolean): { tokenOut: bigint; quoteSpent: bigint } {
+  let remaining = amount, tokenOut = 0n;
+  while (remaining > 0n && state.price !== limit) {
+    const tick = nextTick(state, zeroForOne), boundary = getSqrtRatioAtTick(tick), before = state.price;
+    const target = zeroForOne ? boundary < limit ? limit : boundary : boundary > limit ? limit : boundary;
+    const available = remaining * (PIPS - state.lpFee) / PIPS;
+    const required = zeroForOne ? amount0(target, before, state.liquidity, true) : amount1(before, target, state.liquidity, true);
+    let next: bigint, spent: bigint;
+    if (available >= required) {
+      next = target;
+      spent = required + (state.lpFee === PIPS ? 0n : ceil(required * state.lpFee, PIPS - state.lpFee));
+    } else {
+      next = inputPrice(before, state.liquidity, available, zeroForOne);
+      spent = remaining;
+    }
+    tokenOut += zeroForOne ? amount1(next, before, state.liquidity, false) : amount0(before, next, state.liquidity, false);
+    remaining -= spent;
+    state.price = next;
+    if (next === boundary) {
+      const net = state.liquidityNet.get(tick);
+      if (net !== undefined) state.liquidity += zeroForOne ? -net : net;
+      state.tick = zeroForOne ? tick - 1 : tick;
+    } else if (next !== before) state.tick = getTickAtSqrtRatio(next);
+  }
+  return { tokenOut, quoteSpent: amount - remaining };
+}
+
+/** Exact integer opening-curve outputs for ordered, unopened release templates.
+ * This is not a live-pool quote or execution proof. Funding, token callbacks,
+ * current registry admission and wallet execution remain separate authorities. */
+export function computeLifecycleOpeningBuys(options: { plan: LaunchPlanV1; predictedToken: Address }): LifecycleOpeningBuyQuote[] {
+  const { plan, predictedToken } = options, states = new Map<number, OpeningState>();
+  const quotes: LifecycleOpeningBuyQuote[] = [];
+  for (const [buyIndex, buy] of plan.buys.entries()) {
+    if (!Number.isSafeInteger(buy.marketIndex) || buy.marketIndex < 0 || typeof buy.quoteAmountIn !== "bigint" || buy.quoteAmountIn <= 0n || buy.quoteAmountIn > MAX_UINT256 >> 1n) throw new LifecyclePlanningError("INVALID_BUY", "Opening buy requires a valid market and positive int256 input");
+    let state = states.get(buy.marketIndex);
+    if (state === undefined) { state = openingState(plan, buy.marketIndex); states.set(buy.marketIndex, state); }
+    const market = plan.markets[buy.marketIndex]!, zeroForOne = BigInt(market.quoteAsset) < BigInt(predictedToken);
+    if (typeof buy.sqrtPriceLimitX96 !== "bigint") throw new LifecyclePlanningError("INVALID_BUY_PRICE_LIMIT", "Opening buy price limit must be an exact bigint");
+    // Only the V4 lifecycle adapter resolves this sentinel. Abyss calls its
+    // pool directly, so zero remains invalid there. Never rewrite calldata.
+    const limit = market.configVersion !== 1 && buy.sqrtPriceLimitX96 === 0n
+      ? zeroForOne ? MIN_PRICE + 1n : MAX_PRICE - 1n : buy.sqrtPriceLimitX96;
+    if (market.quoteAsset.toLowerCase() === predictedToken.toLowerCase() || limit <= MIN_PRICE || limit >= MAX_PRICE ||
+      (zeroForOne ? limit >= state.price : limit <= state.price)) throw new LifecyclePlanningError("INVALID_BUY_PRICE_LIMIT", "Opening buy price limit must be strictly beyond the current curve price in the input direction");
+    const hookCharge = buy.quoteAmountIn * state.hookFee / PIPS;
+    const adjusted = buy.quoteAmountIn - hookCharge;
+    const result = swap(state, adjusted, limit, zeroForOne);
+    if (hookCharge > 0n && result.quoteSpent !== adjusted) throw new LifecyclePlanningError("INCOMPLETE_BUY_FILL", "A specified-input hook fee requires the complete adjusted input to fill");
+    quotes.push({ buyIndex, marketIndex: buy.marketIndex, quoteAmountIn: buy.quoteAmountIn, quoteSpent: result.quoteSpent + hookCharge, tokenOut: result.tokenOut, sqrtPriceAfterX96: state.price });
+  }
+  return quotes;
+}