@black-market/sdk 0.14.0 → 0.15.0

package/docs/launch-lifecycle.md

@@ -1,6 +1,6 @@
 # Launch a token with the TypeScript SDK
 
-Use SDK **0.14.0** on Robinhood Chain mainnet (**4663**). For a first launch, run
+Use SDK **0.14.1** on Robinhood Chain mainnet (**4663**). For a first launch, run
 [`launch-erc20-abyss.ts`](../examples/launch-erc20-abyss.ts): one market, one position,
 one buy. [Runner setup](../examples/README.md) covers its environment and commands.
 This guide explains the economics and the public APIs for your own integration.
@@ -188,15 +188,15 @@ examples; it does not predict the impact of a $100 or $1,000 buy.
 A larger buy traverses ranges and can acquire a large share of supply.
 
 `prepareAndPlanLifecycleLaunch({ buySlippageBps: 50 })` derives every ordered buy's
-minimum from stateful diagnostic output, then proves the final protected commitment:
+minimum from the covered exact local curve model or native diagnostic output:
 
 ```text
-minTokenOut = floor(simulatedTokenOut × (10000 - buySlippageBps) / 10000)
-50 bps: floor(simulatedTokenOut × 9950 / 10000)
+minTokenOut = floor(tokenOut × (10000 - buySlippageBps) / 10000)
+50 bps: floor(tokenOut × 9950 / 10000)
 ```
 
-This requires activation inside the simulated prefix. The option accepts 0–9,999
-bps and applies only before begin; omitting it preserves your committed minima.
+Native calibration requires activation in the complete executed sequence. The
+option accepts 0–9,999 bps and applies only before begin; omission preserves minima.
 A 1-wei minimum is effectively unprotected. Never submit the diagnostic draft.
 A Kyber conversion minimum protects ETH→quote output, not quote→launch-token output.
 
@@ -204,7 +204,7 @@ A Kyber conversion minimum protects ETH→quote output, not quote→launch-token
 Its `slippageBps` accepts 1–9,999 (default 50). It may stop a buy early; check partial
 fills and refunds. It does not calculate minimum token output.
 `estimateLaunchInitialBuy` is a pure single-position estimate, not a model of
-multi-band traversal, prior buys, or hook execution. Use exact simulation for signing.
+multi-band traversal, prior buys, or hook execution. Use the ordered model or native calibration.
 Final valuation uses the retained supply after burn and the observed post-buy price.
 
 ## Build the plan
@@ -319,97 +319,94 @@ saved deadline or replace committed conversion bytes after begin.
 
 Staging is not rollback. A begun plan remains begun after its deadline until cancelled.
 Activation cannot be split into separate position mints or buys.
-The SDK never switches your requested mode or removes markets to make it fit.
+An atomic request is a preference: conservative capacity bounds or an actual atomic capacity failure may select staged. Explicit staged stays staged. No markets or buys are removed. Review and persist returned `planned.mode`.
 
 | Operation | Options type / purpose |
 | --- | --- |
-| `prepareAndPlanLifecycleLaunch` | `PrepareAndPlanLifecycleLaunchOptions`: `client`, `account`, `plan`, `mode`; optional `ufg: { config }`, `buySlippageBps`, `fixedFinalEnvelope`, `limits`, `fork`, `receipts`, `confirmations`, `signal`, `onProgress`, topology opt-outs. |
+| `prepareAndPlanLifecycleLaunch` | `PrepareAndPlanLifecycleLaunchOptions`: `client`, `account`, `plan`, `mode`; optional `ufg: { config }`, `buySlippageBps`, `limits`, `fork`, `receipts`, `confirmations`, `signal`, `onProgress`, topology opt-outs. |
 | `planLaunch` | `PlanLaunchOptions`: same execution context, including optional `ufg: { config }` and `signal`; re-admits an already-finalized plan without changing salts/minima. |
 | `simulateLaunchPlan` | `client`, `planned`; optional `limits`, `fork`, `receipts`, `confirmations`, `signal`. |
 | `readLaunchProgress` | `client`, `planned`; optional `receipts`, `confirmations`, `signal`. |
-| `buildNextTransaction` | Progress options, plus optional `action`, `limits`, `fork`, `submissionClient`, `reviewedTransaction`. |
+| `buildNextTransaction` | Progress options, plus optional `action`, `limits`, `fork`, `reviewedTransaction`. |
 
 `buildLaunchTransactions` compiles unsigned commands; it does not prove execution.
-Persist `serializeLaunchPlan(planned.plan)`, mode, confirmation policy, receipt
-references, and UFG config if applicable. `parseLaunchPlan` restores bigint values.
+Persist `serializeLaunchPlan(planned.plan)`, returned `planned.mode`, confirmation policy,
+receipt references, and UFG config if applicable. `parseLaunchPlan` restores bigint values.
 Do not serialize the entire `PlannedLaunch`, which can contain live limit callbacks.
 
