@black-market/sdk 0.4.0 → 0.5.1

package/docs/launch-lifecycle.md

@@ -2,42 +2,63 @@
 
 `@black-market/sdk/lifecycle` is the browser-safe launch API; its exports are also available from `@black-market/sdk`. Supply the exact chain, core, creator and registry domain. Planning, salt preparation, reads and unsigned builders never sign, publish metadata or write to the source chain. A successful controlled-local simulation is not production deployment approval.
 
-The canonical authorities are the registry/certification/adapter/config contracts under `contracts/src/launch/lifecycle/v2`, the typed hook deployers, and `contracts/src/launch/fees/v3` in the sibling protocol repository. Plan identity remains `LaunchPlanV1`; shared V4 accepts **config 4 only**, bound V4 **config 5 only**, and Abyss keeps its canonical schema. Old Atomic/Unified request encoders, template catalogs and old V4 profile/adapter constants have been removed. Immutable old contracts/pools and unrelated DEX/lending functions are not upgraded or rebound.
-
-The keystore-only `DeployPoolLaunchV1` deployment includes fixed pool-bound V4
-(`PoolHookDeployerV1`, `PoolMarketAdapterV1`, `PoolFeeCollectorFactoryV1`) and canonical Abyss:
-two adapters and five automatically admitted profiles.
-Registry V2 has one `LaunchCertificationV2` child and no arbitrary unsigned V4 endpoint.
-V4 uses `profileEnvelope`, `profileId` and signed six-argument `registerProfile`.
-Admin-only `registerAbyssProfile(uint8,registration)` independently certifies the four canonical
-config-1 variants; they have no author envelope or royalty allocation.
-Envelope/bounds/graph types and encoding helpers use `Launch` names.
-There are no old-name aliases. The admission EIP-712 domain is `Black Market Launch Registry`,
-version `2`; regenerate author consent after cutover. Market configuration tuple layouts remain
-unchanged; bounds encoding changes below require fresh profile identities and consent.
-Old deployment evidence is not new-graph proof.
-
-`LaunchBoundsV2` has five members beginning with `minimumTickSpacing`: tick-spacing bounds,
-maximum positions, maximum oracle cardinality and fee-mode flags. Former LP/hook fee ceilings
-and profile-level oracle/external-liquidity pins are removed. Creators independently choose
-valid LP/hook rates below 1,000,000 pips, including 15%, their registered oracle configuration,
-and their per-pool external-liquidity policy. Author royalty ceilings remain separate.
-Regenerate bounds digests, profile IDs and consent for the new tuple.
-
-Robinhood P1 `(1,4096)`, P2 `(6,4096)` and P3 `(17,4096)` are usable on the same admitted profile.
-Planning/preparation validates each selected oracle on the pinned factory at the pinned block;
-unregistered/invalid oracle parameters and excessive cardinality still fail. With
-`externalLiquidityDisabled=false`, third-party LP add/remove is allowed after opening.
-Permanent launch custody and pre-opening protection remain unchanged.
-
-Shared contracts are `FixedFeeSharedHookV1`, `SharedHookDeployerV1` and
-`SharedMarketAdapterV1`. ABI exports are `sharedMarketAdapterV1Abi`,
-`sharedHookDeployerV1Abi`, `poolMarketAdapterV1Abi`, `poolHookDeployerV1Abi` and
-`poolFeeCollectorFactoryV1Abi`; validation uses `validateV4LifecycleMarket`.
-The factory getter is `dependencyDigest(address)`. Identity domains are
-`black-market.launch-profile.v2`, `black-market.v4-dependencies.v2` and
-`black-market.pool-bound-market-economics.v1`. No old-name aliases remain; regenerate
-profile identities, commitments and author consent for these domain labels.
+The canonical authorities are the registry/certification/adapter/config contracts under
+`contracts/src/launch/lifecycle/v2`, typed hook deployers, and `contracts/src/launch/fees/v3`
+in the protocol repository. Plan identity is `LaunchPlanV1`. Pool-bound V4 uses **config 5**,
+canonical Abyss uses **config 1**, and generic current shared-V4 support uses **config 4**.
+
+## Deployed infrastructure
+
+Robinhood mainnet (`4663`) selects the mined `pool-launch-v1` deployment captured at block
+`80548181` in `contracts/deployments/launch/pool-launch-v1/20261005T053747Z-b5a7b88/manifest.json`.
+The manifest records successful receipts and canonical runtime evidence. The graph has two
+adapters and five admitted profiles: one fixed pool-bound V4 profile and four canonical Abyss
+variants. It does not deploy a shared V4 root.
+
+| SDK field | Mainnet address |
+| --- | --- |
+| `launchOrchestrator` | `0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E` |
+| `launchImplementationRegistry` | `0xaa8a410709B79cBA6F118F1be1FF568877A3B8Ee` |
+| `launchFeeOwnerRegistry` | `0x15778Aad08e12D458B2848F035860e2a8c2a0725` |
+
+`getAddresses(4663)` exposes this graph; `robinhoodLaunchApplication` exposes the mined
+launch constants. Launch addresses on `31337` and `46631` remain zero unless configured.
+Address overrides are evaluated once on import: bare names win, then `VITE_`, then
+`NEXT_PUBLIC_`. Configure `LAUNCH_ORCHESTRATOR`, `LAUNCH_IMPLEMENTATION_REGISTRY`, and
+`LAUNCH_FEE_OWNER_REGISTRY` from the same deployment evidence.
+
+Canonical Abyss defaults are retained. DEX overrides apply on `31337` and `46631`, not
+mainnet. Lending mainnet defaults use `contracts/deployments/robinhood/replacement-infrastructure.json`;
+the workbench's existing lending endpoints follow that replacement. Lending overrides apply
+on `31337` (all three prefixes) and `46631` (`VITE_`/`NEXT_PUBLIC_`); liquidation-executor
+overrides use all three prefixes on every chain. Workbench chain RPC configuration reads
+`VITE_RPC_URL`, then `NEXT_PUBLIC_RPC_URL`, then `RPC_URL`; client factories prefer their explicit
+`rpcUrl`, then `RPC_URL`, then the chain endpoint. Select the chain explicitly in applications.
+
+Registry V2 has one `LaunchCertificationV2` child. V4 uses `profileEnvelope`, `profileId`, and
+signed six-argument `registerProfile`. Admin-only `registerAbyssProfile(uint8,registration)`
+independently certifies config-1 variants without an author envelope or royalty allocation.
+The admission EIP-712 domain is `Black Market Launch Registry`, version `2`.
+
+`LaunchBoundsV2` has five members: minimum/maximum tick spacing, maximum positions,
+maximum oracle cardinality, and fee-mode flags. Creators select valid LP/hook rates below
+1,000,000 pips, a registered oracle configuration, and per-pool external-liquidity policy.
+Author royalty ceilings are separate. Robinhood P1 `(1,4096)`, P2 `(6,4096)`, and P3 `(17,4096)`
+can use the same admitted profile; the selected oracle is checked at the pinned block.
+With `externalLiquidityDisabled=false`, third-party LP add/remove is allowed after opening.
+Permanent launch custody and pre-opening protection still apply.
+
+The deployed pool stack uses `FixedFeePoolHookV1`, `PoolHookDeployerV1`,
+`PoolMarketAdapterV1`, and `PoolFeeCollectorFactoryV1`. The complete `fixedFeePoolHookV1Abi`
+includes the exact **one-tuple, 18-field constructor**, callbacks, events, and errors from the
+mined artifact. Its fixed scalar fee calculation does not imply a scalar-argument constructor.
+Generic shared contracts are `FixedFeeSharedHookV1`, `SharedHookDeployerV1`, and
+`SharedMarketAdapterV1`; they require their own admitted deployment graph.
+Other current ABI exports include `sharedMarketAdapterV1Abi`, `sharedHookDeployerV1Abi`,
+`poolMarketAdapterV1Abi`, `poolHookDeployerV1Abi`, and `poolFeeCollectorFactoryV1Abi`.
+Validation uses `validateV4LifecycleMarket`; the collector factory getter is
+`dependencyDigest(address)`. Identity domains are `black-market.launch-profile.v2`,
+`black-market.v4-dependencies.v2`, and `black-market.pool-bound-market-economics.v1`.
 
 ## Public operations
 
