@black-market/sdk 0.9.1 → 0.11.0

package/docs/launch-lifecycle.md

@@ -7,6 +7,50 @@ The canonical authorities are the registry/certification/adapter/config contract
 in the protocol repository. Plan identity is `LaunchPlanV1`. Pool-bound V4 uses **config 6**,
 canonical Abyss uses **config 1**, and generic current shared-V4 support uses **config 4**.
 
+## 0.11.0 release: gas sizing, packing and prefix proof
+
+New atomic/activation envelopes containing HMM V2 markets add one forwarding target:
+`R = 4_250_000 + 500_000 * (hmmMarkets - 1)` gas (zero for non-HMM plans).
+For measured gross gas `G` (`maxUsedGas`, falling back to `gasUsed`), compute is
+`min(max(G + R, ceil(G * (10000 + headroomBps) / 10000)), computeCap)`.
+Begin/preparation/approval/cancel commands do not receive this reserve. Nitro poster
+gas is budgeted separately inside the same complete gas envelope. Optional padding
+and the reserve are targets, not refusal thresholds; exact validated replay proves
+the clamped envelope. There is no bisection or extra ordinary-path request.
+
+Staged planning greedily packs contiguous markets against the unpadded compute cap:
+HMM V2 costs 14.5M per market; other profiles cost a conservative 16M. At 32M,
+1/2/3/5 HMM markets produce `[1]`/`[2]`/`[2,1]`/`[2,2,1]`.
+Only a packed measurement failure consuming at least 95% of its given gas splits
+that batch in half, regardless of its error selector. Low-gas semantic failures
+remain failures. `preparationBatchSize` is removed; inspect each preparation's
+`marketStart`/`marketCount`. The pure unsigned compiler still accepts explicit
+`preparationBatches`.
+
+Robinhood chain 4663 defaults `limits.maxSimulationGas` to **50_000_000n** aggregate
+gas **used**, not the sum of individual legal transaction envelopes. Override it
+for a provider with a different budget. The SDK measures and validates the longest
+estimated prefix that fits: begin 9.5M, preparations as above, activation 6M per
+market plus `R`, and small approvals/cancellation. A measurement failure after
+cumulative use reaches 95% of that cap defers the failed call and suffix.
+If even the immediate estimate cannot fit that budget, refusal first identifies
+any estimated per-transaction compute overflow (gas displayed in millions to one
+decimal), rather than suggesting that a larger RPC budget solves it. Estimates
+alone do not reject an envelope that can still be measured and exactly proved.
+
+`simulation.admitted`, `executionProof: "proved"` and `protocolFit: "proved"` cover
+only the successful proven prefix. **They do not promise eventual activation.**
+`simulation.deferredTransactionIds` explicitly lists unproved remaining steps
+(empty for full coverage); these commands carry no `gas`, `gasPrice`, `estimate`
+or `admission`. Call `buildNextTransaction` before each signature: canonical
+progress advances the proof window and gives the immediate next transaction exact
+gas. Reviewed envelopes receive only a direct exact replay of that immediate step,
+without new measurement, poster/price recommendations or suffix proof.
+
+`buySlippageBps` requires actual activation outputs. If activation is deferred,
+calibration refuses clearly; use a higher-budget native provider or preserve
+already committed minima by omitting recalibration. Outputs are never fabricated.
+
 ## 0.9.1 release: Abyss 0.01% fee tier
 
 `ABYSS_FEE_TIERS` now includes `{ feePips: 100, tickSpacing: 1, label: "0.01%" }`.
@@ -20,72 +64,138 @@ The Robinhood chain 4663 factory has enabled fee 100 with spacing 1. Other
 deployments must enable the tier before execution; local recipe construction is
 not evidence of live profile admission. Existing tiers and defaults are unchanged.
 
-## 0.9.0 release: HMM pool hooks
+## 0.10.0 release: HMM V2 only
+
+The admitted October17 **HMM Fixed V2** and **HMM Dynamic V2** replace the SDK's
+earlier HMM offerings. Generic keys `KnownLifecycleProfile.V4HmmFixedPool`
+(`v4-hmm-fixed-pool`) and `V4HmmDynamicPool` (`v4-hmm-dynamic-pool`) now select V2.
+Versioned hook keys are `KnownLifecycleHook.HmmFixedPoolV2` / `HmmDynamicPoolV2`.
+These are not aliases for the non-HMM fixed/dynamic hooks; those APIs are unchanged.
 
