@black-market/sdk 0.5.0 → 0.5.1

package/README.md

@@ -1,4 +1,4 @@
-![Abyss](assets/splash.png)
+![Abyss](https://raw.githubusercontent.com/abysshopper/black-market-node-sdk/main/assets/splash.png)
 
 # @black-market/sdk
 
@@ -59,30 +59,50 @@ 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.
 
-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.
+See the [launch lifecycle guide](https://github.com/abysshopper/black-market-node-sdk/blob/main/docs/launch-lifecycle.md)
+for codecs, saved-plan review, salt mining, simulation, recovery, and stable-author
+fee claims. [`examples/`](https://github.com/abysshopper/black-market-node-sdk/tree/main/examples)
+also includes read-only discovery and unsigned saved-plan review. `LaunchApiClient`
+handles signed metadata sessions and publication; it does not broadcast a chain launch.
 
-## Create one local smoke token
+## Launch examples: one command per case
 
-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:
+**Running any command below deliberately signs, spends funds, launches a token,
+and publishes through your configured API. Mainnet execution is irreversible.**
+No flags, parameters, fixture files, default private keys or API skips are used.
+
+Setup once with **Node 24+**: install dependencies (`pnpm install` in this repository,
+or `pnpm add @black-market/sdk viem` in a consumer), copy
+[`examples/.env.example`](https://github.com/abysshopper/black-market-node-sdk/blob/main/examples/.env.example)
+to `.env` in your working directory, and set your funded wallet's `PRIVATE_KEY`
+and actual `LAUNCH_API_URL`. Existing process environment wins over `.env`.
+Consumer projects may copy the example files plus both shared helpers into `examples/`;
+the implementation imports the installed public `@black-market/sdk` package.
 
 ```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.
+Run only the case you intend to launch. `RPC_URL` defaults to the SDK official
+chain-4663 mainnet endpoint. Optional `SIMULATION_RPC_URL` selects a separate owned
+loopback Anvil for SDK controlled simulation; otherwise actual native `eth_simulateV1`
+support is required. Admission failures do not change mode or economics.
+Gas/calldata defaults are **EXAMPLE ceilings, not verified provider/account limits**.
+Full setup, exact case economics, optional environment caps, and recovery are in the
+[example guide](https://github.com/abysshopper/black-market-node-sdk/blob/main/examples/README.md#individual-token-creation).
+
+Every run creates a fresh `launch-results/<timestamp-case-random>/` and retains
+redacted logs, plans, signed transaction hashes **before broadcast**, and real receipts
+even on failure. Only `private-recovery.json` (mode `0600`) stores raw signed bytes,
+API signatures and capabilities. **Do not blindly rerun after an ambiguous broadcast**;
+inspect the retained hash first. There is no broadcast retry, relaunch or source rollback.
 
 ## Networks and configuration
 
@@ -135,7 +155,7 @@ LAUNCH_API_TEST_PRIVATE_KEY="$DISPOSABLE_TEST_PRIVATE_KEY" pnpm test:api:write
 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).
+Service requirements are in the [API integration section](https://github.com/abysshopper/black-market-node-sdk/blob/main/docs/launch-lifecycle.md#real-http-api-integration).
 
 ## 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 }));
+}

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