@black-market/sdk 0.6.3 → 0.7.0

package/src/lifecycle/transactions.ts

@@ -0,0 +1,34 @@
+import { encodeFunctionData } from "viem";
+import { launchLifecycleAbi } from "./abi.js";
+import { LifecycleFundingKind, LifecycleMode } from "./schema.js";
+import { LifecyclePlanningError, type BuildLaunchTransactionsOptions, type LifecycleTransaction } from "./types.js";
+import { assertLifecycleTokenAllocation } from "./allocations.js";
+
+/** Pure unsigned launch commands. Every command carries the complete commitment;
+ * preparation splits only empty markets, never positions, buys or public opening.
+ * Allowance discovery, recovery and execution proof belong to the planner. */
+export function buildLaunchTransactions({ plan, mode, preparationBatches }: BuildLaunchTransactionsOptions): LifecycleTransaction[] {
+  if (mode !== "atomic" && mode !== "staged") throw new LifecyclePlanningError("EXPLICIT_MODE_REQUIRED", "Choose atomic or staged explicitly; staged is never silently substituted");
+  if (plan.chainId <= 0n || plan.chainId > BigInt(Number.MAX_SAFE_INTEGER)) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Chain ID must be a positive exact JavaScript integer");
+  if (plan.markets.length === 0 || plan.markets.length > 16) throw new LifecyclePlanningError("INVALID_MARKET_COUNT", "A launch requires between one and sixteen markets");
+  if (mode === "atomic" && preparationBatches !== undefined) throw new LifecyclePlanningError("INVALID_PREPARATION_BATCHES", "Atomic execution has no separate preparation batches");
+  assertLifecycleTokenAllocation(plan);
+  const nativeValue = plan.funding.reduce((total, funding) => total + (funding.kind === LifecycleFundingKind.NativeWrap || funding.kind === LifecycleFundingKind.Swap && BigInt(funding.inputAsset) === 0n ? funding.inputAmount : 0n), 0n);
+  const base = { chainId: Number(plan.chainId), from: plan.creator, to: plan.orchestrator };
+  const transactions: LifecycleTransaction[] = [];
+  if (mode === "atomic") {
+    transactions.push({ ...base, id: "atomic", kind: "atomic", data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "launchAtomic", args: [plan] }), value: nativeValue, dependencies: [], postconditions: [{ kind: "launch", phase: "Active", preparedMarkets: plan.markets.length }] });
+  } else {
+    const batches = preparationBatches ?? [plan.markets.length];
+    if (batches.length === 0 || batches.some((count) => !Number.isSafeInteger(count) || count <= 0) || batches.reduce((total, count) => total + count, 0) !== plan.markets.length) throw new LifecyclePlanningError("INVALID_PREPARATION_BATCHES", "Positive ordered preparation counts must cover every market exactly");
+    transactions.push({ ...base, id: "begin", kind: "begin", data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "beginLaunch", args: [plan, LifecycleMode.Staged] }), value: nativeValue, dependencies: [], postconditions: [{ kind: "launch", phase: "Preparing", preparedMarkets: 0 }] });
+    let first = 0;
+    for (const count of batches) {
+      const completed = first + count;
+      transactions.push({ ...base, id: `prepare:${first}:${count}`, kind: "prepare", data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "prepareMarkets", args: [plan, first, count] }), value: 0n, dependencies: [], marketStart: first, marketCount: count, postconditions: [{ kind: "launch", phase: completed === plan.markets.length ? "Ready" : "Preparing", preparedMarkets: completed }] });
+      first = completed;
+    }
+    transactions.push({ ...base, id: "activate", kind: "activate", data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "activateLaunch", args: [plan] }), value: 0n, dependencies: [], postconditions: [{ kind: "launch", phase: "Active", preparedMarkets: plan.markets.length }] });
+  }
+  return transactions.map((transaction, index) => ({ ...transaction, calldataBytes: (transaction.data.length - 2) / 2, dependencies: index === 0 ? [] : [transactions[index - 1]!.id] }));
+}

package/src/lifecycle/types.ts

@@ -62,6 +62,8 @@ 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 encoded byte count; populated on SDK-built commands, including approvals. */
+  calldataBytes?: number;
   /** Exact current-state execution admission, not a wallet batch or future guarantee. */
   admission?: LifecycleAdmission;
   estimate?: LifecycleTransactionEstimate;
@@ -83,9 +85,18 @@ export type LifecycleAdmission = LifecycleProofOutcomes & {
   blockNumber: bigint; blockHash: Hash; account: Address; chainId: bigint;
   reason?: string; limits: ResolvedLifecycleLimits;
 };
