@black-market/sdk 0.14.1 → 0.15.0

package/examples/launch-example.ts

@@ -309,15 +309,23 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
   }
   const activationTransaction = planned.transactions.find((transaction) => ["atomic", "activate"].includes(transaction.kind));
   const activationStep = planned.simulation.steps.find((step) => step.transactionId === activationTransaction?.id);
-  if (!activationStep?.success || !activationStep.returnData) throw exampleError("MISSING_ECONOMIC_OUTPUTS", "Economic review requires the admitted activation receipt and every ordered buy output");
-  const simulatedReceipt = decodeFunctionResult({ abi: sdk.launchLifecycleAbi,
-    functionName: activationTransaction.kind === "atomic" ? "launchAtomic" : "activateLaunch", data: activationStep.returnData });
-  assert.equal(simulatedReceipt.planHash.toLowerCase(), planned.planHash.toLowerCase(), "Economic receipt exact plan");
-  assert.equal(simulatedReceipt.tokenOut.length, planned.plan.buys.length, "Economic receipt ordered outputs");
-  const simulatedBuys = planned.plan.buys.map((buy, index) => {
-    const tokenOut = simulatedReceipt.tokenOut[index];
-    const quoteSpent = simulatedReceipt.quoteSpent[index];
-    assert.ok(tokenOut >= buy.minTokenOut && tokenOut > 0n && quoteSpent <= buy.quoteAmountIn, "Exact protected simulated buy");
+  let orderedOutputs, buyEvidence;
+  if (activationStep?.success && activationStep.returnData) {
+    const receipt = decodeFunctionResult({ abi: sdk.launchLifecycleAbi,
+      functionName: activationTransaction.kind === "atomic" ? "launchAtomic" : "activateLaunch", data: activationStep.returnData });
+    assert.equal(receipt.planHash.toLowerCase(), planned.planHash.toLowerCase(), "Economic receipt exact plan");
+    assert.equal(receipt.tokenOut.length, planned.plan.buys.length, "Economic receipt ordered outputs");
+    assert.equal(receipt.quoteSpent.length, planned.plan.buys.length, "Economic receipt ordered spending");
+    orderedOutputs = receipt.tokenOut.map((tokenOut, index) => ({ tokenOut, quoteSpent: receipt.quoteSpent[index] }));
+    buyEvidence = "simulated-execution";
+  } else if (planned.simulation.backend === "profiled" && planned.simulation.gasProfile) {
+    orderedOutputs = planned.simulation.gasProfile.initialBuys;
+    buyEvidence = "local-exact-curve";
+  } else throw exampleError("MISSING_ECONOMIC_OUTPUTS", "Economic review requires ordered buy outputs from exact execution or the covered local curve");
+  assert.equal(orderedOutputs.length, planned.plan.buys.length, "Economic review ordered outputs");
+  const reviewedBuys = planned.plan.buys.map((buy, index) => {
+    const { tokenOut, quoteSpent } = orderedOutputs[index];
+    assert.ok(tokenOut >= buy.minTokenOut && tokenOut > 0n && quoteSpent <= buy.quoteAmountIn, "Exact protected opening buy");
     const market = marketEconomics[buy.marketIndex];
     const ratio = market.rawQuotePerRawToken;
     return { buyIndex: index, marketIndex: buy.marketIndex, quoteAsset: market.quoteAsset, quoteSymbol: market.quoteSymbol, quoteSpent, tokenOut,
@@ -325,10 +333,10 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
       feeAndPriceImpactPremiumBps: (quoteSpent * ratio.denominator - tokenOut * ratio.numerator) * 10000n /
         (tokenOut * ratio.numerator),
       // Effective execution price includes fees and path impact, not post-buy marginal spot.
-      priceBasis: "admitted-simulation-all-in-average-including-fees-and-price-impact" };
+      priceBasis: `${buyEvidence}-all-in-average-including-fees-and-price-impact` };
   });
   const economicReview = {
-    schema: "black-market.launch-economic-review.v1", caseId: scenario.id, chainId: fixture.chainId,
+    schema: "black-market.launch-economic-review.v2", caseId: scenario.id, chainId: fixture.chainId,
     targetMarketCapUsdX18: fixture.targetMarketCapUsdX18, quotes, metadata, image: image?.descriptor ?? null,
     actualMintedSupply: token.supply, nftUnit: token.nftUnit, tokenDecimals: 18,
     predictedToken, markets: marketEconomics,
@@ -337,7 +345,7 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
       executorFeeBps: plan.executorFeeBps, feeAssets, v4Markets: scenario.markets.flatMap((spec, marketIndex) => spec.venue === "v4" ?
         [{ marketIndex, feeMode: spec.feeMode ?? 0, protocolFeeDenominator: selected.v4.envelope.protocolFeeDenominator,
           treasury: selected.v4.envelope.protocolTreasury, developerBeneficiary: selected.v4.envelope.beneficiary, developerFeeBps: 0 }] : []) },
-    initialBuy: { slippageBps: BUY_SLIPPAGE_BPS, funding: planned.plan.funding, orderedBuys: planned.plan.buys, simulatedBuys,
+    initialBuy: { slippageBps: BUY_SLIPPAGE_BPS, funding: planned.plan.funding, orderedBuys: planned.plan.buys, reviewedBuys, evidence: buyEvidence,
       observedBlockNumber: planned.simulation.blockNumber, observedBlockHash: planned.simulation.blockHash },
     planHash: planned.planHash, finalizedPlan: finalizedPlan,
   };
@@ -346,7 +354,7 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
   // Complete exact intent is owner-only and durable before attribution or chain signing.
   artifacts.privateRecovery({
     schema: "black-market.launch-example-recovery.v1", sdk: "node", caseId: artifacts.result.caseId,
-    plan: finalizedPlan, mode: scenario.mode, confirmations, executionLimits: fixture.executionLimits, economicReview: { ...economicReview, reviewHash },
+    plan: finalizedPlan, mode: planned.mode, confirmations, executionLimits: fixture.executionLimits, economicReview: { ...economicReview, reviewHash },
   });
   artifacts.save("plan.json", finalizedPlan);
   artifacts.save("hook-deployments.json", planned.hookDeployments);
@@ -490,11 +498,11 @@ async function executePlan({ client, fixture, planned, sdk, artifacts, signal, l
   let activation;
   for (let step = 0; step < 64; step += 1) {
     artifacts.stage("build-next", { step });
-    const reviewedTransaction = planned.transactions[step];
-    const next = await sdk.buildNextTransaction({ client, planned, receipts: references, limits, submissionClient: client, reviewedTransaction, signal });
+    const stored = planned.transactions[step];
+    const reviewedTransaction = stored?.gas === undefined || stored.gasPrice === undefined ? undefined : stored;
+    const next = await sdk.buildNextTransaction({ client, planned, receipts: references, limits, reviewedTransaction, signal });
     if (!next) return { references, activation };
-    assert.ok(reviewedTransaction, "No transaction outside the saved review may be submitted");
-    for (const field of ["id", "kind", "chainId", "from", "to", "data", "value", "nonce", "gas", "gasPrice"]) assert.equal(next[field], reviewedTransaction[field], `Fresh ${field} must match the saved review`);
+    if (reviewedTransaction) for (const field of ["id", "kind", "chainId", "from", "to", "data", "value", "gas", "gasPrice"]) assert.equal(next[field], reviewedTransaction[field], `Fresh ${field} must match the saved exact envelope`);
     if (retainedReferences.length) {
       const progress = await sdk.readLaunchProgress({ client, planned, receipts: references, confirmations: planned.confirmations, signal });
       assertRetainedExampleReceipts({ progress, references, artifacts });
@@ -509,11 +517,11 @@ async function executePlan({ client, fixture, planned, sdk, artifacts, signal, l
     assert.ok(functionName, "Native-input conversion cases do not permit unrelated approval/cancellation writes");
     const args = next.kind === "begin" ? [planned.plan, sdk.LifecycleMode.Staged] : next.kind === "prepare" ? [planned.plan, next.marketStart, next.marketCount] : [planned.plan];
     assert.equal(next.data.toLowerCase(), encodeFunctionData({ abi: sdk.launchLifecycleAbi, functionName, args }).toLowerCase(), "Exact finalized-plan calldata");
-    assert.ok(next.gas !== undefined && (next.gasPrice !== undefined || next.maxFeePerGas !== undefined && next.maxPriorityFeePerGas !== undefined) && next.admission?.admitted === true, "Actual next transaction needs stateful gas/envelope admission");
-    assert.equal(next.admission.executionProof, "proved"); assert.equal(next.admission.protocolFit, "proved");
-    assert.equal(next.admission.transportPreflight, "passed", "Exact immediate-next submission RPC preflight is required before signing");
+    assert.ok(next.gas !== undefined && (next.gasPrice !== undefined || next.maxFeePerGas !== undefined && next.maxPriorityFeePerGas !== undefined) && next.admission?.admitted === true, "Actual next transaction needs an admitted gas envelope");
+    assert.ok(next.admission.executionProof === "proved" && next.admission.protocolFit === "proved" ||
+      next.admission.executionProof === "not-run" && next.admission.protocolFit === "profiled", "Distinguish exact execution from conditional capacity admission");
     const ceiling = next.admission.limits.transactionGasCeiling;
-    assert.ok(next.gas > 0n && (ceiling === undefined || next.gas <= ceiling), "Complete gas envelope must fit supplied restrictions; Nitro compute is separately proved");
+    assert.ok(next.gas === next.admission.limits.executionGasCeiling && (ceiling === undefined || next.gas <= ceiling), "Launch gas must equal the native ceiling and fit supplied restrictions");
     const calldataCap = next.admission.limits.maxCalldataBytes;
     assert.ok(calldataCap === undefined || (next.data.length - 2) / 2 <= calldataCap, "Exact calldata must fit any supplied cap");
     const envelope = transactionEnvelope(next);
@@ -549,7 +557,7 @@ async function executePlan({ client, fixture, planned, sdk, artifacts, signal, l
     addressEqual(includedBlock?.hash, receipt.blockHash, "Canonical included block");
     const latest = BigInt(await client.request({ method: "eth_blockNumber" }));
     assert.ok(latest >= BigInt(receipt.blockNumber) + BigInt(planned.confirmations) - 1n, "Required confirmations must be included canonically");
-    const reference = { transactionHash: row.transactionHash, observedBlockNumber: BigInt(receipt.blockNumber), observedBlockHash: receipt.blockHash, confirmations: planned.confirmations };
+    const reference = { transactionHash: row.transactionHash, nonce: BigInt(row.transaction.nonce), observedBlockNumber: BigInt(receipt.blockNumber), observedBlockHash: receipt.blockHash, confirmations: planned.confirmations };
     row.status = "confirmed"; row.reference = reference; artifacts.saveReceipts();
     references.push(reference);
     if (["atomic", "activate"].includes(next.kind)) {
@@ -883,7 +891,8 @@ async function executeExample({ fixture, privateKey, scenario, sdk, artifacts, s
   const { plan } = planned;
   artifacts.save("planning.json", planned);
   artifacts.event("execution-plan", { mode: planned.mode, simulation: planned.simulation, prerequisites: planned.prerequisites, transactions: planned.transactions });
-  assert.equal(planned.mode, scenario.mode, "Never silently change requested mode"); addressEqual(planned.predictedToken, predictedToken, "Planner token prediction");
+  if (scenario.mode === "staged") assert.equal(planned.mode, "staged", "Explicit staged mode is retained");
+  addressEqual(planned.predictedToken, predictedToken, "Planner token prediction");
   if (!planned.simulation.admitted) throw exampleError("PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The actual SDK did not admit this exact launch", { simulation: planned.simulation });
   const usd = (value) => `${value / UNIT}.${(value % UNIT).toString().padStart(18, "0")}`;
   const fundingSummary = economicReview.quotes.every((quote) => quote.conversion.nativeWrap === true)
@@ -894,7 +903,7 @@ async function executeExample({ fixture, privateKey, scenario, sdk, artifacts, s
   console.log(`Economic review ${reviewHash}\n${metadata.name} (${metadata.symbol}); target USD ${usd(economicReview.targetMarketCapUsdX18)}; minted supply ${usd(economicReview.actualMintedSupply)}\n` +
     economicReview.markets.map((market) => `Market ${market.marketIndex} ${market.venue}/${market.quoteSymbol}: retained-supply opening valuation USD ${usd(market.retainedSupplyOpeningValuationUsdX18)} (minted-supply USD ${usd(market.openingValuationUsdX18)}), token USD ${usd(market.unitPriceUsdX18)}, token ${market.quoteSymbol} ${usd(market.unitPriceQuoteX18)}, ${market.positions.length} positions`).join("\n") +
     `\nExpected rounding burn ${economicReview.expectedUnusedBurn} raw token units; ${planned.plan.buys.length} ordered buys, native input ${fixture.buyAmountWei} wei each (${fundingSummary}); 50 bps conversion and ordered-buy protection.\nLP fee 3000 pips; V4 hook max 10000/min 1000 pips (fixed maximum schedule); executor 275 bps.\nImage ${image ? `${image.descriptor.contentType}, ${image.descriptor.contentLength} bytes, ${image.descriptor.sha256}` : "none (metadata only)"}.\nReview allocations, fees and exact protected buys: ${artifacts.directory}/economic-review.json`);
-  console.log(economicReview.initialBuy.simulatedBuys.map((buy) => `Buy ${buy.buyIndex} market ${buy.marketIndex}/${buy.quoteSymbol}: quote spent ${buy.quoteSpent} raw units; simulated all-in USD/token ${usd(buy.allInUnitPriceUsdX18)}; fees + price-impact premium ${buy.feeAndPriceImpactPremiumBps} bps vs opening`).join("\n"));
+  console.log(economicReview.initialBuy.reviewedBuys.map((buy) => `Buy ${buy.buyIndex} market ${buy.marketIndex}/${buy.quoteSymbol}: quote spent ${buy.quoteSpent} raw units; ${economicReview.initialBuy.evidence} all-in USD/token ${usd(buy.allInUnitPriceUsdX18)}; fees + price-impact premium ${buy.feeAndPriceImpactPremiumBps} bps vs opening`).join("\n"));
   for (const quote of economicReview.quotes) {
     const seed = quote.usdSeed;
     console.log(`${quote.symbol}/USD ${usd(seed.priceUsdX18)}; source ${seed.source}; chain ${seed.chainId}; quote ${seed.tokenAddress} (${seed.tokenDecimals} decimals); retrieved ${seed.retrievedAt}.\n` +
@@ -1054,7 +1063,8 @@ export async function resumeLaunchExample({ fixture, privateKey, sdk, artifacts,
     assert.match(reference.transactionHash, /^0x[\da-fA-F]{64}$/, "Original receipt hash");
     assert.match(reference.observedBlockHash, /^0x[\da-fA-F]{64}$/, "Original receipt block hash");
     assert.ok(reference.observedBlockNumber !== undefined && reference.observedBlockNumber !== null, "Original receipt block number");
-    return { ...reference, observedBlockNumber: BigInt(reference.observedBlockNumber), confirmations: reference.confirmations ?? confirmations };
+    if (reference.nonce !== undefined) assert.ok(typeof reference.nonce === "bigint" || typeof reference.nonce === "string" && /^(0|[1-9]\d*)$/.test(reference.nonce), "Retained submitted nonce must be an exact unsigned integer");
+    return { ...reference, ...(reference.nonce === undefined ? {} : { nonce: BigInt(reference.nonce) }), observedBlockNumber: BigInt(reference.observedBlockNumber), confirmations: reference.confirmations ?? confirmations };
   });
   const retainedHashes = new Set(references.map((reference) => reference.transactionHash.toLowerCase()));
   if (references.some((reference) => reference.replacementHash && !same(reference.replacementHash, reference.transactionHash)) ||

package/examples/launch-lifecycle-smoke.ts

@@ -46,7 +46,7 @@ async function send(transaction) {
   const gasPrice = transaction.gasPrice ?? BigInt(await client.request({ method: "eth_gasPrice" }));
   const head = await client.request({ method: "eth_getBlockByNumber", params: ["latest", false] });
   const ceiling = [BigInt(head.gasLimit), BigInt(policy.chainTransactionGasLimit), BigInt(policy.rpcTransactionGasLimit), BigInt(policy.accountTransactionGasLimit)].reduce((a, b) => a < b ? a : b);
-  const wire = { from: transaction.from, to: transaction.to, data: transaction.data, value: toHex(transaction.value), gasPrice: toHex(gasPrice), ...(transaction.nonce === undefined ? {} : { nonce: toHex(transaction.nonce) }) };
+  const wire = { from: transaction.from, to: transaction.to, data: transaction.data, value: toHex(transaction.value), gasPrice: toHex(gasPrice) };
   const estimated = transaction.gas ?? ((BigInt(await client.request({ method: "eth_estimateGas", params: [{ ...wire, gas: toHex(ceiling) }] })) * BigInt(10000 + Number(policy.headroomBps)) + 9999n) / 10000n);
   assert.ok(estimated <= ceiling, "Unsigned helper must still fit explicit local execution admission");
   const transactionHash = await client.request({ method: "eth_sendTransaction", params: [{ ...wire, gas: toHex(estimated) }] });
@@ -103,9 +103,11 @@ for (const row of exported.plans) for (const mode of ["atomic", "staged"]) {
     const receipts = [];
     let activationReceipt;
     for (let guard = 0; guard < 64; ++guard) {
-      const next = await buildNextTransaction({ client, planned, receipts, limits, fork, submissionClient: client });
+      const next = await buildNextTransaction({ client, planned, receipts, limits, fork });
       if (!next) break;
-      assert.equal(next.admission?.transportPreflight, "passed");
+      assert.equal(next.admission?.admitted, true);
+      assert.ok(next.admission.executionProof === "proved" && next.admission.protocolFit === "proved" ||
+        next.admission.executionProof === "not-run" && next.admission.protocolFit === "profiled");
       const submitted = await send(next);
       receipts.push(submitted.reference);
       if (["atomic", "activate"].includes(next.kind)) activationReceipt = submitted.receipt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {

package/src/lifecycle/authors.ts

@@ -1,6 +1,6 @@
 import { decodeEventLog, encodeFunctionData, isAddress, zeroAddress, type Address, type Hex } from "viem";
 import { launchLifecycleAbi, lifecycleFeeHubAbi, lifecycleFeeHubFactoryAbi, lifecycleRegistryAbi } from "./abi.js";
-import { assertLifecycleBlock, lifecycleRpc, readLifecycleBlock, readLifecycleContract, rpcQuantity } from "./rpc.js";
+import { assertLifecycleBlock, lifecycleRpc, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, rpcQuantity } from "./rpc.js";
 import type { SourceTermsV3 } from "./schema.js";
 import { LifecyclePlanningError, type LifecycleBlock, type LifecycleRpcClient } from "./types.js";
 
@@ -50,7 +50,7 @@ function requirePage(offset: bigint, limit: bigint, maximum: bigint): void {
 async function readAuthorContext(options: LifecycleAuthorOptions, block: LifecycleBlock): Promise<LifecycleAuthor> {
   const { client, registry, authorId } = options;
   requireAddress(registry, "Implementation registry"); requireAddress(authorId, "Stable author identity");
-  const chainId = rpcQuantity(await lifecycleRpc(client, "eth_chainId"), "author chain ID");
+  const chainId = await readLifecycleChainId(client);
   const core = await readLifecycleContract<Address>(client, registry, lifecycleRegistryAbi, "core", [], block);
   requireAddress(core, "Registry core");
   if ((await readLifecycleContract<Address>(client, core, launchLifecycleAbi, "registry", [], block)).toLowerCase() !== registry.toLowerCase()) throw new LifecyclePlanningError("REGISTRY_BINDING", "Selected core does not bind this implementation registry");

package/src/lifecycle/gas-profile.ts

@@ -0,0 +1,175 @@
+import { toHex, zeroAddress, type Address } from "viem";
+import { AUCTION_QUOTE_OPTIONS } from "../auction.js";
+import { getTickAtSqrtRatio } from "../launch.js";
+import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
+import { computeLifecycleOpeningBuys, hasProfiledOpeningMath } from "./opening-buys.js";
+import { getKnownLifecycleProfile, hmmV2ForwardingReserve } from "./presets.js";
+import { lifecyclePinnedRpc, lifecycleSessionRead, nitroPosterGasBound, readNitroPrices, registerLifecycleFinalCheck, resolveLifecycleLimits, rpcHex, rpcQuantity } from "./rpc.js";
+import { LifecycleFundingKind, LifecycleRewardMode, LifecycleTokenKind, type LaunchPlanV1 } from "./schema.js";
+import { buildLifecycleCommand } from "./transactions.js";
+import { UFG_LAUNCH_PROXY_ADDRESS, ufgPlanPrincipal, type UfgLaunchConfig } from "./ufg-config.js";
+import type { NextTransactionEnvelope } from "./simulation.js";
+import { LifecyclePlanningError, type LifecycleBlock, type LifecycleLaunchGasBounds, type LifecycleOpeningBuyQuote, type LifecycleSimulation, type LifecycleTransaction, type SimulateLaunchPlanOptions } from "./types.js";
+
+export const LIFECYCLE_GAS_PROFILE_VERSION = "robinhood-4663-arbos61-v1";
+
+// Coverage, not token admission: unlisted currencies still use exact execution.
+const profiledQuotes = new Set<string>();
+for (const quote of AUCTION_QUOTE_OPTIONS) if (quote.address !== zeroAddress) profiledQuotes.add(quote.address.toLowerCase());
+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; spacing: number; openingTick: number; ticks: number[] };
+
+function covered(plan: LaunchPlanV1): boolean {
+  return plan.chainId === 4663n && hasProfiledOpeningMath(plan) &&
+    plan.markets.every((market) => profiledQuotes.has(market.quoteAsset.toLowerCase())) &&
+    plan.funding.every((funding) => funding.kind !== LifecycleFundingKind.ERC20 || profiledQuotes.has(funding.inputAsset.toLowerCase()));
+}
+
+function marketGas(plan: LaunchPlanV1): MarketGas[] {
+  return plan.markets.map((market) => {
+    const preset = getKnownLifecycleProfile({ chainId: plan.chainId, orchestrator: plan.orchestrator, profileId: market.profileId })!;
+    const abyss = market.configVersion === 1;
+    const config = abyss ? decodeAbyssLifecycleMarketConfig(market.config) : decodePoolBoundV4LifecycleMarketConfig(market.config, 6);
+    const price = "openingSqrtPriceX96" in config ? config.openingSqrtPriceX96 : config.sqrtPriceX96;
+    const spacing = "tickSpacing" in config ? config.tickSpacing : config.fee === 100 ? 1 : config.fee === 500 ? 10 : config.fee === 3000 ? 60 : 200;
+    const ticks = new Set<number>();
+    for (const position of config.positions) { ticks.add(position.tickLower); ticks.add(position.tickUpper); }
+    return { abyss, hmm: preset.key.includes("hmm"), ufgHook: preset.key.includes("ufg"), positions: config.positions.length,
+      spacing, openingTick: getTickAtSqrtRatio(price), ticks: [...ticks] };
+  });
+}
+
+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) +
+    22_000n * BigInt(Math.ceil(utf8Bytes(token.name) / 32) + Math.ceil(utf8Bytes(token.symbol) / 32) + Math.ceil(utf8Bytes(token.metadataURI) / 32));
+}
+
+/** Capacity classification only. No value returned here ever sets a transaction gas limit. */
+function capacityBasis(plan: LaunchPlanV1, transaction: LifecycleTransaction, markets: readonly MarketGas[], quotes: readonly LifecycleOpeningBuyQuote[], ufgRoute: boolean): bigint {
+  const atomic = transaction.kind === "atomic";
+  let gas = atomic ? 19_500_000n + tokenCreationGas(plan.token) + (ufgRoute ? 6_500_000n : 0n) : 1_000_000n;
+  for (const [index, market] of markets.entries()) {
+    if (!atomic) gas += market.abyss ? 2_500_000n + 1_600_000n * BigInt(market.positions) : 2_000_000n + 600_000n * BigInt(market.positions);
+    else gas += (index === 0 ? market.hmm ? 7_000_000n : market.ufgHook ? 1_000_000n : market.abyss ? 500_000n : 0n
+      : market.hmm ? 15_000_000n : market.ufgHook ? 9_000_000n : 8_000_000n) +
+      (market.abyss ? 1_500_000n : 600_000n) * BigInt(market.positions - 1);
+    if (!atomic && market.hmm) gas += 6_000_000n;
+  }
+  const ticks = markets.map((market) => market.openingTick);
+  for (const quote of quotes) {
+    const market = markets[quote.marketIndex]!, before = ticks[quote.marketIndex]!, after = getTickAtSqrtRatio(quote.sqrtPriceAfterX96);
+    const low = Math.min(before, after), high = Math.max(before, after);
+    const words = Math.abs(Math.floor(after / (market.spacing * 256)) - Math.floor(before / (market.spacing * 256))) + 2;
+    let crossings = 0;
+    for (const tick of market.ticks) if (tick >= low && tick <= high) crossings += 1;
+    gas += 300_000n + 8_000n * BigInt(words) + 80_000n * BigInt(crossings);
+    if (plan.token.kind === LifecycleTokenKind.ERC404) gas += 70_000n * ceil(quote.tokenOut, plan.token.nftUnit);
+    ticks[quote.marketIndex] = after;
+  }
+  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;
+};
+
+/** Internal shared computation; callers reuse both compiled commands and ordered math. */
+export function deriveLifecycleLaunchCapacity(options: CapacityOptions, openingBuys?: readonly LifecycleOpeningBuyQuote[]): ProfiledLaunchCapacity | undefined {
+  const { plan, ufg } = options;
+  if (!covered(plan) || plan.funding.some((funding) => funding.kind === LifecycleFundingKind.Swap) ||
+    (plan.creator.toLowerCase() === UFG_LAUNCH_PROXY_ADDRESS.toLowerCase()) !== (ufg !== undefined)) 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 and10000 basis points");
+  const initialBuys = openingBuys ?? computeLifecycleOpeningBuys(options);
+  const route = ufg === undefined ? undefined : { account: ufgPlanPrincipal(plan), config: ufg.config };
+  const atomic = buildLifecycleCommand(plan, { kind: "atomic" }, route), 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 + headroomBps), 10000n);
+    return buffered > basis + reserve ? buffered : basis + reserve;
+  };
+  return { bounds: { atomicComputeGasUpperBound: bound(atomic), activationComputeGasUpperBound: bound(activation) }, initialBuys, headroomBps, atomic, activation };
+}
+
+/** Pure, versioned conservative compute bounds for mode/builder capacity, excluding poster gas.
+ * Undefined means unprofiled, not unavailable functionality. A large upper bound is uncertain. */
+export function computeLifecycleLaunchGasBounds(options: CapacityOptions): LifecycleLaunchGasBounds | undefined {
+  return deriveLifecycleLaunchCapacity(options)?.bounds;
+}
+
+export type ProfiledLifecycleTransactions = { simulation: LifecycleSimulation; profileOnly: boolean };
+
+/** Native ceilings determine every launch envelope. Profiles decide capacity only;
+ * conversions and uncertain activation shapes still require exact execution. */
+export async function profileLifecycleTransactions(options: SimulateLaunchPlanOptions, transactions: readonly LifecycleTransaction[], block: LifecycleBlock,
+  reviewed?: NextTransactionEnvelope, openingBuys?: readonly LifecycleOpeningBuyQuote[], capacity?: ProfiledLaunchCapacity): Promise<ProfiledLifecycleTransactions | undefined> {
+  const { client, planned } = options, plan = planned.plan;
+  const onlyApprovals = transactions.every(approval);
+  if (planned.chainId !== 4663n || !onlyApprovals && !covered(plan)) return undefined;
+  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);
+  if (!onlyApprovals && observed.limits.arbOSVersion !== 61n) return undefined;
+  const [prices, balanceValue, accountCode] = await Promise.all([
+    readNitroPrices(client, block),
+    lifecyclePinnedRpc(client, "eth_getBalance", [planned.account, toHex(block.number)], block),
+    lifecycleSessionRead(client, `${planned.chainId}:account-code:${planned.account.toLowerCase()}`, () => lifecyclePinnedRpc(client, "eth_getCode", [planned.account, toHex(block.number)], block)),
+  ]);
+  if (rpcHex(accountCode, "account code") !== "0x") return undefined;
+  options.signal?.throwIfAborted(); observed.assertCurrent(); registerLifecycleFinalCheck(client, observed.assertCurrent);
+  const { limits } = observed, baseFee = block.baseFeePerGas ?? 0n;
+  const requiredGasPrice = prices[5] > baseFee ? prices[5] : baseFee;
+  const gasPrice = reviewed?.gasPrice ?? (prices[5] > baseFee * 2n ? prices[5] : baseFee * 2n);
+  if (reviewed !== undefined && !onlyApprovals && reviewed.gas !== limits.executionGasCeiling) throw new LifecyclePlanningError("STALE_REVIEWED_GAS", "Reviewed gas differs from the native transaction ceiling; review the launch again");
+  const needsBuys = transactions.some((transaction) => transaction.kind === "atomic" || transaction.kind === "activate");
+  const currentCapacity = needsBuys ? capacity?.headroomBps === limits.headroomBps ? capacity : deriveLifecycleLaunchCapacity({ plan, predictedToken: planned.predictedToken, ufg: planned.ufg, headroomBps: limits.headroomBps }, openingBuys) : undefined;
+  if (needsBuys && currentCapacity === undefined) return undefined;
+  const quotes = currentCapacity?.initialBuys ?? [], bounds = currentCapacity?.bounds;
+  let profileOnly = !plan.funding.some((funding) => funding.kind === LifecycleFundingKind.Swap) ||
+    !transactions.some((transaction) => transaction.kind === "begin" || transaction.kind === "atomic" || transaction.kind === "activate");
+  for (const transaction of transactions) {
+    if (transaction.kind !== "atomic" && transaction.kind !== "activate") continue;
+    const compute = transaction.kind === "atomic" ? bounds!.atomicComputeGasUpperBound : bounds!.activationComputeGasUpperBound;
+    if (compute + nitroPosterGasBound(transaction, prices).posterGas > limits.executionGasCeiling) profileOnly = false;
+  }
+  const launch = transactions.find((transaction) => !approval(transaction));
+  const immediate = transactions[0], gasLimit = limits.executionGasCeiling;
+  const envelopeFailure = launch !== undefined && limits.transactionGasCeiling !== undefined && gasLimit > limits.transactionGasCeiling;
+  const calldataFailure = transactions.find((transaction) => limits.maxCalldataBytes !== undefined && (transaction.data.length - 2) / 2 > limits.maxCalldataBytes);
+  const feeFailure = reviewed !== undefined && gasPrice < requiredGasPrice;
+  const affordabilityFailure = launch !== undefined && launch.value + gasLimit * gasPrice > rpcQuantity(balanceValue, "creator native balance");
+  const semanticFailure = quotes.find((quote) => quote.tokenOut < plan.buys[quote.buyIndex]!.minTokenOut);
+  const expired = block.timestamp > plan.deadline && transactions.some((transaction) => transaction.kind !== "cancel");
+  const refused = envelopeFailure || calldataFailure !== undefined || feeFailure || affordabilityFailure || semanticFailure !== undefined || expired;
+  const poster = immediate === undefined || approval(immediate) ? undefined : nitroPosterGasBound(immediate, prices).posterGas;
+  const simulation: LifecycleSimulation = {
+    backend: "profiled", confidence: "profiled", executionProof: "not-run", protocolFit: "profiled", admitted: profileOnly && !refused,
+    blockNumber: block.number, blockHash: block.hash, account: planned.account, chainId: planned.chainId, limits, steps: [], deferredTransactionIds: [],
+    ...(bounds === undefined ? {} : { gasProfile: { version: LIFECYCLE_GAS_PROFILE_VERSION, bounds, initialBuys: quotes } }),
+    ...(immediate === undefined || approval(immediate) ? {} : { estimate: { gasLimit, gasPrice, executionFee: gasLimit * gasPrice, dataFee: 0n, totalFee: gasLimit * gasPrice,
+      posterGas: poster, posterFee: poster! * gasPrice, dataFeeIncludedInGas: true, feeConfidence: "native-ceiling-and-data" as const } }),
+    ...(envelopeFailure ? { failureCategory: "capacity" as const, capacityConstraint: "gas-envelope" as const, failedTransactionId: launch!.id, reason: "Native transaction ceiling exceeds the supplied complete gas policy" } : {}),
+    ...(calldataFailure === undefined ? {} : { failureCategory: "capacity" as const, capacityConstraint: "calldata" as const, failedTransactionId: calldataFailure.id, reason: "Encoded command exceeds the caller's calldata byte policy" }),
+    ...(affordabilityFailure ? { failureCategory: "affordability" as const, failedTransactionId: launch!.id, reason: "Creator native balance cannot reserve transaction value and the native gas ceiling" } : {}),
+    ...(semanticFailure === undefined ? {} : { failureCategory: "semantic" as const, failedTransactionId: transactions.find((transaction) => transaction.kind === "atomic" || transaction.kind === "activate")?.id, reason: "Opening curve output is below the committed minimum" }),
+    ...(expired ? { failureCategory: "semantic" as const, failedTransactionId: transactions.find((transaction) => transaction.kind !== "cancel")?.id, reason: "Launch deadline has expired at the pinned block" } : {}),
+    ...(feeFailure ? { failedTransactionId: immediate?.id, reason: "Reviewed gas price is below the pinned required fee" } : {}),
+  };
+  return { simulation, profileOnly: profileOnly || refused };
+}

package/src/lifecycle/index.ts

@@ -11,9 +11,11 @@ export { ABYSS_LIFECYCLE_CONFIG_SCHEMA, readLifecycleTokenAtBlock, readLifecycle
 export * from "./fork.js";
 export * from "./authors.js";
 export * from "./presets.js";
-export * from "./transactions.js";
+export { preparationGasEstimate, packPreparationBatches, buildLaunchTransactions } 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 { computeLifecycleOpeningBuys } from "./opening-buys.js";
+export { computeLifecycleLaunchGasBounds } from "./gas-profile.js";
 export { assertLaunchTopologyCoverage, getTickAtSqrtRatio, type LaunchTopologyCoverageInput, type LaunchTopologyPosition } from "../launch.js";

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;
+    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;
+}