@black-market/sdk 0.12.0 → 0.13.0

package/README.md

@@ -2,13 +2,17 @@
 
 # Abyss TypeScript SDK
 
-TypeScript SDK for token launches, swaps, and lending with [viem](https://viem.sh).
-Import the public package as `@black-market/sdk`. Requires Node 24+ to run the examples.
+Use `@black-market/sdk` with [viem](https://viem.sh) to launch tokens, swap, and read lending markets.
+This guide targets SDK **0.13.0** on Robinhood Chain mainnet (**4663**).
+The package supports Node 20+; running the checkout's TypeScript examples requires **Node 24+**.
 
 ## Install
 
-Install the package with `pnpm add @black-market/sdk viem`, or use a checkout
-to run and customize the examples:
+```sh
+pnpm add @black-market/sdk@0.13.0 viem
+```
+
+To run the examples, use a checkout:
 
 ```sh
 git clone https://github.com/abysshopper/black-market-node-sdk.git
@@ -17,107 +21,103 @@ pnpm install --frozen-lockfile
 pnpm build
 ```
 
-### UFG treasury launches (0.12.0)
-
-Opt in with `prepareAndPlanLifecycleLaunch({ ..., ufg: { config } })`. UFG supports
-reward-free ERC20 launches with native Abyss QUOTE/QUOTE_ORACLE markets and the
-new `KnownLifecycleProfile.V4UfgFixedPool` / `V4UfgDynamicPool` presets.
-All reserve fees fund the upstream treasury; launch-token fees are burned.
-These are separate offerings, not a change to existing fixed, dynamic or HMM launches.
-
-Set `plan.creator = UFG_LAUNCH_PROXY_ADDRESS` and
-`plan.nonce = ufgLaunchNonce(principal, nonce96)`, while the planning account and
-every transaction sender remain the principal. Use `buildUfgFeeAssetPolicies`
-with the core's predicted token; approve the **proxy**, not the escrow.
-`readUfgTreasury(client, token)` returns the upstream treasury or `undefined`.
-The [UFG lifecycle guide](docs/launch-lifecycle.md#0120-release-opt-in-ufg-treasuries)
-covers restrictions, tail encoding, unsigned builders and recovery.
-[`ufg-launch-config.ts`](examples/ufg-launch-config.ts) is a pure, no-wallet example.
-
-### HMM V2 pool hooks (0.10.0)
-
-Robinhood mainnet has admitted **HMM Fixed V2** and **HMM Dynamic V2** presets:
-`KnownLifecycleProfile.V4HmmFixedPool` / `V4HmmDynamicPool`. The generic keys and
-`HmmLaunchConfig` now mean V2 only. Config6 appends an exact **512-byte** tail;
-old HMM profiles and 448-byte payloads are not supported by these helpers.
-Both require zero LP and developer fees.
-
-`defaultHmmLaunchConfig({ tokenBudget, quoteAsset, quoteDecimals, maxBidQuote,
-referenceDeviation })` preserves existing WETH/USDG calibration, but requires
-explicit bid-principal and oracle-reference guards. There are no guessed V2 risk
-defaults. Unknown quotes still require explicit raw quote thresholds.
-
-On each swap, the configured share of fees in **both currencies**, after treasury,
-funds the per-market HMM manager; the remainder follows normal fee distribution.
-HMM does not burn fees or touch locked launch positions. The current fee owner
-can change the share, all 15 strategy settings, and placement pause state using
-the exported V2 ABIs. See [HMM configuration and migration](docs/launch-lifecycle.md#0100-release-hmm-v2-only)
-and the [pure, unsigned example](examples/hmm-launch-config.ts).
-
-## Examples
-
-The most complete case is [`launch-erc20-dividends-multiquote-mixed.ts`](examples/launch-erc20-dividends-multiquote-mixed.ts).
-On Robinhood mainnet (**chain 4663**), it:
-
-1. Creates an ERC20 with 1,000,000 initial tokens and holder dividends.
-   Fee-asset allocations split 40% to rewards and 60% to the owner, not a 40% tax.
-2. Splits liquidity across V4/WETH (two positions), V4/USDG (two), and Abyss/WETH
-   (three), priced from the same whole-supply USD valuation (default $5,000).
-3. Funds one opening buy per market with 0.00001 ETH each by default. ETH wraps
-   into WETH; USDG uses an admitted Kyber conversion. ETH for gas is additional.
-4. Prepares and proves the staged plan, prints the economic review, and saves
-   artifacts. Activation outputs must fit the provider's proof budget; configure
-   `EXAMPLE_SIMULATION_GAS_CAP` only for a provider supporting that budget.
-   The default dry-run never signs or submits anything.
-5. With authorization, stages metadata, begins and prepares the markets, then
-   activates all seven positions and three buys together. It verifies chain
-   results and API publication; optional images are verified before submission.
-
-### Configure and run
-
-From the checkout root, create `.env` without overwriting existing configuration:
+## Check the deployment first
 
 ```sh
-cp -n examples/.env.example .env
-chmod 600 .env
+pnpm examples
+# To load configuration from an existing working-directory .env explicitly:
+node --env-file=.env examples/quickstart.ts
 ```
 
-Set `LAUNCH_API_URL` and exactly one key source: `PRIVATE_KEY`, or
-`EXAMPLE_KEYSTORE_PATH` to an owner-only V3 scrypt keystore (`EXAMPLE_KEYSTORE_PASSWORD`
-defaults to empty). Optional `RPC_URL` overrides the official chain4663 RPC.
-Remote endpoints require HTTPS; existing environment values override `.env`.
+`pnpm examples` builds and runs [`examples/quickstart.ts`](examples/quickstart.ts).
+It reads chain identity, the orchestrator's registry, and current profile admission.
+It needs no wallet and makes no writes. It reads the process environment; it does **not** load `.env` itself.
+Export `RPC_URL` in your shell or use `--env-file` as shown. `CHAIN_ID` defaults to `4663`.
 
-```sh
-# Dry run: no signing, chain submission, image upload, or publication.
-node examples/launch-erc20-dividends-multiquote-mixed.ts
-# Explicitly authorize spending funds and publishing; no confirmation prompt.
-node examples/launch-erc20-dividends-multiquote-mixed.ts --broadcast
-# After partial execution, replace this path with the ORIGINAL run directory.
-node examples/launch-erc20-dividends-multiquote-mixed.ts --resume "launch-results/<original-run>"
-```
+## Run a one-market ERC20 launch
 
-Dry-run needs live RPC/API access, the creator key, funding, and admission.
-Review the saved `economic-review.json` in `launch-results/`. Broadcast builds a
-**fresh plan**; resume may spend/publish but retains the original plan and session.
-Keep recovery files; never commit or share keys, private artifacts, or signed bytes.
+Start with [`launch-erc20-abyss.ts`](examples/launch-erc20-abyss.ts): one Abyss/WETH market,
+one permanent position, one opening buy, no holder rewards, atomic execution.
 
-## Creating your own
+```sh
+cp -n examples/.env.example .env
+chmod 600 .env
+```
 
-Copy the case wrapper beside its helpers, then customize it:
+Set `LAUNCH_API_URL=https://api.abyss.trading` and exactly one signer source:
+`PRIVATE_KEY`, or `EXAMPLE_KEYSTORE_PATH` with optional `EXAMPLE_KEYSTORE_PASSWORD`.
+Use your own funded account. Keep secrets and recovery files out of git.
+The launch wrappers load the working-directory `.env`; existing environment values win.
+Optional `RPC_URL` selects another Robinhood RPC. Remote endpoints require HTTPS.
 
 ```sh
-cp examples/launch-erc20-dividends-multiquote-mixed.ts examples/launch-my-token.ts
-node examples/launch-my-token.ts
+# Unsigned planning; no chain transactions, uploads, or publication.
+node examples/launch-erc20-abyss.ts
+# Authorizes spending and publication, with no further prompt.
+node examples/launch-erc20-abyss.ts --broadcast
+# After partial execution, use the ORIGINAL run directory.
+node examples/launch-erc20-abyss.ts --resume "launch-results/<original-run-dir>"
 ```
 
-Edit the object passed to `runLaunchExample`: unique `id`, `tokenKind`
-(0 ERC20 / 1 ERC404), `rewardMode` (0 none / 1 staking / 2 dividends),
-`mode` (`atomic` / `staged`), `markets` (`venue`, `quote`, `positions`), and
-`buysPerMarket`. Supported venues are `v4`/`abyss`, quotes `WETH`/`USDG`.
-Customize identity, valuation, and buy input with the `EXAMPLE_*` keys in
-[`.env.example`](examples/.env.example). For supply, fees, budgets, or ranges,
-adapt `constructPlan` in `launch-example.ts` and `deriveExampleMarketEconomics`
-in `launch-example-support.ts`. If copying elsewhere, include the Kyber helper too.
-
-See the [launch/API guide](docs/launch-lifecycle.md), [runner configuration](examples/README.md),
-and [MIT license](LICENSE) for deeper reference.
+**Broadcast builds a fresh plan**, including a new nonce and token identity; it does not sign the dry-run plan.
+Review the broadcast's printed economics too. `--resume` can spend funds and publish;
+it continues the saved identity and does not require `--broadcast`.
+A dry run still needs a signer source, sufficient funding, and live RPC/API access for admission.
+
+### Understand the defaults
+
+- ERC20 supply: **1,000,000 tokens**. Target FDV: **$5,000**, or **$0.005/token** before tick alignment.
+- FDV is a valuation, not cash deposited. Initial positions contain launch tokens only.
+- Opening buy: **0.00001 ETH per buy**. ETH wraps into WETH; USDG cases convert through Kyber.
+- ETH for gas is extra. The buy's output depends on fees, ranges, and the aligned opening price.
+- `EXAMPLE_TARGET_MARKET_CAP_USD` and `EXAMPLE_BUY_AMOUNT_WEI` change the target and buy input.
+  These defaults are examples, not a recommended valuation or an anti-sniper guarantee.
+
+Use the [worked pricing guide](docs/launch-lifecycle.md#price-the-launch) before changing supply or ranges.
+
+## Choose an example
+
+Each filename below is in `examples/`. V4 cases use the fixed-fee pool-bound profile;
+quotes are WETH unless USDG is listed. Positions are permanently locked.
+
+| File | Token / rewards | Markets / position counts | Mode / buys |
+| --- | --- | --- | --- |
+| `launch-erc20-abyss.ts` | ERC20 / none | Abyss: 1 | atomic / 1 |
+| `launch-erc20-v4.ts` | ERC20 / none | V4: 1 | atomic / 1 |
+| `launch-erc404-v4.ts` | ERC404 / none | V4: 1 | staged / 1 |
+| `launch-erc404-abyss.ts` | ERC404 / none | Abyss: 1 | atomic / 1 |
+| `launch-erc20-staking-v4.ts` | ERC20 / staking | V4: 2 | staged / 2 |
+| `launch-erc20-dividends-abyss.ts` | ERC20 / dividends | Abyss: 3 | staged / 1 |
+| `launch-erc20-burn-mixed.ts` | ERC20 / 30% token-fee burn | V4: 2; Abyss: 1 | staged / 2 |
+| `launch-erc404-dividends-mixed.ts` | ERC404 / dividends | V4: 2; Abyss: 3 | staged / 2 |
+| `launch-erc20-multi-quote.ts` | ERC20 / none | V4 WETH: 1; V4 USDG: 1; Abyss WETH: 1 | staged / 3 |
+| `launch-erc20-depth-v4.ts` | ERC20 / none | V4: 4, Early Scarcity | staged / 1 |
+| `launch-erc20-dividends-multiquote-mixed.ts` | ERC20 / dividends | V4 WETH: 2; V4 USDG: 2; Abyss WETH: 3 | staged / 3 |
+
+## Choose an offering for your integration
+
+Run discovery before selecting a profile. Frozen SDK presets describe supported construction;
+`readLifecycleProfiles` reports current admission.
+
+| Offering | Choose it for | Guide |
+| --- | --- | --- |
+| Canonical Abyss | STANDARD / STANDARD_ORACLE / QUOTE / QUOTE_ORACLE pools | [Choose an offering](docs/launch-lifecycle.md#choose-an-offering) |
+| Fixed V4 | One hook per pool, fixed hook fee, optional LP fee | [Build the plan](docs/launch-lifecycle.md#build-the-plan) |
+| Dynamic V4 | Oracle-velocity hook fee between your minimum and maximum; LP fee 0 | [Fee configuration](docs/reference.md#pool-bound-v4-version-6) |
+| HMM V2 | Fee-funded auxiliary bids/asks; LP and developer fees 0 | [Configure HMM V2](docs/launch-lifecycle.md#configure-hmm-v2) |
+| UFG | Quote-fee treasury and holder redemption; reward-free ERC20 only | [Launch a UFG treasury](docs/launch-lifecycle.md#launch-a-ufg-treasury) |
+
+The eleven launch wrappers do not launch HMM or UFG. Start those integrations with
+[`hmm-launch-config.ts`](examples/hmm-launch-config.ts) or [`ufg-launch-config.ts`](examples/ufg-launch-config.ts)
+and the linked guide. They are pure configuration examples, not deployment commands.
+
+## Recover and integrate
+
+After an interrupted send, inspect the saved transaction hash and use `--resume` on the original directory.
+If markets are already active but publication failed, resume publication; do not deploy another token.
+The runner saves artifacts under `launch-results/`; retain its owner-only recovery file.
+
+- [Launch guide](docs/launch-lifecycle.md): pricing → planning → signing → publication → fees and recovery.
+- [Runner reference](examples/README.md): environment, eleven cases, artifacts, and resume behavior.
+- [SDK reference](docs/reference.md): addresses, codecs, limits, Nitro gas, and author APIs.
+- [Changelog](CHANGELOG.md) · [MIT license](LICENSE)

package/dist/lifecycle/planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/lifecycle/planner.ts"],"names":[],"mappings":"AASA,OAAO,EAA0B,KAAK,2BAA2B,EAAkN,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,oCAAoC,EAAE,KAAK,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAqQld;wFACwF;AACxF,wBAAsB,6BAA6B,CAAC,OAAO,EAAE,oCAAoC,GAAG,OAAO,CAAC,aAAa,CAAC,CA+DzH;AAED,qGAAqG;AACrG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAMnF;AA0JD;uFACuF;AACvF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAyC1H;AAED;qFACqF;AACrF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWzG"}
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/lifecycle/planner.ts"],"names":[],"mappings":"AASA,OAAO,EAA0B,KAAK,2BAA2B,EAAkN,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,oCAAoC,EAAE,KAAK,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAuQld;wFACwF;AACxF,wBAAsB,6BAA6B,CAAC,OAAO,EAAE,oCAAoC,GAAG,OAAO,CAAC,aAAa,CAAC,CAgFzH;AAED,qGAAqG;AACrG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAQnF;AA4JD;uFACuF;AACvF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAqD1H;AAED;qFACqF;AACrF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWzG"}

package/dist/lifecycle/planner.js

@@ -3,9 +3,9 @@ import { ABYSS_FEE_TIERS } from "../abyss.js";
 import { assertLaunchTopologyCoverage, getTickAtSqrtRatio } from "../launch.js";
 import { launchLifecycleAbi, lifecycleAdapterAbi, lifecycleErc20Abi } from "./abi.js";
 import { hashLaunchIdentity, hashLaunchPlan, LifecycleFundingKind, LifecyclePhase, LifecycleRewardMode, LifecycleTokenKind, LIFECYCLE_MAX_REWARD_ERC20_SUPPLY, LIFECYCLE_MAX_ERC404_SUPPLY, parseLaunchPlan, serializeLaunchPlan } from "./schema.js";
-import { readLaunchProgress, readLifecycleProfiles, readLifecycleTokenAtBlock, readPoolBoundHookDeployment } from "./progress.js";
+import { readLaunchProgress, readLifecycleHeadProgress, readLifecycleProfiles, readLifecycleTokenAtBlock, readPoolBoundHookDeployment } from "./progress.js";
 import { decodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig, decodeV4LifecycleMarketConfig, encodePoolBoundV4LifecycleMarketConfig, isPoolBoundV4ConfigVersion, minePoolBoundHookSalt } from "./markets.js";
-import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, resolveLifecycleLimits, rpcHex, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
+import { assertLifecycleBlock, assertLifecycleReadClientOpen, lifecycleFailureReason, lifecyclePinnedRpc, lifecycleStaticRpc, lifecycleRpc, lifecycleStage, readLifecycleBlock, readLifecycleChainId, readLifecycleContract, readLifecycleGasPrice, resolveLifecycleLimits, rpcHex, rpcQuantity, withLifecycleReadClient } from "./rpc.js";
 import { prepareLaunchSimulation, simulateLaunchTransactions } from "./simulation.js";
 import { LifecyclePlanningError } from "./types.js";
 import { deriveKnownPoolBoundHookDeployment, protectOrderedBuyMinimums, validateBuySlippageBps } from "./calibration.js";
@@ -159,7 +159,7 @@ function orderedTransactions(plan, mode, progress, approvals, batches, ufg) {
     const commands = compiled.filter((transaction) => (transaction.kind !== "begin" && transaction.kind !== "atomic" || progress.canonical.phase === LifecyclePhase.None) &&
         (transaction.kind !== "prepare" || (transaction.marketStart ?? 0) >= prepared));
     const transactions = progress.canonical.phase === LifecyclePhase.None ? [...approvals, ...commands] : commands;
-    return transactions.map((transaction, index) => ({ ...transaction, calldataBytes: (transaction.data.length - 2) / 2, dependencies: index === 0 ? [] : [transactions[index - 1].id] }));
+    return transactions.map((transaction, index) => ({ ...transaction, nonce: progress.pendingAccountNonce + BigInt(index), calldataBytes: (transaction.data.length - 2) / 2, dependencies: index === 0 ? [] : [transactions[index - 1].id] }));
 }
 function attachEstimates(transactions, simulation) {
     return transactions.map((transaction) => {
@@ -180,7 +180,8 @@ function readReviewedNextTransaction(transaction) {
         typeof transaction.data !== "string" || !/^0x(?:[\da-fA-F]{2})*$/.test(transaction.data) ||
         typeof transaction.value !== "bigint" || transaction.value < 0n || transaction.value >= 1n << 256n ||
         typeof transaction.gas !== "bigint" || transaction.gas <= 0n || transaction.gas >= 1n << 64n ||
-        typeof transaction.gasPrice !== "bigint" || transaction.gasPrice < 0n || transaction.gasPrice >= 1n << 256n) {
+        typeof transaction.gasPrice !== "bigint" || transaction.gasPrice < 0n || transaction.gasPrice >= 1n << 256n ||
+        transaction.nonce !== undefined && (typeof transaction.nonce !== "bigint" || transaction.nonce < 0n || transaction.nonce >= 1n << 64n)) {
         throw new LifecyclePlanningError("INVALID_REVIEWED_TRANSACTION", "Reviewed transaction must contain a well-formed exact chain/account/target/calldata/value and uint64 gas/uint256 price envelope");
     }
     return transaction;
@@ -188,7 +189,8 @@ function readReviewedNextTransaction(transaction) {
 function matchesReviewedNextTransaction(next, reviewed) {
     return next !== undefined && next.id === reviewed.id && next.kind === reviewed.kind && next.chainId === reviewed.chainId &&
         next.from.toLowerCase() === reviewed.from.toLowerCase() && next.to.toLowerCase() === reviewed.to.toLowerCase() &&
-        next.data.toLowerCase() === reviewed.data.toLowerCase() && next.value === reviewed.value;
+        next.data.toLowerCase() === reviewed.data.toLowerCase() && next.value === reviewed.value &&
+        (reviewed.nonce === undefined || next.nonce === reviewed.nonce);
 }
 function assertReviewedTransactionUnchanged(options, reviewed, next) {
     if (options.planned.ufg !== undefined)
@@ -297,9 +299,15 @@ export async function prepareAndPlanLifecycleLaunch(options) {
     const { commitment, ufgConfigHash } = validatePlanningIntent(options);
     if (options.buySlippageBps !== undefined)
         validateBuySlippageBps(options.buySlippageBps);
+    const fixed = options.fixedFinalEnvelope;
+    if (fixed !== undefined && (fixed === null || typeof fixed !== "object" || options.mode !== "atomic" || typeof fixed.gas !== "bigint" || fixed.gas <= 0n || fixed.gas >= 1n << 64n ||
+        fixed.gasPrice !== undefined && (typeof fixed.gasPrice !== "bigint" || fixed.gasPrice < 0n || fixed.gasPrice >= 1n << 256n))) {
+        throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope requires atomic mode, exact positive uint64 gas and optional uint256 price");
+    }
+    const heldEnvelope = fixed === undefined ? undefined : Object.freeze({ ...fixed });
     const needsMining = options.plan.markets.some((market) => isPoolBoundV4ConfigVersion(market.configVersion));
     const needsProtection = options.buySlippageBps !== undefined && options.plan.buys.length !== 0;
-    if (!needsMining && !needsProtection)
+    if (!needsMining && !needsProtection && fixed === undefined)
         return planLaunch(options);
     const draft = parseLaunchPlan(serializeLaunchPlan(options.plan));
     const assertDraft = () => {
@@ -308,8 +316,11 @@ export async function prepareAndPlanLifecycleLaunch(options) {
             throw new LifecyclePlanningError("PLAN_MUTATED", "Economic plan changed during asynchronous preparation; previous construction is invalid");
         if ((options.ufg === undefined ? undefined : hashUfgLaunchConfig(options.ufg.config)) !== ufgConfigHash)
             throw new LifecyclePlanningError("PLAN_MUTATED", "UFG config changed during asynchronous preparation");
+        if (fixed === undefined ? options.fixedFinalEnvelope !== undefined : options.fixedFinalEnvelope !== fixed ||
+            fixed.gas !== heldEnvelope.gas || fixed.gasPrice !== heldEnvelope.gasPrice)
+            throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope changed during preparation");
     };
-    return withLifecycleReadClient(options.client, async (client) => {
+    const result = await withLifecycleReadClient(options.client, async (client) => {
         const [block, chainId] = await Promise.all([readLifecycleBlock(client), readLifecycleChainId(client)]);
         if (chainId !== draft.chainId)
             throw new LifecyclePlanningError("CHAIN_MISMATCH", "RPC chain differs from the economic plan being finalized");
@@ -337,13 +348,19 @@ export async function prepareAndPlanLifecycleLaunch(options) {
         // start at a fresh post-mining snapshot and share it through final protection.
         const executionBlock = needsMining ? await readLifecycleBlock(client) : block;
         assertDraft();
+        const price = heldEnvelope === undefined ? undefined : heldEnvelope.gasPrice ?? rpcQuantity(await readLifecycleGasPrice(client), "gas price");
+        const baseFeeEnvelope = (executionBlock.baseFeePerGas ?? 0n) * 2n;
+        const finalEnvelope = heldEnvelope === undefined ? undefined : Object.freeze({
+            gas: heldEnvelope.gas,
+            gasPrice: heldEnvelope.gasPrice ?? (price > baseFeeEnvelope ? price : baseFeeEnvelope),
+        });
         let plan = { ...draft, markets };
         let ownedProgress;
         if (needsProtection) {
             // A diagnostic minimum is never returned as an admitted or executable plan.
             // Price guards, funding minima, recipients and all ordered budgets stay exact.
             const diagnosticPlan = { ...plan, buys: plan.buys.map((buy) => ({ ...buy, minTokenOut: 1n })) };
-            const diagnostic = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan: diagnosticPlan }, client, executionBlock, undefined, true));
+            const diagnostic = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan: diagnosticPlan }, client, executionBlock, undefined, true, undefined, finalEnvelope));
             assertDraft();
             if (diagnostic.progress.canonical.phase !== LifecyclePhase.None || diagnostic.progress.head.phase !== LifecyclePhase.None)
                 throw new LifecyclePlanningError("LAUNCH_ALREADY_STARTED", "Buy protection cannot replace an already committed launch plan");
@@ -352,7 +369,7 @@ export async function prepareAndPlanLifecycleLaunch(options) {
             // state. No onchain commitment existed at this exact snapshot to replace.
             ownedProgress = { ...diagnostic.progress, planHash: hashLaunchPlan(plan) };
         }
-        const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan }, client, executionBlock, ownedProgress));
+        const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads({ ...options, plan }, client, executionBlock, ownedProgress, false, undefined, finalEnvelope));
         assertDraft();
         assertFinalPlan(planned, options.signal);
         if (planned.progress.canonical.phase !== LifecyclePhase.Active && planned.progress.canonical.phase !== LifecyclePhase.Cancelled) {
@@ -366,16 +383,21 @@ export async function prepareAndPlanLifecycleLaunch(options) {
             throw new LifecyclePlanningError("PROTECTED_PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The final protected launch did not establish exact execution proof", planned.simulation);
         return planned;
     });
+    assertDraft();
+    assertFinalPlan(result, options.signal);
+    return result;
 }
 /** Independently fresh current-state admission of an already finalized commitment. No broadcasts. */
 export async function planLaunch(options) {
-    return withLifecycleReadClient(options.client, async (client) => {
+    const result = await withLifecycleReadClient(options.client, async (client) => {
         const planned = await lifecycleStage(client, "plan", () => planLaunchWithReads(options, client));
         assertFinalPlan(planned, options.signal);
         return planned;
     });
+    assertFinalPlan(result, options.signal);
+    return result;
 }
-async function planLaunchWithReads(options, client, pinnedBlock, ownedProgress, diagnostic = false, reviewed) {
+async function planLaunchWithReads(options, client, pinnedBlock, ownedProgress, diagnostic = false, reviewed, fixedFinalEnvelope) {
     const { plan, account, mode, ufg } = options;
     const { commitment: planHash, marketConfigs, ufgConfigHash } = validatePlanningIntent(options);
     const launchId = hashLaunchIdentity(plan);
@@ -400,7 +422,10 @@ async function planLaunchWithReads(options, client, pinnedBlock, ownedProgress,
         preset ?? readTokenFactoryBinding(client, plan.orchestrator, block),
         resolveLifecycleLimits({ client, account, orchestrator: plan.orchestrator, block, chainId: plan.chainId }, options.limits),
         lifecycleStage(client, "plan.progress", async () => {
-            const predictedToken = await readLifecycleTokenAtBlock(client, plan, block);
+            const [predictedToken] = await Promise.all([
+                readLifecycleTokenAtBlock(client, plan, block),
+                ownedProgress === undefined ? readLifecycleHeadProgress(client, plan, account, block) : undefined,
+            ]);
             const identity = { plan, planHash, launchId, predictedToken, account, mode, confirmations: options.confirmations ?? 1,
                 ...(ufg === undefined ? {} : { ufg: { config: ufg.config, configHash: ufgConfigHash } }) };
             if (ufg !== undefined)
@@ -459,6 +484,9 @@ async function planLaunchWithReads(options, client, pinnedBlock, ownedProgress,
         batches = [...(prepared > 0 ? [prepared] : []), count, ...(start + count < plan.markets.length ? [plan.markets.length - start - count] : [])];
     }
     let transactions = orderedTransactions(plan, mode, progress, funding.approvals, batches, ufg);
+    if (fixedFinalEnvelope !== undefined && (transactions.length !== 1 || transactions[0].kind !== "atomic")) {
+        throw new LifecyclePlanningError("INVALID_GAS_ENVELOPE", "Fixed final envelope requires one immediate atomic launch with no preceding approvals");
+    }
     if (reviewed !== undefined) {
         if (!matchesReviewedNextTransaction(transactions[0], reviewed))
             throw new LifecyclePlanningError("REVIEWED_TRANSACTION_MISMATCH", "Reviewed transaction differs from the current canonical unfinished next step");
@@ -468,9 +496,10 @@ async function planLaunchWithReads(options, client, pinnedBlock, ownedProgress,
         await assertLifecycleBlock(client, block, plan.chainId);
         return { ...planned, simulation: { ...placeholder, confidence: "stateful", reason: metadata.reasons.join("; "), failureCategory: "semantic" }, transactions, totalCalldataBytes: transactions.reduce((total, transaction) => total + (transaction.data.length - 2) / 2, 0) };
     }
-    const preparedSimulation = prepareLaunchSimulation({ client, planned, limits: options.limits, fork: options.fork, signal: options.signal }, block, true, reviewed);
+    const envelope = diagnostic ? undefined : reviewed ?? fixedFinalEnvelope;
+    const preparedSimulation = prepareLaunchSimulation({ client, planned, limits: options.limits, fork: options.fork, signal: options.signal }, block, true, envelope, fixedFinalEnvelope?.gasPrice);
     try {
-        const execute = diagnostic ? preparedSimulation.measure : (candidate) => preparedSimulation(candidate, reviewed);
+        const execute = diagnostic ? preparedSimulation.measure : (candidate) => preparedSimulation(candidate, envelope);
         let simulation = await execute(transactions);
         assertFinalPlan(planned, options.signal);
         if (mode === "staged") {
@@ -523,6 +552,7 @@ async function preflightNextTransaction(options, next, simulation, reviewed) {
             throw new Error("Active submission RPC chain differs from the reviewed transaction");
         const estimated = rpcQuantity(await lifecycleRpc(submissionClient, "eth_estimateGas", [{
                 from: next.from, to: next.to, data: next.data, value: toHex(next.value), gas: toHex(next.gas), gasPrice: toHex(next.gasPrice),
+                ...(next.nonce === undefined ? {} : { nonce: toHex(next.nonce) }),
             }, "latest"]), "submission gas estimate");
         if (estimated <= 0n || estimated > next.gas)
             throw new Error("Submission RPC gas estimate exceeds the exact reviewed envelope or is zero");
@@ -536,14 +566,6 @@ async function preflightNextTransaction(options, next, simulation, reviewed) {
         const reason = `Exact next-transaction submission preflight failed: ${lifecycleFailureReason(failure)}`;
         throw new LifecyclePlanningError("SUBMISSION_PREFLIGHT_FAILED", reason, { ...simulation, transportPreflight: "failed", reason });
     }
-    const [canonical, chainId] = await Promise.all([
-        readLifecycleBlock(options.client, toHex(simulation.blockNumber)),
-        lifecycleRpc(options.client, "eth_chainId"),
-    ]);
-    if (canonical.hash.toLowerCase() !== simulation.blockHash.toLowerCase())
-        throw new LifecyclePlanningError("STATE_REORGED", "Pinned launch proof changed during submission preflight; rebuild from canonical progress");
-    if (rpcQuantity(chainId, "chain ID") !== simulation.chainId)
-        throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during submission preflight");
     if (next.admission === undefined)
         throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Next transaction omitted its exact simulation admission", simulation);
     assertPlanningActive(options.signal);
@@ -557,9 +579,17 @@ export async function buildNextTransaction(options) {
     // Snapshot only the reviewed wire fields; caller proofs and commands are never
     // reused, and final checks compare the mutable input with this one local copy.
     const reviewed = supplied === undefined ? undefined : Object.freeze({ id: supplied.id, kind: supplied.kind, chainId: supplied.chainId,
-        from: supplied.from, to: supplied.to, data: supplied.data, value: supplied.value, gas: supplied.gas, gasPrice: supplied.gasPrice });
-    return withLifecycleReadClient(options.client, async (client) => {
+        from: supplied.from, to: supplied.to, data: supplied.data, value: supplied.value, gas: supplied.gas, gasPrice: supplied.gasPrice, nonce: supplied.nonce });
+    const result = await withLifecycleReadClient(options.client, async (client) => {
         const block = await readLifecycleBlock(client);
+        const limitSource = options.limits === undefined ? options.planned.limits : options.limits;
+        if (getKnownLifecycleDeployment({ chainId: options.planned.chainId, orchestrator: options.planned.plan.orchestrator }) !== undefined && typeof limitSource !== "function") {
+            await Promise.all([
+                readLifecycleTokenAtBlock(client, options.planned.plan, block),
+                readLifecycleHeadProgress(client, options.planned.plan, options.planned.account, block),
+                resolveLifecycleLimits({ client, account: options.planned.account, orchestrator: options.planned.plan.orchestrator, block, chainId: options.planned.chainId }, limitSource),
+            ]);
+        }
         const progress = await readLaunchProgress({ ...options, client }, block);
         if (progress.canonical.phase === LifecyclePhase.Active || progress.canonical.phase === LifecyclePhase.Cancelled) {
             // Only the confirmed canonical terminal phase is terminal; a head-only
@@ -580,6 +610,7 @@ export async function buildNextTransaction(options) {
             assertFinalPlan(planned, options.signal);
             const transaction = planned.ufg !== undefined ? buildUfgCancelTransaction({ plan: planned.plan, preparedMarkets: progress.canonical.preparedMarkets })
                 : { id: "cancel", kind: "cancel", chainId: Number(planned.chainId), from: planned.account, to: planned.plan.orchestrator, data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "cancelLaunch", args: [planned.plan] }), value: 0n, dependencies: [], postconditions: [{ kind: "launch", phase: "Cancelled", preparedMarkets: progress.canonical.preparedMarkets }] };
+            transaction.nonce = progress.pendingAccountNonce;
             if (reviewed !== undefined && !matchesReviewedNextTransaction(transaction, reviewed))
                 throw new LifecyclePlanningError("REVIEWED_TRANSACTION_MISMATCH", "Reviewed transaction differs from the current canonical cancellation");
             const simulation = await simulateLaunchTransactions({ client, planned, limits: options.limits === undefined ? planned.limits : options.limits, fork: options.fork, signal: options.signal }, [transaction], block, reviewed);
@@ -601,6 +632,10 @@ export async function buildNextTransaction(options) {
             return undefined;
         return preflightNextTransaction(options, next, refreshed.simulation, reviewed);
     });
+    assertFinalPlan(options.planned, options.signal);
+    if (result !== undefined)
+        assertReviewedTransactionUnchanged(options, reviewed, result);
+    return result;
 }
 /** Re-simulates only canonical unfinished work with the same submitted receipt
  * evidence and confirmation depth as build-next, never silently dropping context. */