@black-market/sdk 0.15.1 → 0.16.0

package/docs/launch-lifecycle.md

@@ -1,6 +1,6 @@
 # Launch a token with the TypeScript SDK
 
-Use SDK **0.14.1** on Robinhood Chain mainnet (**4663**). For a first launch, run
+Use SDK **0.16.0** on Robinhood Chain mainnet (**4663**). For a first launch, run
 [`launch-erc20-abyss.ts`](../examples/launch-erc20-abyss.ts): one market, one position,
 one buy. [Runner setup](../examples/README.md) covers its environment and commands.
 This guide explains the economics and the public APIs for your own integration.
@@ -19,6 +19,7 @@ staking, or dividends. A pool profile selects the admitted venue/hook implementa
 | HMM V2 | `V4HmmFixedPool`, `V4HmmDynamicPool` | Auxiliary fee-funded bids/asks; LP and developer fees 0; explicit risk guards. |
 | UFG | Abyss QUOTE/QUOTE_ORACLE or `V4UfgFixedPool`, `V4UfgDynamicPool` | Treasury route; ERC20 without rewards; quote-only fees, executor bounty 0. |
 | Auto-compounding | `V4AutoCompoundStaticPool`, `V4AutoCompoundDynamicPool` | Net hook fees fund permanently locked full-range liquidity; both fee modes; LP and developer fees 0. |
+| Raeto | `V4RaetoFixedPool`, `V4RaetoDynamicPool` | QuoteOnly WETH/USDG; Raeto share 5/10/25/50/75%; LP and developer fees 0. |
 
 SDK presets are the source of supported profiles and deployment wiring. Profiles
 registered after this release appear with a subsequent SDK update.
@@ -655,6 +656,69 @@ exit fee; this is not a guaranteed USD floor. Accrued pool fees are not collecte
 backing. Inspect collection failure events as well as receipt success; a fork check
 needed at least 750k gas for `collect()`, not a universal mainnet gas limit.
 