@@ -108,13 +129,13 @@ Registry `authorizationDigest`, `beneficiaryNonces` and `registerProfile` ABIs e
 (uint16,uint24,int24,uint160,uint24,uint8,uint8,address,bool,bytes32,bytes32,bytes32,bytes32,address,uint16,(int24,int24,uint128,bytes32,uint256)[])
 ```
 
-Both preserve LP/hook fees, tick spacing, opening price, fee mode/denominator/treasury, external-liquidity policy and canonical oracle identity. Then come `profileId`, `termsDigest`, `developerBeneficiary` and explicit `developerFeeBps`, followed by positions. Version 5 inserts `hookSalt` immediately before `profileId`. There is no conversion from config 2/3 and no SDK default developer rate, including when the chosen rate is zero. Copy terms from the selected profile, not another shared/bound template's envelope. Inner/outer profile IDs must match; author identity is not the live payout. The creator rate cannot exceed either reviewed maximum or protocol ceiling.
+Both preserve LP/hook fees, tick spacing, opening price, fee mode/denominator/treasury, external-liquidity policy, and canonical oracle identity. Then come `profileId`, `termsDigest`, `developerBeneficiary`, and explicit `developerFeeBps`, followed by positions. Version 5 inserts `hookSalt` immediately before `profileId`. Every developer rate, including zero, is creator-selected. Copy terms from the selected profile's envelope. Inner/outer profile IDs must match; author identity is not the live payout. The creator rate cannot exceed either reviewed maximum or protocol ceiling.
 
 ```ts
 const profile = profiles.find((row) => row.id === selectedProfileId);
 if (!profile?.admitted || !profile.envelope || !profile.developerTerms) throw new Error("Selected profile is not reviewed/admitted");