+export type LifecycleFailureCategory = "semantic" | "capacity" | "opaque" | "source" | "postcondition" | "affordability";
+export type LifecycleCapacityConstraint = "compute" | "gas-envelope" | "calldata" | "simulation-gas";
 export type LifecycleSimulationStep = {
   transactionId: string; success: boolean; gasUsed?: bigint; gasLimit?: bigint; gasRequired?: bigint;
   returnData?: Hex; error?: string; estimate?: LifecycleTransactionEstimate;
+  failureCategory?: LifecycleFailureCategory; decodedError?: string;
+  /** Safe failed-call facts only; native messages and error-data bytes are never copied here. */
+  nativeErrorCode?: number;
+  nativeErrorKind?: "out-of-gas" | "execution-reverted" | "vm-error" | "other" | "missing";
+  nativeErrorDataBytes?: number;
+  /** Explicit native simulator report, not inferred from gas consumption or the requested limit. */
+  nativeGasCapped?: boolean;
 };
 export type LifecycleSimulation = LifecycleProofOutcomes & {
   backend: "eth_simulateV1" | "controlled-fork" | "unavailable";
@@ -93,6 +104,7 @@ export type LifecycleSimulation = LifecycleProofOutcomes & {
   blockNumber: bigint; blockHash: Hash; account: Address; chainId: bigint;
   steps: readonly LifecycleSimulationStep[]; limits: ResolvedLifecycleLimits;
   reason?: string; failedTransactionId?: string;
+  failureCategory?: LifecycleFailureCategory; capacityConstraint?: LifecycleCapacityConstraint;
 };
 export type LifecycleFundingPrerequisite = {
   funding: AssetFundingV1; inputBalance: bigint; requiredInput: bigint;
@@ -104,6 +116,8 @@ export type LifecycleProfile = {
   envelope?: LaunchEnvelopeV2; developerTerms?: LifecycleDeveloperTerms; protocolMaximumDeveloperFeeBps?: number;
   admitted: boolean; reason?: string;
 };
+/** Release construction data only. Current registry eligibility is not asserted. */
+export type LifecycleConstructionProfile = Omit<LifecycleProfile, "admitted" | "reason"> & { metadataSource: "preset" };
 export type LifecycleMarketProgress = {
   index: number; prepared: PreparedMarketV1; live?: MarketLiveStateV1; error?: string;
 };
@@ -131,16 +145,29 @@ export type PlannedLaunch = {
   tokenFactory: Address; tokenFactoryCodeHash: Hex;
   account: Address; chainId: bigint; mode: LaunchExecutionMode; confirmations: number;
   transactions: readonly LifecycleTransaction[]; prerequisites: readonly LifecycleFundingPrerequisite[];
-  profiles: readonly LifecycleProfile[]; simulation: LifecycleSimulation;
+  /** Sum of exact calldata bytes across the returned remaining commands, including approvals. */
+  totalCalldataBytes: number;
+  profiles: readonly (LifecycleProfile | LifecycleConstructionProfile)[]; simulation: LifecycleSimulation;
   /** Exact CREATE2 metadata captured from the final committed bound markets. */
   hookDeployments: readonly LifecyclePoolBoundHookDeployment[];
-  atomicAttempt: LifecycleSimulation; progress: CanonicalLaunchProgress;
+  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;
+  confirmations?: number; signal?: AbortSignal;
+};
+export type PrepareAndPlanLifecycleLaunchOptions = PlanLaunchOptions & {
+  onProgress?: (progress: PoolBoundLifecyclePreparationProgress) => void;
+  /** Protect every ordered buy from its actual diagnostic receipt output, rounded down.
+   * Omitted preserves the caller's committed minima. Only an unstarted launch may be protected. */
+  buySlippageBps?: number;
+};
+export type BuildLaunchTransactionsOptions = {
+  plan: LaunchPlanV1; mode: LaunchExecutionMode;
+  /** Positive ordered preparation counts covering every market exactly. Staged only. */
+  preparationBatches?: readonly number[];
 };
 export type SimulateLaunchPlanOptions = {
   client: LifecycleRpcClient; planned: PlannedLaunch; limits?: LifecycleLimitSource; fork?: ControlledLifecycleFork;
@@ -148,15 +175,20 @@ export type SimulateLaunchPlanOptions = {
    * stored plan when omitted, exactly as build-next consumes them; resimulation
    * never silently drops submitted-transaction context. */
   receipts?: readonly LifecycleReceiptReference[]; confirmations?: number;
+  signal?: AbortSignal;
 };
 export type ReadLaunchProgressOptions = {
   client: LifecycleRpcClient; planned: Pick<PlannedLaunch, "plan" | "planHash" | "launchId" | "predictedToken" | "account" | "mode" | "confirmations">;
   receipts?: readonly LifecycleReceiptReference[]; confirmations?: number;
+  signal?: AbortSignal;
 };
 export type BuildNextTransactionOptions = ReadLaunchProgressOptions & {
   planned: PlannedLaunch; action?: "continue" | "cancel"; limits?: LifecycleLimitSource; fork?: ControlledLifecycleFork;
   /** Optional active submission RPC. Only the immediate next exact transaction is estimated, read-only. */
   submissionClient?: LifecycleRpcClient;
+  /** Untrusted reviewed next envelope. Fresh canonical semantics and complete
+   * execution/headroom/affordability proof must accept its exact gas and gasPrice. */
+  reviewedTransaction?: LifecycleTransaction;
 };
 export class LifecyclePlanningError extends Error {
   readonly code: string;