-Robinhood proof requires native Nitro `eth_simulateV1`. A generic Anvil/Hardhat fork
-can exercise EVM behavior but cannot certify Nitro compute/poster accounting.
-The default aggregate proof window is **50M used gas**, not a per-transaction ceiling.
-Inspect `simulation.deferredTransactionIds` even when `simulation.admitted` is true:
-admission can cover only a prefix. Deferred steps have no gas, price, or admission.
-Buy-output calibration refuses a deferred activation. Start with one market; raise
-`limits.maxSimulationGas` only with a provider that supports the larger window.
-
-The full simulated prefix still checks whether later staged commands can execute.
-Only its immediate command receives a final gas/price/estimate/admission. Later
-`simulation.steps` have `provisional: true`: their conservative, affordable
-`gasLimit` is a feasibility budget, not a transaction estimate. Their unsigned
-commands have no gas/price/estimate/admission until `buildNextTransaction` obtains
-a fresh poster quote, sizes that command and validates its exact returned envelope.
-Calibration and separable prior compute observations size proposals, never admission.
-Without one, unvalidated sizing uses affordable per-call ceilings. Only an upfront
-funds refusal permits one second unvalidated attempt sharing the remaining budget.
-No semantic, HTTP or cancellation failure retries, and the final exact validated
-pass never retries or changes its returned gas.
+Every launch step uses the native total transaction ceiling:32M on4663, including
+poster gas. Approvals omit gas/fees for wallet preparation. Covered Robinhood
+ArbOS61 templates use capacity bounds and exact local ordered-buy math, never
+component-sized gas limits. Their evidence is `profiled` / `not-run`, not a receipt.
+Conversion-carrying begin/atomic and consuming activation require exact native
+execution. Unknown coverage or uncertain activation gets full-sequence execution
+before begin. Explicit `simulateLaunchPlan` always executes; a generic fork is not Nitro proof.
+
+Review checks the complete sequence, not just a successful prefix. There is no
+SDK-invented 50M aggregate cap. A caller `maxSimulationGas` still tightens policy;
+incomplete execution proof refuses admission. A refused full review cannot begin
+a new launch. Only the immediate command receives final gas/price/estimate/admission.
+Suffix metrics remain provisional; build-next admits only the canonical next command
+at its fresh native-ceiling budget, never reusing a provisional estimate.
+
+See [capacity, native/fork evidence and migration](lifecycle-gas-profiles.md)
+for exact proof fields, upfront affordability and the public capacity-bound helper.
 
 Review the returned final plan/hash, aligned price, burn, retained supply, fees,
 ordered buy outputs/minima, funding, refunds, and complete gas envelope. A fresh
-`buildNextTransaction` proves the immediate next step as canonical progress advances.
-`submissionClient` adds read-only exact-envelope preflight on the sending RPC.
+`buildNextTransaction` admits the immediate next step as canonical progress advances.
+The wallet owns sending-RPC preparation; `submissionClient` has been removed.
 
-`planned.transactions[0]` already contains the immediate exact `from/to/data/value`,
-`nonce`, `gas` and `gasPrice` when that step has admitted execution proof. There is
-no need for another unreviewed build just to discover its envelope. The envelope
-is reviewable and reusable; its block-bound admission is historical, not permission
+`planned.transactions[0]` contains exact immediate `from/to/data/value` and, for
+launch commands, native-ceiling `gas` and current `gasPrice`. Approvals omit both.
+There is no fixed wallet nonce; the wallet assigns it. The plan identity nonce is unchanged.
+The envelope is reusable, but its block-bound admission is historical, not permission
 to sign later. Pass it as `reviewedTransaction` for fresh immediate admission after
-review or recovery. This is execution revalidation, not a second user review gate.
+review or recovery. This is not a second user review gate.
 Reuse `planned.progress` for the same result's display instead of reading progress
 independently beside the plan.
 
-For an atomic caller with a chosen final gas envelope, prepare with
-`fixedFinalEnvelope: { gas: 31_000_000n }`. This is an explicit chosen gas amount,
-not a universal gas recommendation. `limits.accountGasLimit` remains only a ceiling.
-The option accepts exactly one immediate atomic command with no approval prefix;
-staged mode and approval-first shapes refuse it. Diagnostic and final protection
-share one frozen fee recommendation. Supplying `gasPrice` holds that fee exactly;
-it is never bumped to obtain admission. The final protected calldata still receives
-one natural-child-fee validated replay at the exact chosen envelope. Failure never
-enlarges it or switches mode.
+`fixedFinalEnvelope` and `LifecycleFinalEnvelope` are removed. A reviewed launch gas
+that differs from the native ceiling refuses with `STALE_REVIEWED_GAS`; re-review,
+never silently rewrite it. A lower caller complete-envelope cap refuses rather than
+shrinking gas. Held prices below the pinned fee floor also refuse without bumping.
+On Nitro the floor is max(ArbGasInfo L2 price, header base fee); twice base fee is
+fresh recommendation headroom only. Reserve value plus ceiling×price, without
+adding poster fees again. Actual activation capacity refusal asks the user to
+reduce positions/pools; a large conservative bound alone is not such a refusal.
 
 On chain4663, one RPC L2 header pins the invocation. Token prediction, native/token
-balances, allowances, launch progress and Nitro getters share one Multicall3 call
+balances, allowances, launch progress, Nitro getters and prices share one Multicall3 call
 at that explicit L2 block. Further independent stages use one aggregate, even for
 one or two reads. Multicall3's block-number/hash getters expose L1 values on Nitro
 and must not select the L2 pin.
 The same pin survives salt mining and buy calibration; there are no final chain or
 canonical-header guard reads. Receipt confirmation/reorg checks remain.
 