-const config = encodeV4LifecycleMarketConfig({
-  version: 4, lpFeePips, tickSpacing, sqrtPriceX96, hookFeePips, feeMode,
+const config = encodePoolBoundV4LifecycleMarketConfig({
+  version: 5, hookSalt: zeroHash, lpFeePips, tickSpacing, sqrtPriceX96, hookFeePips, feeMode,
   protocolFeeDenominator: profile.envelope.protocolFeeDenominator,
   treasury: profile.envelope.protocolTreasury,
   externalLiquidityDisabled: creatorSelectedExternalLiquidityDisabled,
@@ -238,6 +259,143 @@ Lifecycle dividend tokens retain independent current-owner dividend bounty up to
 node examples/generate-lifecycle-commitment-fixture.mjs test/fixtures/launch-lifecycle-v1.json
 ```
 
-After concurrent source changes settle, build/test the package and run `examples/quickstart.mjs`. Meaningful regressions cover commitment/identity/numerical domains, retired codecs, reviewed terms/rate/bounds, salt normalization/mining/cancellation, receipt recovery and author authentication/routing/page outcomes. Retired wording/selector/source-wiring tests are removed rather than re-pinned.
+Build and run the offline unit suite with `pnpm test`, and deployed read-only discovery with
+`pnpm examples`. Unit regressions cover commitment/identity/numerical domains,
+reviewed terms/rate/bounds, salt normalization/mining, receipt recovery, and author
+authentication/routing/page outcomes. Wire vectors remain
+offline schema references; they are not a mainnet launch or an admitted deployment graph.
+
+`examples/launch.mjs` reviews a saved plan without signatures or source-chain writes:
+
+```sh
+pnpm build
+node examples/launch.mjs --plan plan.json --rpc https://rpc.mainnet.chain.robinhood.com/ --mode staged --mine
+```
+
+The saved plan must use that RPC's chain and current deployment. `--mine` finalizes bound
+salts offchain; `--limits current-limits.json`, `--receipts receipts.json`, and `--confirmations N`
+supply explicit execution/recovery evidence. The command never invents provider/account limits.
+Without a sequential simulation backend and matching execution-limit provenance, its review
+can be provisional and cannot produce an admitted next transaction.
+
+`examples/launch-lifecycle-smoke.mjs manifest.json sdk-plans.json` executes Solidity-exported
+plans only on explicitly authorized owned loopback fixtures. It exercises atomic/staged
+modes, typed predeployment, ordered buys, permanent custody, canonical recovery, no-argument
+V3 harvest, and authenticated author claims. `test/lifecycle-chain.test.mjs` exercises
+real-graph refusals/reorg/cancellation with the same fixture environment. See
+[example instructions](../examples/README.md#actual-owned-fixture-proof) for the explicit
+local-execution opt-in and required files.
+
+## Individual token creation examples
+
+Eight independent `examples/launch-erc20-*.mjs` / `launch-erc404-*.mjs` files invoke
+the shared `runLaunchExample(caseObject)` using fixed economics and no parameters or
+fixture files. See the [example guide](../examples/README.md#individual-token-creation)
+for the eight one-line commands and setup-once working-directory `.env`.
+Node 24+ loads `.env` once, with existing process environment taking precedence.
+`PRIVATE_KEY` and `LAUNCH_API_URL` are required before RPC/signing/API work; there is
+no default key, guessed API or API-omission mode. Running a case deliberately authorizes
+real local signing, source-chain transactions and API publication; mainnet writes are
+irreversible. The official SDK chain-4663 RPC is the default.
+
+The implementation imports public `@black-market/sdk`, resolves `getAddresses(4663)`,
+derives the creator from the key and discovers the actual admitted profiles. V4 requires
+bound topology/config `5`; Abyss requires exact adapter `profileId(3)` QUOTE_ORACLE/config
+`1`. It verifies wrapped-native binding/decimals and registered P1 oracle `(1,4096)`.
+All eight original token/reward/venue/position/mode cases retain their exact economics:
+ERC20 `1_000_000e18` supply; ERC404 `10_000e18` supply / `100e18` NFT unit; selected
+staking/dividends and token-only burn; one through five permanent positions and ordered
+native-wrap opening buys. It saves identity/finalized salts/plans before execution and
+never changes mode, drops positions/buys or overrides failed admission.
+Optional `NFT_BASE_URI` provides an ERC404 base URI you actually host; its default is
+empty, with real NFT units/mirror behavior but no claim of hosted NFT metadata.
+
+Optional `SIMULATION_RPC_URL` uses the canonical SDK controlled fork on a separate
+owned disposable loopback Anvil. Otherwise real native sequential `eth_simulateV1` is
+required. Only the simulation fork is reset/impersonated/reverted. Source RPC requests
+have a 120-second bound and are not retried. Default gas `16000000`, calldata `131072`
+and headroom `1000` bps are explicitly **EXAMPLE ceilings, not verified provider/account
+limits**; the chain cap is bounded by observed block gas limits. Environment overrides
+are documented in the example guide and remain subject to full SDK admission.
+
+Execution rechecks chain/creator/destination and exact finalized calldata before each
+send. Exact admitted envelopes are signed locally; computed hashes and unsigned
+envelopes are saved **before** the single raw broadcast, and included receipts are
+saved before status/provenance assertions. One canonical confirmation is required.
+Actual verification covers Active state, factory/token runtime/name/symbol/kind/rewards,
+ERC404 unit/URI/mirror, opened markets, sealed V4 custody/permanent Abyss lock terms,
+fee policies and ordered activation buys.
+
+Actual SDK API metadata staging uses locally signed full-domain attribution. Only the
+real activation hash is published. Genuine pending-indexer HTTP `202` is polled within
+90 seconds respecting `Retry-After`; other failures are not retried. Success requires
+an optimistic/final session and real indexed `/api/v1/launches/<token>?chainId=4663`
+DTO with matching creator/token/hash/metadata. Missing/incompatible indexing fails
+honestly without manufacturing projections, skipping API or launching another token.
+
+Every run automatically creates fresh `launch-results/<timestamp-case-random>/`:
+
+| Artifact | Evidence |
+| --- | --- |
+| `events.jsonl` | Timestamped case/stage events, RPC/API errors, admission/simulation and actual chain observations. |
+| `plan.json` | Full finalized portable SDK plan saved before execution. |
+| `receipts.json` | Exact signed-envelope hashes retained pre-broadcast, followed by real receipts/references. |
+| `result.json` | `black-market.launch-example-result.v1`, end-to-end status, failure stage and causal evidence. |
+| `published-token.json` | Actual indexed API representation. |
+| `private-recovery.json` | Mode `0600`; signed raw bytes, API signature and one-time capability. Never share/commit. |
+
+Public artifacts redact known keys/signatures/raw bytes/capabilities/auth values and
+endpoint secrets while retaining public calldata/hashes/revert bytes. Configuration,
+admission, broadcast, publication and interruption failures exit nonzero and preserve
+evidence. No source rollback, cancellation, broadcast retry or relaunch occurs.
+Inspect retained transaction hashes before deciding to run a new case after an
+ambiguous send. `test/launch-example.test.mjs` covers offline signing/retention/config
+boundaries only, not actual chain/API proof. The older independent whole-graph local
+Solidity-exported proof remains separate.
+
+## Real HTTP API integration
+
+The opt-in suites use `LaunchApiClient` and actual HTTP requests—not a mocked transport.
+They do not start a service or provision storage. Configure an abyss-api service with:
+
+- `/api/v1/launch-upload-sessions` and its capability-protected read route;
+- real application PostgreSQL storage with launch-upload-session migrations applied;
+- an enabled request chain matching `LAUNCH_API_TEST_CHAIN_ID`;
+- its current launch verifying contract matching `LAUNCH_API_TEST_ORCHESTRATOR`.
+
+For the actual abyss-api service, that verifying contract is the configured deployment
+`contracts.launchFactory` field, which must contain the current orchestrator address.
+The signed attribution domain is `Abyss Launch Attribution`, version `1`. Session signature
+deadlines must be future timestamps at most 15 minutes away. Metadata hashes use canonical
+NFC/trimmed text, normalized URLs, fixed field order, and null absent optional values.
+
+| Environment | Meaning |
+| --- | --- |
+| `LAUNCH_API_TEST_URL` | Required HTTP service root, e.g. `http://127.0.0.1:18763`; no implicit production target. |
+| `LAUNCH_API_TEST_CHAIN_ID` | Defaults to `4663`; must be configured on the test service. |
+| `LAUNCH_API_TEST_ORCHESTRATOR` | Defaults to `0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E`; must match the service's signing domain. |
+| `LAUNCH_API_TEST_PRIVATE_KEY` | Required only for the explicit signed suite; disposable EOA key, never a production key. |
+
+```sh
+# Read-only capability/error boundaries; no key and no storage writes.
+LAUNCH_API_TEST_URL=http://127.0.0.1:18763 pnpm test:api
+
+# Signed metadata-session writes, allowed only on an owned disposable loopback service.
+LAUNCH_API_TEST_URL=http://127.0.0.1:18763 \
+LAUNCH_API_TEST_PRIVATE_KEY="$DISPOSABLE_TEST_PRIVATE_KEY" pnpm test:api:write
+```
 
-`examples/launch-lifecycle-smoke.mjs manifest.json sdk-plans.json` executes current Solidity-exported `plans` on explicitly authorized owned loopback fixtures, with distinct fork and reviewed controlled-local operator limits. It exercises explicit atomic/staged modes, mined typed predeployment, actual ordered buys/permanent custody, canonical recovery, no-arg V3 harvest and authenticated author page claims with actual payout balance checks. `test/lifecycle-chain.test.mjs` adds real-graph refusal/reorg/cancellation boundaries when the same fixture environment is provided. See [the current evidence index](../../black-market/docs/10-4-audit/README.md) for exercised results and limits; this guide makes no live broadcast/UI/provider-ceiling claim.
+The write suite creates metadata-only sessions, reads persisted normalized metadata,
+replays the byte-identical signed body without reissuing the one-time capability, refuses a
+changed authorized payload under the same idempotency key, and checks capability isolation.
+It also rejects wrong signers, wrong orchestrator/chain domains, altered metadata, a changed
+idempotency key, expired authorization, and invalid signatures. The private key signs EIP-712
+metadata only; it need not have a balance. Unique session/key/nonces permit repeat runs.
+The disposable service operator owns database cleanup; the API has no session-deletion route.
+
+Neither suite needs an image store, indexed launch, confirmed transaction hash, or chain
+write. Metadata sessions do not prove token deployment, image publication, or transaction
+indexing. Image/upload/publication operations require those additional real prerequisites
+and are not exercised here. Explicitly selected suites fail on missing URL/key, absent
+storage/routes, an unreachable service, or incompatible signing configuration instead of
+silently skipping. Ordinary `pnpm test` stays offline and does not select HTTP integration.

package/examples/.env.example

@@ -0,0 +1,20 @@
+# Copy to .env in the directory from which you run node (Node 24+).
+# Running a launch-*.mjs file deliberately signs, spends funds and publishes.
+PRIVATE_KEY=
+LAUNCH_API_URL=
+
+# Optional: blank uses the SDK official Robinhood chain-4663 mainnet RPC.
+RPC_URL=
+# Optional: separate owned loopback Anvil used only for SDK controlled simulation.
+# Blank selects the actual RPC native eth_simulateV1 backend.
+SIMULATION_RPC_URL=
+# Optional ERC404 NFT metadata base URI that you actually host; blank means empty URI.
+NFT_BASE_URI=
+
+# Optional EXAMPLE ceilings, NOT verified provider/account limits.
+# Chain cap is also bounded by every observed block gas limit.
+# EXAMPLE_CHAIN_GAS_CAP=16000000
+# EXAMPLE_RPC_GAS_CAP=16000000
+# EXAMPLE_ACCOUNT_GAS_CAP=16000000
+# EXAMPLE_MAX_CALLDATA_BYTES=131072
+# EXAMPLE_HEADROOM_BPS=1000

package/examples/README.md

@@ -0,0 +1,223 @@
+# Examples
+
+The launch examples use the installed public `@black-market/sdk` package and viem,
+including when copied into a consumer project. The deployed chain-4663 graph uses
+pool-bound V4 config 5 and canonical Abyss config 1. Discovery is read-only; running
+a fixed launch example with configured wallet/API deliberately executes real writes.
+
+| Script | Behavior |
+| --- | --- |
+| `quickstart.mjs` | Reads the current mainnet orchestrator, checks its registry binding, and discovers admitted profiles. No wallet or writes. |
+| `launch.mjs` | Reviews/reconstructs an explicit saved plan and selected atomic/staged mode; optional offchain config-5 salt mining. Prints simulation, progress, and an admitted unsigned next transaction when evidence permits. |
+| `generate-lifecycle-commitment-fixture.mjs` | Independent offline ABI reference for current config-4/Abyss commitment bytes/hash/identity, not a deployment or executable launch. |
+| `launch-lifecycle-smoke.mjs` | Actual SDK launch/recovery/custody/fee operations, only on an explicitly authorized owned disposable loopback graph. |
+| `launch-erc20-*.mjs`, `launch-erc404-*.mjs` | Eight independent zero-parameter launch cases with actual SDK admission, local signing, chain verification and mandatory API publication/indexing. |
+
+## Deployed read-only discovery
+
+```sh
+pnpm install
+pnpm examples
+# Optional: RPC_URL=https://your-robinhood-rpc pnpm examples
+```
+
+`CHAIN_ID` defaults to `4663`. Local `31337` and workbench `46631` require a matching
+RPC and explicit `LAUNCH_ORCHESTRATOR`, `LAUNCH_IMPLEMENTATION_REGISTRY`, and
+`LAUNCH_FEE_OWNER_REGISTRY`. The example checks RPC chain identity and registry binding.
+Profile discovery verifies live registry admission and certified dependencies; it does
+not build/sign a launch, choose a developer fee, or select market economics.
+
+## Unsigned saved-plan review
+
+Supply full `LaunchPlanV1` JSON using the selected RPC's current deployment:
+
+```sh
+pnpm build
+node examples/launch.mjs \
+  --plan plan.json --rpc https://rpc.mainnet.chain.robinhood.com/ --mode staged --mine
+```
+
+`--mine` finalizes config-5 salts offchain and prints the final plan. Persist that exact
+commitment before begin. `--receipts receipts.json` and `--confirmations N` restore
+canonical recovery context. The CLI never signs, submits source-chain transactions,
+uploads metadata, or publishes a launch. Modes never fall back silently.
+
+Executable admission additionally requires current matching execution-limit evidence
+(`--limits current-limits.json`) and sequential `eth_simulateV1`, or an explicitly
+supplied **separate disposable loopback fork** (`--fork-rpc URL`). Limits must include
+chain/account/core/observed-block/hash provenance and actual chain/RPC/account/calldata
+caps; encode bigint values as decimal strings. Missing facts produce provisional/refused
+admission, not invented provider/account policy. See the
+[lifecycle guide](../docs/launch-lifecycle.md#execution-constraints-and-stateful-simulation).
+
+## Real HTTP metadata sessions
+
+The real HTTP integration suite uses the public `LaunchApiClient` against a separately
+running service. Reads are unsigned; metadata-session writes require a disposable key
+and an owned loopback service with real application storage:
+
+```sh
+LAUNCH_API_TEST_URL=http://127.0.0.1:18763 pnpm test:api
+LAUNCH_API_TEST_URL=http://127.0.0.1:18763 \
+LAUNCH_API_TEST_PRIVATE_KEY="$DISPOSABLE_TEST_PRIVATE_KEY" pnpm test:api:write
+```
+
+These are metadata-only session tests, not token deployment or image/transaction
+publication. No image store, indexer, wallet balance, or chain transaction is needed.
+See [service prerequisites](../docs/launch-lifecycle.md#real-http-api-integration).
+
+## Individual token creation
+
+**Running one of these files signs and broadcasts a real launch and writes to your
+configured API. Mainnet execution is irreversible and spends real funds.** Choose
+one command per intended launch; there are no flags, parameters or fixture files.
+
+### Setup once
+
+Use **Node 24+**. In this repository run `pnpm install`. In a consumer project install
+both public dependencies with `pnpm add @black-market/sdk viem` (or
+`npm install @black-market/sdk viem`) and copy the selected files with
+`launch-example.mjs` and `launch-example-support.mjs` into `examples/`.
+Copy `examples/.env.example` to `.env` in the directory you will run commands from:
+
+```sh
+cp examples/.env.example .env
+chmod 600 .env
+```
+
+Edit `.env` once:
+
+```dotenv
+PRIVATE_KEY=
+LAUNCH_API_URL=
+RPC_URL=
+SIMULATION_RPC_URL=
+```
+
+Set `PRIVATE_KEY` to **your funded EOA's** 32-byte hex key and `LAUNCH_API_URL` to
+your actual HTTPS or owned loopback API service root. There is no default wallet,
+public development key, guessed API URL, or silent API skip. The API needs actual
+application storage and an indexer observing the same chain as the execution RPC.
+Existing environment variables take precedence over the working-directory `.env`,
+loaded once using Node's native `process.loadEnvFile`. No shell interpolation is used.
+
+Blank `RPC_URL` uses the SDK official Robinhood chain-4663 mainnet endpoint; HTTPS
+providers and explicit owned loopback HTTP execution RPCs are supported.
+The creator is derived locally from the key, and the deployment/WETH addresses come
+from `getAddresses(4663)`. The runner checks chain identity, EOA and deployed core,
+discovers admitted profiles, verifies the actual wrapped-native binding and reads
+the registered P1 `(1,4096)` oracle configuration. No fixture defines these facts.
+Optional `NFT_BASE_URI` supplies your actually hosted ERC404 NFT metadata base URI.
+Blank uses an empty base URI: NFT units/mirror behavior remain real, but the example
+does not claim hosted NFT metadata exists.
+
+Blank `SIMULATION_RPC_URL` selects the actual SDK native sequential `eth_simulateV1`
+backend. Set it only to a **separate owned disposable loopback Anvil** for the canonical
+SDK controlled fork; only this simulation environment is reset/impersonated/reverted.
+Unsupported native simulation, insufficient funds or failed admission stop before API
+staging/broadcast. There is no mode fallback, admission override or reduced case.
+
+### Commands and fixed cases
+
+```sh
+node examples/launch-erc20-v4.mjs
+node examples/launch-erc20-abyss.mjs
+node examples/launch-erc404-v4.mjs
+node examples/launch-erc404-abyss.mjs
+node examples/launch-erc20-staking-v4.mjs
+node examples/launch-erc20-dividends-abyss.mjs
+node examples/launch-erc20-burn-mixed.mjs
+node examples/launch-erc404-dividends-mixed.mjs
+```
+
+| File suffix | Token / rewards | Markets and permanent positions | Mode / opening buys |
+| --- | --- | --- | --- |
+| `erc20-v4` | ERC20 / none | V4: 1 | atomic / 1 |
+| `erc20-abyss` | ERC20 / none | Abyss: 1 | atomic / 1 |
+| `erc404-v4` | ERC404 / none | V4: 1 | staged / 1 |
+| `erc404-abyss` | ERC404 / none | Abyss: 1 | atomic / 1 |
+| `erc20-staking-v4` | ERC20 / staking | V4: 2 | staged / 2 |
+| `erc20-dividends-abyss` | ERC20 / dividends | Abyss: 3 | staged / 1 |
+| `erc20-burn-mixed` | ERC20 / token-only burn 3000 bps | dual-fee V4: 2; Abyss: 1 | staged / 1 per market |
+| `erc404-dividends-mixed` | ERC404 / dividends | V4: 2; Abyss: 3 | staged / 1 per market |
+
+ERC20 supply is `1_000_000e18`; ERC404 supply is `10_000e18`, NFT unit `100e18`.
+Positions retain `1000e18` liquidity and the case's exact ranges. Each ordered buy
+spends up to `0.001 ETH` through native-wrap funding. Rewards use 4000 bps where
+selected; token-only burn is 3000 bps in the burn case. V4 uses frozen registered
+treasury/author terms with developer rate `0`; executor fee is 275 bps.
+Hook salts/random identities are finalized and saved before execution.
+
+### Example execution ceilings
+
+Defaults are **EXAMPLE ceilings, not verified provider or account limits**:
+chain/RPC/account gas `16000000`, calldata `131072` bytes, headroom `1000` bps.
+The chain cap is additionally bounded by every observed block gas limit. If your
+provider/account policy differs, configure decimal environment values:
+`EXAMPLE_CHAIN_GAS_CAP`, `EXAMPLE_RPC_GAS_CAP`, `EXAMPLE_ACCOUNT_GAS_CAP`,
+`EXAMPLE_MAX_CALLDATA_BYTES`, `EXAMPLE_HEADROOM_BPS`. These do not bypass SDK admission.
+
+### Evidence and failure recovery
+
+Each run automatically creates `launch-results/<timestamp-case-random>/`; there is
+no user output option. Inspect `result.json`, `events.jsonl`, finalized `plan.json`,
+`receipts.json` and `published-token.json`. Exact admitted wallet envelopes are signed
+locally; computed hashes and unsigned envelopes are durably retained as
+`broadcast-attempt` **before the one raw broadcast**. Real receipts are saved before
+status/canonical-state assertions. No unlocked-account signing or sending is used.
+Public evidence redacts known keys, signatures, signed raw bytes, API capabilities,
+authorization values and RPC endpoint credentials. Only `private-recovery.json`
+(mode `0600`) retains raw signed transactions and one-time API recovery material;
+never share or commit it. `launch-results/` is ignored.
+
+Every case requires actual API metadata staging, publication using the activation
+hash, and an indexed DTO matching token/creator/hash/metadata. Genuine pending-indexer
+HTTP `202` responses are polled for up to 90 seconds respecting `Retry-After`;
+other API failures are not retried or converted to partial success. Broadcast/API
+failures retain logs/hashes and exit nonzero. The runner never retries a raw send,
+relaunches, cancels or rolls back the source chain. **Do not blindly rerun after an
+ambiguous broadcast**: inspect the durable transaction hash on chain first.
+See [chain/API invariants](../docs/launch-lifecycle.md#individual-token-creation-examples).
+
+### Owned-local wallet verification helpers
+
+`launch-example-support.mjs` exports
+`createLocalLaunchWallet({privateKey,creator,chainId,orchestrator,client,redactor})`
+and `submitSignedRecorded({transaction,wallet,client,wait,artifacts,signal})`.
+`client.request({method,params})` is an explicit RPC adapter; `transaction` carries
+`id`, `kind`, and exact unsigned `wire` chain/from/to/data/value/gas fields plus
+optional nonce/fees/type/accessList. `wait(hash)` returns a real receipt.
+The signer exposes `address`, `signTypedData(typedData)` and `signTransaction(wire)`
+returning `{wire,rawTransaction,transactionHash}`. Retain the result privately.
+Use `RunArtifacts(output,caseId,redactor)` with `Redactor` and a fresh directory for
+durable evidence; call `initialize()` before work and `finish(status,error)` afterward.
+The shared `runLaunchExample(caseObject)` in `launch-example.mjs` takes the same fixed
+case objects as the eight files, loads environment and auto-creates its output.
+Offline diagnostic tests are in `test/launch-example.test.mjs`; they do not claim
+real launch or API-indexer proof.
+
+
+## Actual owned-fixture proof
+
+The manifest must declare `fixtureOnly: true`, exact reviewed graph addresses, and
+`executionLimits.provenance.scope: "controlled-local-measurement"`. The plan file
+contains Solidity-exported `plans` with encoded-plan/hash/identity/token vectors.
+Do not pass a mined mainnet manifest as a writable fixture.
+
+```sh
+pnpm build
+LAUNCH_LIFECYCLE_RPC_URL=http://127.0.0.1:18555 \
+LAUNCH_LIFECYCLE_FORK_RPC_URL=http://127.0.0.1:18556 \
+LAUNCH_LIFECYCLE_ALLOW_LOCAL_EXECUTION=1 \
+node examples/launch-lifecycle-smoke.mjs manifest.json sdk-plans.json
+```
+
+This explicitly authorized command executes disposable fixture transactions and
+restores snapshots per plan/mode. It exercises ordered buys, canonical Active state,
+permanent custody, typed deployment provenance, V3 no-argument `claimAndSplit()`,
+reserved owner/developer balances, and authenticated author claims. Cursor completion
+and payment success stay separate.
+
+For chain boundary regressions, also set `LAUNCH_LIFECYCLE_MANIFEST` and
+`LAUNCH_LIFECYCLE_FIXTURES`, then run `node --test test/lifecycle-chain.test.mjs` with
+the same local-execution environment. Ordinary `pnpm test` does not authorize chain writes.

package/examples/generate-lifecycle-commitment-fixture.mjs

@@ -0,0 +1,49 @@
+import { encodeAbiParameters, keccak256, parseAbiParameters, stringToHex } from "viem";
+import { writeFile } from "node:fs/promises";
+
+// Independent wire-format reference: does not import the SDK encoder under test.
+const wire = "(uint256 chainId,address orchestrator,address creator,uint256 nonce,(uint8 kind,uint8 rewardMode,string name,string symbol,uint256 supply,uint256 nftUnit,string metadataURI,bytes32 salt,address inventoryRecipient,bool burnOnCancel) token,(address asset,uint256 amount,uint8 kind,address inputAsset,uint256 inputAmount,address target,bytes data)[] funding,(address asset,uint16 ownerBps,uint16 rewardsBps,uint16 burnBps)[] feeAssets,(bytes32 adapterId,bytes32 profileId,address quoteAsset,uint256 tokenBudget,uint32 configVersion,bytes config)[] markets,(uint32 marketIndex,uint256 quoteAmountIn,uint256 minTokenOut,address recipient,uint160 sqrtPriceLimitX96)[] buys,uint256 deadline,uint16 executorFeeBps) plan";
+const address = (value) => `0x${value.toString(16).padStart(40, "0")}`;
+const bytes32 = (value) => `0x${value.toString(16).padStart(64, "0")}`;
+const zero = address(0);
+const plan = {
+  chainId: 31337n, orchestrator: address(0xf0), creator: address(0xa0), nonce: 2n ** 192n + 17n,
+  token: { kind: 1, rewardMode: 1, name: "Lifecycle commitment 🜁", symbol: "LCV", supply: 10n ** 27n,
+    nftUnit: 100n * 10n ** 18n, metadataURI: "ipfs://lifecycle-vector/", salt: bytes32(0x1234), inventoryRecipient: address(0xa0), burnOnCancel: true },
+  funding: [
+    { asset: address(0x20), amount: 500_000_001n, kind: 0, inputAsset: address(0x20), inputAmount: 500_000_001n, target: zero, data: "0x" },
+    { asset: address(0x30), amount: 10n ** 20n, kind: 1, inputAsset: address(0x30), inputAmount: 10n ** 20n, target: zero, data: "0x" },
+  ],
+  feeAssets: [
+    { asset: address(0x10), ownerBps: 8000, rewardsBps: 0, burnBps: 2000 },
+    { asset: address(0x20), ownerBps: 6000, rewardsBps: 4000, burnBps: 0 },
+    { asset: address(0x30), ownerBps: 6000, rewardsBps: 4000, burnBps: 0 },
+  ],
+  markets: [
+    { adapterId: bytes32(1), profileId: bytes32(11), quoteAsset: address(0x20), tokenBudget: 4n * 10n ** 26n, configVersion: 4,
+      config: encodeAbiParameters(parseAbiParameters("(uint16,uint24,int24,uint160,uint24,uint8,uint8,address,bool,bytes32,bytes32,bytes32,address,uint16,(int24,int24,uint128,bytes32,uint256)[])"), [[4, 3000, 60, 2n ** 96n, 10000, 0, 6, address(0xa0), true, keccak256(encodeAbiParameters(parseAbiParameters("uint24,uint16"), [17, 4096])), bytes32(11), bytes32(21), address(0xd0), 250, [[60, 120, 10n ** 18n, bytes32(1), 10n ** 24n]]]]) },
+    { adapterId: bytes32(2), profileId: bytes32(12), quoteAsset: address(0x30), tokenBudget: 5n * 10n ** 26n, configVersion: 1,
+      config: encodeAbiParameters(parseAbiParameters("(uint8,uint24,bytes32,uint160,(int24,int24,uint128,uint256)[])"), [[3, 3000, bytes32(0x55), 2n ** 96n, [[60, 120, 10n ** 18n, 10n ** 24n]]]]) },
+  ],
+  buys: [
+    { marketIndex: 1, quoteAmountIn: 13n * 10n ** 18n, minTokenOut: 1n, recipient: address(0xb1), sqrtPriceLimitX96: 2n ** 96n - 1n },
+    { marketIndex: 0, quoteAmountIn: 20_000_000n, minTokenOut: 2n, recipient: address(0xb2), sqrtPriceLimitX96: 2n ** 96n - 1n },
+    { marketIndex: 1, quoteAmountIn: 7n * 10n ** 18n, minTokenOut: 3n, recipient: address(0xb3), sqrtPriceLimitX96: 2n ** 96n - 1n },
+  ],
+  deadline: 2_000_000_000n, executorFeeBps: 275,
+};
+const domain = keccak256(stringToHex("BLACK_MARKET_LAUNCH_PLAN_V1"));
+const fixture = {
+  schema: "black-market.launch-lifecycle-commitment-vector.v1", description: "Portable reviewed config-4/Abyss economic wire vector, not a deployed launch. Both modes commit identical economics.",
+  plan, encodedPlan: encodeAbiParameters(parseAbiParameters(wire), [plan]),
+  planHash: keccak256(encodeAbiParameters(parseAbiParameters(`bytes32 domain,${wire}`), [domain, plan])),
+  launchId: keccak256(encodeAbiParameters(parseAbiParameters("uint256,address,address,uint256"), [plan.chainId, plan.orchestrator, plan.creator, plan.nonce])),
+  domain, modes: ["atomic", "staged"],
+};
+const json = `${JSON.stringify(fixture, (_key, value) => typeof value === "bigint" ? value.toString() : value, 2)}\n`;
+const outputs = process.argv.slice(2);
+if (outputs.length === 0) process.stdout.write(json);
+else {
+  for (const output of outputs) await writeFile(output, json);
+  console.log(JSON.stringify({ generated: outputs, planHash: fixture.planHash, launchId: fixture.launchId }));
+}

package/examples/launch-erc20-abyss.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc20-abyss-basic", description: "ERC20, one canonical Abyss position, atomic opening",
+  tokenKind: 0, rewardMode: 0, mode: "atomic",
+  markets: [{ venue: "abyss", positions: 1 }], buysPerMarket: 1,
+});

package/examples/launch-erc20-burn-mixed.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc20-burn-mixed", description: "Burn policy, dual-fee V4 and Abyss markets for one token",
+  tokenKind: 0, rewardMode: 0, mode: "staged", burnBps: 3000,
+  markets: [{ venue: "v4", positions: 2, feeMode: 1 }, { venue: "abyss", positions: 1 }], buysPerMarket: 1,
+});

package/examples/launch-erc20-dividends-abyss.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc20-dividends-abyss", description: "Holder dividends and three canonical Abyss positions",
+  tokenKind: 0, rewardMode: 2, mode: "staged",
+  markets: [{ venue: "abyss", positions: 3 }], buysPerMarket: 1,
+});

package/examples/launch-erc20-staking-v4.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc20-staking-v4", description: "Staking rewards, two V4 positions and two ordered opening buys",
+  tokenKind: 0, rewardMode: 1, mode: "staged",
+  markets: [{ venue: "v4", positions: 2 }], buysPerMarket: 2,
+});

