@black-market/sdk 0.5.0 → 0.5.2

package/README.md

@@ -1,142 +1,45 @@
-![Abyss](assets/splash.png)
+![Abyss](https://raw.githubusercontent.com/abysshopper/black-market-node-sdk/main/assets/abyss-social.webp)
 
-# @black-market/sdk
+# Abyss TypeScript SDK
 
-TypeScript tools for Black Market launches, the Abyss DEX, and lending on
-[Robinhood Chain](https://robinhoodchain.blockscout.com). Built on
-[viem](https://viem.sh): ESM, Node.js 20+, bigint amounts.
+Token launches, swaps, and lending with [viem](https://viem.sh).
 
 ## Install
 
 ```sh
-npm install @black-market/sdk viem
-# or: pnpm add @black-market/sdk viem
+pnpm add @black-market/sdk viem
 ```
 
-## Discover the deployed launch graph
+## Examples
 
-Save this as `discover.mjs` and run `node discover.mjs`. It reads mainnet only;
-no wallet, private key, or transaction is needed.
-
-```js
-import {
-  createProtocolPublicClient, getAddresses, readLifecycleProfiles,
-} from "@black-market/sdk";
-
-const client = createProtocolPublicClient({ chainId: 4663 });
-const { launchOrchestrator } = getAddresses(4663);
-const profiles = await readLifecycleProfiles({ client, orchestrator: launchOrchestrator });
-console.table(profiles.map(({ id, venueKind, topology, admitted, reason }) => ({
-  profile: id, venue: venueKind, config: topology.configVersion, admitted, reason,
-})));
-```
-
-The mined deployment has **pool-bound V4 config 5** and **Abyss config 1**:
-two adapters and five profiles. Discovery checks registry binding, runtime and
-dependency commitments, and current admission—not a hard-coded template list.
-
-From this repository, the same read-only example is available with:
+Clone this repository to run the examples. Requires Node 24+.
 
 ```sh
-pnpm install
-pnpm examples
-# Optional RPC override: RPC_URL=https://your-robinhood-rpc pnpm examples
+pnpm install && pnpm build
+node examples/quickstart.mjs
 ```
 
-## Launch workflow
-
-1. Discover an admitted profile and copy its exact schema, bounds, and author terms.
-2. Build an explicit `LaunchPlanV1`: creator, token, sorted funding/fee policies,
-   market budgets/configs, ordered buys, deadline, and selected developer rate.
-3. For V4 config 5, finalize its hook salt with `preparePoolBoundLifecyclePlan`.
-   Save `serializeLaunchPlan(result.plan)`; do not submit a draft commitment.
-4. Review `planLaunch` with an explicit `"atomic"` or `"staged"` mode and current
-   execution limits. Use `readLaunchProgress` and `buildNextTransaction` for recovery.
-5. Your application authenticates the wallet chain, signs the exact admitted
-   transaction, and stores receipt references. SDK planning/builders never sign.
-
-Staged preparation does **not** split activation: minting, permanent locking,
-every initial buy, and public opening remain one transaction. Unavailable
-stateful simulation or execution-limit evidence prevents executable admission.
+The quickstart reads available launch profiles without a wallet.
 
-See the [launch lifecycle guide](docs/launch-lifecycle.md) for codecs, saved-plan
-review, salt mining, simulation, recovery, and stable-author fee claims.
-[`examples/`](examples/README.md) includes unsigned review and explicitly authorized
-local-chain execution. `LaunchApiClient` optionally handles signed metadata
-sessions and publication; it does not create or broadcast a chain launch.
-
-## Create one local smoke token
-
-Use the [owned-fixture smoke guide](docs/launch-lifecycle.md#individual-token-creation-smoke)
-to prepare a current-chain fork, then run one catalogue case:
+For token launches, set `PRIVATE_KEY` and `LAUNCH_API_URL` in your working
+folder's `.env`. An optional `RPC_URL` overrides the default endpoint.
+Run one example for the token you want to create:
 
 ```sh
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json --list
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json \
-  --case erc20-v4-basic --output /tmp/node-launch-one \
-  --execute --api-url http://127.0.0.1:18763
+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
 ```
 
-Without `--execute`, this only saves an unsigned finalized plan—no simulation
-transactions, signing, API session or launch. Execution verifies the actual token,
-markets, permanent custody, buys and API publication/indexing. `--chain-only`
-explicitly skips the API and is not an end-to-end pass. Every run uses a fresh
-directory with redacted evidence retained on failure; no source-chain rollback,
-production write, package publishing or git push is performed.
-
-## Networks and configuration
-
-| Chain | Use | Launch defaults |
-| --- | --- | --- |
-| `4663` | Robinhood mainnet | Current mined deployment |
-| `46631` | Robinhood fork workbench | Explicit environment configuration |
-| `31337` | Local Anvil | Explicit environment configuration |
-
-Pass a chain ID explicitly: `getAddresses()` otherwise selects `46631`, while
-client factories otherwise select local `31337`. Mainnet lending addresses come
-from the replacement infrastructure; canonical Abyss DEX utilities remain available.
-
-| Mainnet launch contract | Address |
-| --- | --- |
-| Orchestrator | `0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E` |
-| Implementation registry | `0xaa8a410709B79cBA6F118F1be1FF568877A3B8Ee` |
-| Fee-owner registry | `0x15778Aad08e12D458B2848F035860e2a8c2a0725` |
-
-Launch address overrides are evaluated on import: bare `LAUNCH_ORCHESTRATOR`,
-`LAUNCH_IMPLEMENTATION_REGISTRY`, and `LAUNCH_FEE_OWNER_REGISTRY` take precedence
-over their `VITE_` and `NEXT_PUBLIC_` forms. Configure the whole matching graph.
-Client RPC precedence is explicit `rpcUrl`, then `RPC_URL`, then the selected
-chain's default endpoint. See the guide for DEX/lending override details.
-The browser-safe `@black-market/sdk/lifecycle` entrypoint contains launch codecs,
-ABIs, planning, recovery, and author APIs without selecting a deployed address.
-
-## Tests
-
-```sh
-pnpm test         # Build and run the offline node:test unit suite
-pnpm typecheck    # TypeScript public surface
-LAUNCH_API_TEST_URL=http://127.0.0.1:18763 pnpm test:api
-```
-
-`test:api` uses actual HTTP session reads and capability boundaries, without a key
-or writes. It requires a running abyss-api service with launch-session routes and
-real application storage. Missing configuration/storage or an unreachable service
-fails the explicitly selected suite; integration tests are not part of `pnpm test`.
-
-For signed metadata-only create/read/replay/conflict/authorization tests, use an
-**owned disposable loopback service and database**, with an explicit disposable key:
-
-```sh
-LAUNCH_API_TEST_URL=http://127.0.0.1:18763 \
-LAUNCH_API_TEST_PRIVATE_KEY="$DISPOSABLE_TEST_PRIVATE_KEY" pnpm test:api:write
-```
-
-`LAUNCH_API_TEST_CHAIN_ID` defaults to `4663`; `LAUNCH_API_TEST_ORCHESTRATOR`
-defaults to the mainnet orchestrator above and must match the service signing domain.
-No image store, indexed launch, funded wallet, or chain write is required. These
-sessions prove HTTP metadata behavior, not image publication or a chain launch.
-Service requirements are in the [API integration section](docs/launch-lifecycle.md#real-http-api-integration).
-
-## License
+Launch examples spend real funds and publish to your configured API.
+Plans, transaction hashes, receipts, and errors are saved in `launch-results/`.
+Keep `.env` and private recovery files out of Git.
 
-MIT
+[Example setup](https://github.com/abysshopper/black-market-node-sdk/tree/main/examples)
+· [API guide](https://github.com/abysshopper/black-market-node-sdk/blob/main/docs/launch-lifecycle.md)
+· [MIT license](https://github.com/abysshopper/black-market-node-sdk/blob/main/LICENSE)

package/docs/launch-lifecycle.md

@@ -286,93 +286,72 @@ 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 smoke
-
-`pnpm smoke:launch` builds the SDK and runs `examples/smoke-launch.mjs` for **one**
-case from an explicit `black-market.launch-smoke-fixture.v1` file. The
-[shared local setup and eight case commands](../../black-market/docs/sdk-launch-smoke.md)
-create separate owned loopback execution/simulation Anvil instances on chain `4663`
-using the current deployed graph, not a replacement launcher. Use a real loopback
-API with application storage and an indexer configured for that same execution chain.
-No default live endpoint, private key, source-chain snapshot rollback or production
-write is used. The older whole-suite Solidity-exported proof remains separate.
-
-```sh
-pnpm smoke:launch --help
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json --list
-
-# Default plan-only: registry/provenance reads, token prediction and offchain salt mining.
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json \
-  --case erc20-staking-v4 --output /tmp/node-staking-plan
-
-# Actual metadata signature/session, launch, custody/buy checks, publication and token GET.
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json \
-  --case erc20-staking-v4 --output /tmp/node-staking-launch \
-  --execute --api-url http://127.0.0.1:18763 --publish-timeout-seconds 90
-
-# API omitted by explicit choice, not a full end-to-end pass.
-pnpm smoke:launch --fixture /tmp/sdk-smoke/fixture.json \
-  --case erc404-abyss --output /tmp/node-erc404-chain --execute --chain-only
-```
-
-`--list` reads only the fixture catalogue, with no RPC, signature or write. A default
-run persists the finalized portable `plan.json` and reports **“Plan prepared; launch
-not executed”**, `scope: "plan-only"`, `execution: "not-run"` and API `not-run`.
-Only `--execute` permits SDK `planLaunch`/controlled-fork simulation, metadata signing,
-session creation and `eth_sendTransaction` from the fixture's unlocked Anvil creator.
-Every endpoint must be an explicit loopback root and the fixture must declare
-`fixtureOnly: true`; execution/simulation ports must differ. An API endpoint can come
-from `fixture.apiUrl` or `--api-url`, never the production SDK default.
-Local execution and instrumented simulation RPC HTTP calls have a bounded
-120-second per-request timeout to accommodate cold nested-fork state reads; they
-are not retried. API requests retain their separate timeout and publication deadline.
-
-All eight cases cover ERC20/ERC404, staking/dividends, token-only burn, atomic/staged
-execution, V4/Abyss/mixed markets and one through five permanent positions. Profiles
-are registry-discovered: V4 must be admitted bound topology/config `5`; Abyss must be
-the adapter's exact `profileId(3)` QUOTE_ORACLE/config `1`, not the first Abyss entry.
-The runner uses exact frozen V4 treasury/denominator/author terms, explicit developer
-rate `0`, measured local gas/calldata caps, current-block deadline and NativeWrap
-funding. ERC20 supply is `1_000_000e18`; ERC404 supply is `10_000e18` with `100e18`
-NFT units. It finalizes hook salts and saves the random identity before any write,
-never switching mode, dropping positions/buys or changing economics to obtain admission.
+## 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. Submitted envelopes/hashes are persisted **before** receipt polling; included
-receipts are preserved **before** status/provenance assertions and require one canonical
-confirmation. Verification reads actual Active state, token runtime/name/symbol/factory
-kind/reward binding, ERC404 unit/URI/mirror, canonical opened markets, permanent V4 sealed
-custody/Abyss lock terms, fee policies and ordered activation buys.
-
-The API session uses the SDK attribution schema with full EIP-712 domain and the same
-name/symbol as the token, signed via owned Anvil `eth_signTypedData_v4`. Only the actual
-atomic/activate transaction hash is published. Genuine `LaunchPublishPending` HTTP `202`
-responses are polled within the configured deadline, respecting `Retry-After`; all other
-errors fail immediately. Success additionally requires an actual optimistic/final session
-matching that token/hash and an actual `/api/v1/launches/<token>?chainId=4663` representation
-with matching creator, provenance and metadata. An API that cannot index `LaunchActivated`
-must fail honestly; the runner does not manufacture projections or claim chain-only as
-end-to-end success.
-
-Every run requires a fresh exclusive `--output` directory (its parent must exist):
+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 SDK/case/stage events, RPC/API errors, simulation backend/steps/gas, timing and canonical observations. |
-| `plan.json` | Full finalized SDK portable economic plan, written before execution. |
-| `receipts.json` | Every submitted exact envelope/hash and subsequently observed receipt/reference, including failures. |
-| `result.json` | `black-market.launch-smoke-result.v1`, scope, terminal passed/failed stage, chain/API observations, causal stacks and revert data. |
-| `private-recovery.json` | Mode `0600`; the only file retaining API authorization signature and one-time capability. Do not share or commit it. |
-
-Public artifacts recursively redact signatures, keys, capability/auth values and URL
-credentials/query secrets while retaining public transaction calldata, hashes, selector
-and revert bytes. Profile/draft/identity/planning/progress files provide additional
-redacted context. Configuration, admission, transaction, publication and interruption
-failures exit nonzero and preserve available evidence. The source chain is **not**
-reverted, cancelled or relaunched after failure; only the SDK's separate simulation fork
-restores its isolated simulation snapshots. Recover from stored evidence before deciding
-to run a new case. Runner diagnostic unit tests are `test/smoke-launch.test.mjs`; they do
-not replace actual fixture/API execution.
+| `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
 

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 }));
+}