@black-market/sdk 0.1.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 # @black-market/sdk
 
-Canonical TypeScript SDK for the Black Market protocol on [Robinhood Chain](https://robinhoodchain.blockscout.com) — Abyss DEX infrastructure, Atomic token launches, and the lending market.
+Canonical TypeScript SDK for Black Market on [Robinhood Chain](https://robinhoodchain.blockscout.com): reviewed multi-market launch planning and recovery, stable-author fee APIs, optional signed metadata integration, Abyss DEX infrastructure and lending.
 
 Built on [viem](https://viem.sh). ESM-only, Node 20+.
 
@@ -34,26 +34,61 @@ const wallet = createProtocolWalletClient({
 });
 ```
 
-### Atomic launches
+### Reviewed multi-market launches
+
+The root package and browser-safe `@black-market/sdk/lifecycle` entrypoint expose the same current launch API. Select profiles from the explicit reviewed registry; template IDs are not SDK allowlists. Shared V4 uses config **4**, pool-bound V4 uses config **5**, and Abyss retains its canonical schema. Both V4 configurations explicitly commit `profileId`, `termsDigest`, stable `developerBeneficiary` and creator-selected `developerFeeBps`; bound config also commits `hookSalt` immediately before `profileId`. There is no default developer rate, conversion from old configs or old launcher compatibility path.
+
+```ts
+import {
+  readLifecycleProfiles, preparePoolBoundLifecyclePlan, planLaunch,
+  readLaunchProgress, buildNextTransaction,
+} from "@black-market/sdk/lifecycle";
+
+const profiles = await readLifecycleProfiles({ client, orchestrator: plan.orchestrator });
+// Select admitted schema/topology and copy that profile's exact envelope/terms into the plan.
+const finalized = await preparePoolBoundLifecyclePlan({ client, plan });
+const planned = await planLaunch({
+  client, account: finalized.plan.creator, plan: finalized.plan,
+  mode: "staged", limits, fork, // execution mode is explicit; no automatic fallback
+});
+const progress = await readLaunchProgress({ client, planned, receipts });
+const next = await buildNextTransaction({ client, planned, receipts, limits, fork });
+// No SDK operation above signs or writes to the source chain.
+// A separately authenticated wallet may submit only the exact admitted next envelope.
+```
+
+Registry authority, runtime/dependency hashes, reviewed bounds, frozen author consent, canonical oracle configuration, exact code chunks/initcode/constructor and deployer-recorded runtime provenance are verified. Hook address bits alone are not proof. One V4 market per quote is enforced across templates and topologies; an Abyss market may use the same quote.
+
+Staged execution splits **only empty infrastructure preparation**. Minting, permanent locking, every ordered buy and public opening remain one indivisible activation. The planner uses sequential `eth_simulateV1` or an explicitly supplied separate disposable loopback fork. Unknown chain/RPC/account/calldata limits or unavailable stateful execution prevent transaction admission. Recovery rereads confirmation-bound canonical state and receipt/replacement/reorg evidence, not a cached step index; pending cancellation does not require readmission of retired profiles.
+
+Read the [lifecycle guide](docs/launch-lifecycle.md) for exact codecs, profile discovery, execution-limit provenance, salt finalization, simulation, wallet-domain checks, recovery and V3 fee accounting.
+
+### Stable authors and V3 fees
 
 ```ts
 import {
-  LAUNCH_TEMPLATES,
-  deriveAtomicLaunchPoolRecipe,
-  estimateAtomicLaunchInitialBuy,
-  buildAtomicLaunchCalldata,
-  DEFAULT_ATOMIC_LAUNCH_TARGET_MARKET_CAP_USD,
+  readLifecycleAuthor, readAuthorHubs, readDeveloperFees,
+  buildSetAuthorPayoutTransaction, buildClaimDeveloperFeesTransaction,
+  buildClaimDeveloperFeesPageTransaction, decodeDeveloperClaimReceipt,
 } from "@black-market/sdk";
 
-// Derive the one-sided launch position from a target FDV.
-const recipe = deriveAtomicLaunchPoolRecipe({
-  /* … */
+const author = await readLifecycleAuthor({ client, registry, authorId });
+const hubs = await readAuthorHubs({ client, registry, authorId, offset: 0n, limit: 100n });
+const fees = await readDeveloperFees({ client, registry, authorId, hub });
+const unsigned = await buildClaimDeveloperFeesPageTransaction({
+  client, registry, authorId, offset: 0n, limit: 10n, assets: [],
+  account, chainId,
 });
-
-// Encode an Atomic launch request for the AtomicLaunchFactory.
-const calldata = buildAtomicLaunchCalldata(request, nativeBuyAmount);
+// Execution is caller-owned. After canonical confirmation:
+const result = decodeDeveloperClaimReceipt({ receipt, transaction: unsigned });
+// result.cursorComplete is independent from result.paymentsSucceeded.
+// Preserve result.retryableResults; advancing the discovery cursor does not pay failed rows.
 ```
 
+`authorId` is the immutable economic beneficiary, while `authorPayout(authorId)` is the live payout/controller. The admin or current controller may build an unsigned routing update; direct/page claims have no caller-selected recipient. Hub authentication is anchored to `registry.core -> core.feeFactory -> factory.isHub`, never attacker hub self-reports. V3 ordinary harvest uses the exported `lifecycleFeeHubAbi` and **no-argument `claimAndSplit()`**, including current source-specific developer allocations and reserved owner/developer credits.
+
+`LaunchApiClient` remains the optional signed metadata/image-upload/transaction-publication client. It does not sign, broadcast or choose launch economics. Its browser-native `fetch` and `globalThis.setTimeout` implementation remains browser-safe.
+
 ### Networks
 
 | Chain ID | Network                       |
@@ -64,27 +99,30 @@ const calldata = buildAtomicLaunchCalldata(request, nativeBuyAmount);
 
 `getAddresses()` defaults to the workbench chain (`46631`); pass `4663` for the canonical mainnet deployment or `31337` for a local Anvil fork.
 
-Deployment addresses can be overridden with environment variables, evaluated once at module load. Where an override applies, the bare name wins, then `VITE_`, then `NEXT_PUBLIC_` (e.g. `ABYSS_ROUTER` > `VITE_ABYSS_ROUTER` > `NEXT_PUBLIC_ABYSS_ROUTER`). Overrides apply to the launch-application addresses on every chain, to the Abyss infrastructure addresses on `31337` and `46631` (mainnet `4663` always uses the canonical deployment), and to the lending-market addresses on `31337` (bare + `VITE_` + `NEXT_PUBLIC_`) and `46631` (`VITE_`/`NEXT_PUBLIC_` only). The workbench RPC URL reads `VITE_RPC_URL`, then `NEXT_PUBLIC_RPC_URL`, then `RPC_URL`.
+Deployment addresses can be overridden with environment variables, evaluated once at module load. Bare names win, then `VITE_`, then `NEXT_PUBLIC_`. Reviewed launch addresses (`LAUNCH_ORCHESTRATOR`, `LAUNCH_IMPLEMENTATION_REGISTRY`, `LAUNCH_FEE_OWNER_REGISTRY`) are explicit on every chain and default to zero; old launcher addresses are not fallback targets. Abyss infrastructure overrides apply on `31337`/`46631` (mainnet `4663` retains its canonical DEX deployment). Lending overrides apply on `31337` (all three prefixes) and `46631` (`VITE_`/`NEXT_PUBLIC_` only). The workbench RPC URL reads `VITE_RPC_URL`, then `NEXT_PUBLIC_RPC_URL`, then `RPC_URL`.
 
 ## Package layout
 
 | Module         | Contents                                                              |
 | -------------- | --------------------------------------------------------------------- |
-| `addresses`    | Chain definitions, canonical deployment addresses, env overrides      |
+| `addresses`    | Chain definitions, explicit reviewed launch addresses and env overrides |
 | `abis`         | Lending-market ABIs (pool, data providers, lens, oracle, vesting, …)  |
-| `abyss`        | Abyss DEX ABIs and launch-module ABIs, pool profiles, fee tiers       |
-| `auction`      | Atomic launch supply constants and paired-asset (quote) catalog       |
-| `launch`       | Launch templates, Atomic launch recipe derivation, calldata building  |
+| `abyss`        | Unchanged Abyss DEX ABIs, pool profiles, fee tiers and wrapped-native funding |
+| `auction`      | Display supply and paired-asset metadata catalog (not an admission list) |
+| `launch`       | Pure pool geometry and initial-buy estimates (not execution proof) |
+| `launch-api`   | Optional signed launch metadata, upload, and publication API client   |
+| `lifecycle`    | Reviewed schemas/ABIs, registry admission, planner/simulation/recovery and author APIs |
 | `live`         | Reserve/user position normalization from lens & data-provider rows    |
 | `format`       | RAY/WAD math, health-factor and units formatting helpers              |
 | `client`       | viem public/wallet client factories                                   |
 
 ## Examples
 
-Runnable offline scripts live in [`examples/`](examples/) — no RPC endpoint or wallet required. They import the built package output, so build first:
+Runnable scripts live in [`examples/`](examples/). `quickstart.mjs` demonstrates current config-4 commitment bytes and pure math offline. `launch.mjs` reviews an explicit saved plan without signatures or source-chain writes. The actual lifecycle smoke requires separately authorized owned loopback fixtures.
 
 ```sh
-pnpm examples   # pnpm build && node examples/quickstart.mjs
+pnpm build
+node examples/quickstart.mjs
 ```
 
 ## Development
@@ -96,6 +134,26 @@ pnpm test       # build + node:test suite
 pnpm typecheck
 ```
 
+## 0.3.1 migration
+
+- Breaking cutover to explicit lifecycle plans and signed V2 registry profiles.
+  Historical Atomic/Unified builders, template catalogs and old-name aliases are removed.
+- V4 shared config 4 and pool-bound config 5 commit author terms and an explicit developer rate.
+  Old configs are rejected; no automatic conversion or compatibility fallback is provided.
+- Registry admission uses `registerProfile`, reads use `profileEnvelope` / `profileId`,
+  and the EIP-712 domain is `Black Market Launch Registry`, version `2`.
+  Regenerate author consent for the exact new deployment graph.
+- Pool deployment exports use `FixedFeePoolHookV1`, `PoolHookDeployerV1`,
+  `PoolMarketAdapterV1`, `PoolFeeCollectorDeployerV1` and `PoolFeeCollectorFactoryV1`.
+  Profile/dependency hash preimages and current economic tuples remain unchanged.
+- The root and `/lifecycle` package entrypoints support commitment codecs, explicit
+  planning/recovery and stable-author V3 fee operations. No production launch deployment
+  or author authorization is bundled with this release.
+
+The earlier `v0.2.0` and `v0.3.0` GitHub releases are preserved; their npm uploads failed.
+Version `0.3.1` adds the matching GitHub repository metadata required by npm trusted
+publishing, without changing the lifecycle API.
+
 ## Releasing
 
 Releases are published to npm by GitHub Actions with [trusted publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) — no npm tokens are stored in this repository.