package/examples/launch-erc20-v4.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc20-v4-basic", description: "ERC20, one pool-bound V4 position, atomic opening",
+  tokenKind: 0, rewardMode: 0, mode: "atomic",
+  markets: [{ venue: "v4", positions: 1 }], buysPerMarket: 1,
+});

package/examples/launch-erc404-abyss.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc404-abyss", description: "ERC404 NFT units and metadata, atomic canonical Abyss",
+  tokenKind: 1, rewardMode: 0, mode: "atomic",
+  markets: [{ venue: "abyss", positions: 1 }], buysPerMarket: 1,
+});

package/examples/launch-erc404-dividends-mixed.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc404-dividends-mixed", description: "ERC404 holder dividends, both venues and five permanent positions",
+  tokenKind: 1, rewardMode: 2, mode: "staged",
+  markets: [{ venue: "v4", positions: 2 }, { venue: "abyss", positions: 3 }], buysPerMarket: 1,
+});

package/examples/launch-erc404-v4.mjs

@@ -0,0 +1,7 @@
+import { runLaunchExample } from "./launch-example.mjs";
+
+await runLaunchExample({
+  id: "erc404-v4", description: "ERC404 NFT units and metadata, staged pool-bound V4",
+  tokenKind: 1, rewardMode: 0, mode: "staged",
+  markets: [{ venue: "v4", positions: 1 }], buysPerMarket: 1,
+});