-Final measurement validates the exact calldata once; there is no later exact-gas
-replay. Poster allocation is estimated only for the immediate final command.
-`buildNextTransaction` preserves the original staged batch spans and proves only
-the next command, rather than simulating the whole remaining launch.
+Required native execution validates the exact calldata once; there is no later
+exact-gas replay. Poster allocation comes from the same-review price tuple and a
+local size bound, not a per-transaction oracle. Build-next encodes only its canonical
+next command, preserving normal/UFG calldata and original/clipped batch spans.
 
 Multicall3 runtime, Nitro backend capability and account-code observations are
-retained for the caller's session. Financial state and execution proof are not.
+retained for the caller's session. Chain identity is observed once per bound client;
+recreate the client on chain changes. Financial state and required proof stay fresh.
 The 4663 preset uses the deployed `hookSaltMiner`; returned salts are verified
-locally. The optional `launchLens` preset is unset in this release. Once deployed,
-its address enables dependent progress, market, balance and hook-mining reads in
-the same initial aggregate. See [read caching](reference.md#cache-static-reads-and-inspect-timing).
+locally. Its deployed `launchLens` supplies dependent progress, market, balance
+and hook-mining reads in the same initial aggregate. Callers need no lens
+configuration. See [read caching](reference.md#cache-static-reads-and-inspect-timing).
 
 ## Sign and confirm
 
 Call `buildNextTransaction` before **every signature**, including approvals and
-cancellation. For a reviewed command, pass `reviewedTransaction` so the SDK replays
-the same gas/fee/nonce rather than rediscovering it. Send the exact returned
-`from/to/data/value/nonce/gas/gasPrice` with a matching explicit viem chain.
+cancellation. Pass `reviewedTransaction` to hold the same gas/fee and intent, not a
+wallet nonce. Send the exact returned `from/to/data/value/gas/gasPrice`.
 `confirmations` defaults to 1; choose and retain your policy before begin.
-SDK affordability is observed at block B, not at the provider's pending state.
-Immediately before signing, the host must freshly compare pending nonce and
-balance with this exact envelope and verify the active provider account/chain
-after asynchronous work. Changed identity, nonce, intent or insufficient pending
-funds blocks the signature; never overwrite the reviewed nonce or replay a write.
+The wallet owns its queue, nonce assignment and sending-RPC preparation. Unrelated
+pending transactions are not an SDK confirmation-safety refusal. Retain the actual
+submitted nonce and let the wallet advance locally; unknown reload recovery may
+need one host-owned queue read, never a per-plan nonce gate. Check the active wallet
+account/provider chain after asynchronous work, and never automatically replay a write.
 The following local-account loop signs only when explicitly called by your application.
 Use a new owner-only journal path inside a private directory; on reload, restore the
 original plan and receipt references before calling it. Journal records contain secrets.
@@ -437,7 +434,7 @@ export async function executeLaunch(
     confirmations: planned.confirmations, ufg: planned.ufg, receipts });
   for (;;) {
     const next = await buildNextTransaction({
-      client, planned, receipts, submissionClient: client,
+      client, planned, receipts,
     });
     if (!next) {
       const progress = await readLaunchProgress({ client, planned, receipts });
@@ -448,29 +445,21 @@ export async function executeLaunch(
       }
       return { progress, activationHash };
     }
-    if (!next.admission?.admitted || next.gas === undefined || next.gasPrice === undefined) {
+    const approval = next.kind === "approve" || next.kind === "approve-reset";
+    if (!next.admission?.admitted || !approval && (next.gas === undefined || next.gasPrice === undefined)) {
       throw new Error("Immediate transaction is not admitted");
     }
-    const [nonce, pendingBalance] = await Promise.all([
-      client.getTransactionCount({ address: next.from, blockTag: "pending" }),
-      client.getBalance({ address: next.from, blockTag: "pending" }),
-    ]);
-    const dataFee = next.estimate?.dataFee;
-    if (next.nonce === undefined || BigInt(nonce) !== next.nonce || dataFee === undefined
-      || pendingBalance < next.value + next.gas * next.gasPrice + dataFee) {
-      throw new Error("Pending nonce or complete affordability changed; revalidate");
-    }
+    const request = await wallet.prepareTransactionRequest({
+      chain: wallet.chain, account: wallet.account,
+      to: next.to, data: next.data, value: next.value, gas: next.gas, gasPrice: next.gasPrice,
+    });
     const [address] = await wallet.getAddresses();
     if (wallet.chain.id !== next.chainId || await wallet.getChainId() !== next.chainId
-      || await client.getChainId() !== next.chainId
       || address?.toLowerCase() !== next.from.toLowerCase()
       || wallet.account.address.toLowerCase() !== planned.account.toLowerCase()) {
       throw new Error("Wallet account or chain changed");
     }
-    const raw = await wallet.signTransaction({
-      chain: wallet.chain, account: wallet.account, nonce,
-      to: next.to, data: next.data, value: next.value, gas: next.gas, gasPrice: next.gasPrice,
-    });
+    const raw = await wallet.signTransaction(request);
     const hash = keccak256(raw);
     await record({ transactionId: next.id, kind: next.kind, hash, raw });
     const sent = await client.sendRawTransaction({ serializedTransaction: raw });
@@ -483,7 +472,7 @@ export async function executeLaunch(
       throw new Error("Reverted or replaced transaction; reconcile before continuing");
     }
     receipts.push({ transactionHash: hash, confirmations: planned.confirmations,
-      observedBlockNumber: receipt.blockNumber, observedBlockHash: receipt.blockHash });
+      nonce: BigInt(request.nonce), observedBlockNumber: receipt.blockNumber, observedBlockHash: receipt.blockHash });
     if (next.kind === "atomic" || next.kind === "activate") activationHash = hash;
     await record({ receipts, activationHash });
   }
