@black-market/sdk 0.1.0 → 0.4.0

package/dist/lifecycle/types.d.ts

@@ -0,0 +1,273 @@
+import type { Address, Hash, Hex } from "viem";
+import type { AdapterRegistrationV1, AssetFundingV1, LaunchExecutionMode, LaunchPlanV1, LaunchProgressV1, MarketLiveStateV1, PreparedMarketV1, ProfileRegistrationV1, ProfileTopologyV1, LaunchEnvelopeV2, LifecycleDeveloperTerms } from "./schema.js";
+/** viem public clients or a raw JSON-RPC client; neither selects a transport. */
+export type LifecycleRpcClient = {
+    request(args: {
+        method: string;
+        params?: readonly unknown[];
+    }): Promise<unknown>;
+};
+export type LifecycleBlock = {
+    number: bigint;
+    hash: Hash;
+    timestamp: bigint;
+    gasLimit: bigint;
+    baseFeePerGas?: bigint;
+};
+export type LifecycleLimitContext = {
+    client: LifecycleRpcClient;
+    account: Address;
+    orchestrator: Address;
+    block: LifecycleBlock;
+    chainId: bigint;
+};
+export type LifecycleLimits = {
+    headroomBps?: number;
+    chainGasLimit?: bigint;
+    rpcGasLimit?: bigint;
+    accountGasLimit?: bigint;
+    maxCalldataBytes?: number;
+    maxSimulationGas?: bigint;
+    chainId?: bigint;
+    orchestrator?: Address;
+    account?: Address;
+    observedBlockNumber?: bigint;
+    observedBlockHash?: Hash;
+    /** Chain-specific L1/data-fee oracle, called with exact calldata and the pinned block. */
+    estimateDataFee?: (transaction: LifecycleTransaction, context: LifecycleLimitContext) => Promise<bigint>;
+};
+export type LifecycleLimitSource = LifecycleLimits | ((context: LifecycleLimitContext) => Promise<LifecycleLimits>);
+export type ResolvedLifecycleLimits = {
+    executionGasCeiling: bigint;
+    headroomBps: number;
+    maxCalldataBytes?: number;
+    maxSimulationGas?: bigint;
+    blockGasLimit: bigint;
+    chainGasLimit?: bigint;
+    rpcGasLimit?: bigint;
+    accountGasLimit?: bigint;
+    admissionKnown: boolean;
+    unknownExecutionConstraints: readonly string[];
+    unknownConstraints: readonly string[];
+};
+/** Only explicitly disposable RPCs may execute snapshot-isolated simulation transactions. */
+export type ControlledLifecycleFork = {
+    client: LifecycleRpcClient;
+    isolation: "disposable";
+    allowTransactions: true;
+    expectedChainId?: bigint;
+    expectedBlockHash?: Hash;
+    impersonation?: "anvil" | "hardhat" | "none";
+    receiptTimeoutMs?: number;
+    sourceRpcUrl: string;
+    forkRpcUrl: string;
+    resetMethod?: "anvil_reset" | "hardhat_reset";
+};
+export type LifecycleTransactionKind = "approve-reset" | "approve" | "atomic" | "begin" | "prepare" | "activate" | "cancel";
+export type LifecyclePostcondition = {
+    kind: "allowance";
+    asset: Address;
+    spender: Address;
+    minimum: bigint;
+    exact?: bigint;
+} | {
+    kind: "launch";
+    phase: "Preparing" | "Ready" | "Active" | "Cancelled";
+    preparedMarkets: number;
+};
+export type LifecycleTransaction = {
+    id: string;
+    kind: LifecycleTransactionKind;
+    chainId: number;
+    from: Address;
+    to: Address;
+    data: Hex;
+    value: bigint;
+    dependencies: readonly string[];
+    postconditions: readonly LifecyclePostcondition[];
+    marketStart?: number;
+    marketCount?: number;
+    gas?: bigint;
+    gasPrice?: bigint;
+    /** Exact current-state execution admission, not a wallet batch or future guarantee. */
+    admission?: LifecycleAdmission;
+    estimate?: LifecycleTransactionEstimate;
+};
+export type LifecycleTransactionEstimate = {
+    gasUsed: bigint;
+    gasLimit: bigint;
+    gasPrice: bigint;
+    executionFee: bigint;
+    dataFee?: bigint;
+    totalFee?: bigint;
+    feeConfidence: "execution-and-data" | "execution-only";
+};
+export type LifecycleAdmission = {
+    admitted: boolean;
+    confidence: "stateful" | "provisional";
+    reason?: string;
+    limits: ResolvedLifecycleLimits;
+};
+export type LifecycleSimulationStep = {
+    transactionId: string;
+    success: boolean;
+    gasUsed?: bigint;
+    gasLimit?: bigint;
+    gasRequired?: bigint;
+    returnData?: Hex;
+    error?: string;
+    estimate?: LifecycleTransactionEstimate;
+};
+export type LifecycleSimulation = {
+    backend: "eth_simulateV1" | "controlled-fork" | "unavailable";
+    confidence: "stateful" | "provisional";
+    admitted: boolean;
+    blockNumber: bigint;
+    blockHash: Hash;
+    account: Address;
+    chainId: bigint;
+    steps: readonly LifecycleSimulationStep[];
+    limits: ResolvedLifecycleLimits;
+    reason?: string;
+    failedTransactionId?: string;
+};
+export type LifecycleFundingPrerequisite = {
+    funding: AssetFundingV1;
+    inputBalance: bigint;
+    requiredInput: bigint;
+    allowance?: bigint;
+    spender: Address;
+    nativeValue: bigint;
+    conversion: "none" | "native-wrap" | "allowlisted-swap";
+};
+export type LifecycleProfile = {
+    id: Hex;
+    registration: ProfileRegistrationV1;
+    adapter: AdapterRegistrationV1;
+    topology: ProfileTopologyV1;
+    venueKind: "uniswap-v4" | "abyss" | "unknown";
+    envelope?: LaunchEnvelopeV2;
+    developerTerms?: LifecycleDeveloperTerms;
+    protocolMaximumDeveloperFeeBps?: number;
+    admitted: boolean;
+    reason?: string;
+};
+export type LifecycleMarketProgress = {
+    index: number;
+    prepared: PreparedMarketV1;
+    live?: MarketLiveStateV1;
+    error?: string;
+};
+export type LifecycleReceiptReference = {
+    transactionHash: Hash;
+    replacementHash?: Hash;
+    confirmations?: number;
+    observedBlockNumber?: bigint;
+    observedBlockHash?: Hash;
+};
+export type LifecycleReceiptStatus = {
+    transactionHash: Hash;
+    effectiveHash: Hash;
+    status: "pending" | "confirmed" | "reverted" | "reorged" | "unconfirmed" | "replacement-cancelled";
+    blockNumber?: bigint;
+    blockHash?: Hash;
+    confirmations?: bigint;
+    replaced: boolean;
+};
+export type CanonicalLaunchProgress = {
+    canonical: LaunchProgressV1;
+    blockNumber: bigint;
+    blockHash: Hash;
+    chainId: bigint;
+    head: LaunchProgressV1;
+    confirmationDepth: number;
+    confirmedBlockNumber: bigint;
+    confirmedBlockHash: Hash;
+    confirmedAccountNonce: bigint;
+    headAccountNonce: bigint;
+    pendingAccountNonce: bigint;
+    confirmationSafe: boolean;
+    markets: readonly LifecycleMarketProgress[];
+    receipts: readonly LifecycleReceiptStatus[];
+    token: Address;
+    planHash: Hash;
+    launchId: Hash;
+};
+export type PoolBoundHookDeployment = {
+    deployer: Address;
+    initCodeHash: Hex;
+    salt: Hex;
+    predictedHook: Address;
+};
+export type LifecyclePoolBoundHookDeployment = PoolBoundHookDeployment & {
+    marketIndex: number;
+};
+export type PoolBoundHookSaltProgress = {
+    attempts: bigint;
+    salt: Hex;
+    predictedHook: Address;
+};
+export type PoolBoundLifecyclePreparationProgress = PoolBoundHookSaltProgress & {
+    marketIndex: number;
+};
+export type PlannedLaunch = {
+    plan: LaunchPlanV1;
+    planHash: Hash;
+    launchId: Hash;
+    predictedToken: Address;
+    tokenFactory: Address;
+    tokenFactoryCodeHash: Hex;
+    account: Address;
+    chainId: bigint;
+    mode: LaunchExecutionMode;
+    confirmations: number;
+    transactions: readonly LifecycleTransaction[];
+    prerequisites: readonly LifecycleFundingPrerequisite[];
+    profiles: readonly LifecycleProfile[];
+    simulation: LifecycleSimulation;
+    /** Exact CREATE2 metadata captured from the final committed bound markets. */
+    hookDeployments: readonly LifecyclePoolBoundHookDeployment[];
+    atomicAttempt: LifecycleSimulation;
+    progress: CanonicalLaunchProgress;
+    preparationBatchSize: number;
+    limits?: LifecycleLimitSource;
+};
+export type PlanLaunchOptions = {
+    client: LifecycleRpcClient;
+    account: Address;
+    plan: LaunchPlanV1;
+    mode: LaunchExecutionMode;
+    limits?: LifecycleLimitSource;
+    fork?: ControlledLifecycleFork;
+    receipts?: readonly LifecycleReceiptReference[];
+    confirmations?: number;
+};
+export type SimulateLaunchPlanOptions = {
+    client: LifecycleRpcClient;
+    planned: PlannedLaunch;
+    limits?: LifecycleLimitSource;
+    fork?: ControlledLifecycleFork;
+    /** Submitted receipt evidence and confirmation depth are inherited from the
+     * stored plan when omitted, exactly as build-next consumes them; resimulation
+     * never silently drops submitted-transaction context. */
+    receipts?: readonly LifecycleReceiptReference[];
+    confirmations?: number;
+};
+export type ReadLaunchProgressOptions = {
+    client: LifecycleRpcClient;
+    planned: Pick<PlannedLaunch, "plan" | "planHash" | "launchId" | "predictedToken" | "account" | "mode" | "confirmations">;
+    receipts?: readonly LifecycleReceiptReference[];
+    confirmations?: number;
+};
+export type BuildNextTransactionOptions = ReadLaunchProgressOptions & {
+    planned: PlannedLaunch;
+    action?: "continue" | "cancel";
+    limits?: LifecycleLimitSource;
+    fork?: ControlledLifecycleFork;
+};
+export declare class LifecyclePlanningError extends Error {
+    readonly code: string;
+    readonly simulation?: LifecycleSimulation;
+    constructor(code: string, message: string, simulation?: LifecycleSimulation);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lifecycle/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/types.js

@@ -0,0 +1,11 @@
+export class LifecyclePlanningError extends Error {
+    code;
+    simulation;
+    constructor(code, message, simulation) {
+        super(message);
+        this.name = "LifecyclePlanningError";
+        this.code = code;
+        this.simulation = simulation;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/lifecycle/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AA6HA,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,IAAI,CAAS;IACb,UAAU,CAAuB;IAC1C,YAAY,IAAY,EAAE,OAAe,EAAE,UAAgC;QACzE,KAAK,CAAC,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACvG,CAAC;CACF"}

package/docs/launch-lifecycle.md

@@ -0,0 +1,243 @@
+# 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 registry domain. Planning, salt preparation, reads and unsigned builders never sign, publish metadata or write to the source chain. A successful controlled-local simulation is not production deployment approval.
+
+The canonical authorities are the registry/certification/adapter/config contracts under `contracts/src/launch/lifecycle/v2`, the typed hook deployers, and `contracts/src/launch/fees/v3` in the sibling protocol repository. Plan identity remains `LaunchPlanV1`; shared V4 accepts **config 4 only**, bound V4 **config 5 only**, and Abyss keeps its canonical schema. Old Atomic/Unified request encoders, template catalogs and old V4 profile/adapter constants have been removed. Immutable old contracts/pools and unrelated DEX/lending functions are not upgraded or rebound.
+
+The keystore-only `DeployPoolLaunchV1` deployment includes fixed pool-bound V4
+(`PoolHookDeployerV1`, `PoolMarketAdapterV1`, `PoolFeeCollectorFactoryV1`) and canonical Abyss:
+two adapters and five automatically admitted profiles.
+Registry V2 has one `LaunchCertificationV2` child and no arbitrary unsigned V4 endpoint.
+V4 uses `profileEnvelope`, `profileId` and signed six-argument `registerProfile`.
+Admin-only `registerAbyssProfile(uint8,registration)` independently certifies the four canonical
+config-1 variants; they have no author envelope or royalty allocation.
+Envelope/bounds/graph types and encoding helpers use `Launch` names.
+There are no old-name aliases. The admission EIP-712 domain is `Black Market Launch Registry`,
+version `2`; regenerate author consent after cutover. Market configuration tuple layouts remain
+unchanged; bounds encoding changes below require fresh profile identities and consent.
+Old deployment evidence is not new-graph proof.
+
+`LaunchBoundsV2` has five members beginning with `minimumTickSpacing`: tick-spacing bounds,
+maximum positions, maximum oracle cardinality and fee-mode flags. Former LP/hook fee ceilings
+and profile-level oracle/external-liquidity pins are removed. Creators independently choose
+valid LP/hook rates below 1,000,000 pips, including 15%, their registered oracle configuration,
+and their per-pool external-liquidity policy. Author royalty ceilings remain separate.
+Regenerate bounds digests, profile IDs and consent for the new tuple.
+
+Robinhood P1 `(1,4096)`, P2 `(6,4096)` and P3 `(17,4096)` are usable on the same admitted profile.
+Planning/preparation validates each selected oracle on the pinned factory at the pinned block;
+unregistered/invalid oracle parameters and excessive cardinality still fail. With
+`externalLiquidityDisabled=false`, third-party LP add/remove is allowed after opening.
+Permanent launch custody and pre-opening protection remain unchanged.
+
+Shared contracts are `FixedFeeSharedHookV1`, `SharedHookDeployerV1` and
+`SharedMarketAdapterV1`. ABI exports are `sharedMarketAdapterV1Abi`,
+`sharedHookDeployerV1Abi`, `poolMarketAdapterV1Abi`, `poolHookDeployerV1Abi` and
+`poolFeeCollectorFactoryV1Abi`; validation uses `validateV4LifecycleMarket`.
+The factory getter is `dependencyDigest(address)`. Identity domains are
+`black-market.launch-profile.v2`, `black-market.v4-dependencies.v2` and
+`black-market.pool-bound-market-economics.v1`. No old-name aliases remain; regenerate
+profile identities, commitments and author consent for these domain labels.
+
+## Public operations
+
+| Operation | Contract |
+| --- | --- |
+| `readLifecycleProfiles({client, orchestrator, profileIds?, offset?, limit?})` | Bounded registry discovery, schema/topology dispatch, reviewed graph/terms certification and current registry admission. Default offset/limit is 0/100; explicit IDs can select a reviewed deployment's identities. |
+| `predictLifecycleToken({client, plan})` | Exact prediction from the explicit core. |
+| `preparePoolBoundLifecyclePlan({client, plan, signal?, onProgress?})` | Finalizes current config-5 salts offchain, then rechecks frozen plan, token-factory binding and exact deployment metadata. Does not deploy. |
+| `readPoolBoundHookDeployment({client, plan, marketIndex})` | Verifies typed factory, code chunks, constructor, normalized economics, initcode, salt, CREATE2 prediction and recorded provenance of existing code. Works with draft salts; permission bits are additionally required for executable predeployment. |
+| `buildPoolBoundHookDeploymentTransaction({client, plan, marketIndex})` | Optional permissionless typed `deploy(parameters,salt)` calldata. Does not create a token, register/initialize a pool, bind a collector or activate a launch. |
+| `planLaunch({client, account, plan, mode, limits?, fork?, receipts?, confirmations?})` | Validates domain/funding/admission and canonical progress, records the exact atomic attempt, and reviews only the explicitly selected mode. |
+| `simulateLaunchPlan({client, planned, limits?, fork?, receipts?, confirmations?})` | Rereads canonical state and proves remaining work. Preserves receipt evidence, economics and selected mode. |
+| `readLaunchProgress({client, planned, receipts?, confirmations?})` | Confirmation-bound canonical state, latest head, receipt/replacement/reorg status, account-nonce safety and actual prepared market/live state. |
+| `buildNextTransaction({client, planned, limits?, fork?, receipts?, confirmations?, action?})` | Rereads progress, constraints and stateful proof before returning one admitted transaction. `action: "cancel"` uses the stored commitment without requiring fresh adapter/profile admission. Terminal launches return `undefined`. |
+
+Clients may be viem public clients or raw `request({method,params})` RPC clients. Transport, wallet, signing and durable storage are application-owned. `PlannedLaunch` contains bigint values and live limit callbacks: persist `serializeLaunchPlan(plan)`, explicit execution mode, confirmation policy and receipt references, not the entire object.
+
+## Commitment and integer representation
+
+The economic tuple contains chain/core/creator/nonce; ERC20/ERC404 token and token-global reward configuration; sorted funding outputs and fee assets; ordered markets; ordered initial buys; deadline; and initial executor fee. Each market commits exact adapter/profile/quote/budget/version/config bytes. Each buy commits market index, quote input, minimum token output, recipient and Q64.96 price limit; repeated indices keep their order.
+
+`hashLaunchPlan` is `keccak256(abi.encode(keccak256(bytes("BLACK_MARKET_LAUNCH_PLAN_V1")),plan))`. `hashLaunchIdentity` is `keccak256(abi.encode(chainId,orchestrator,creator,nonce))`. Token prediction depends on that identity and token configuration, not the economic plan hash, so the predicted token can appear in sorted fee assets without circularity. Economics cannot change after begin. Mode/batching are execution metadata outside the tuple.
+
+Use bigint for uint256/uint160/uint128 values and decimal strings in portable JSON. `parseLaunchPlan` rejects lossy JSON numbers and out-of-width values. Amounts are base units, liquidity is uint128, and `1n << 96n` is raw-unit price ratio 1, not a display-unit price. The pure helpers `deriveLaunchPoolRecipe`, `estimateLaunchInitialBuy` and `deriveLaunchBuySqrtPriceLimitX96` do not prove fees, market admission or execution; derive actual minimum outputs from stateful simulation and review the resulting final commitment again.
+
+Bounds: 1–16 markets, 1–8 fee assets, at most 8 funding outputs, 64 ordered buys and 32 total positions. None guarantees gas feasibility. Reward-free ERC20 allows the positive uint256 supply domain; reward-enabled ERC20 is capped at `10^77`; ERC404 supply fits uint96. Current exported supply bounds preserve these exact numerical domains.
+
+```ts
+import { parseLaunchPlan, serializeLaunchPlan, encodeLaunchPlan, hashLaunchPlan, hashLaunchIdentity } from "@black-market/sdk/lifecycle";
+const plan = parseLaunchPlan(savedPlanJson);
+const bytes = encodeLaunchPlan(plan);
+const commitment = hashLaunchPlan(plan);
+const identity = hashLaunchIdentity(plan);
+const portable = serializeLaunchPlan(plan);
+```
+
+## Registry-driven profile selection and frozen consent
+
+The exact canonical registry getters are `profileCount`, `profileIds(offset,limit)`, `adapterCount`, `adapterIds(offset,limit)`, `profile`, `adapter`, `profileTopology` and `requireEligible`. There is no SDK template-ID allowlist and no invented `profiles()`/`isProfileEligible()` ABI. Schema plus certified topology dispatches supported implementations; an unsupported schema is reported separately from invalid/unsupported positions.
+
+`LifecycleProfile` contains `registration`, `adapter`, unchanged `topology`, `venueKind`, `admitted` and optional refusal `reason`. Reviewed V4 adds:
+
+- `envelope?: LaunchEnvelopeV2`: artifact/review/bounds/terms digests; topology, config/economic versions, capabilities, flags/callbacks, treasury policy, stable beneficiary/maximum rate, numerical bounds and the exact dependency graph.
+- `developerTerms?: {adapter, beneficiary, maximumDeveloperFeeBps, termsDigest, enabled}`.
+- `protocolMaximumDeveloperFeeBps?: number`.
+
+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.
+
+Registry `authorizationDigest`, `beneficiaryNonces` and `registerProfile` ABIs expose canonical reviewed admission/author consent. Admission does not make a template name an SDK allowlist or bypass current `requireEligible`. Profile retirement prevents new/pending source binding; it does not rewrite frozen active source terms or disable stable-author fee claims.
+
+## Current venue codecs
+
+### Shared V4, version 4
+
+`encodeV4LifecycleMarketConfig` / `decodeV4LifecycleMarketConfig` accept only inner version 4. Market `configVersion` is 4. Exact schema:
+
+```text
+(uint16,uint24,int24,uint160,uint24,uint8,uint8,address,bool,bytes32,bytes32,bytes32,address,uint16,(int24,int24,uint128,bytes32,uint256)[])
+```
+
+### Pool-bound V4, version 5
+
+`encodePoolBoundV4LifecycleMarketConfig` / `decodePoolBoundV4LifecycleMarketConfig` accept only inner version 5. Market `configVersion` is 5. Exact schema:
+
+```text
+(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.
+
+```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,
+  protocolFeeDenominator: profile.envelope.protocolFeeDenominator,
+  treasury: profile.envelope.protocolTreasury,
+  externalLiquidityDisabled: creatorSelectedExternalLiquidityDisabled,
+  oracleConfigId: creatorSelectedOracleConfigId,
+  profileId: profile.id, termsDigest: profile.developerTerms.termsDigest,
+  developerBeneficiary: profile.developerTerms.beneficiary,
+  developerFeeBps: creatorSelectedRate, positions,
+});
+```
+
+`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.
+
+## Freeze and finalize bound economics
+
+Freeze chain/core/creator/nonce, token identity, sorted fee policies, all funding/budgets/positions/terms and ordered buys before mining. Create config 5 with the chosen bound profile's exact terms and a draft salt; never implicitly reinterpret a shared config.
+
+```ts
+const stop = new AbortController();
+const finalized = await preparePoolBoundLifecyclePlan({
+  client, plan: draft, signal: stop.signal,
+  onProgress: ({marketIndex, attempts, predictedHook}) => console.log(marketIndex, attempts.toString(), predictedHook),
+});
+const saved = serializeLaunchPlan(finalized.plan);
+const boundIndex = finalized.plan.markets.findIndex((market) => market.configVersion === 5);
+const optionalPredeploy = await buildPoolBoundHookDeploymentTransaction({client, plan: finalized.plan, marketIndex: boundIndex});
+// Inspect only; separately admit/authenticate/sign any optional predeployment.
+```
+
+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.
+
+## Explicit execution mode and indivisible activation
+
+Every planning call requires `mode: "atomic" | "staged"`. For an unstarted launch, `atomicAttempt` records the exact approval/funding plus atomic sequence independently of the requested graph.
+
+- Atomic: after funding prerequisites, token creation, empty infrastructure, all mint/lock/buys/public activation are one transaction.
+- Staged: prerequisites, `beginLaunch(Staged)`, contiguous empty `prepareMarkets` batches, then one `activateLaunch`. Preparation batches may shrink to fit.
+- Activation cannot split. If mint/lock/all buys/opening cannot fit, staged is also refused. No position/buy/minimum is omitted to manufacture success.
+
+No automatic atomic-to-staged fallback exists. Obtain separate consent to review the same commitment as staged. Both venues use token transfer restrictions plus activation-time canonical opening-state checks, not a pool gate. Manipulated opening price or preactivation liquidity fails verification; the token stays inactive and the launch remains Ready/cancellable. Failed activation rolls back every mint, seal, buy and opening together.
+
+## Execution constraints and stateful simulation
+
+Admission requires current `chainGasLimit`, `rpcGasLimit`, `accountGasLimit` and `maxCalldataBytes`; block gas limit alone cannot fill missing transaction/RPC/account policy. Use a `LifecycleLimitSource` callback whose returned chain/account/core/observed block/hash match the requested pinned context and actual provider-owned policy. Static supplied facts are only current at that exact context; relabeling stale limits is not proof.
+
+The ceiling is the minimum of block and explicit transaction caps. Headroom defaults to 1,500 bps, bounded 0–10,000. The measurement pass is followed by execution at exact returned gas/fee limits. Fork execution uses gross sequential estimates rather than refund-reduced receipt gas as an executable minimum. Transactions expose `estimate.executionFee`, optional `dataFee/totalFee` and `feeConfidence: "execution-and-data" | "execution-only"`; missing rollup/data fee is not an invented all-in estimate. Limits are refreshed before every next transaction.
+
+Sequential backends:
+
+1. `eth_simulateV1`: actual ordered transactions, state carried between synthetic blocks, exact gas-envelope verification, core returns/events and ordered buy bounds.
+2. Explicit separate disposable loopback fork: snapshot-isolated real transactions, exact pinned chain/header identity, canonical poststate/allowances and cleanup. Source RPC stays read-only.
+3. Neither: unavailable/provisional/unadmitted; no executable next transaction.
+
+Atomic/activation simulation `steps[].returnData` encodes the actual `LaunchReceiptV1` tuple. Controlled-fork output is reconstructed from matching real activation/buy receipt logs and canonical state, never geometric estimates or echoed request minima. `tokenOut` and `quoteSpent` are parallel arrays indexed by ordered buys.
+
+```ts
+const fork = createControlledLifecycleFork({
+  sourceRpcUrl: "http://127.0.0.1:18555", forkRpcUrl: "http://127.0.0.1:18556",
+  allowTransactions: true, impersonation: "anvil",
+});
+const planned = await planLaunch({client, account: plan.creator, plan, mode: "staged", limits, fork});
+```
+
+The fork endpoint must be distinct/loopback, including localhost/IP aliases and effective port. Anvil reset/impersonation is default; disposable Hardhat may explicitly use its reset method/impersonation. Never pass the source client as a fork or use a live unlocked wallet as a disposable backend. Operators own exclusive fork access during proof. Controlled-local policy does not prove live provider/account admission or imply bound topology is a gas optimization.
+
+## Wallet submission and canonical recovery
+
+The SDK never signs. Before **every** approval/reset/core/predeploy/cancel signature, compare the wallet's configured chain (if any) and fresh connected `getChainId()` with the returned `next.chainId`. Failure/invalid identity is a refusal. Supply a matching explicit viem Chain descriptor; do not pass `chain: null` or disable wallet chain checks. Send exact `from/to/data/value/gas/gasPrice`, not a cached estimate or wallet batch.
+
+Persist transaction hashes immediately. After receipt, retain `observedBlockNumber`, `observedBlockHash`, confirmation policy and, for replacements, original `transactionHash` plus effective `replacementHash`. A same-nonce self-transfer is replacement-cancelled, not launch completion. Removed observed blocks are reorged; status zero is reverted; a missing receipt at the unchanged observed block remains pending. Unknown hashes do not invent reorgs.
+
+`confirmations` is positive and defaults to 1. Progress anchors confirmed canonical and latest head hashes, compares confirmed/head/pending account nonces, and prevents ref-free reloads from advancing unconfirmed work. Pending receipts/state return no executable envelope (`RECEIPT_PENDING`/`UNCONFIRMED_STATE`). Reload the exact plan/mode/policy/receipt references; never trust a cached step counter. Market read failures are surfaced without removing adapter-independent cancellation.
+
+## Funding and cancellation
+
+Creator/payer/refund recipient are the same address. ERC20 prerequisites approve immutable `fundingEscrow`, not core/adapters; amounts aggregate by input asset and insufficient nonzero allowances reset before exact approval. NativeWrap requires canonical wrapped-native binding and exact summed native value; there is no invented launch fee. Swap funding commits approved target/spender/code hash and exact input/output/calldata. Unrelated donations/other launches are not swept as refunds.
+
+Preparing/Ready cancellation uses the stored commitment after expiry/retirement without calling adapters or requiring new profile/funding admission. It refunds unspent external funding only. Wrapped-native refunds are wrapped ERC20, not original native gas funds. Cancelled token inventory remains inactive or burns according to the plan. Cancellation still needs current execution admission and nonce/receipt safety; Active/Cancelled are terminal and there is no postactivation creator pause.
+
+```ts
+const cancel = await buildNextTransaction({client, planned, receipts, limits, fork, action: "cancel"});
+// Apply identical wallet-domain/exact-envelope/receipt handling before submission.
+```
+
+## Stable author APIs and V3 fees
+
+`developerBeneficiary`/envelope `beneficiary` is stable `authorId`. Registry `authorPayout(authorId)` is mutable live routing/controller; zero means unknown. Registry admin or current payout/controller may change a known nonzero route with `setAuthorPayout`. Retirement never changes stable identity or blocks existing active developer credits.
+
+| Helper | Inputs / semantics |
+| --- | --- |
+| `readLifecycleAuthor` | `{client,registry,authorId}` → canonical core/factory, known/live payout, hub count, pinned chain/block. |
+| `readAuthorHubs` | Same + `offset?:bigint,limit?:bigint` (defaults 0/100), bounded **1..100**, offset ≤ total, actual hubs/nextOffset/total/cursorComplete. |
+| `readDeveloperFees` | Same + `hub,assets?` → authenticated V3 hub, actual assets, claimable/reserved balances, frozen source terms/assets. Explicit unsupported assets are flagged, not relabeled supported. |
+| `buildSetAuthorPayoutTransaction` | Same + `payout,account,chainId:bigint`; requires current controller/admin and known identity. |
+| `buildClaimDeveloperFeesTransaction` | Same + `hub,asset,account,chainId:bigint`; permissionless fixed-live-payout direct claim. |
+| `buildClaimDeveloperFeesPageTransaction` | Same + `offset:bigint,limit:bigint,assets?,account,chainId:bigint`; factory page **1..10**. |
+| `decodeDeveloperClaimReceipt` | `{receipt,transaction}` using exact unsigned claim context; validates emitter/account/target/context/cursor/status/rows. |
+
+Unsigned objects carry exact `chainId/from/to/data/value`, with no execution default. Canonical membership is anchored to **registry.core → core.feeFactory → factory.isHub** before any hub self-report; selected registry/core/factory bindings are also checked. Page assets are sorted unique nonzero addresses, at most eight; `[]` means each hub's actual assets. Page cursor completion is independent of payment success: statuses **0 paid, 1 zero, 2 unsupported, 3 failed** remain distinct; preserve retryable failed rows even when the cursor reaches total. A successful direct receipt without `DeveloperFeesClaimed` is `unobserved`, not an invented zero payment.
+
+Choose an explicit page gas budget under the current account/RPC/chain limits, including every bounded hub/asset call plus factory overhead and EIP-150 headroom. `eth_estimateGas` success alone does not prove every row was attempted: the factory can complete the cursor while reporting failed rows under insufficient caller gas. Always decode and retry failed rows; never equate transaction success or cursor completion with payment success.
+
+Current ordinary fee preview/building uses public `lifecycleFeeHubAbi` with **no-argument `claimAndSplit()`**. Preview via viem `simulateContract`/`eth_call`, and build unsigned calldata with `encodeFunctionData`; neither guarantees execution. V3 freezes each source's adapter/profile/terms/stable author/maximum/selected rate. For each actual collected asset: executor bounty is deducted, owner/rewards/burn policy is split with canonical dust allocation, then developer fees are floor-rounded from each source's proportional contribution to the owner share. Developer fees do not reduce rewards/burn, do not reward donations and do not spend prior reserved credits. Owner and developer allocations are reserved before external payouts. `Distributed` includes `developerAmount`; hub reserved inventory is `reservedOwnerFees + reservedDeveloperFees`, not owner reserves alone.
+
+Current registered fee owners may update executor bounty up to 1,000 bps. Each no-arg harvest snapshots one rate for all sources, including already accrued source fees. Owner/reward/burn policy and frozen developer terms do not change; old owner credits remain with the credited owner. Owner `claimOwnerFees(asset,recipient)` withdraws reserved credits without harvesting/bounty. Developer `claimDeveloperFees(authorId,asset)` has no recipient argument and resolves live registry payout at execution.
+
+Lifecycle dividend tokens retain independent current-owner dividend bounty up to 1,000 bps, gross previews and net beneficiary payments with separate caller bounty; self-claims get full gross. Staking claims have no dividend payout bounty. Oracle genesis/cardinality/opening state is not lending-feed maturity, depth or recency approval; unrelated lending checks remain unchanged.
+
+## Independent vectors and local proof
+
+`test/fixtures/launch-lifecycle-v1.json` is a portable **offline wire vector**, not a deployed launch. Its independent generator owns the literal canonical ABI tuple:
+
+```sh
+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.
+
+`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.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.1.0",
-  "description": "Canonical TypeScript SDK for the Black Market protocol on Robinhood Chain (Abyss DEX, Atomic launches, lending market).",
+  "version": "0.4.0",
+  "description": "Canonical TypeScript SDK for Black Market on Robinhood Chain (reviewed multi-market launches, Abyss DEX, lending).",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abysshopper/black-market-node-sdk.git"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,11 +14,16 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle/index.d.ts",
+      "import": "./dist/lifecycle/index.js"
     }
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "engines": {