@black-market/sdk 0.15.0 → 0.16.0

package/docs/lifecycle-gas-profiles.md

@@ -1,6 +1,6 @@
 # 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.
+Version **0.16.0**, model **`robinhood-4663-capacity-v4`**, separates the native transaction ceiling, conservative capacity bounds, exact opening-curve quotes and actual transaction receipts. A ready assessment is not execution proof.
 
 ## One native ceiling, not component-sized gas
 
@@ -12,43 +12,160 @@ A reviewed launch gas differing from the ceiling is stale and refuses with `STAL
 
 ## 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.
+`computeLifecycleLaunchGasBounds({ plan, predictedToken, ufg?, headroomBps? })` returns conservative `atomicComputeGasUpperBound` and `activationComputeGasUpperBound`, excluding poster gas, or undefined for unknown coverage. The v4 model covers Raeto fixed/dynamic and current auto-compounding static/dynamic in addition to the existing Abyss, V4, HMM and UFG templates. It accounts for token/reward creation, actual UFG proxy/treasury route, measured 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.
+An atomic request is a preference. Multiple markets or conversion funding always select staged; one non-conversion market can remain atomic only when its conservative bound plus poster allocation fits. Explicit staged remains staged. Review and persist returned `planned.mode`, not the requested mode. No positions, markets or buys are dropped, and the gas envelope is never resized.
 
-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.
+Preparation greedily packs contiguous markets using measured per-template/per-position costs, full calldata processing and padding. Activation cannot split. An activation bound plus poster allocation above 32M refuses before begin with `ACTIVATION_GAS_LIMIT`; an unknown profile refuses with `UNKNOWN_GAS_PROFILE`. A conservative refusal is not proof the actual transaction would overflow, but there is no simulation or execution fallback.
 
-## Which admission path runs
+## What planning does, and does not prove
 
-| 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.
+Planning and build-next read one pinned input/progress snapshot, compute exact local opening-buy outputs, check deterministic capacity and check affordability. They **never execute launch calldata**, including for conversion funding. The real router enforces its committed conversion floor/deadline when the user submits the transaction.
 
-### Honest result fields
+| Command | Planning/build-next behavior |
+| --- | --- |
+| Approval/reset | Discover allowance; wallet owns gas preparation. |
+| Begin | Check inputs, complete activation capacity and full-ceiling affordability. |
+| Prepare markets/hooks | Pack deterministic contiguous batches and check their budgets. |
+| Activate and opening buys | Check unsplittable activation capacity and exact local ordered-buy floors. |
+| Atomic launch | Require one non-conversion market with known capacity headroom. |
+| Cancel | Build from canonical progress; no new profile capacity requirement. |
 
-- 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.
+Check `planned.assessment.ready`, `code`, `reason`, optional `capacityConstraint`,
+`assessment.estimate` and `assessment.gasProfile`. The gas profile contains
+`version`, capacity `bounds` and exact local `initialBuys`, never invented
+`gasUsed`. Launch commands use the native ceiling; approvals omit gas/fees.
+Only actual included receipts and canonical Active/public-market state establish
+execution. The owned fork harness below exercises the real contracts separately;
+it is never selected as a planning backend.
 
 ## 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.
+`robinhood-4663-capacity-v4` extends the retained release-template budgets with [Raeto and auto-compounding measurements](#raeto-and-auto-compounding-v4-evidence). These are empirical capacity bounds, not gas-limit sizing, a promise about arbitrary upgrades/future ArbOS rules, or native execution proof. Currency admission is separate: only Raeto imposes its deployed WETH/USDG quote allowlist.
 
 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.
 
+## Raeto and auto-compounding v4 evidence
+
+`test/integration/template-gas.fork.mjs` owns an explicitly supplied loopback
+Anvil on **8571** and accepts only its unlocked default development account.
+It never loads a key or sends to mainnet. Each case snapshots/reverts the fork
+and executes real SDK-produced calldata against the admitted deployment graph.
+The matrix retains full portable plans and receipts' transaction hashes,
+block numbers, `gasUsed`, characterization envelopes, calldata sizes,
+Anvil minimum-gas estimates and separate 32M `eth_call` fit results in
+`test/fixtures/template-gas-matrix.json`. Separate read-only SDK planning/build-next
+assessments, referencing those retained real executions without replaying them,
+are in `test/fixtures/template-gas-smoke.json`.
+The creator/token identity may repeat across **isolated, reverted** cases, and
+identical CREATE2 preimages reuse the SDK's deterministic mined salt. This avoids
+unnecessary new empty-slot archive queries without retaining any launch state
+between experiments. Complete plans identify the exact identity used in every
+observation. The harness verifies the source pin and Anvil version and always
+skips any scenario already recorded. The final missing-case selection covers
+boundary depths/buys/market counts rather than repeating a redundant Cartesian
+interior. Earlier valid observations remain in the evidence unchanged.
+
+The source block/hash and Anvil version are recorded per run. Public RPC pruning,
+rate limits and archive backend failures are not execution failures; the final
+missing cases use a configured Alchemy archive. Its credential-bearing URL is
+never logged or committed; evidence identifies the provider only as `alchemy`.
+The synthetic economics ($5,000 FDV, WETH $3,000 / USDG $1) are explicit test
+fixtures, not a live pricing recommendation.
+Single-position recipes and adjacent 8-position distributions use SDK helpers;
+an explicit adjacent 32-band fixture reaches the templates' structural maximum
+without changing the public distribution catalogue's 2–16-position API.
+Two-market cases divide at most 32 **total** positions between WETH and USDG.
+Raeto cannot have a third V4 market because those are its only allowed quotes.
+
+Anvil does not implement ArbOS precompiles. The harness reads
+`ArbGasInfo.getPricesInWei` from the real native chain through the configured
+archive at the fork's source pin. For read-only LaunchLens planning snapshots,
+an `eth_call`-only ArbSys override maps `arbBlockNumber()` / `arbBlockHash(uint256)`
+to Anvil's actual `NUMBER` / `BLOCKHASH` environment; it does not invent balances,
+progress, addresses or protocol results. No deployed launch code/storage is
+overridden and no measured launch is replayed by that smoke. All launch execution
+uses the ordinary fork contracts.
+USDG fixture funding is an ordinary deployed-token transfer from the fork's
+real PoolManager balance, using fork-only impersonation; protocol code/storage
+is not replaced. Characterization uses 100M gas to measure without assuming fit,
+and separately calls the exact launch at 32M. The read-only profiled smoke checks
+the SDK's actual 32M next-command envelope without re-executing a retained case.
+**Anvil compute and successful local 32M calls are not native ArbOS/poster proof.**
+
+The committed run contains **84 real launches / 186 successful launch
+transactions** at Robinhood block **101,180,179**
+(`0xe778e5d89ca2cab5843eedeb8c27b10f5463313d4b95b8971986ac72e297933c`):
+59 retained observations plus 25 approved missing boundary cases. No retained
+case was replayed. Depths are 1/8/32 total positions, one/two markets and
+0/1/4 ordered buys, with both Raeto quotes and both auto-compound fee modes.
+
+Observed peak EVM `gasUsed`, in millions (preparation columns distinguish batch size):
+
+| Template | Cases | Atomic max | Prepare 1 market max | Prepare 2 markets max | Activation max |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Raeto fixed | 42 | 41.664 | 11.222 | 17.831 | 22.228 |
+| Raeto dynamic | 22 | 41.694 | 11.186 | 17.804 | 22.332 |
+| Auto-compound static | 10 | 41.285 | 10.694 | 16.874 | 22.403 |
+| Auto-compound dynamic | 10 | 41.369 | 10.753 | 16.992 | 22.445 |
+
+The 32-position atomic extremes exceed 32M and select staged; their
+activations fit. All measured one/eight-position atomic cases fit, including
+several buys. `test/template-gas.test.mjs` requires every transaction's observed
+gas **and** Anvil forwarding estimate to fit its model bound, at least 5%
+observed-gas margin, and a bound below 32M whenever the observation fit that
+ceiling. Begin uses the native 32M budget rather than a fabricated estimate.
+
+V4 template coefficients below are compute basis, before at least **25%**
+padding (or larger requested headroom), calldata processing and applicable
+token/reward/NFT/fee-asset work. Existing offerings' coefficients are unchanged.
+
+| Component | Raeto fixed/dynamic | Auto-compound static/dynamic |
+| --- | --- | --- |
+| One-market atomic base | 18,000,000 | 18,000,000 |
+| Atomic extra position | 600,000 | 600,000 |
+| Activation call base | 1,500,000 | 1,500,000 |
+| Activation per market | 500,000 | 750,000 |
+| Activation per position | 500,000 | 500,000 |
+| Preparation per market | 9,300,000 | 8,900,000 |
+| Preparation extra position | 70,000 | 70,000 |
+| Each opening buy | 500,000 + 25,000 × that market's positions | Same |
+
+The per-buy position term matters: at 32 positions the measured marginal
+exceeds 1M gas per buy, so inheriting the ordinary flat 0.5M would understate
+larger buy sequences. Full calldata contributes 24 gas/byte and fee assets
+100,000 each before padding. `computeLifecycleLaunchGasBounds` remains the
+consumer API; coefficients are not transaction gas limits.
+
+Auto-compounding's `_attemptCompound` exits for `Opening` before its 80k
+low-gas guard whenever `_openingCompletedAt == 0`. The orchestrator executes all
+ordered `_buy` calls before `_openMarkets`; opening completion is the terminal
+market boundary. The harness checks exact quote spend/token outputs against
+`InitialBuyExecuted`, every opening deferral, no `CompoundExecuted`, and
+opening-completed event ordering. Therefore launch activation needs no
+post-opening compounding forwarding reserve; HMM's separate reserve stays intact.
+These launch constants are **not** gas limits for post-opening swaps.
+
+```sh
+# In each terminal, source the existing credential environment without printing it:
+source ~/.config/robinhood-archive-rpc.env
+export ROBINHOOD_ARCHIVE_RPC_URL
+# Terminal 1; stop Anvil when finished:
+anvil --fork-url "$ROBINHOOD_ARCHIVE_RPC_URL" \
+  --fork-block-number 101180179 --chain-id 4663 --port 8571 --host 127.0.0.1 \
+  --hardfork cancun --gas-limit 120000000 --quiet
+# Terminal 2, in the worktree (source/export the environment here too):
+pnpm build
+TEMPLATE_FORK_RPC_URL=http://127.0.0.1:8571 \
+  node test/integration/template-gas.fork.mjs
+# Read-only assessment of retained executed plans; no launch replay:
+TEMPLATE_FORK_RPC_URL=http://127.0.0.1:8571 \
+  node test/integration/template-gas.fork.mjs --smoke
+```
+
 ## 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.
+`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. Auto-compounding defers until opening completes, after all initial buys; Raeto reuses the ordinary fixed/dynamic fee curve. 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.
 

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.1** addresses, limits, wire formats, fees, and diagnostics.
+This page covers SDK **0.16.0** addresses, limits, wire formats, fees, and diagnostics.
 
 ## Deployed infrastructure
 