-The October11 registered **HMM Fixed** and **HMM Dynamic** use
-`KnownLifecycleProfile.V4HmmFixedPool` (`v4-hmm-fixed-pool`) and
-`KnownLifecycleProfile.V4HmmDynamicPool` (`v4-hmm-dynamic-pool`), with hook keys
-`KnownLifecycleHook.HmmFixedPoolV1` / `HmmDynamicPoolV1`. Their frozen profile,
-adapter, envelope, graph, runtime hashes and creation code come from Black Market
-main `1ca9881`, admissions `20261011T214314Z-hmm-fixed` and
-`20261011T220032Z-hmm-dynamic`. Each graph has its own HMM collector/deployer and
-locker; these are not aliases for the existing fixed/dynamic hooks.
-Live `readLifecycleProfiles` remains the authority for `admitted`, not the presets.
+| Preset | Admitted V2 profile ID |
+| --- | --- |
+| HMM Fixed V2 (`hooks/hmm-fixed-v2`) | `0x45e957bcc7068350a65f5b4de5453b674d54d0f5eb2a88fc839da13197e80e98` |
+| HMM Dynamic V2 (`hooks/hmm-dynamic-v2`) | `0x8e500f203ace505072e209c5f077e11de6d071ac7f298cd75c0e05c6a55c36e6` |
 
-Both require `lpFeePips: 0` and `developerFeeBps: 0`. Fixed uses `hookFeePips`
-as the static trading fee; Dynamic uses the same minimum/maximum/sensitivity
-policy as the Dynamic Fee Hook. Config6 requires `hmmLaunchConfig`:
+Frozen adapters, envelopes, complete dependency graphs, creation code and admission
+fixtures preserve the V2 release and pinned registry readback at block 91,874,655.
+Each graph has its own collector/deployer, locker and hook deployer. Presets are
+construction data, not a current admission certificate: live
+`readLifecycleProfiles` and execution proof remain authoritative.
+
+Both require `lpFeePips: 0` and `developerFeeBps: 0`. Fixed charges `hookFeePips`
+as its static fee; Dynamic uses config6 minimum/maximum/sensitivity policy.
+Config6 requires a typed `hmmLaunchConfig`:
 
 ```ts
 const hmmLaunchConfig = defaultHmmLaunchConfig({
   tokenBudget: marketTokenBudget, quoteAsset: "USDG", quoteDecimals: 6,
+  // Illustrative caller choices, not SDK risk defaults:
+  maxBidQuote: 100n * 10n ** 6n, // maximum 100 USDG of new/refreshed bid principal
+  referenceDeviation: 0, // do not ask below or bid above the rounded reference
 });
-// Optional explicit UI choices:
-hmmLaunchConfig.strategyShareBps = 2500; // 25%; default 50%; 100% is also valid.
-hmmLaunchConfig.strategy.premiumDecaySeconds = 259200; // 72h; default off (0).
+hmmLaunchConfig.strategyShareBps = 2500; // optional 25%; existing default is 50%
+hmmLaunchConfig.strategy.premiumDecaySeconds = 259200; // optional 72h; default off
 const config = encodePoolBoundV4LifecycleMarketConfig({
   ...reviewedV6Fields, lpFeePips: 0, developerFeeBps: 0, hmmLaunchConfig,
 });
 ```
 
