@black-market/sdk 0.3.1 → 0.5.0

package/docs/launch-lifecycle.md

@@ -1,17 +1,64 @@
-# Reviewed launch lifecycle API
+# Launch lifecycle API
 
-`@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 reviewed 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.
+`@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 reviewed registry/certification/adapter/config contracts under `contracts/src/launch/lifecycle/v2`, the reviewed typed hook deployers, and `contracts/src/launch/fees/v3` in the sibling protocol repository. Plan identity remains `LaunchPlanV1`; shared V4 now 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 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**.
 
-The clean pool-only deployment uses `DeployPoolLaunchV1`, `PoolHookDeployerV1`,
-`PoolMarketAdapterV1`, `PoolFeeCollectorFactoryV1` and `LaunchCertificationV2`.
-Registry V2 has no legacy certification child or unsigned admission endpoint.
-Use `profileEnvelope`, `profileId` and signed `registerProfile`; envelope/bounds/graph
-types and encoding helpers now use `Launch` names without the `Reviewed` prefix.
-There are no old-name aliases. The admission EIP-712 domain is `Black Market Launch Registry`,
-version `2`; regenerate author consent after cutover. Existing profile/dependency hash
-preimages and config tuples remain unchanged. Old deployment evidence is not new-graph proof.
+## 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
 
@@ -58,7 +105,7 @@ The exact canonical registry getters are `profileCount`, `profileIds(offset,limi
 - `developerTerms?: {adapter, beneficiary, maximumDeveloperFeeBps, termsDigest, enabled}`.
 - `protocolMaximumDeveloperFeeBps?: number`.
 
-The profile identity uses domain `black-market.reviewed-launch-profile.v2` and commits the four review/economic digests, topology/config/economic versions, stable beneficiary, maximum rate and capabilities. It deliberately excludes instance addresses. `hashLifecycleProfile`, `encode/decodeLaunchEnvelope`, `encode/decode/hashLaunchBounds` and `hashLaunchDependencies` expose exact canonical encodings/domains. Graph dependency hashing includes chain/core/registry/registrar, live runtime commitments and exact code-chunk provenance; only the shared deployment salt is outside that economic dependency digest.
+The profile identity uses domain `black-market.launch-profile.v2` and commits the four review/economic digests, topology/config/economic versions, stable beneficiary, maximum author rate and capabilities. It deliberately excludes instance addresses. `hashLifecycleProfile`, `encode/decodeLaunchEnvelope`, `encode/decode/hashLaunchBounds` and `hashLaunchDependencies` expose exact canonical encodings/domains. Graph dependency hashing includes chain/core/registry/registrar, live runtime commitments and exact code-chunk provenance; only the shared deployment salt is outside that economic dependency digest.
 
 Profile certification checks reviewed capabilities/bounds, adapter/core/graph runtime hashes, manager/oracle/locker/collector dependencies, typed hook deployer and STOP-prefixed creation-code chunks. Shared roots additionally require exact constructor/salt prediction and the deployer's recorded runtime. Bound roots require exact immutable constructor/key/economic commitment and recorded runtime when deployed. Address bits `0x1afc` under mask `0x3fff` are necessary but never sufficient. Runtime/initcode portability bounds remain 24,576/49,152 bytes; no compiler/code-size relaxation is assumed.
 
@@ -82,24 +129,28 @@ 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: profile.envelope.bounds.externalLiquidityDisabled,
-  oracleConfigId: profile.envelope.bounds.oracleConfigId,
+  externalLiquidityDisabled: creatorSelectedExternalLiquidityDisabled,
+  oracleConfigId: creatorSelectedOracleConfigId,
   profileId: profile.id, termsDigest: profile.developerTerms.termsDigest,
   developerBeneficiary: profile.developerTerms.beneficiary,
   developerFeeBps: creatorSelectedRate, positions,
 });
 ```
 