@@ -20,6 +20,7 @@ start historical log queries there, in chunks of at most **10M blocks**.
 | `UFG_TREASURY_FACTORY_ADDRESS` | `0x26Aa5D52134c8E6c4C01E9fb53A7568c0C64901F` |
 | `UFG_UPSTREAM_FACTORY_ADDRESS` | `0xA170b5A58C111334A7237F2Ea2c428ec5022f68E` |
 | Known deployment `launchLens` | `0xcb4bb3caca71fe52eace8170cf83e901418646f8` |
+| `RAETO_PAYOUT_REGISTRY_ADDRESS` | `0xBEC2C0e91612090F82df6743F31CDF18B4386b50` |
 
 `getKnownLifecycleDeployment`, `getKnownLifecycleProfile`, and
 `listKnownLifecycleProfiles` are pure selectors keyed by chain/core. Unknown
@@ -133,8 +134,96 @@ 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/Raeto constructor economics hash the zero-salt prefix;
+auto-compounding profiles 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, UFG and Raeto 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.
+
+## Raeto profiles
+
+All of the following are exported from `@black-market/sdk/lifecycle` (and the
+root). These presets are supported on the known Robinhood 4663 deployment.
+
+| Profile key / identity constant | Profile ID |
+| --- | --- |
+| `V4RaetoFixedPool` / `RAETO_FIXED_PROFILE_ID` | `0x9161833b162e7ca8160b11c64aedb307561e19a9136fd32f99cd797aab6da3ca` |
+| `V4RaetoDynamicPool` / `RAETO_DYNAMIC_PROFILE_ID` | `0x08387d00ee4f75f860810cc8fb434087328592c2f39ea3321109e589039f80e1` |
+
+`RAETO_FIXED_ADAPTER_ID` is
+`0x911d7ecefe56489d329235e3484829717dc00400d4181902f0f2de45f9338615`;
+`RAETO_DYNAMIC_ADAPTER_ID` is
+`0x8ab9c8c9b8fd4c8bbf12b780d9474463fa0fa52e3b450f0d5f68fd067dc1674d`.
+`isRaetoProfile(profileId)` compares IDs case-insensitively.
+`RAETO_PAYOUT_REGISTRY_ADDRESS` identifies the controller-managed payout registry.
+`RAETO_QUOTE_ASSETS` is the frozen checksummed `[WETH, USDG]` tuple:
+`0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73`,
+`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`.
+
+`RAETO_SHARE_BPS_OPTIONS` is readonly `[500, 1000, 2500, 5000, 7500]`.
+`RaetoLaunchConfigV1 = { shareBps: number }`, `validateRaetoLaunchConfig`,
+`encodeRaetoLaunchTail` and `decodeRaetoLaunchTail` enforce exactly that menu and
+exactly `abi.encode(uint16 shareBps)` (one 32-byte word). Noncanonical uint16
+padding, extra/missing bytes, zero and non-menu shares throw
+`INVALID_RAETO_CONFIG`. V6 `raetoLaunchConfig` is mutually exclusive with all
+other tails; Raeto requires QuoteOnly, zero LP/developer fees and allowed quotes.
+`validateRaetoLaunchPlan(plan)` checks **every** market and throws
+`INVALID_RAETO_PLAN`, including for wrong profiles/adapters, schemas or quotes.
+It adds no UFG token/reward/proxy restrictions.
+
+`raetoFeeCollectorV1Abi` is generated from verified standard-output and includes
+`shareBps()`, `owed(address)`, `launchToken()`, `quoteAsset()`,
+`setShareBps(uint16)`, `claimRaeto(address)` and the exact three Raeto events.
+See [fee ownership and collection semantics](launch-lifecycle.md#configure-raeto).
+
+`test/fixtures/raeto-registry-readback.json` preserves admission bytes/receipts,
+runtime hashes, factory metadata, verified ABI provenance and real factory
+`eth_call` share-menu results at **101,180,179**
+(`0xe778e5d89ca2cab5843eedeb8c27b10f5463313d4b95b8971986ac72e297933c`).
+The deployed source commit is `a39c958` (go-live record `02e5cf3`), **not** the
+later local `80ea8c8` share-range change. The generator proves hook creation bytes
+equal the SDK's existing fixed and zero-royalty dynamic bytecode.
+
+```sh
+# Offline, deterministic regeneration from saved evidence (Node 24+):
+node --experimental-transform-types scripts/generate-raeto-presets.mjs
+# Explicit read-only refresh, checking the preserved go-live records:
+node --experimental-transform-types scripts/generate-raeto-presets.mjs \
+  --readback /path/to/black-market
+pnpm build
+node --test test/integration/raeto.live.test.mjs
+```
 
 ## Choose a fee tier
 
@@ -313,6 +402,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.16.0** 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).
 