+## Configure Raeto
+
+Raeto is a constrained **fee-sharing offering**, not a UFG treasury or a redemption
+contract. Select `V4RaetoFixedPool` (fixed maximum hook fee) or
+`V4RaetoDynamicPool` (minimum/maximum/sensitivity schedule). The hook creation
+bytes are identical to the ordinary zero-royalty fixed/dynamic templates; the
+Raeto collector, factory, locker, adapter and frozen terms are different.
+
+```ts
+import {
+  getKnownLifecycleProfile, KnownLifecycleProfile, RAETO_QUOTE_ASSETS,
+  RAETO_SHARE_BPS_OPTIONS, encodeRaetoLaunchTail, validateRaetoLaunchPlan,
+  type RaetoLaunchConfigV1,
+} from "@black-market/sdk/lifecycle";
+
+const preset = getKnownLifecycleProfile({
+  chainId: 4663, orchestrator: "0x91560876033d568d25CDe98C78c33ff8FC43962c",
+  key: KnownLifecycleProfile.V4RaetoFixedPool,
+})!;
+const raetoLaunchConfig: RaetoLaunchConfigV1 = { shareBps: 500 };
+console.log(preset.profile.id, RAETO_QUOTE_ASSETS, RAETO_SHARE_BPS_OPTIONS,
+  encodeRaetoLaunchTail(raetoLaunchConfig));
+// Add raetoLaunchConfig to the market's V4PoolBoundLifecycleMarketConfigV6.
+// Once all markets are built: validateRaetoLaunchPlan(plan).
+```
+
+Every Raeto-route market must use its Raeto config6 profile/adapter, **WETH or
+USDG**, `feeMode: 1` (QuoteOnly), `lpFeePips: 0`, and `developerFeeBps: 0`.
+One V4 market per quote means at most two Raeto markets, with at most 32 total
+positions. Preserve normal token/reward choices and fee-asset policies; no UFG
+proxy, treasury, special nonce, or UFG funding approvals are involved.
+
+Set `raetoLaunchConfig.shareBps` to **500, 1000, 2500, 5000, or 7500**.
+The 5% floor cannot be disabled. **1234, 8000 and 10000 are not deployed options**,
+even though a newer local contract source accepts a wider range. This release
+pins the deployed five-item menu, proved by read-only calls to both live factories
+at block 101,180,179. The encoder appends exactly one canonical 32-byte uint16
+word; missing/extra/mixed HMM/UFG/auto-compounding tails reject.
+
+Use `validateRaetoLaunchPlan(plan)` for the exclusive Raeto route; it rejects
+every non-Raeto or malformed market with `INVALID_RAETO_PLAN`. Config/tail and
+market fee/quote errors use `INVALID_RAETO_CONFIG`. Then use the ordinary
+`prepareAndPlanLifecycleLaunch` / `buildNextTransaction` flow. A share change
+changes the full plan hash, but Raeto's hook-constructor commitment hashes only
+the zero-salt V6 prefix, not the collector share. Always re-review changed plans.
+
+At collection the collector books `floor(post-treasury quote fees × shareBps /
+10000)` as Raeto credit and forwards the remainder into the normal fee hub.
+The **current fee owner** can call `setShareBps` with another menu value,
+including immediately before collection; that selection applies to all
+uncollected fees. Collection does not pay or consult the payout registry.
+Anyone can call `claimRaeto(quoteAsset)` to pay the registry's **current** payout,
+not a caller-selected recipient. Donations are not fee revenue or Raeto credit.
+Use `raetoFeeCollectorV1Abi` for `shareBps`, `owed`, token/quote getters, the
+share/claim methods and `RaetoShareUpdated` / `RaetoFeesBooked` /
+`RaetoFeesClaimed`. [Reference and preserved deployment evidence](reference.md#raeto-profiles)
+identify the payout registry and profile/adapter IDs.
+
+Both variants use the measured v4 capacity model, with deterministic preparation
+batches, exact local opening-buy quotes and the unchanged native 32M total gas
+ceiling. A ready assessment is a budget/input check, **not execution proof**.
+See [gas evidence](lifecycle-gas-profiles.md#raeto-and-auto-compounding-v4-evidence).
+
 ## Configure auto-compounding
 
 Select `V4AutoCompoundStaticPool` for a fixed hook fee or
@@ -691,11 +755,16 @@ include the recorded readback and read-only verification command.
 
 The hook owns its new full-range liquidity permanently; the non-compounding
 remainder follows the launch's normal fee-asset policies. It burns the allocated
-launch-token fees and uses quote fees to buy and compound. Every post-opening swap
-performs compounding in `afterSwap`; insufficient gas reverts with
-`CompoundOutOfGas()` rather than silently skipping work. Do not cap swap gas below
-`eth_estimateGas`. Launch transactions retain the SDK's native ceiling; these new
-templates require exact execution admission, not uncalibrated fixed-hook capacity bounds.
+launch-token fees and uses quote fees to buy and compound. During launch,
+`_attemptCompound` defers until `openingCompletedAt` is set **after all opening
+buys**, so the local ordered opening-buy curve remains exact. Post-opening swaps
+can compound in `afterSwap`; the hook's low-gas guard reverts `CompoundOutOfGas()`.
+Do not cap swap gas below `eth_estimateGas` or treat launch bounds as swap limits.
+Launch transactions now have measured static/dynamic capacity and preparation
+costs in `robinhood-4663-capacity-v4`, not ordinary fixed-hook guesses. They retain
+the native 32M total gas ceiling and never execute calldata during planning.
+See [the fork matrix and ArbOS caveat](lifecycle-gas-profiles.md#raeto-and-auto-compounding-v4-evidence).
+
 
 <a id="0100-release-hmm-v2-only"></a>
 ## Configure HMM V2

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 the calibrated fixed/dynamic V4 configuration-v6 templates, including HMM/UFG, on ArbOS61 with an EOA payer and known release quote implementations. Auto-compounding presets are not covered by these capacity bounds and require exact execution. 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
@@ -134,8 +135,8 @@ UFG adds a canonical dynamic tuple via `encodeUfgLaunchConfig`:
 `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 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.
+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
 
@@ -160,7 +161,7 @@ The disabled `0x1e41…1d68` / `0x53dd…e0d7` profiles are not supported.
 `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.
+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.
@@ -170,6 +171,60 @@ for these profiles. Never mine against a prefix-only commitment or append a shar
 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
 
 One million pips is 100%; 10,000 pips is 1%. Basis points use a 10,000 denominator.

package/examples/README.md

@@ -1,6 +1,6 @@
 # Run the examples
 
-These commands use the checkout's built `@black-market/sdk` **0.15.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 require staged preparation and a bounded activation.
 For valuation, token ordering, ranges, and buy protection, read the
@@ -20,7 +20,7 @@ chmod 600 .env
 Launch wrappers load `.env` from the working directory with `process.loadEnvFile`.
 Existing environment values take precedence. Values are literal; shell interpolation
 is not applied. Use the matching SDK version when copying wrappers into a consumer project:
-`pnpm add @black-market/sdk@0.14.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {

package/src/lifecycle/deployments/raeto-dynamic-pool-v1-20261029.ts

@@ -0,0 +1,74 @@
+import type { LaunchEnvelopeV2, AdapterRegistrationV1, ProfileRegistrationV1, ProfileTopologyV1 } from "../schema.js";
+
+// Generated by scripts/generate-raeto-presets.mjs from admission and registry readback.
+// Robinhood block 101180179, 0xe778e5d89ca2cab5843eedeb8c27b10f5463313d4b95b8971986ac72e297933c; admission 0x3148a6696c36bb1de00f8142b2aa6480681ded86203ffa6486a44c4e985c3b31.
+export const raetoDynamicEnvelope = Object.freeze({
+  artifactDigest: "0xd448a4117b78714cc4f96824356c6a90ec666449fde5c57e2b7bbe072f5e4a7a",
+  reviewManifestDigest: "0x9edfb13596015293cd41cf887758bb3799b121d680fac092191afcc0d29a6194",
+  configBoundsDigest: "0x11ec57e16f972e0ac5f687d4078d785a51de11d421bcf97e2ba129dfd83fe7b4",
+  termsDigest: "0x458cf6674ee60f1e56086a12d0d981db2c1ed815109f552318b1d8fd27a80ba2",
+  topology: 2,
+  configVersion: 6,
+  economicVersion: 3,
+  capabilities: 123n,
+  flags: 0n,
+  callbackFlags: 6908,
+  callbackMask: 16383,
+  protocolTreasury: "0x961981916AB6575C3af3eeCecbf6A3b7Fad7C9e1",
+  protocolFeeDenominator: 6,
+  beneficiary: "0x7cb44b8693b3C350A2BcD4b681aF85365aa27783",
+  maximumDeveloperFeeBps: 0,
+  bounds: Object.freeze({
+    minimumTickSpacing: 1,
+    maximumTickSpacing: 32767,
+    maximumPositions: 32,
+    maximumOracleCardinality: 4096,
+    feeModeFlags: 2,
+  }),
+  graph: Object.freeze({
+    manager: "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+    hookRoot: "0x0000000000000000000000000000000000000000",
+    oracleFactory: "0xe7feF2BC860B25bbdEB6F6AB96d88bAAa77ddad7",
+    locker: "0xBF9005094bDa89d5a119A324d6e609A2d8217C1C",
+    collectorFactory: "0x3E201A0d72221A9F8c0AEd06EdAE850E27226166",
+    collectorDeployer: "0x796E8899824999f6Da8740f712A709dBC65cbEd7",
+    hookDeployer: "0x788b88E46be3051633792896F3000EB2Ca57F97E",
+    coreCodeHash: "0x9fb8f46c3b980b9db25dfdb487a69a308a86be145860269b4036a4e74480787b",
+    managerCodeHash: "0xbd3881180b547f5fe817545743cfb4343e96b1bc6640dcd70c106b0066e95626",
+    hookRuntimeCodeHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    oracleFactoryCodeHash: "0x974fb5c72d91ccb99f1eb4679a5d4432c82bbaa0906b1c2917ec4da3499b7b98",
+    lockerCodeHash: "0x0990b18576da69dcf545010ddd7abc2252018a1bb0406b07a14e55a2315c6b27",
+    collectorFactoryCodeHash: "0xf5a1dea71122eeb3db1b925d7311a3bc89609a218ba8501038936c18fde8c892",
+    collectorDeployerCodeHash: "0xb2d108fe4ab95e42ca012cc8a48734a0fcf8cb65325e4874568a6d145dc9e617",
+    hookDeployerCodeHash: "0xb71fc43dc8000386815e3d1c5c54be6840b83281ca294db9929867d0862d118f",
+    hookCreationCodeHash: "0xd448a4117b78714cc4f96824356c6a90ec666449fde5c57e2b7bbe072f5e4a7a",
+    codeChunk0: "0x8F8756D9A50fD968a0207a09B997D4ec32525062",
+    codeChunk0Hash: "0x818c56bf10ae21129fe54f1b8991d6f807ce4ccef35b34c56251c1fd2d7d623f",
+    codeChunk1: "0xdfA2F95713d09a13d1861f09CBD4a94274b18c87",
+    codeChunk1Hash: "0xbc73944bfa7e74df5968907a05fe2579a17ab155d3a0db407588d1baff51b4de",
+    sharedHookSalt: "0x0000000000000000000000000000000000000000000000000000000000000000",
+  }),
+}) satisfies LaunchEnvelopeV2;
+export const raetoDynamicAdapter = Object.freeze({
+  implementation: "0xfc1502090D8326AB9b70aa93a01c93bEBb6f4910",
+  codeHash: "0x1ee51eb5074c356255713d5f66c9fac07e028a6d20161c623a1f409920598a16",
+  capabilities: 123n,
+  configVersion: 6,
+  enabled: true,
+}) satisfies AdapterRegistrationV1;
+export const raetoDynamicRegistration = Object.freeze({
+  adapterId: "0x8ab9c8c9b8fd4c8bbf12b780d9474463fa0fa52e3b450f0d5f68fd067dc1674d",
+  configSchema: "0x51c5ca14c40012f78425cd1afb1ea77980da3fed0490a00911a8a4ed34792045",
+  dependencyDigest: "0x2709d930b96f60427579a60cb9801b5ce5aadbda95e261a963fc783e4d2036de",
+  venue: "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+  factory: "0x0000000000000000000000000000000000000000",
+  hook: "0x0000000000000000000000000000000000000000",
+  capabilities: 123n,
+  enabled: true,
+}) satisfies ProfileRegistrationV1;
+export const raetoDynamicTopology = Object.freeze({
+  hookTopology: 2,
+  configVersion: 6,
+  hookDeployer: "0x788b88E46be3051633792896F3000EB2Ca57F97E",
+  hookCreationCodeHash: "0xd448a4117b78714cc4f96824356c6a90ec666449fde5c57e2b7bbe072f5e4a7a",
+}) satisfies ProfileTopologyV1;

package/src/lifecycle/deployments/raeto-fixed-pool-v1-20261029.ts

@@ -0,0 +1,74 @@
+import type { LaunchEnvelopeV2, AdapterRegistrationV1, ProfileRegistrationV1, ProfileTopologyV1 } from "../schema.js";
+
+// Generated by scripts/generate-raeto-presets.mjs from admission and registry readback.
+// Robinhood block 101180179, 0xe778e5d89ca2cab5843eedeb8c27b10f5463313d4b95b8971986ac72e297933c; admission 0x99089e4418bcf59fc4a2efb5dd36c95f92331a079401dcfaae36d1c94a08326a.
+export const raetoFixedEnvelope = Object.freeze({
+  artifactDigest: "0x11c4c7b1f265ed708b7d53ab828c89d237ca821333daa808f1913986c6f8f1ab",
+  reviewManifestDigest: "0x684131bdefed80771e37364f9d5af4969591a31345fbe57c503a4839b4050be2",
+  configBoundsDigest: "0x11ec57e16f972e0ac5f687d4078d785a51de11d421bcf97e2ba129dfd83fe7b4",
+  termsDigest: "0x22ac34826ee23febf81eb209a7c0ab4c0a44be4744410a3e0b5b1720b93aaacc",
+  topology: 2,
+  configVersion: 6,
+  economicVersion: 3,
+  capabilities: 123n,
+  flags: 0n,
+  callbackFlags: 6908,
+  callbackMask: 16383,
+  protocolTreasury: "0x961981916AB6575C3af3eeCecbf6A3b7Fad7C9e1",
+  protocolFeeDenominator: 6,
+  beneficiary: "0x7cb44b8693b3C350A2BcD4b681aF85365aa27783",
+  maximumDeveloperFeeBps: 0,
+  bounds: Object.freeze({
+    minimumTickSpacing: 1,
+    maximumTickSpacing: 32767,
+    maximumPositions: 32,
+    maximumOracleCardinality: 4096,
+    feeModeFlags: 2,
+  }),
+  graph: Object.freeze({
+    manager: "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+    hookRoot: "0x0000000000000000000000000000000000000000",
+    oracleFactory: "0xe7feF2BC860B25bbdEB6F6AB96d88bAAa77ddad7",
+    locker: "0x12985Fa618974b45a5de8fA40c1DE90d15E9c5c8",
+    collectorFactory: "0xb2f84D9f31cBCfA75E998852B1dCcF176BeaAeDC",
+    collectorDeployer: "0xb07558776a71C0b58779F1CAF89775d8E466c173",
+    hookDeployer: "0xfdB07076Cab21715244Bc9699A381b4F461157ea",
+    coreCodeHash: "0x9fb8f46c3b980b9db25dfdb487a69a308a86be145860269b4036a4e74480787b",
+    managerCodeHash: "0xbd3881180b547f5fe817545743cfb4343e96b1bc6640dcd70c106b0066e95626",
+    hookRuntimeCodeHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    oracleFactoryCodeHash: "0x974fb5c72d91ccb99f1eb4679a5d4432c82bbaa0906b1c2917ec4da3499b7b98",
+    lockerCodeHash: "0x304fff24ef51d2a583541fcdeddcc2cb256fe6911bbb737d68871195d14e6cc6",
+    collectorFactoryCodeHash: "0xe1ee1bfb72f9e652c121945a9ecf312d92258f937b3defd60be34d692fd1487b",
+    collectorDeployerCodeHash: "0xb2d108fe4ab95e42ca012cc8a48734a0fcf8cb65325e4874568a6d145dc9e617",
+    hookDeployerCodeHash: "0xd291bbfbbf60fb0b5eaf2569a3300408b7ac81f102a092872fd54e76b8bc766a",
+    hookCreationCodeHash: "0x11c4c7b1f265ed708b7d53ab828c89d237ca821333daa808f1913986c6f8f1ab",
+    codeChunk0: "0x46B4C3a2D205C220A20B4432e857a3254B4D051c",
+    codeChunk0Hash: "0xe5f56287276954b21f4211cabf2d9c251aae68836c5fa86ce68091ffccdee26b",
+    codeChunk1: "0x629Ab46e20f87db9ae761E75EEa733E0B396638D",
+    codeChunk1Hash: "0x76efd61e1a109a85140ce3473c43694a83f490eaac54d18673c17872a5262a47",
+    sharedHookSalt: "0x0000000000000000000000000000000000000000000000000000000000000000",
+  }),
+}) satisfies LaunchEnvelopeV2;
+export const raetoFixedAdapter = Object.freeze({
+  implementation: "0x995Da3cB2b643A9D986f28179F62511BE8757e58",
+  codeHash: "0x9b6d2c83d25a6cad137ccab7bbe17c948aa1ce27a03b53ed5a4ac7f18d06d5ec",
+  capabilities: 123n,
+  configVersion: 6,
+  enabled: true,
+}) satisfies AdapterRegistrationV1;
+export const raetoFixedRegistration = Object.freeze({
+  adapterId: "0x911d7ecefe56489d329235e3484829717dc00400d4181902f0f2de45f9338615",
+  configSchema: "0x51c5ca14c40012f78425cd1afb1ea77980da3fed0490a00911a8a4ed34792045",
+  dependencyDigest: "0x52beccb89ebac17f1028986ef4ee2e4646b23edc7779400b82976af7e35bc41c",
+  venue: "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+  factory: "0x0000000000000000000000000000000000000000",
+  hook: "0x0000000000000000000000000000000000000000",
+  capabilities: 123n,
+  enabled: true,
+}) satisfies ProfileRegistrationV1;
+export const raetoFixedTopology = Object.freeze({
+  hookTopology: 2,
+  configVersion: 6,
+  hookDeployer: "0xfdB07076Cab21715244Bc9699A381b4F461157ea",
+  hookCreationCodeHash: "0x11c4c7b1f265ed708b7d53ab828c89d237ca821333daa808f1913986c6f8f1ab",
+}) satisfies ProfileTopologyV1;