-`HmmStrategyConfig` / `HmmLaunchConfig` mirror Solidity
-`HMMStrategyConfigV1` / `HMMLaunchConfigV1`; `encodeHmmLaunchTail` produces exactly
-`abi.encode(HMMLaunchConfigV1)` (448 bytes). The V6 codec automatically appends it
-only for HMM profile IDs and rejects a missing tail. Decoding preserves the typed
-tail through `prepareAndPlanLifecycleLaunch` salt mining and recovery; plain V6,
-noncanonical prefixes and incorrectly sized tails are rejected before RPC planning.
-The full plan hash includes the tail. The hook constructor's market-economics
-commitment hashes only the canonical V6 prefix with zero salt, exactly as the
-HMM collector factory does.
-
-`validateHmmLaunchConfig` mirrors the collector factory: share <=10,000 bps;
-positive bid/ask widths and stale displacement, nonnegative gap, positive stale
-seconds and harvest thresholds; resale premium <=5,000 bps; 1–8 asks; exposure
->= ask count and minimum token harvest; inventory >= minimum token harvest;
-both caps <= uint128 max. Solidity int24/uint32/uint256 widths are enforced.
-Minimum quote deployment may be zero; premium decay is any uint32.
-Widths, gap and displacement are **tick spacings**, not raw ticks.
-
-Defaults: 50% share; widths 5/5, gap 1, stale 86,400 seconds/displacement 5,
-resale premium 500 bps, 4 asks, decay off. Token thresholds are raw market-budget
-ratios: harvest budget/100,000, ask exposure budget/10, acquired inventory budget.
-Budgets too small to produce a positive harvest or above uint128 are rejected.
-WETH minimum quote deploy/harvest is 0.0005/0.005 ETH; USDG is 1/10 six-decimal
-units. Symbols and canonical catalog addresses work; supplied decimals must match.
-Other quotes require explicit `minQuoteDeploy` and `minQuoteHarvest` raw values.
-Do not infer USD prices or units for unsupported assets.
-
-Each harvest sends the share of collected **QUOTE** fees to the per-market manager;
-the remainder follows the normal owner/holder-reward split. Token-side fees are
-untouched. The fee owner may call `HMMFeeCollectorV1.setStrategyShareBps` later.
-The manager bids below price and re-sells acquired inventory at/above realized
-cost plus premium; it never touches the locked launch positions.
-
-Independent Solidity ABI fixtures are generated by
-`node scripts/generate-hmm-fixtures.mjs` (Foundry `cast abi-encode`). Snapshot
-regeneration uses `node --experimental-transform-types scripts/generate-hmm-presets.mjs
-/path/to/black-market`; it reads hash-checked storage-child runtime code from
-Robinhood without modifying the evidence checkout.
+`HmmStrategyConfig` / `HmmLaunchConfig` are V2-only and mirror Solidity
+`HMMStrategyConfigV2` / `HMMLaunchConfigV2`. `encodeHmmLaunchTail` produces exactly
+`abi.encode(HMMLaunchConfigV2)`: **16 static words / 512 bytes**. The V6 codec
+appends the tail only for current HMM profile IDs. Missing tails, old 448-byte
+tails, extra words and noncanonical prefixes are rejected before RPC planning.
+Mining and recovery preserve the typed tail. The full launch-plan hash binds
+every tail byte, including both new guards.
+
+The hook constructor is still **one 20-word / 640-byte
+`PoolBoundHookParametersV2` tuple**. Do not append the HMM tail to creation code.
+The collector factory hashes only the canonical config6 prefix with zero hook
+salt for the hook's market-economics commitment; the auxiliary strategy settings
+are handed to the manager through the collector. Changing those settings changes
+the full plan commitment, but not the hook constructor's prefix-only commitment.
+
+`validateHmmLaunchConfig` enforces the factory's exact launch guards and Solidity
+field widths. Share is 0..10,000 bps. All 15 strategy fields are listed in wire order:
+
+| Field | Unit and accepted launch values |
+| --- | --- |
+| `bidWidth` | Tick spacings; positive int24 |
+| `askWidth` | Tick spacings; positive int24 |
+| `gap` | Tick spacings; nonnegative int24 |
+| `staleAfterSeconds` | Positive uint32 seconds |
+| `staleDisplacement` | Tick spacings; positive int24 |
+| `minQuoteDeploy` | Raw quote units; any uint256, including zero |
+| `minQuoteHarvest` | Raw quote units; positive uint256 |
+| `minTokenHarvest` | Raw launch-token units; positive, covered by both token caps |
+| `resalePremiumBps` | 0..5,000 bps |
+| `maxAsks` | 1..8 |
+| `maxAskTokenExposure` | Raw launch-token units; at least ask count and minimum token harvest, at most uint128 max |
+| `maxAcquiredInventory` | Raw launch-token units; at least minimum token harvest, at most uint128 max |
+| `premiumDecaySeconds` | Any uint32 seconds; zero disables decay |
+| `maxBidQuote` | Raw quote-principal ceiling for new/refreshed bids; positive and at most uint128 max |
+| `referenceDeviation` | Tick spacings; nonnegative int24 |
+
+For reference pool tick `R`, deviation `D` and spacing `S`, ask lower is at least
+`R - D*S` and bid upper is at most `R + D*S`, with side-appropriate grid rounding.
+The reference comes from the hook's truncated oracle, not an independent spot
+price supplied by the caller.
+
+The default helper **requires explicit `maxBidQuote` and `referenceDeviation`**;
+neither has a guessed risk default. All other defaults are preserved: 50% share,
+widths 5/5, gap 1, stale 86,400 seconds/displacement 5, premium 500 bps, 4 asks,
+decay off. Token thresholds are raw market-budget ratios: harvest budget/100,000,
+ask exposure budget/10, inventory budget. Too-small budgets producing zero harvest
+and budgets above uint128 are rejected. WETH quote deploy/harvest thresholds remain
+0.0005/0.005 ETH; USDG is 1/10 six-decimal units. Catalog symbols/addresses work;
+explicit decimals must match. Other quotes require explicit `minQuoteDeploy` and
+`minQuoteHarvest`; no unsupported asset's USD price or units are inferred.
+
+### V2 fee funding and owner controls
+
+V2 reserves the strategy share **on each swap in both pool currencies, after the
+protocol treasury share**, rather than waiting for harvest. The remaining fees
+follow the normal fee-hub distribution. HMM itself does not burn fees and never
+touches the permanently locked launch positions.
+
+The browser-safe lifecycle and root exports include complete
+`hmmLiquidityManagerV2Abi`, `hmmFeeCollectorV2Abi`, `hmmFeeCollectorFactoryV2Abi`,
+`hmmFixedHookV2Abi` and `hmmDynamicHookV2Abi`. Use ordinary viem contract calls;
+the SDK adds no speculative transaction wrappers:
+
+- Read `strategyOwner()` and `liquidityManager()` on the collector. Authority
+  follows the **current** fee owner from the canonical hub/fee-owner registry.
+- Call collector `setStrategyShareBps(uint16)` for 0..10,000 bps. It changes future
+  swap reservations, not fees already reserved.
+- Read manager `strategyConfig()` for the complete 15-field tuple, then call
+  `setStrategyConfig(HMMStrategyConfigV2)` to update every setting immediately.
+  This queues a book refresh for the next maintenance pass. Lowering intake caps
+  does not forcibly liquidate existing inventory; existing lots keep their stored
+  floor and age. New premium settings apply to newly acquired lots.
+- Read `placementsPaused()` and call `setPlacementsPaused(bool)` on the manager.
+  Pausing queues auxiliary-liquidity withdrawal on maintenance and stops new
+  placements, not trading or fee collection. It does not withdraw locked launch LP.
+
+These writes require the current fee-owner wallet and explicit transaction
+authorization. Read-only planning never invokes them.
+
+### Breaking migration from the earlier HMM SDK
+
+Rebuild unstarted HMM plans with the new preset IDs/adapters/graphs, supply both
+new guards, re-encode the 512-byte tail, and re-mine/re-prove the resulting plan.
+Do not pad old 448-byte payloads, reuse an old graph/salt, or relabel old bytes.
+The former `HmmFixedPoolV1` / `HmmDynamicPoolV1` enum members and old HMM metadata
+have no compatibility aliases. Existing onchain HMM V1 profiles/markets were not
+deregistered or upgraded by this SDK release; submitted legacy plans must not be
+mutated into V2 plans. Use tooling matching their original contract release.
+
+Independent Solidity ABI fixtures are regenerated with
+`node scripts/generate-hmm-fixtures.mjs` (Foundry `cast abi-encode` / `calldata`).
+To regenerate canonical V2 metadata/ABIs from preserved evidence without RPC or
+onchain writes, use `node --experimental-transform-types
+scripts/generate-hmm-presets.mjs release.json live.json`; both JSON files must be
+the exact V2 release and matching successful admission/pinned-readback records.
 
 ## 0.8.1 release
 