@@ -494,7 +483,7 @@ A send timeout is ambiguous: the hash may already be mined. Stop, query the save
 hash, and reconcile pending nonce/receipt state; do not automatically resend.
 For an interactive review delay, pass the previously displayed command as
 `reviewedTransaction` to a fresh `buildNextTransaction` before signing.
-That directly replays the same immediate envelope at its held nonce, gas and gas price.
+That revalidates the same immediate intent at its held gas/fee; the wallet owns its nonce.
 
 Completion has **four checks**: receipt confirmed → markets active → metadata
 published → API indexed. A successful transaction alone does not establish the last two.

package/docs/lifecycle-gas-profiles.md

@@ -0,0 +1,90 @@
+# Lifecycle gas, capacity, execution evidence and RPC budgets
+
+Version 0.15.0 separates the native transaction ceiling, conservative capacity bounds, exact curve quotes and actual execution proof. A local quote or submitted hash is not an execution receipt.
+
+## One native ceiling, not component-sized gas
+
+Every launch command (begin, prepare, activate, atomic and cancel) uses the chain's native total transaction ceiling. On Robinhood4663 this is `ROBINHOOD_NATIVE_TRANSACTION_GAS_LIMIT = 32_000_000n`, also exposed as `getKnownLifecycleDeployment({ chainId, orchestrator }).nativeTransactionGasLimit`. The32M includes poster gas. Other chains retain their resolved generic ceiling.
+
+Unused gas is refunded. The payer must still reserve `value + gasLimit * gasPrice` upfront. The SDK never shrinks the ceiling to accommodate a tight balance, adds poster gas to32M, or retries with a smaller envelope. Approvals/reset approvals are not launch steps: their returned `gas`, `gasPrice` and estimates are omitted for wallet preparation.
+
+A reviewed launch gas differing from the ceiling is stale and refuses with `STALE_REVIEWED_GAS`; re-review rather than silently rewriting it. A caller complete-envelope cap below the ceiling refuses too. `fixedFinalEnvelope`, `LifecycleFinalEnvelope`, stored compute-sizing hints and unvalidated gas-sizing retries are removed.
+
+## Capacity selects the mode, not the gas limit
+
+`computeLifecycleLaunchGasBounds({ plan, predictedToken, ufg?, headroomBps? })` returns conservative `atomicComputeGasUpperBound` and `activationComputeGasUpperBound`, excluding poster gas, or undefined for unknown coverage. The versioned model accounts for token/reward creation, actual UFG proxy/treasury route, market/position work, ordered buys, NFT minting and HMM forwarding overhead. UFG route overhead is independent of market profile names.
+
+An atomic request is a preference. A conservative atomic bound plus poster allocation above the ceiling selects staged; explicit staged remains staged. An actual atomic capacity failure can also select staged with fresh full-sequence admission. Review and persist returned `planned.mode`, not the requested mode. No positions, markets or buys are dropped.
+
+A large conservative activation upper bound is uncertainty, not proof of overflow. Uncertain activation receives exact full-sequence execution before begin. An actual activation capacity failure returns `capacityConstraint: "activation"` and asks the user to reduce positions/pools; staging cannot split activation. For example, an independently observed24-position activation fit32M despite a larger conservative upper bound, while a32-position deep Abyss activation needed a47.48M minimum successful envelope. Neither observation licenses a universal count-only hard cap.
+
+## Which admission path runs
+
+| Command | Covered direct plan with proven-fit activation | Plan containing an aggregator conversion |
+| --- | --- | --- |
+| Approval/reset | Wallet prepares gas/fees | Wallet prepares gas/fees |
+| Begin | Conditional template admission | Exact native execution of the conversion |
+| Prepare markets/hooks | Conditional template admission | Conditional admission when isolated after begin |
+| Activate and opening buys | Conditional admission and exact local curve math | Exact native execution consuming conversion funding |
+| Atomic launch | Conditional admission and exact local curve math | Exact native execution of the complete transaction |
+| Cancel | Conditional admission | Conditional admission when isolated |
+
+A conversion review proves the complete staged sequence through activation in one validated `eth_simulateV1` call, with every launch call at32M. Unknown template/currency coverage, another chain/ArbOS epoch or uncertain activation also uses real execution. A refused full review cannot authorize a new begin from a successful prefix; already-started recovery and cancellation remain available. Explicit `simulateLaunchPlan` always requests execution. A generic EVM fork is not Nitro protocol proof.
+
+Unknown curve behavior retains a separate provisional, unvalidated buy-output diagnostic at the same ceiling before protecting minima. It is not gas sizing, final admission or a retry. The final protected commitment still requires its exact execution. There is no SDK-invented50M aggregate window; explicit `maxSimulationGas` policies remain enforced against complete observed work without prefix admission.
+
+### Honest result fields
+
+- Conditional admission: `backend/confidence: "profiled"`, `executionProof: "not-run"`, `protocolFit: "profiled"`. `gasProfile` carries `version`, capacity `bounds` and local `initialBuys`, not per-step estimates or fabricated receipts.
+- The immediate fixed-ceiling budget is `simulation.estimate`, with `feeConfidence: "native-ceiling-and-data"` and no invented `gasUsed`. Approval budgets are absent.
+- Successful exact native execution reports `backend: "eth_simulateV1"`, `executionProof: "proved"`, `protocolFit: "proved"` after required postconditions.
+- Only an immediate launch command receives final gas/price/estimate/admission. Exact suffix steps remain `provisional: true` with no executable estimate. Build-next constructs only the canonical next command at a fresh pin; it never treats a suffix observation as an estimate.
+
+## Retained empirical evidence
+
+`robinhood-4663-arbos61-v1` covers shipped Abyss configuration-v1 and current pool-bound V4 configuration-v6 templates, including HMM/UFG, on ArbOS61 with an EOA payer and known release quote implementations. This is capacity coverage, not a currency admission allowlist. Unknown currencies remain supported through exact execution; smart-account proof is not claimed.
+
+Research retained176 lifecycle receipts, including75 successful current-template atomic/activation observations with opening buys. Isolated forks extend depth, buys and combinations; failed CREATE2 cases were not counted as successful coverage. One Abyss and one fixed-V4 historical native/fork calibration matched compute exactly (19,272,603 and18,130,251 gas), while minimum successful envelopes were higher (20,527,230 and19,356,279). These two calibrations do not establish general Anvil/Nitro equivalence. Compute and poster components remain separate. Profiles are empirical capacity bounds, never transaction gas sizing or proof about arbitrary upgrades/future ArbOS rules.
+
+## Exact ordered opening-buy math
+
+`computeLifecycleOpeningBuys({ plan, predictedToken })` follows all liquidity bands, prior buys, initialized zero-net ticks, bitmap boundaries, both currency directions, LP/opening-hook fees, partial fills and integer output floors. HMM opening work occurs after initial buys. V4's zero price-limit sentinel resolves locally to the contract-defined directional limit without changing calldata; Abyss still rejects zero.
+
+Covered `buySlippageBps` protection uses `floor(tokenOut * (10000 - bps) / 10000)`. A zero floor rejects, never becomes1. Independent parity matched token output, quote spent and final square-root price across97 native/fork cases, including both directions, overlapping bands and gaps. Portable historical vectors and focused rounding/sentinel cases live under `test/fixtures/lifecycle-opening-buys.json` and `test/lifecycle-opening-buys.test.mjs`. These conditional curve quotes do not prove conversion, funding or wallet submission.
+
+## One same-review Nitro price observation
+
+The initial L2-pinned aggregate includes `ArbGasInfo.getPricesInWei`. There are no per-transaction `NodeInterface.gasEstimateL1Component` calls or separate4663 `eth_gasPrice` calls. Tuple element1 supplies L1 per-byte price; element5 supplies L2 price. Fresh gas price is max(L2 price, twice header base fee). A held price must meet max(L2 price, header base fee), but is not bumped to the fresh recommendation.
+
+For empty-access-list EOA legacy calldata of `D` bytes:
+
+```text
+N = D + 384
+B = N + 8 * floor(N / 1024) + 64
+posterFeeBound = B * l1PricePerByte
+posterGas = 2 * ceil(posterFeeBound / l2GasPrice)
+```
+
+The local serialization/Brotli bound and2x allocation are conservative, not an observation of the eventual compressed signature or a promise about future L1 prices. Poster stays inside32M. `dataFeeIncludedInGas` is true, `dataFee` is zero and `totalFee = gasLimit * gasPrice`; never add poster fee again.
+
+## 0.15.0 caller migration
+
+- Wallet nonce is absent from unsigned `LifecycleTransaction`; `LaunchPlanV1.nonce` remains its domain identity. Let the wallet assign send nonce. Learn actual nonce from wallet/transaction, retain optional exact `LifecycleReceiptReference.nonce`, and advance the wallet-owned queue locally. A supplied nonce mismatch refuses receipt attribution. Portable journals use decimal strings, not JSON numbers.
+- Progress has no confirmed/head/pending account nonce gates. Unrelated pending transactions are queued by the wallet, not an SDK confirmation-safety refusal. Planning/build-next make no `eth_getTransactionCount`; unknown reload recovery may need one host-owned read.
+- `BuildNextTransactionOptions.submissionClient` and proof `transportPreflight` are removed. Keep wallet account/provider-chain checks and never automatically replay an ambiguous write.
+- Retain each bound client; chain identity is read at most once per client object. Recreate the client after wallet/chain changes. Cache invalidation does not repoint an existing client to another chain.
+- Persist selected `planned.mode`. Handle approval envelopes without gas/fees, `STALE_REVIEWED_GAS`, actionable activation capacity refusal, optional `simulation.estimate` and capacity-only `gasProfile.bounds`. Remove `gasProfile.estimates` and `computeGasRequired` usage.
+- Economic review schema v2 separates `local-exact-curve` from `simulated-execution`; consume `initialBuy.reviewedBuys`, not assumed receipt fields. `transactionGasEstimate` is removed; unsigned compilation and preparation packing remain available.
+
+## Observed recording-transport budgets
+
+The same historical, already-protected plans and explicit 200M aggregate policy use deterministic recording-transport block/state/execution responses, without requesting buy recalibration. This is RPC counting, not live admission. Both commitments remain unchanged. Counts exclude wallet preparation/send, polling and supplied receipt/transaction/canonicality reads, which vary with confirmation policy.
+
+| Case | Version | Prepare/review | Each build-next | Prepare + first build | Prepare + all builds |
+| --- | --- | ---: | ---: | ---: | ---: |
+| Conversion historical plan (`0xf05…fe98fe98`, four builds) | 0.14.1 | 12 | 8 | 20 | 44 |
+| Same conversion plan | 0.15.0 | 7 | 3 | 10 | 19 |
+| Direct NativeWrap historical plan (`0x4cbc…85231`, three builds) | 0.14.1 | 12 | 8 | 20 | 36 |
+| Same direct plan | 0.15.0 | 5 | 2 | 7 | 11 |
+
+The conversion case retains six native simulation RPCs across review/builds because its historical currencies are outside capacity coverage: one session capability, one full review and four next-step proofs. The covered direct case drops six simulation RPCs to zero. Both cases have one total chain read and zero account-nonce, separate gas-price or per-transaction poster-oracle reads. Cold costs include session attestations/capability; warm counts are not cold totals. These are SDK-only figures, not whole-application telemetry.