-`validateReviewedV4LifecycleMarket` checks profile/terms/topology/version, explicit rate ceilings and exact envelope bounds. Registry/adapter validation remains the execution authority. Positions must require **zero quote deposit** at the committed opening price in actual token orientation. Quotes fund ordered buys, not two-sided initial LP. At most one V4 market per quote is allowed across all templates/topologies/fees/salts; put that quote's positions into one market. Abyss may use the same quote.
+`validateV4LifecycleMarket` checks profile/terms/topology/version, explicit author-rate ceilings and exact envelope bounds. Registry/adapter validation remains the execution authority. Positions must require **zero quote deposit** at the committed opening price in actual token orientation. Quotes fund ordered buys, not two-sided initial LP. At most one V4 market per quote is allowed across all templates/topologies/fees/salts; put that quote's positions into one market. Abyss may use the same quote.
+
+`validateV4LifecycleOracle({client,envelope,oracleConfigId,block})` checks the selected registered
+oracle against the certified factory and `maximumOracleCardinality`. Profile discovery does
+not choose an oracle or query a profile-pinned oracle ID.
 
 Abyss retains `encodeAbyssLifecycleMarketConfig` / `decodeAbyssLifecycleMarketConfig`: canonical pool profile, fee, oracle ID, opening price and ordered tick/liquidity/token-max positions. Quote/fee assets and direct ERC20/native-wrap funding are permissionless subject to actual code, transfers/balances/budgets and canonical bindings. Quote catalog metadata is not admission. Only swap-conversion inputs/targets use registry funding admission.
 