@@ -276,15 +386,13 @@ progress, funding/allowances and deployment/profile authority. It matches
 Preparation batching remains SDK-derived, not caller-selected. Malformed,
 wrong-step or changed envelopes refuse without returning executable calldata.
 
-Fresh measurement and complete native validated replay use the held price.
-The immediate replay uses the exact held gas; later unfinished steps receive
-fresh gas bounds and remain in the same stateful sequence. Current compute,
-poster, minimum headroom, tightening ceilings and full-sequence actual-balance
-affordability still apply. Exact replay also checks gross-gas headroom without
-counting Nitro's temporary compute hold. Neither natural child base fees nor
-payer balances are overridden. A higher advisory quote alone is not a refusal;
-an invalid current fee, insufficient gas or failed proof never silently raises
-the held envelope.
+The SDK directly validates only the immediate transaction at its exact held
+gas/price. It does not repeat measurement, quote a new gas price/poster budget or
+simulate future steps. Current protocol/transaction limits, native metering,
+postconditions and immediate actual-balance affordability still apply. Existing
+padding may be consumed; neither a new padding target nor a higher advisory quote
+alone invalidates a held envelope. Natural child base fees and payer balances are
+never overridden, and failed replay never raises held gas or switches backend.
 
 Approvals/resets, atomic launches, every staged next step and cancellation use
 this same contract. Cancellation retains its adapter-independent recovery policy.
@@ -676,13 +784,13 @@ Validation uses `validateV4LifecycleMarket`; the collector factory getter is
 | --- | --- |
 | `readLifecycleProfiles({client, orchestrator, profileIds?, offset?, limit?})` | Bounded registry discovery, schema/topology dispatch, reviewed graph/terms certification and current registry admission. Default offset/limit is 0/100; explicit IDs can select a reviewed deployment's identities. |
 | `predictLifecycleToken({client, plan})` | Exact prediction from the explicit core. |
-| `prepareAndPlanLifecycleLaunch({client, account, plan, mode, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?, onProgress?})` | Mines config6/V2 salts offchain, verifies per-market launch topology and exact final deployment bindings, and returns complete selected-mode admission under one SDK-owned fresh post-mining snapshot. No source-chain deployment or broadcast. |
+| `prepareAndPlanLifecycleLaunch({client, account, plan, mode, buySlippageBps?, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?, onProgress?})` | Mines config6/V2 salts offchain, verifies per-market topology and exact final deployment bindings, and proves the selected-mode prefix under one fresh post-mining snapshot. Reports deferred steps; buy calibration requires activation coverage. No source-chain deployment or broadcast. |
 | `readPoolBoundHookDeployment({client, plan, marketIndex})` | Verifies typed factory, code chunks, constructor, normalized economics, initcode, salt, CREATE2 prediction and recorded provenance of existing code. Works with draft salts; permission bits are additionally required for executable predeployment. |
 | `buildPoolBoundHookDeploymentTransaction({client, plan, marketIndex})` | Optional permissionless typed `deploy(parameters,salt)` calldata. Does not create a token, register/initialize a pool, bind a collector or activate a launch. |
 | `planLaunch({client, account, plan, mode, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?})` | Independently fresh per-market topology/domain/funding/profile/progress/execution admission of the already-finalized commitment, simulating only the explicitly selected mode. |
 | `simulateLaunchPlan({client, planned, limits?, fork?, receipts?, confirmations?})` | Rereads canonical state and proves remaining work. Preserves receipt evidence, economics and selected mode. |
 | `readLaunchProgress({client, planned, receipts?, confirmations?})` | Confirmation-bound canonical state, latest head, receipt/replacement/reorg status, account-nonce safety and actual prepared market/live state. |