package/docs/reference.md

@@ -2,7 +2,7 @@
 
 Use the [launch guide](launch-lifecycle.md) for the end-to-end flow and the
 [runner reference](../examples/README.md) for environment and recovery artifacts.
-This page covers SDK **0.14.0** addresses, limits, wire formats, fees, and diagnostics.
+This page covers SDK **0.14.1** addresses, limits, wire formats, fees, and diagnostics.
 
 ## Deployed infrastructure
 
@@ -19,6 +19,7 @@ start historical log queries there, in chunks of at most **10M blocks**.
 | `UFG_LAUNCH_PROXY_ADDRESS` | `0xf6673d859DE03eB74A0b01696Edb97f941dFD0CA` |
 | `UFG_TREASURY_FACTORY_ADDRESS` | `0x26Aa5D52134c8E6c4C01E9fb53A7568c0C64901F` |
 | `UFG_UPSTREAM_FACTORY_ADDRESS` | `0xA170b5A58C111334A7237F2Ea2c428ec5022f68E` |
+| Known deployment `launchLens` | `0xcb4bb3caca71fe52eace8170cf83e901418646f8` |
 
 `getKnownLifecycleDeployment`, `getKnownLifecycleProfile`, and
 `listKnownLifecycleProfiles` are pure selectors keyed by chain/core. Unknown