@@ -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.1 viem`.
+`pnpm add @black-market/sdk@0.16.0 viem`.
 Copy `launch-example.ts`, `launch-example-support.ts`, and `launch-example-kyber.ts` with the wrapper.
 
 ### Configure the environment
@@ -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` | 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,19 +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, profiled or executed economic review; 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`.
 
-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.
+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
 

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,21 +306,9 @@ 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);
-  let orderedOutputs, buyEvidence;
-  if (activationStep?.success && activationStep.returnData) {
-    const receipt = decodeFunctionResult({ abi: sdk.launchLifecycleAbi,
-      functionName: activationTransaction.kind === "atomic" ? "launchAtomic" : "activateLaunch", data: activationStep.returnData });
-    assert.equal(receipt.planHash.toLowerCase(), planned.planHash.toLowerCase(), "Economic receipt exact plan");
-    assert.equal(receipt.tokenOut.length, planned.plan.buys.length, "Economic receipt ordered outputs");
-    assert.equal(receipt.quoteSpent.length, planned.plan.buys.length, "Economic receipt ordered spending");
-    orderedOutputs = receipt.tokenOut.map((tokenOut, index) => ({ tokenOut, quoteSpent: receipt.quoteSpent[index] }));
-    buyEvidence = "simulated-execution";
-  } else if (planned.simulation.backend === "profiled" && planned.simulation.gasProfile) {
-    orderedOutputs = planned.simulation.gasProfile.initialBuys;
-    buyEvidence = "local-exact-curve";
-  } else throw exampleError("MISSING_ECONOMIC_OUTPUTS", "Economic review requires ordered buy outputs from exact execution or the covered local curve");
+  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];
@@ -346,7 +333,7 @@ async function constructPlan({ client, fixture, scenario, sdk, artifacts, signal
         [{ 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, reviewedBuys, evidence: buyEvidence,
-      observedBlockNumber: planned.simulation.blockNumber, observedBlockHash: planned.simulation.blockHash },
+      observedBlockNumber: planned.assessment.blockNumber, observedBlockHash: planned.assessment.blockHash },
     planHash: planned.planHash, finalizedPlan: finalizedPlan,
   };
   const reviewHash = economicReviewHash(economicReview);
@@ -485,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 });
@@ -517,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 an admitted gas envelope");
-    assert.ok(next.admission.executionProof === "proved" && next.admission.protocolFit === "proved" ||
-      next.admission.executionProof === "not-run" && next.admission.protocolFit === "profiled", "Distinguish exact execution from conditional capacity admission");
-    const ceiling = next.admission.limits.transactionGasCeiling;
-    assert.ok(next.gas === next.admission.limits.executionGasCeiling && (ceiling === undefined || next.gas <= ceiling), "Launch gas must equal the native ceiling and fit supplied restrictions");
-    const calldataCap = next.admission.limits.maxCalldataBytes;
+    assert.ok(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 };
@@ -890,10 +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 });
+  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.simulation.admitted) throw exampleError("PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The actual SDK did not admit this exact launch", { simulation: planned.simulation });
+  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"
@@ -1089,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) {