-| `buildNextTransaction({client, planned, reviewedTransaction?, submissionClient?, limits?, fork?, receipts?, confirmations?, action?})` | Rereads progress, constraints and complete stateful proof before returning one admitted transaction. Optional untrusted `reviewedTransaction` must match the current canonical next step and freshly prove its exact gas/price. Optional `submissionClient` adds read-only immediate exact-envelope preflight. `action: "cancel"` uses the stored commitment without requiring fresh adapter/profile admission. Terminal launches return `undefined`. |
+| `buildNextTransaction({client, planned, reviewedTransaction?, submissionClient?, limits?, fork?, receipts?, confirmations?, action?})` | Rereads canonical progress and constraints, proves the immediate next transaction plus the fitting prefix, and returns one admitted envelope. With `reviewedTransaction`, directly replays only that matching immediate step at its exact held gas/price. Optional `submissionClient` adds read-only exact-envelope preflight. `action: "cancel"` retains adapter-independent recovery. Terminal launches return `undefined`. |
 
 Clients may be viem public clients or raw `request({method,params})` RPC clients. Transport, wallet, signing and durable storage are application-owned. `PlannedLaunch` contains bigint values and live limit callbacks: persist `serializeLaunchPlan(plan)`, explicit execution mode, confirmation policy and receipt references, not the entire object.
 
@@ -813,17 +921,17 @@ Mining is cancellable/nonblocking; `abort()` raises `AbortError` and does not ca
 Every planning call requires `mode: "atomic" | "staged"`. Only that requested mode receives economic simulation; staged does not compute or expose an unused atomic attempt.
 
 - Atomic: after funding prerequisites, token creation, empty infrastructure, all mint/lock/buys/public activation are one transaction.
-- Staged: prerequisites, `beginLaunch(Staged)`, contiguous empty `prepareMarkets` batches, then one `activateLaunch`. Only a stateful preparation refusal classified as capacity with a compute or gas-envelope constraint can partition into smaller empty batches. Opaque `DeploymentFailed`, unclassified/source/provider-clamp errors, byte-cap refusals and near-cap consumption do not authorize that search. Core/validator/registry/hook invariant errors stop planning.
+- Staged: prerequisites, `beginLaunch(Staged)`, greedily packed contiguous empty `prepareMarkets` batches, then one `activateLaunch`. A packed measurement failure using at least 95% of its given gas splits only that batch; low-gas semantic errors, byte caps and unlocated provider failures do not justify a split. Proof may cover only a prefix, with the unproved suffix explicitly deferred.
 - Activation cannot split. If mint/lock/all buys/opening cannot fit, staged is also refused. No position/buy/minimum is omitted to manufacture success.
 
 No automatic atomic-to-staged fallback exists. Obtain separate consent to review the same commitment as staged. Both venues use token transfer restrictions plus activation-time canonical opening-state checks, not a pool gate. Manipulated opening price or preactivation liquidity fails verification; the token stays inactive and the launch remains Ready/cancellable. Failed activation rolls back every mint, seal, buy and opening together.
 
 ## Execution constraints and stateful simulation
 
-Optional `chainGasLimit`, `rpcGasLimit`, `accountGasLimit`, `maxCalldataBytes` and
-`maxSimulationGas` tighten admission when supplied. Missing policy remains explicit in
-`limits.unknownExecutionConstraints`/`unknownConstraints`; it does not reject an otherwise
-proved exact sequence or invent a provider/account cap. No policy service is required.
+Optional `chainGasLimit`, `rpcGasLimit`, `accountGasLimit` and `maxCalldataBytes`
+tighten admission. `maxSimulationGas` sets the aggregate used-gas proof-window
+budget (default 50M on 4663, unknown on other chains). Missing policy stays explicit
+in `limits.unknownExecutionConstraints`/`unknownConstraints`; no policy service is required.
 A `LifecycleLimitSource` callback receives the canonical chain/account/core/block context.
 Any supplied provenance must match it; stale/mismatched/malformed facts or a failed supplied
 resolver reject rather than disappearing into optional uncertainty. Gas caps are positive
@@ -831,7 +939,9 @@ exact uint64 `bigint`; calldata is a positive safe integer byte count.
 Reviewed gas envelopes are positive uint64 too; zero-metering observations cannot admit
 a zero-gas transaction. Headroom calculations retain wide exact bigint intermediates.
 