@@ -55,7 +56,7 @@ These are structural maxima, not a guarantee that activation fits gas.
 | Initial executor bounty | 0–1,000 bps; UFG requires 0 |
 | Gas-envelope caps | Positive uint64 bigint |
 | Gas headroom | `headroomBps`: 0–10,000; default 1,500 |
-| Robinhood simulation-used gas | `maxSimulationGas`: default 50,000,000 aggregate |
+| Robinhood simulation-used gas | `maxSimulationGas`: optional aggregate policy ceiling; no SDK-invented default |
 
 Use `LIFECYCLE_MAX_ERC404_SUPPLY` and `LIFECYCLE_MAX_REWARD_ERC20_SUPPLY` for the
 exported supply bounds. Market token budgets equal total minted supply; position
@@ -157,49 +158,44 @@ splits are separate values. The example's 3000/60 is not the venue's sole fee ti
 
 ## Account for Nitro compute and poster gas
 
-On chain 4663, the SDK reads ArbSys (`0x64`) `arbOSVersion` and ArbGasInfo (`0x6c`)
-`getMaxTxGasLimit` / `getMaxBlockGasLimit` at the pinned block. ArbSys returns
-55 + logical version; raw must be at least 105. `limits.arbOSVersion` reports the
-logical version. The minimum validated compute getter is `executionGasCeiling`.
-Failed getters cannot fall back to the large header gas limit or a hard-coded 32M.
-
-`transactionGasCeiling`, when set, is the minimum complete-envelope chain/RPC/account
-restriction. It is separate from compute. NodeInterface (`0xc8`)
-`gasEstimateL1Component` estimates poster allocation once for the next final
-transaction, using its exact sender/target/calldata/value at the same block.
-Compute-only calibration and fresh poster allocation size the immediate envelope
-before native validation. `step.computeGasRequired` retains a separable compute
-observation, never the old poster charge or provisional budget. A fresh poster
-quote is combined once when that command becomes next. Both unvalidated sizing
-and the final exact pass use affordable pinned envelopes; validation:false does
-not disable Nitro's upfront funds check. The final pass uses exactly returned gas.
-Sizing starts with per-call ceilings because unused gas is refunded between calls.
-Only a genuine upfront-funds refusal permits one second unvalidated sizing attempt
-with the budget shared across the sequence. Other failures do not retry; the final
-exact validated pass is never replayed.
-
-A tight payer balance can cover smaller exact staged envelopes yet not the
-discovery margin. This may return `failureCategory: "affordability"` even though
-the underlying launch could fit. The refused RPC exposes no successful-prefix
-results; the SDK does not invent them or add more metering attempts.
-
-Suffix steps are marked `provisional: true` and have no transaction estimate:
-their conservative complete budgets check sequence feasibility, bounded across
-the pinned affordable remaining balance. `buildNextTransaction` never reuses
-those budgets as estimates; it freshly quotes and proves only the next command.
+On chain4663, `ROBINHOOD_NATIVE_TRANSACTION_GAS_LIMIT` and the deployment preset's
+`nativeTransactionGasLimit` specify32M **total** gas for begin, prepare, activate,
+atomic and cancel. This includes poster gas. Guard-only maximum-gas getters are
+not read. Pinned ArbSys version selects capacity coverage/native capability, not
+a gas size. Other chains retain their resolved generic transaction ceiling.
+
+`transactionGasCeiling`, when set, is a caller complete-envelope restriction.
+Below the native ceiling it refuses; it never shrinks a launch step. Approvals
+omit gas/fees and leave preparation to the wallet. One `ArbGasInfo.getPricesInWei`
+leg in the initial aggregate supplies L1 per-byte and L2 prices, with no per-tx
+NodeInterface oracle. See [capacity and poster evidence](lifecycle-gas-profiles.md).
+
+`computeLifecycleLaunchGasBounds({ plan, predictedToken, ufg? })` returns conservative
+atomic/activation compute upper bounds, excluding poster, or undefined for unknown
+coverage. These select modes, not gas limits. Atomic is a preference that may select
+staged; persist returned `planned.mode`. A large upper bound is uncertain, not
+proof of overflow. Unknown activation gets full-sequence execution before begin.
+Conversion-carrying commands/consuming activation always retain exact execution.
+
+Only an immediate launch command receives a final gas/price/estimate/admission.
+Suffix execution metrics stay provisional; build-next constructs only the canonical
+next command at the same native ceiling with fresh fees and required admission.
+There are no sizing passes or funds-only retries. Balance must cover value plus
+the entire ceiling fee even when actual execution uses less gas. Incomplete proof
+cannot authorize begin; explicit aggregate policies still refuse excessive work.
 
 On Nitro, `estimate.posterGas` / `posterFee` are buffered allocations **inside**
 `gasLimit`; `dataFeeIncludedInGas` is true, `dataFee` is zero, and `totalFee` equals
 `gasLimit × gasPrice`. Do not add poster fees a second time. Custom `estimateDataFee`
 is rejected on Nitro; generic EVM clients can use it for an external fee.
