@black-market/sdk 0.14.1 → 0.15.1

package/docs/reference.md

@@ -56,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
@@ -133,8 +133,42 @@ UFG adds a canonical dynamic tuple via `encodeUfgLaunchConfig`:
 `abi.encode((uint16,uint16,address[]))`, including the leading `0x20` offset.
 `decodeUfgLaunchConfig` rejects alternate encodings and extra bytes;
 `hashUfgLaunchConfig` hashes the tuple. Config6 appends typed `ufgLaunchConfig`
-for UFG profiles only; Abyss carries no UFG tail. Full plan hashes bind auxiliary
-tails; hook-constructor economics hashes bind the zero-salt prefix only.
+for UFG profiles only; Abyss carries no UFG tail. Full plan hashes bind every
+auxiliary tail. HMM/UFG constructor economics hash the zero-salt prefix; the
+auto-compounding profiles below hash the zero-salt prefix **and** their tail.
+
+## Auto-compounding profiles
+
+| `KnownLifecycleProfile` | Profile ID |
+| --- | --- |
+| `V4AutoCompoundStaticPool` | `0xdd53c2c686f822b2d17536ccf4f9db954b4976d1be80404bc74571253179fae0` |
+| `V4AutoCompoundDynamicPool` | `0x46b81bfe9316fbaa90e930c6f1d5ad5e6ecfced2c886fd5520ca2bae11b92744` |
+
+`AUTO_COMPOUND_STATIC_V1_PROFILE_ID` / `AUTO_COMPOUND_DYNAMIC_V1_PROFILE_ID`
+export these identities. The presets freeze the admitted envelope, adapter,
+registration, topology and exact hook creation code. The generator checks preserved
+admission bytes and successful receipts against registry `profile`,
+`profileTopology`, `profileEnvelope`, adapter metadata, module identity and runtime
+hashes at Robinhood block **100,486,085**
+(`0xa41849e3e83fb977ed2fbfc7ff71c639bdf1fc34489dc46878128c021fdb6c44`).
+These are construction snapshots, not a claim of current admission.
+The disabled `0x1e41…1d68` / `0x53dd…e0d7` profiles are not supported.
+
+`AutoCompoundConfigV1` contains `compoundShareBps` (integer 0–10,000).
+`encodeAutoCompoundTail` / `decodeAutoCompoundTail` encode exactly
+`abi.encode(bytes32 version, uint16 compoundShareBps)` (64 bytes), where
+`AUTO_COMPOUND_CONFIG_VERSION = keccak256("black-market.auto-compound.config.v1")`.
+The decoder requires the exact version, length and canonical narrow-integer
+padding. Config6's typed `autoCompoundConfig` selects this tail only for these
+two profiles; HMM and UFG tails cannot be combined with it.
+`validateAutoCompoundConfig`, the market codec and `validateV4LifecycleMarket`
+reject invalid shares; the market boundaries also require zero LP/developer fees.
+Both InputToken and QuoteOnly fee modes are supported.
+
+`hashPoolBoundV4MarketCommitment` includes the entire canonical zero-salt config
+for these profiles. Never mine against a prefix-only commitment or append a share
+after mining. Use [the launch guide](launch-lifecycle.md#configure-auto-compounding)
+for selection and gas behavior.
 
 ## Choose a fee tier
 
@@ -158,49 +192,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
 
@@ -210,19 +239,22 @@ 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
+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.
@@ -315,6 +347,26 @@ From the checkout root, `pnpm test` runs offline tests and `pnpm examples` perfo
 read-only deployed discovery. The following checks require separate infrastructure;
 run write-capable checks only with explicit permission on disposable services.
 
+### Auto-compounding read-only checks
+
+After `pnpm build`, compare both profiles and fee modes with the live collector
+factory's metadata/decoder and the reference Python encoder (no signing or sends):
+
+```sh
+BLACK_MARKET_REFERENCE_ROOT=/path/to/black-market \
+  node --test test/integration/auto-compound.live.test.mjs
+```
+
+The reference checkout must contain `scripts/auto_compound_config.py` and its
+Python dependencies. Regenerate the frozen deployment modules offline with:
+
+```sh
+node --experimental-transform-types scripts/generate-auto-compound-presets.mjs
+# Explicitly refresh readback from a new pinned L2 header plus preserved admission evidence:
+node --experimental-transform-types scripts/generate-auto-compound-presets.mjs \
+  --readback /path/to/black-market
+```
+
 ### UFG owned-fork check
 
 Run Anvil and the test in separate terminals; stop Anvil afterward:

package/examples/.env.example

@@ -37,6 +37,3 @@ NFT_BASE_URI=
 # EXAMPLE_MAX_CALLDATA_BYTES=
 # EXAMPLE_HEADROOM_BPS=1500
 #
-# Robinhood aggregate simulation gas-used budget defaults to 50M. Override only for
-# a provider supporting that budget; buy-output calibration needs activation coverage.
-# EXAMPLE_SIMULATION_GAS_CAP=100000000

package/examples/README.md

@@ -1,8 +1,8 @@
 # Run the examples
 
-These commands use the checkout's built `@black-market/sdk` **0.14.1** and viem.
+These commands use the checkout's built `@black-market/sdk` **0.15.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.
+`launch-erc20-abyss.ts`; larger cases require staged preparation and a bounded activation.
 For valuation, token ordering, ranges, and buy protection, read the
 [launch guide](../docs/launch-lifecycle.md#price-the-launch).
 
@@ -44,7 +44,6 @@ 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. |
 
 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,18 +116,20 @@ 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, local economic review and gas-budget checks; 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 |
 
-Dry-run needs the signer source, RPC/API, and sufficient funds for execution admission.
+Dry-run needs the signer source, RPC/API, and sufficient funds for current input/gas-budget checks.
 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.
+Every launch transaction uses the native ceiling,32M total on4663. Capacity profiles
+only choose mode/chunks and reject oversized activation; exact local ordered math
+protects opening buys. Multiple markets or conversion funding always stage.
+There is no launch simulation, including Kyber. Routers enforce conversion minima
+and deadlines on-chain; `assessment.ready` is not a receipt or guaranteed execution.
+See [coverage and migration](../docs/lifecycle-gas-profiles.md).
 
 ### 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

package/examples/launch-example-support.ts

@@ -252,14 +252,10 @@ export function exampleError(code, message, details = {}) {
   return Object.assign(new Error(message), { name: "LaunchExampleError", code, ...details });
 }
 
-/** An interrupted simulation still must restore its snapshot; never revert source state. */
-export function rpcRequestSignal(signal, backend, method) {
-  const cleanup = backend === "simulation" && ["evm_revert", "anvil_stopImpersonatingAccount", "hardhat_stopImpersonatingAccount"].includes(method);
-  if (!cleanup) signal.throwIfAborted();
-  // Cold nested-fork state fetches can exceed 30 seconds. Bound each request,
-  // including instrumented controlled simulation; never retry a source broadcast.
-  const timeout = AbortSignal.timeout(120_000);
-  return cleanup ? timeout : AbortSignal.any([signal, timeout]);
+/** Bound each request and preserve interruption; launch planning owns no fork cleanup. */
+export function rpcRequestSignal(signal) {
+  signal.throwIfAborted();
+  return AbortSignal.any([signal, AbortSignal.timeout(120_000)]);
 }
 
 
@@ -540,7 +536,6 @@ export async function readExampleConfiguration(sdk, redactor, env = process.env)
       chainTransactionGasLimit: gasCap("EXAMPLE_CHAIN_GAS_CAP"),
       rpcTransactionGasLimit: gasCap("EXAMPLE_RPC_GAS_CAP"),
       accountTransactionGasLimit: gasCap("EXAMPLE_ACCOUNT_GAS_CAP"),
-      rpcTotalSimulationGasLimit: gasCap("EXAMPLE_SIMULATION_GAS_CAP"),
       maxCalldataBytes: integer("EXAMPLE_MAX_CALLDATA_BYTES", undefined, 1, Number.MAX_SAFE_INTEGER),
       headroomBps: integer("EXAMPLE_HEADROOM_BPS", 1500, 0, 10000),
       provenance: { scope: "user-ceilings", note: "Optional local tightening restrictions, not verified provider or account limits" },

package/examples/launch-example.ts

@@ -78,7 +78,7 @@ function rpcClient(url, artifacts, signal, label) {
   // the example RPC client is admitted identically to the UI it validates.
   if (endpoint.hostname === "rpc.mainnet.chain.robinhood.com") headers.Origin = "https://abyss.trading";
   return { async request({ method, params = [] }) {
-    const requestSignal = rpcRequestSignal(signal, label, method);
+    const requestSignal = rpcRequestSignal(signal);
     const started = Date.now();
     try {
       const response = await fetch(endpoint, {
@@ -90,7 +90,6 @@ function rpcClient(url, artifacts, signal, label) {
       const body = await response.json();
       if (body.error) throw exampleError(body.error.code ?? "RPC_ERROR", `${label} ${method}: ${body.error.message}`, { data: body.error.data, cause: body.error });
       if (!("result" in body)) throw exampleError("INVALID_RPC_RESPONSE", `${label} ${method}: result was omitted`, { data: body });
-      if (method === "eth_simulateV1") artifacts.event("rpc-observation", { backend: label, method, params, result: body.result, elapsedMs: Date.now() - started });
       return body.result;
     } catch (error) {
       artifacts.event("rpc-error", { backend: label, method, params, elapsedMs: Date.now() - started, error: errorEvidence(error) });
@@ -307,17 +306,13 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
     market.retainedSupplyOpeningValuationUsdX18 = ratio.numerator * retainedSupply * market.quoteUsdX18 /
       (ratio.denominator * 10n ** BigInt(market.quoteDecimals));
   }
-  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");
+  const orderedOutputs = planned.assessment.gasProfile?.initialBuys;
+  if (!orderedOutputs) throw exampleError("MISSING_ECONOMIC_OUTPUTS", "Economic review requires the supported exact local opening curve");
+  const buyEvidence = "local-exact-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 +320,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,8 +332,8 @@ 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,
-      observedBlockNumber: planned.simulation.blockNumber, observedBlockHash: planned.simulation.blockHash },
+    initialBuy: { slippageBps: BUY_SLIPPAGE_BPS, funding: planned.plan.funding, orderedBuys: planned.plan.buys, reviewedBuys, evidence: buyEvidence,
+      observedBlockNumber: planned.assessment.blockNumber, observedBlockHash: planned.assessment.blockHash },
     planHash: planned.planHash, finalizedPlan: finalizedPlan,
   };
   const reviewHash = economicReviewHash(economicReview);
@@ -346,7 +341,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);
@@ -477,7 +472,6 @@ function limitSource(fixture, artifacts) {
       chainGasLimit: policy.chainTransactionGasLimit === undefined ? undefined : BigInt(policy.chainTransactionGasLimit),
       rpcGasLimit: policy.rpcTransactionGasLimit === undefined ? undefined : BigInt(policy.rpcTransactionGasLimit),
       accountGasLimit: policy.accountTransactionGasLimit === undefined ? undefined : BigInt(policy.accountTransactionGasLimit),
-      maxSimulationGas: policy.rpcTotalSimulationGasLimit === undefined ? undefined : BigInt(policy.rpcTotalSimulationGasLimit),
       maxCalldataBytes: policy.maxCalldataBytes, headroomBps: policy.headroomBps,
     };
     artifacts.event("execution-limits", { limits, provenance: policy.provenance });
@@ -490,11 +484,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,12 +503,10 @@ 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");
-    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");
-    const calldataCap = next.admission.limits.maxCalldataBytes;
+    assert.ok(next.gas !== undefined && (next.gasPrice !== undefined || next.maxFeePerGas !== undefined && next.maxPriorityFeePerGas !== undefined) && next.assessment?.ready === true, "Actual next transaction needs a current gas budget");
+    const ceiling = next.assessment.limits.transactionGasCeiling;
+    assert.ok(next.gas === next.assessment.limits.executionGasCeiling && (ceiling === undefined || next.gas <= ceiling), "Launch gas must equal the native ceiling and fit supplied restrictions");
+    const calldataCap = next.assessment.limits.maxCalldataBytes;
     assert.ok(calldataCap === undefined || (next.data.length - 2) / 2 <= calldataCap, "Exact calldata must fit any supplied cap");
     const envelope = transactionEnvelope(next);
     const wire = { ...envelope };
@@ -549,7 +541,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)) {
@@ -882,9 +874,10 @@ async function executeExample({ fixture, privateKey, scenario, sdk, artifacts, s
   const { planned, predictedToken, economicReview, reviewHash } = await constructPlan({ client, fixture, scenario, sdk, artifacts, signal, limits, metadata, image });
   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 (!planned.simulation.admitted) throw exampleError("PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The actual SDK did not admit this exact launch", { simulation: planned.simulation });
+  artifacts.event("execution-plan", { mode: planned.mode, assessment: planned.assessment, prerequisites: planned.prerequisites, transactions: planned.transactions });
+  if (scenario.mode === "staged") assert.equal(planned.mode, "staged", "Explicit staged mode is retained");
+  addressEqual(planned.predictedToken, predictedToken, "Planner token prediction");
+  if (!planned.assessment.ready) throw exampleError(planned.assessment.code ?? "PLAN_NOT_READY", planned.assessment.reason ?? "Refresh the launch review before continuing.", { assessment: planned.assessment });
   const usd = (value) => `${value / UNIT}.${(value % UNIT).toString().padStart(18, "0")}`;
   const fundingSummary = economicReview.quotes.every((quote) => quote.conversion.nativeWrap === true)
     ? "payable native wrap"
@@ -894,7 +887,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 +1047,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)) ||
@@ -1079,7 +1073,7 @@ export async function resumeLaunchExample({ fixture, privateKey, sdk, artifacts,
   if (![sdk.LifecyclePhase.Preparing, sdk.LifecyclePhase.Ready, sdk.LifecyclePhase.Active].includes(progress.canonical.phase)) {
     throw exampleError("RESUME_PHASE_UNSUPPORTED", "Resume requires canonical Preparing, Ready or Active; an unstarted or cancelled launch must never be relaunched");
   }
-  if (!planned.simulation.admitted) throw exampleError("PLAN_NOT_ADMITTED", planned.simulation.reason ?? "Remaining committed launch work was not admitted", { simulation: planned.simulation });
+  if (!planned.assessment.ready) throw exampleError(planned.assessment.code ?? "PLAN_NOT_READY", planned.assessment.reason ?? "Refresh the unfinished launch review before continuing.", { assessment: planned.assessment });
   Object.assign(artifacts.result.chain, { planHash: planned.planHash, launchId: planned.launchId, predictedToken: planned.predictedToken });
   // Canonical receipts restore the begin/deployment logs needed by verifyChain.
   for (const reference of references) {

package/examples/launch-lifecycle-smoke.ts

@@ -1,23 +1,22 @@
-// Deliberately executing proof on an owned disposable loopback fixture only.
+// Deliberately executing actual transactions on an owned disposable loopback fixture only.
 import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import { decodeEventLog, decodeFunctionResult, encodeFunctionData, toHex, zeroHash } from "viem";
 import {
   buildClaimDeveloperFeesPageTransaction, buildNextTransaction, buildPoolBoundHookDeploymentTransaction,
-  createControlledLifecycleFork, decodeDeveloperClaimReceipt, decodePoolBoundV4LifecycleMarketConfig,
+  decodeDeveloperClaimReceipt, decodePoolBoundV4LifecycleMarketConfig,
   encodeLaunchPlan, encodePoolBoundV4LifecycleMarketConfig, hashLaunchIdentity, hashLaunchPlan,
   launchLifecycleAbi, lifecycleAdapterAbi, lifecycleDirectoryAbi, lifecycleErc20Abi, lifecycleFeeHubAbi,
   LifecyclePhase, parseLaunchPlan, planLaunch, predictLifecycleToken, prepareAndPlanLifecycleLaunch,
   readAuthorHubs, readDeveloperFees, readLaunchProgress, readLifecycleProfiles, readPoolBoundHookDeployment,
-  simulateLaunchPlan, isPoolBoundV4ConfigVersion,
+  isPoolBoundV4ConfigVersion,
 } from "@black-market/sdk/lifecycle";
 const [manifestFile, plansFile] = process.argv.slice(2);
 if (!manifestFile || !plansFile) throw new Error("Usage: node examples/launch-lifecycle-smoke.ts manifest.json sdk-plans.json");
 const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
 const exported = JSON.parse(await readFile(plansFile, "utf8"));
 const rpcUrl = process.env.LAUNCH_LIFECYCLE_RPC_URL;
-const forkRpcUrl = process.env.LAUNCH_LIFECYCLE_FORK_RPC_URL;
-if (!rpcUrl || !forkRpcUrl || !["127.0.0.1", "localhost", "[::1]"].includes(new URL(rpcUrl).hostname) || process.env.LAUNCH_LIFECYCLE_ALLOW_LOCAL_EXECUTION !== "1" || manifest.fixtureOnly !== true) throw new Error("Smoke requires explicitly authorized owned loopback fixture execution and a separate disposable fork");
+if (!rpcUrl || !["127.0.0.1", "localhost", "[::1]"].includes(new URL(rpcUrl).hostname) || process.env.LAUNCH_LIFECYCLE_ALLOW_LOCAL_EXECUTION !== "1" || manifest.fixtureOnly !== true) throw new Error("Smoke requires explicitly authorized owned loopback fixture execution");
 if (!Array.isArray(exported.plans) || exported.plans.length === 0) throw new Error("Current Solidity-exported reviewed plans are required");
 let requestId = 0;
 const client = { async request({ method, params = [] }) {
@@ -36,7 +35,6 @@ const limits = async ({ block, chainId, account, orchestrator }) => ({
   chainGasLimit: BigInt(policy.chainTransactionGasLimit), rpcGasLimit: BigInt(policy.rpcTransactionGasLimit),
   accountGasLimit: BigInt(policy.accountTransactionGasLimit), maxCalldataBytes: Number(policy.maxCalldataBytes), headroomBps: Number(policy.headroomBps),
 });
-const fork = createControlledLifecycleFork({ sourceRpcUrl: rpcUrl, forkRpcUrl, allowTransactions: true, impersonation: "anvil" });
 async function readContract(to, abi, functionName, args = []) {
   return decodeFunctionResult({ abi, functionName, data: await client.request({ method: "eth_call", params: [{ to, data: encodeFunctionData({ abi, functionName, args }) }, "latest"] }) });
 }
@@ -46,7 +44,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) }] });
@@ -81,7 +79,7 @@ for (const row of exported.plans) for (const mode of ["atomic", "staged"]) {
     const draft = { ...plan, markets: plan.markets.map((market) => isPoolBoundV4ConfigVersion(market.configVersion) ? {
       ...market, config: encodePoolBoundV4LifecycleMarketConfig({ ...decodePoolBoundV4LifecycleMarketConfig(market.config, market.configVersion), hookSalt: zeroHash }),
     } : market) };
-    let planned = await prepareAndPlanLifecycleLaunch({ client, account: draft.creator, plan: draft, mode, limits, fork });
+    let planned = await prepareAndPlanLifecycleLaunch({ client, account: draft.creator, plan: draft, mode, limits });
     plan = planned.plan;
     assert.equal(hashLaunchPlan(plan).toLowerCase(), row.planHash.toLowerCase(), "Offchain mining reproduces the independent constructor/salt vector");
     if (mode === "staged") for (const deployment of planned.hookDeployments) {
@@ -90,22 +88,14 @@ for (const row of exported.plans) for (const mode of ["atomic", "staged"]) {
       const actual = await readPoolBoundHookDeployment({ client, plan, marketIndex: deployment.marketIndex });
       assert.equal(actual.predictedHook.toLowerCase(), deployment.predictedHook.toLowerCase());
     }
-    if (mode === "staged" && planned.hookDeployments.length > 0) planned = await planLaunch({ client, account: plan.creator, plan, mode, limits, fork });
-    assert.equal(planned.simulation.admitted, true, planned.simulation.reason);
-    const atomicReceipt = planned.simulation.steps.find((step) => step.transactionId === "atomic")?.returnData;
-    if (atomicReceipt) {
-      const decoded = decodeFunctionResult({ abi: launchLifecycleAbi, functionName: "launchAtomic", data: atomicReceipt });
-      assert.equal(decoded.planHash.toLowerCase(), planned.planHash.toLowerCase());
-      for (let i = 0; i < plan.buys.length; ++i) assert.ok(decoded.tokenOut[i] >= plan.buys[i].minTokenOut);
-    }
-    const replay = await simulateLaunchPlan({ client, planned, limits, fork });
-    assert.equal(replay.admitted, true, replay.reason);
+    if (mode === "staged" && planned.hookDeployments.length > 0) planned = await planLaunch({ client, account: plan.creator, plan, mode, limits });
+    assert.equal(planned.assessment.ready, true, planned.assessment.reason);
     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 });
       if (!next) break;
-      assert.equal(next.admission?.transportPreflight, "passed");
+      assert.equal(next.assessment?.ready, true);
       const submitted = await send(next);
       receipts.push(submitted.reference);
       if (["atomic", "activate"].includes(next.kind)) activationReceipt = submitted.receipt;
@@ -130,7 +120,7 @@ for (const row of exported.plans) for (const mode of ["atomic", "staged"]) {
         assert.equal(liquidity, position.liquidity); assert.equal(custody.toLowerCase(), market.prepared.custody.toLowerCase());
       }
     }
-    assert.equal(await buildNextTransaction({ client, planned, receipts, limits, fork }), undefined);
+    assert.equal(await buildNextTransaction({ client, planned, receipts, limits }), undefined);
     const hub = progress.canonical.feeHub;
     assert.equal(await readContract(hub, lifecycleFeeHubAbi, "economicVersion"), 3);
     const authors = new Map();