-Headroom defaults to 1,500 bps, bounded 0–10,000. Generic EVM admission uses the pinned
+Headroom defaults to 1,500 bps, bounded 0–10,000; it clamps to current legal ceilings
+instead of rejecting a fitting measured requirement. HMM V2 adds the forwarding
+target documented above once on atomic/activation. Generic EVM admission uses the pinned
 bounded header and supplied total-envelope restrictions plus actual validated RPC proof.
 It reports an absent independent per-transaction cutoff honestly, without importing a
 universal Ethereum cutoff. `executionGasCeiling` and `transactionGasCeiling` are equal on
@@ -844,8 +954,8 @@ carries that successfully replayed ceiling, never a smaller unproved envelope.
 Replay source, HTTP and malformed-response failures remain provisional with
 `executionProof: "unavailable"` and do not retry economic execution. `AbortError`
 propagates unchanged, including cancellation during supplied policy and Nitro getter
-reads. A recognized execution refusal may discover at most one genuinely larger
-validated envelope within the same legal compute/total limits. Without returned
+reads. Only explicit genuine native out-of-gas evidence may discover at most one
+larger validated envelope within the same legal compute/total limits. Without returned
 failing-call evidence, `failedTransactionId` stays absent; an opaque RPC error does
 not invent a failing transaction or authorize preparation partitioning.
 Returned failures retain the actual exact-replay prefix and its first failing
@@ -883,10 +993,10 @@ The buffered compute-discovery envelope plus buffered poster budget is carried i
 exact validated replay; an approximate poster quote is never subtracted from total
 gas use to certify exact compute fit.
 Measurement waits for successful capability and candidate-specific poster evidence,
-then uses the legal complete compute-plus-poster envelope. Near-cap gas consumption
-does not diagnose OOG, constructor failure or collision. Unsupported/transport
-evidence remains unavailable, and only a recognized execution-envelope refusal
-can trigger bounded envelope discovery.
+then uses the legal complete compute-plus-poster envelope. A packed preparation
+failure consuming at least 95% may invalidate its cost estimate without claiming
+its selector diagnoses OOG. Unsupported/transport evidence remains unavailable,
+except an observed aggregate-budget exhaustion can preserve a successful prefix.
 
 A separate pinned validated simulation probes all three ArbOS/version/getter values
 against the canonical observations. Only that isolated capability probe temporarily
@@ -909,13 +1019,13 @@ does not manufacture an all-in estimate. All observations and limits refresh for
 For initial construction, the exact legacy gas-price envelope is the greater of
 the fresh RPC recommendation and twice the pinned base fee. This avoids
 underpriced submission when `eth_gasPrice` lags the block base fee. Reviewed
-envelopes retain their exact gas/price only after fresh full-sequence measurement,
-native validated replay, current minimum headroom and affordability checks.
+envelopes retain exact gas/price through direct immediate native validated replay
+and immediate affordability, without repeating measurement or applying new padding.
 The held price need not equal a new recommendation or twice the current base fee;
 natural child fees and the actual submission estimate must accept it. Replay,
 affordability and submission use that same price, without a base-fee override.
-A known aggregate budget whose legal minimum already exceeds its ceiling refuses
-before capability probes or poster work; equality is allowed. A definitive returned
+An aggregate budget selects the longest fitting estimated prefix; only when even
+the immediate estimate does not fit is no proof possible. A definitive returned
 failure from the final exact replay skips a later payer-balance lookup, while
 retaining fee/estimate validation and final canonical checks. Successful replay
 still requires current actual-balance affordability.
@@ -947,14 +1057,15 @@ Simulation and `next.admission` carry flat, independent proof outcomes:
 
 | Field | Values | Scope |
 | --- | --- | --- |
-| `executionProof` | `"proved"`, `"failed"`, `"unavailable"` | Complete stateful exact-envelope execution and postconditions, never permissive measurement alone. |
+| `executionProof` | `"proved"`, `"failed"`, `"unavailable"` | Stateful exact-envelope execution/postconditions for the proven prefix (or the immediate reviewed step), never measurement alone or an unproved suffix. |
 | `protocolFit` | `"proved"`, `"failed"`, `"unknown"` | Applicable proven protocol and known tightening restrictions. Missing optional policy remains separately disclosed. |
 | `transportPreflight` | `"not-requested"`, `"passed"`, `"failed"` | Immediate exact next-transaction acceptance estimate on the supplied submission RPC. |
 