-`feeConfidence` distinguishes `execution-and-data` from `execution-only` estimates.
-Initial legacy gas price is the greater of fresh RPC recommendation and twice pinned
-base fee. Reviewed immediate envelopes retain their exact held gas/price.
+`feeConfidence` distinguishes actual execution evidence from the conditional
+`native-ceiling-and-data` budget. Fresh gas price is max(pinned price, twice base fee).
+Held Nitro price must meet max(ArbGasInfo L2 price, header base fee), without an
+automatic bump. Reviewed gas differing from the ceiling is stale and refuses.
 
-HMM atomic/activation sizing adds one forwarding target of
-`4,250,000 + 500,000 × (HMM markets - 1)` gas. Staged packing estimates 14.5M per HMM
-market and 16M per other market before measurement. These are sizing inputs, not
-fixed transaction fees or proof that every permitted topology fits.
+Capacity-only profiles account for route, position and HMM forwarding overhead.
+Staged packing retains conservative per-market grouping, but never changes the
+gas assigned to a launch transaction or splits its final activation.
 
 ## Cache static reads and inspect timing
 
@@ -209,24 +205,30 @@ fixed transaction fees or proof that every permitted topology fits.
 | `sessionCache: createLifecycleSessionCache()` | Caller-owned reuse of SDK-selected static reads at one pin; successful deployment/backend observations also survive across blocks. Without it, those observations belong to the supplied client object. |
 | `onDiagnostic(event)` | Local opt-in stage/RPC timing listener; no automatic console output or telemetry. |
 
-Call `sessionCache.invalidate()` on wallet/chain switches and after each confirmed
-transaction to discard pinned static values. Session deployment/backend facts are
-keyed by chain and account where applicable and live until the session owner is
-discarded. `sessionCache.block` is readonly `{ number, hash }` or undefined.
+Call `sessionCache.invalidate()` after confirmed transactions to discard pinned
+static values. Deployment/backend facts are retained for the session owner and
+keyed by chain/account where applicable. Chain identity is cached by bound client
+object; create a new client on a chain change rather than mutating/reusing it.
+`sessionCache.block` is readonly `{ number, hash }` or undefined.
 Planning pins retain the actual RPC L2 block number and header hash. EVM
 `BLOCKNUMBER`/`BLOCKHASH`, including Multicall3's metadata getters, expose L1 values
 on Nitro and are not L2 pin sources.
-Balances, allowances, current progress, receipts, nonces, policy callbacks, and
-stateful execution proof stay fresh. Session caching does not extend admission.
+Balances, allowances, current progress, receipts, policy callbacks and required
+execution proof stay fresh. Planning/build-next do not read account queue nonces;
+the wallet assigns them and retains the observed submitted nonce for recovery.
+Session caching does not extend admission.
 
 One RPC L2 header supplies number, hash, timestamp, gas limit and base fee.
 The initial Multicall3 call uses that explicit L2 block and includes native balance,