@@ -119,7 +170,7 @@ const optionalPredeploy = await buildPoolBoundHookDeploymentTransaction({client,
 // Inspect only; separately admit/authenticate/sign any optional predeployment.
 ```
 
-The reviewed collector supplies canonical normalized economic commitment and constructor metadata. `hashPoolBoundV4MarketCommitment` uses domain `black-market.reviewed-pool-bound-market-economics.v1`: chain, core, registrar, predicted token, adapter/profile/quote/budget/version and encoded config hash with **only hookSalt zeroed**. Developer identity/digest/rate remain committed. The 18-word constructor freezes manager, registrar, oracle factory, core, locker, token/quote, fees/spacing/price/policy, economic commitment and position count. Salt is used verbatim by CREATE2, not as a constructor argument.
+The collector supplies canonical normalized economic commitment and constructor metadata. `hashPoolBoundV4MarketCommitment` uses domain `black-market.pool-bound-market-economics.v1`: chain, core, registrar, predicted token, adapter/profile/quote/budget/version and encoded config hash with **only hookSalt zeroed**. Developer identity/digest/rate remain committed. The 18-word constructor freezes manager, registrar, oracle factory, core, locker, token/quote, fees/spacing/price/policy, economic commitment and position count. Salt is used verbatim by CREATE2, not as a constructor argument.
 
 Mining is cancellable/nonblocking; `abort()` raises `AbortError` and does not cancel an onchain launch. Persist the returned finalized plan, not the draft. A salt-only change preserves normalized economics but changes final plan hash. Other changes invalidate initcode/mining; concurrent mutation is refused. Normal next-step review rechecks token factory and the captured `hookDeployments` baseline. Predeployment is permissionless, but code presence or self-reported getters alone cannot be adopted as provenance. It does not register/initialize/seal/open a market and does not eliminate real code-deposit/setup gas.
 
@@ -208,6 +259,164 @@ 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 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.
+
+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):
+
+| 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.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Canonical TypeScript SDK for Black Market on Robinhood Chain (reviewed multi-market launches, Abyss DEX, lending).",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,8 @@
   "files": [
     "dist",
     "src",
-    "docs"
+    "docs",
+    "assets"
   ],
   "sideEffects": false,
   "engines": {
@@ -39,8 +40,12 @@
     "dev": "tsc -p tsconfig.json --watch",
     "examples": "pnpm build && node examples/quickstart.mjs",
     "lint": "tsc -p tsconfig.json --noEmit",
+    "smoke:launch": "pnpm build && node examples/smoke-launch.mjs",
     "prepublishOnly": "pnpm build",
-    "test": "pnpm build && node --test test/*.test.mjs",
+    "test": "pnpm test:unit",
+    "test:unit": "pnpm build && node --test test/*.test.mjs",
+    "test:api": "pnpm build && node --test test/integration/launch-api.read.test.mjs",
+    "test:api:write": "pnpm build && node --test test/integration/launch-api.sessions.test.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {

package/src/addresses.ts

@@ -20,7 +20,7 @@ export type AbyssInfrastructureAddresses = {
 };
 
 export type LaunchApplicationAddresses = {
-  /** No reviewed deployment is selected implicitly; set these from exact deployment evidence. */
+  /** Mined mainnet deployment; local chains require explicit environment configuration. */
   launchOrchestrator: Address;
   launchImplementationRegistry: Address;
   launchFeeOwnerRegistry: Address;
@@ -177,19 +177,26 @@ export const robinhoodAbyssInfrastructure: AbyssInfrastructureAddresses = {
   abyssFeeRouter: "0x2c3B1b6fe0EDa8e10C0445567b47e66E825B34cd",
 };
 
+/** Mined pool-launch-v1 deployment, 20261005T053747Z-b5a7b88 (manifest.json). */
+export const robinhoodLaunchApplication: LaunchApplicationAddresses = {
+  launchOrchestrator: "0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E",
+  launchImplementationRegistry: "0xaa8a410709B79cBA6F118F1be1FF568877A3B8Ee",
+  launchFeeOwnerRegistry: "0x15778Aad08e12D458B2848F035860e2a8c2a0725",
+};
+
 
-/** Workbench deployment snapshot — override via env when redeploying. */
+/** Robinhood-mainnet fork lending defaults; launch deployment remains explicit. */
 const workbenchDefaults: ProtocolAddresses = {
   ...robinhoodAbyssInfrastructure,
   ...launchApplicationFromEnv(zeroLaunchApplication),
-  lendingPool: "0xe1576c5CF12F670911BEd5Cc0AEDBcD4E5E9550c",
-  addressesProvider: "0x9Fcca440F19c62CDF7f973eB6DDF218B15d4C71D",
-  dataProvider: "0x79E8AB29Ff79805025c9462a2f2F12e9A496f81d",
+  lendingPool: "0x5D8878b145904425C598f12EB8eD550985369a82",
+  addressesProvider: "0x892faB533E8D04135D902F94974e45dB48C17697",
+  dataProvider: "0x1f3faA42C1D5cC330f6BD0242B9a56d611bdC78a",
   uiPoolDataProvider: zero,
   walletBalanceProvider: zero,
-  aaveOracle: "0x9c65f85425c619A6cB6D29fF8d57ef696323d188",
+  aaveOracle: "0x6837B3cF5d959d01e07bf6DaB53f562877BF7d53",
   liquidationExecutor: zero,
-  protocolVault: "0xAe120F0df055428E45b264E7794A18c54a2a3fAF",
+  protocolVault: "0x83Ec5DbFEd6d972be89df88d3654EA2c70Fa2FB3",
   ethUsdFeed: ROBINHOOD_ETH_USD,
   weth: ROBINHOOD_WETH,
   wethGateway: zero,
@@ -233,26 +240,26 @@ export const addresses: Record<SupportedChainId, ProtocolAddresses> = {
     tokenVesting: envAddr(["TOKEN_VESTING", "VITE_TOKEN_VESTING", "NEXT_PUBLIC_TOKEN_VESTING"]),
     faucet: envAddr(["FAUCET", "VITE_FAUCET", "NEXT_PUBLIC_FAUCET"]),
   },
-  /** Lending/DEX defaults remain canonical; reviewed launches require explicit evidence. */
+  /** Current mined launch, canonical Abyss, and replacement lending infrastructure. */
   4663: {
     ...robinhoodAbyssInfrastructure,
-    ...launchApplicationFromEnv(zeroLaunchApplication),
-    lendingPool: "0x5b8F732A4F7a62D642070bb49255d6C434A76766",
-    addressesProvider: "0xaaD329d0Da03C8c00E8460b5b208D0A21A48C9df",
-    dataProvider: "0x3B097A7899DF433552B8428E774964661b53C193",
-    uiPoolDataProvider: "0x2F35A64c7E7cBc0c05A1A1C3e2F3952E103fD5b8",
-    walletBalanceProvider: "0x833BB152212DD5d2d6C7b0501aB38efb9602AD8B",
-    aaveOracle: "0xb9441f8D3Eda65Ac7cbb6b542b5345c98067e5Fb",
+    ...launchApplicationFromEnv(robinhoodLaunchApplication),
+    lendingPool: "0x5D8878b145904425C598f12EB8eD550985369a82",
+    addressesProvider: "0x892faB533E8D04135D902F94974e45dB48C17697",
+    dataProvider: "0x1f3faA42C1D5cC330f6BD0242B9a56d611bdC78a",
+    uiPoolDataProvider: "0x02D2CA3bBbBaBD3C25bEDD4bE0eE6E5885C4D152",
+    walletBalanceProvider: "0xBbb5D81123C3d514456974e9Fe6C7C8d7a0E4E2A",
+    aaveOracle: "0x6837B3cF5d959d01e07bf6DaB53f562877BF7d53",
     liquidationExecutor: envAddr([
       "LIQUIDATION_EXECUTOR",
       "VITE_LIQUIDATION_EXECUTOR",
       "NEXT_PUBLIC_LIQUIDATION_EXECUTOR",
     ]),
-    protocolVault: "0x961981916AB6575C3af3eeCecbf6A3b7Fad7C9e1",
+    protocolVault: "0x83Ec5DbFEd6d972be89df88d3654EA2c70Fa2FB3",
     ethUsdFeed: ROBINHOOD_ETH_USD,
     weth: ROBINHOOD_WETH,
-    wethGateway: "0xAbc9E3B20e8773536BDCa5ba28C619762C8e0570",
-    lens: "0x82FA6e601F48d64b4f163Eb47D6001f2d5040f9B",
+    wethGateway: "0xa16aB7646267327cB26dD3533526309cDe676d9d",
+    lens: "0xB56079f966597CB9edaE27c589F8190f4dCD12df",
     tokenVesting: zero,
     faucet: zero,
   },

package/src/client.ts

@@ -20,7 +20,7 @@ export function createProtocolPublicClient(opts?: {
 }): PublicClient {
   const chainId = opts?.chainId ?? 31337;
   const chain = chains[chainId] ?? foundry;
-  const transport = http(opts?.rpcUrl ?? process.env.RPC_URL ?? "http://127.0.0.1:8545");
+  const transport = http(opts?.rpcUrl ?? process.env.RPC_URL ?? chain.rpcUrls.default.http[0]);
   return createPublicClient({ chain, transport });
 }
 
@@ -31,7 +31,7 @@ export function createProtocolWalletClient(opts: {
 }): WalletClient {
   const chainId = opts.chainId ?? 31337;
   const chain: Chain = chains[chainId] ?? foundry;
-  const transport: Transport = http(opts.rpcUrl ?? process.env.RPC_URL ?? "http://127.0.0.1:8545");
+  const transport: Transport = http(opts.rpcUrl ?? process.env.RPC_URL ?? chain.rpcUrls.default.http[0]);
   const account: Account = privateKeyToAccount(opts.privateKey);
   return createWalletClient({ account, chain, transport });
 }

package/src/launch-api.ts

@@ -14,7 +14,7 @@ export type LaunchAttributionAuthorization = { nonce: Hex; deadline: string; sig
 export type LaunchSessionCreateRequest = { chainId: number; wallet: Address; metadata: LaunchSessionCreateMetadata; image?: LaunchSessionImageDescriptor; authorization: LaunchAttributionAuthorization };
 export type LaunchSessionPublishRequest = { chainId: number; transactionHash: Hash };
 export type LaunchSessionStatus = "awaiting_upload" | "verifying_image" | "ready_to_launch" | "transaction_submitted" | "awaiting_indexer" | "optimistic" | "final" | "reorged" | "expired" | "rejected";
-export type LaunchSessionDirectUpload = { url: string; headers: Record<string, string>; expiresAt: string };
+export type LaunchSessionDirectUpload = { url: string; method: "PUT"; headers: Record<string, string>; expiresInSeconds: number };
 export type LaunchSessionResponse = { sessionId: string; chainId: number; wallet: Address; status: LaunchSessionStatus; metadata: { name: string; symbol: string; description: string | null; websiteUrl: string | null; twitterUrl: string | null; telegramUrl: string | null; discordUrl: string | null }; image: { sha256: Hex; contentType: LaunchImageContentType; contentLength: number; width: number | null; height: number | null } | null; transactionHash?: Hash | null; token?: Address | null; canonicalStatus: "pending" | "optimistic" | "final" | "reorged"; metadataStatus: "queued" | "ready" | "needs_owner_action" | "none"; imageStatus: "none" | "upload_pending" | "verifying" | "ready" | "rejected"; retryable: boolean; createdAt: string; updatedAt: string; sessionExpiresAt: string; publishedAt?: string; upload?: LaunchSessionDirectUpload; capability?: string; imageUrl?: string };
 export type LaunchApiErrorCode = "INVALID_REQUEST" | "INVALID_ADDRESS" | "INVALID_IDEMPOTENCY_KEY" | "INVALID_CAPABILITY" | "UNSUPPORTED_CHAIN" | "NOT_FOUND" | "IMAGE_INVALID" | "SESSION_STATE_CONFLICT" | "SESSION_EXPIRED" | "IDEMPOTENCY_CONFLICT" | "UPLOAD_CONFLICT" | "RATE_LIMITED" | "OVERLOADED" | "RPC_UNAVAILABLE" | "RPC_TIMEOUT" | "INDEXER_UNAVAILABLE" | "APP_STORAGE_UNAVAILABLE" | "IMAGE_STORAGE_UNAVAILABLE" | "TX_REVERTED" | "TX_PROVENANCE_MISMATCH" | "TX_METADATA_MISMATCH" | (string & {});
 
@@ -102,7 +102,8 @@ export const launchAttributionTypes = { LaunchAttribution: [
   { name: "idempotencyKey", type: "string" }, { name: "nonce", type: "bytes32" }, { name: "deadline", type: "uint256" },
 ] } as const;
 export function canonicalLaunchMetadataHash(metadata: LaunchSessionMetadata): Hex {
-  return keccak256(stringToHex(JSON.stringify({ name: metadata.name.normalize("NFC").trim(), symbol: metadata.symbol.normalize("NFC").trim(), description: (metadata.description ?? "").normalize("NFC").trim(), websiteUrl: metadata.websiteUrl ?? null, twitterUrl: metadata.twitterUrl ?? null, telegramUrl: metadata.telegramUrl ?? null, discordUrl: metadata.discordUrl ?? null, imageKey: metadata.imageKey ?? null })));
+  const url = (value: string | undefined) => value === undefined ? null : new URL(value.normalize("NFC").trim()).toString();
+  return keccak256(stringToHex(JSON.stringify({ name: metadata.name.normalize("NFC").trim(), symbol: metadata.symbol.normalize("NFC").trim(), description: (metadata.description ?? "").normalize("NFC").trim(), websiteUrl: url(metadata.websiteUrl), twitterUrl: url(metadata.twitterUrl), telegramUrl: url(metadata.telegramUrl), discordUrl: url(metadata.discordUrl), imageKey: metadata.imageKey ?? null })));
 }
 export async function sha256Hex(bytes: ArrayBuffer): Promise<Hex> {
   const digest = await crypto.subtle.digest("SHA-256", bytes);

package/src/launch.ts

@@ -3,7 +3,7 @@ import { AUCTION_SUPPLY } from "./auction.js";
 
 export const LAUNCH_REWARD_DURATION = 7 * 24 * 60 * 60;
 
-/** Canonical Abyss oracle ID; reviewed V4 uses the selected envelope's exact ID. */
+/** Canonical P3 oracle default; reviewed V4 markets may select any valid registered oracle within their cardinality bounds. */
 export const LAUNCH_ORACLE_CONFIG_ID =
   "0xc0e9bed88d70a13fd3ab31451fefdd073b7266e838aee0ad1c236c8c9eff855d" as const;
 export const LAUNCH_DEADLINE_SECONDS = 20 * 60;