-`admitted` means the current exact sequence is proved to fit and affordable; it is
-not guaranteed wallet submission or future execution. Admission reuses simulation
-`blockNumber`, `blockHash`, `account`, `chainId` and `limits`. Plans never preflight
-future dependent transactions against state that does not exist.
+`admitted` means the proven prefix fits and is affordable, not that deferred
+transactions have executed or that eventual activation is guaranteed. Always
+inspect `simulation.deferredTransactionIds`. Admission reuses `blockNumber`,
+`blockHash`, `account`, `chainId` and `limits`; signing uses only fresh build-next
+admission. Plans never preflight future steps independently against nonexistent state.
 
 ```ts
 const planned = await planLaunch({ client, account: plan.creator, plan, mode: "atomic" });

package/examples/.env.example

@@ -35,3 +35,7 @@ NFT_BASE_URI=
 # EXAMPLE_ACCOUNT_GAS_CAP=
 # 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,15 +1,17 @@
 # Examples
 
-The launch examples use the public `@black-market/sdk` 0.9.0 package and viem.
+The launch examples use the public `@black-market/sdk` 0.11.0 package and viem.
 Build this checkout before running its examples; in a consumer project install
-`@black-market/sdk@0.8.0` or later for the `positionGaps` and recovery APIs.
+`@black-market/sdk@0.11.0` for current gas packing and proof-coverage semantics.
 The default chain-4663 launch cases retain
 the October8 mined fixed pool-bound V4 config6/V2 and canonical Abyss config1 deployment.
 The SDK additionally knows the October11 zero-author-royalty Dynamic Fee Hook;
 its registration does not change the fixed cases' selection or fee schedule.
-HMM Fixed/Dynamic are additional October11 presets; their required typed launch
-tail and defaults are demonstrated by `hmm-launch-config.ts`. Existing fixed
-cases are intentionally unchanged. See the HMM section in the lifecycle guide.
+HMM Fixed/Dynamic V2 are additional admitted October17 presets; their required
+512-byte typed launch tail and explicit bid/reference guards are demonstrated by
+`hmm-launch-config.ts`. The generic HMM profile keys now select V2 only.
+Existing fixed cases are intentionally unchanged. See the lifecycle guide for
+the breaking migration, per-swap funding and fee-owner configuration/pause ABIs.
 Historical October5 config5 evidence is not relabeled as these graphs. Discovery
 is read-only; fixed launch examples default to an unsigned dry run. Only
 `--broadcast` (or deliberate `--resume` continuation) authorizes real writes.
@@ -22,7 +24,7 @@ examples; their relative support imports use explicit `.ts` extensions for Node
 | Script | Behavior |
 | --- | --- |
 | `quickstart.ts` | Reads the current mainnet orchestrator, checks its registry binding, and discovers admitted profiles. No wallet or writes. |
-| `hmm-launch-config.ts` | Pure HMM fixed/dynamic config construction with typed defaults and an automatically appended launch tail; no RPC, signatures or writes. |
+| `hmm-launch-config.ts` | Pure HMM V2 fixed/dynamic config construction with caller-chosen bid/reference guards and an automatically appended 512-byte launch tail; no RPC, signatures or writes. |
 | `launch.ts` | Reviews/reconstructs an explicit saved plan and selected atomic/staged mode; optional offchain config6/V2 salt mining. Prints simulation, progress, and an admitted unsigned next transaction when evidence permits. |
 | `generate-lifecycle-commitment-fixture.ts` | Frozen independent historical config4/Abyss ABI bytes/hash/identity vector. Its pre-cutover allocations are not an executable 0.7.1 plan. |
 | `launch-lifecycle-smoke.ts` | Actual SDK launch/recovery/custody/fee operations, only on an explicitly authorized owned disposable loopback graph. |
@@ -71,6 +73,18 @@ generic EVM, not as a Nitro metering substitute. Unsigned review reports
 RPC to build-next. See the
 [lifecycle guide](../docs/launch-lifecycle.md#execution-constraints-and-stateful-simulation).
 
+Robinhood defaults to a 50M aggregate simulation gas-used budget. Inspect
+`simulation.deferredTransactionIds`: admitted/proved means the proven prefix,
+not every future transaction or eventual activation. Deferred commands have no
+gas/price/estimate/admission; obtain each fresh immediate envelope through
+`buildNextTransaction` after canonical progress advances. Reviewed envelopes are
+replayed directly, without measuring/replaying the suffix again. The saved-plan
+CLI prints proof coverage and never signs. Override `limits.maxSimulationGas` only
+for a provider that supports the selected budget. Examples requiring actual
+activation outputs for `buySlippageBps` or economic review refuse if activation is
+deferred; use a suitably higher-budget provider rather than inventing buy outputs.
+
+
 For a real new graph, create the saved plan using `readLifecycleProfiles` with its
 explicit chain/core and admitted pool-bound config6 profile. Supply that graph's RPC
 to `launch.ts`; do not substitute the historical known preset. Applications may use
@@ -379,6 +393,13 @@ to tighten the complete transaction envelope: `EXAMPLE_CHAIN_GAS_CAP`,
 restrictions, not invented provider/account assurances or admission bypasses.
 Poster allocation is already inside Nitro gas/affordability and is not charged twice.
 
+Robinhood's separate aggregate simulation gas-used budget defaults to **50M**.
+`EXAMPLE_SIMULATION_GAS_CAP` overrides that budget (positive decimal gas) for
+providers supporting more or less. It does not change per-transaction compute
+capacity. Multi-step examples requiring full activation outputs for buy protection
+and economic review need a provider/budget covering activation, or refuse before
+signing; do not raise the setting beyond the provider's actual supported budget.
+
 ### Evidence and failure recovery
 
 Each dry run or broadcast automatically creates `launch-results/<timestamp-case-random>/`;

package/examples/hmm-launch-config.ts

@@ -10,7 +10,10 @@ const tokenBudget = 1000000n * 10n ** 18n;
 for (const key of [KnownLifecycleProfile.V4HmmFixedPool, KnownLifecycleProfile.V4HmmDynamicPool]) {
   const preset = getKnownLifecycleProfile({ ...identity, key })!;
   const envelope = preset.profile.envelope!;
-  const hmmLaunchConfig = defaultHmmLaunchConfig({ tokenBudget, quoteAsset: "USDG", quoteDecimals: 6 });
+  // Illustrative caller-chosen guards: at most 100 six-decimal USDG
+  // of bid principal, and no ask below/bid above the rounded oracle reference.
+  const hmmLaunchConfig = defaultHmmLaunchConfig({ tokenBudget, quoteAsset: "USDG", quoteDecimals: 6,
+    maxBidQuote: 100n * 10n ** 6n, referenceDeviation: 0 });
   // Optional explicit choices: share 2500/5000/10000 bps; decay off/259200 (72h).
   const config = encodePoolBoundV4LifecycleMarketConfig({
     version: 6, lpFeePips: 0, tickSpacing: 60, sqrtPriceX96: 1n << 96n,

package/examples/launch-example-support.ts

@@ -540,6 +540,7 @@ 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

@@ -477,6 +477,7 @@ 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 });

package/examples/launch.ts

@@ -30,6 +30,7 @@ const options = { client, account: plan.creator, plan, mode, limits, fork, recei
 const planned = args.includes("--mine")
   ? await prepareAndPlanLifecycleLaunch({ ...options, onProgress: ({ marketIndex, attempts }) => console.error("salt mining", marketIndex, attempts.toString()) })
   : await planLaunch(options);
+console.error("Proof coverage:", planned.simulation.steps.length, "steps; deferred:", planned.simulation.deferredTransactionIds);
 const progress = await readLaunchProgress({ client, planned, receipts, confirmations });
 const next = planned.simulation.admitted ? await buildNextTransaction({ client, planned, limits, fork, receipts, confirmations }) : undefined;
 console.log(JSON.stringify({ plan: JSON.parse(serializeLaunchPlan(planned.plan)), mode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,7 @@
     "lint": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "pnpm build",
     "test": "pnpm test:unit",
-    "test:unit": "pnpm build && node --test test/*.test.mjs",
+    "test:unit": "pnpm build && node --import ./test/register-typescript.mjs --test test/*.test.mjs",
     "test:api": "pnpm build && node --test test/integration/launch-api.read.test.mjs",
     "test:api:write": "pnpm build && node --test test/integration/launch-api.sessions.test.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/src/lifecycle/abi.ts

@@ -5,6 +5,7 @@ import {
   profileRegistrationV1Components, profileTopologyV1Components, launchEnvelopeV2Components, sourceTermsV3Components,
 } from "./schema.js";
 import { poolBoundHookParametersV1Components, poolBoundHookParametersV2Components, v4LifecycleMarketComponents } from "./markets.js";
+export { hmmLiquidityManagerV2Abi, hmmFeeCollectorV2Abi, hmmFeeCollectorFactoryV2Abi, hmmFixedHookV2Abi, hmmDynamicHookV2Abi } from "./hmm-abi.js";
 
 const planInput = { name: "plan", type: "tuple", components: launchPlanV1Components } as const;
 export const launchLifecycleAbi = [

package/src/lifecycle/calibration.ts

@@ -43,6 +43,7 @@ export function validateBuySlippageBps(bps: number): void {
 export function protectOrderedBuyMinimums(planned: PlannedLaunch, bps: number): LaunchPlanV1 {
   validateBuySlippageBps(bps);
   const { simulation, plan } = planned;
+  if (simulation.deferredTransactionIds.length !== 0) throw new LifecyclePlanningError("LAUNCH_DIAGNOSTIC_FAILED", "Buy slippage calibration requires actual activation outputs beyond the proven RPC prefix; use a higher aggregate simulation cap/provider or preserve already committed minima without buySlippageBps", simulation);
   if (simulation.confidence !== "stateful" || simulation.backend === "unavailable" || simulation.steps.length !== planned.transactions.length || simulation.steps.some((step, index) => !step.success || step.transactionId !== planned.transactions[index]?.id)) throw new LifecyclePlanningError("LAUNCH_DIAGNOSTIC_FAILED", simulation.reason ?? "The complete diagnostic launch sequence did not execute successfully", simulation);
   const activation = planned.transactions.find((transaction) => transaction.kind === "atomic" || transaction.kind === "activate");
   const step = simulation.steps.find((candidate) => candidate.transactionId === activation?.id);