-funding/progress and Nitro getters. Independent getters are aggregated with no
-minimum-count threshold. Runtime code is attested once per
-session. The optional preset `launchLens` remains unset until deployment; once set,
-one `launchLensAbi.snapshot` call replaces dependent token/hook/market/funding reads
-inside that aggregate. The deployed preset `hookSaltMiner` replaces local mining
-during combined preparation; every returned winner is verified locally.
+funding/progress, Nitro getters and `getPricesInWei`. Independent getters are aggregated with no
+minimum-count threshold. Multicall3 runtime code is attested once per session.
+The 4663 preset enables `launchLensAbi.snapshot` without caller configuration:
+one call replaces dependent token/hook/market/funding reads inside that aggregate.
+Its `launchLensCodeHash` pins the reviewed deployed runtime as frozen release
+metadata, like `tokenFactoryCodeHash`, without another guard-only RPC.
+The deployed preset `hookSaltMiner` replaces local mining during combined
+preparation; every returned winner is verified locally.
+Lens failures surface directly; planning does not retry through legacy reads.
 
 Diagnostic events carry `stage`, `phase`, optional `durationMs`, `queueMs`,
 `requestId`, allowlisted RPC `method`, and cache `hits` / `misses` / `reuses`.

package/examples/README.md

@@ -1,6 +1,6 @@
 # Run the examples
 
-These commands use the checkout's built `@black-market/sdk` **0.14.0** and viem.
+These commands use the checkout's built `@black-market/sdk` **0.14.1** and viem.
 Use **Node 24+** for direct TypeScript execution. Start with the one-market
 `launch-erc20-abyss.ts`; larger cases can exceed the RPC's simulation budget.
 For valuation, token ordering, ranges, and buy protection, read the
@@ -20,7 +20,7 @@ chmod 600 .env
 Launch wrappers load `.env` from the working directory with `process.loadEnvFile`.
 Existing environment values take precedence. Values are literal; shell interpolation
 is not applied. Use the matching SDK version when copying wrappers into a consumer project:
-`pnpm add @black-market/sdk@0.14.0 viem`.
+`pnpm add @black-market/sdk@0.14.1 viem`.
 Copy `launch-example.ts`, `launch-example-support.ts`, and `launch-example-kyber.ts` with the wrapper.
 
 ### Configure the environment
@@ -44,7 +44,7 @@ Copy `launch-example.ts`, `launch-example-support.ts`, and `launch-example-kyber
 | `EXAMPLE_ACCOUNT_GAS_CAP` | Optional wallet/account transaction gas-envelope ceiling. |
 | `EXAMPLE_MAX_CALLDATA_BYTES` | Optional whole-transaction byte ceiling. |
 | `EXAMPLE_HEADROOM_BPS` | Gas headroom, default `1500`; accepted range 0–10,000. |
-| `EXAMPLE_SIMULATION_GAS_CAP` | Aggregate simulation-used gas budget; default 50M on chain 4663. |
+| `EXAMPLE_SIMULATION_GAS_CAP` | Optional aggregate simulation-used gas ceiling; no SDK-invented default window. |
 
 Configure **exactly one** of `PRIVATE_KEY` and `EXAMPLE_KEYSTORE_PATH`.
 A keystore must be a regular file owned by your user with owner-only permissions.
@@ -117,7 +117,7 @@ node examples/launch-erc20-abyss.ts --resume "launch-results/<original-run-dir>"
 
 | Mode | Reads / writes | Identity |
 | --- | --- | --- |
-| No flags | Live discovery, funding quotes, preparation, simulation, economic output; unsigned, no API writes | Fresh plan/run directory |
+| No flags | Live discovery, funding quotes, preparation, profiled or executed economic review; unsigned, no API writes | Fresh plan/run directory |
 | `--broadcast` | Signs, spends, stages/uploads metadata, deploys, verifies, and publishes; no further prompt | **Fresh plan**, not the preceding dry run |
 | `--resume <original-run-dir>` | May sign remaining steps or finish publication | Retained plan, receipts, mode, confirmation policy, and API session |
 
@@ -125,10 +125,11 @@ Dry-run needs the signer source, RPC/API, and sufficient funds for execution adm
 Review its economics, then review the fresh broadcast output too. Mode flags cannot
 be combined or duplicated. Resume is an execution authorization; omit `--broadcast`.
 
-The default proof window is **50M aggregate used gas**, not a per-transaction limit.
-Opening-buy calibration needs activation inside the proven prefix. A deferred activation
-cannot produce protected buy minima. Raise `EXAMPLE_SIMULATION_GAS_CAP` only when your
-provider supports it; start with one market when checking an unfamiliar RPC.
+Covered template steps use generous gas profiles and exact local ordered curve math.
+Conversions and activation consuming conversion funding still require exact native
+execution of the complete staged sequence; a successful prefix is not admission.
+An explicit `EXAMPLE_SIMULATION_GAS_CAP` may tighten policy, not authorize partial proof.
+See [coverage and migration](../docs/lifecycle-gas-profiles.md) for evidence and limitations.
 
 ### Fund opening buys
 
@@ -166,8 +167,10 @@ It does not automatically retry sends, adopt replacements, cancel, or create ano
 | Unstarted / Cancelled / unresolved signed hash | Stops for reconciliation; do not use a new invocation as a retry. |
 
 Resume retains salts and buy minima; it does not rerun preparation or recalibrate economics.
-For replacements, retain original `transactionHash` and effective `replacementHash`,
-plus observed block number/hash. A missing receipt alone does not establish a reorg.
+For replacements, retain original `transactionHash`, effective `replacementHash`,
+observed block number/hash and the actual submitted nonce as an exact bigint
+(decimal string in journals). SDK planning has no account-queue nonce gate; the
+wallet assigns and tracks nonces. A missing receipt alone does not establish a reorg.
 
 Metadata is staged before deployment. Publication uses the **original activation hash**.
 A `LaunchPublishPending` response means indexing is pending; the runner polls for up