@black-market/sdk 0.12.0 → 0.14.0

package/src/lifecycle/types.ts

@@ -5,11 +5,13 @@ import type {
   MarketLiveStateV1, PreparedMarketV1, ProfileRegistrationV1, ProfileTopologyV1, LaunchEnvelopeV2, LifecycleDeveloperTerms,
 } from "./schema.js";
 
-/** Local opt-in timing only: never contains request arguments, addresses, results or errors. */
+/** Local opt-in timing only: never contains request arguments, addresses, results or errors.
+ * Since 0.14.0, removed replay/envelope stages are represented by simulation.measure,
+ * which includes the final validated execution at the returned gas envelope. */
 export type LifecycleDiagnosticStage =
   | "plan" | "plan.context" | "plan.domain" | "plan.progress" | "plan.inputs" | "rpc"
   | "profile.certification" | "simulation.context" | "simulation.nitro"
-  | "simulation.poster" | "simulation.measure" | "simulation.replay" | "simulation.envelope" | "session-cache";
+  | "simulation.poster" | "simulation.measure" | "session-cache";
 export type LifecycleDiagnosticEvent = {
   stage: LifecycleDiagnosticStage;
   phase: "queued" | "start" | "success" | "failure" | "reuse";
@@ -35,7 +37,7 @@ export type LifecycleRpcClient = {
   sessionCache?: LifecycleSessionCache;
 };
 export type LifecycleBlock = { number: bigint; hash: Hash; timestamp: bigint; gasLimit: bigint; baseFeePerGas?: bigint };
-/** A session retains only static reads at one canonical block, never execution proof. */
+/** A session retains pinned static reads and deployment/backend capability observations. */
 export type LifecycleSessionCache = {
   readonly block: Readonly<Pick<LifecycleBlock, "number" | "hash">> | undefined;
   /** Call on wallet/chain changes and after every confirmed transaction. */
@@ -76,10 +78,11 @@ export type LifecyclePostcondition =
 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;
+  marketStart?: number; marketCount?: number; gas?: bigint; gasPrice?: bigint; nonce?: 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. */
+  /** Only the immediate command receives exact gas/price/estimate/admission.
+   * Future commands must be re-sized and proved by buildNextTransaction. */
   admission?: LifecycleAdmission;
   estimate?: LifecycleTransactionEstimate;
 };
@@ -104,7 +107,12 @@ export type LifecycleFailureCategory = "semantic" | "capacity" | "opaque" | "sou
 export type LifecycleCapacityConstraint = "compute" | "gas-envelope" | "calldata" | "simulation-gas";
 export type LifecycleSimulationStep = {
   transactionId: string; success: boolean; gasUsed?: bigint; gasLimit?: bigint; gasRequired?: bigint;
+  /** Compute-only sizing observation, excluding Nitro poster gas; not admission. */
+  computeGasRequired?: bigint;
   returnData?: Hex; error?: string; estimate?: LifecycleTransactionEstimate;
+  /** Suffix feasibility budget only, not a transaction estimate or execution admission.
+   * buildNextTransaction obtains a fresh poster quote and exact envelope at its turn. */
+  provisional?: boolean;
   failureCategory?: LifecycleFailureCategory; decodedError?: string;
   /** Safe failed-call facts only; native messages and error-data bytes are never copied here. */
   nativeErrorCode?: number;
@@ -115,13 +123,15 @@ export type LifecycleSimulationStep = {
 };
 export type LifecycleSimulation = LifecycleProofOutcomes & {
   backend: "eth_simulateV1" | "controlled-fork" | "unavailable";
-  /** Admission/proved outcomes cover the successful prefix, not the deferred suffix. */
+  /** Full successful prefix feasibility; only its immediate envelope is final. */
   confidence: "stateful" | "provisional"; admitted: boolean;
   blockNumber: bigint; blockHash: Hash; account: Address; chainId: bigint;
   steps: readonly LifecycleSimulationStep[]; limits: ResolvedLifecycleLimits;
   /** Unproved suffix. These transactions receive no gas, price, estimate or admission. */
   deferredTransactionIds: readonly string[];
   reason?: string; failedTransactionId?: string;
+  /** Affordability can mean insufficient sizing margin, even if smaller exact
+   * envelopes could fit. A refused RPC exposes no prefix results to refine them. */
   failureCategory?: LifecycleFailureCategory; capacityConstraint?: LifecycleCapacityConstraint;
 };
 export type LifecycleFundingPrerequisite = {
@@ -164,6 +174,8 @@ export type PlannedLaunch = {
   account: Address; chainId: bigint; mode: LaunchExecutionMode; confirmations: number;
   /** Opt-in proxy routing; the committed creator remains the proxy, account is its principal. */
   ufg?: { config: UfgLaunchConfig; configHash: Hash };
+  /** With admitted exact proof, transactions[0] is the immediate reviewed envelope,
+   * including nonce, gas and gasPrice. Deferred commands have no execution admission. */
   transactions: readonly LifecycleTransaction[]; prerequisites: readonly LifecycleFundingPrerequisite[];
   /** Sum of exact calldata bytes across the returned remaining commands, including approvals. */
   totalCalldataBytes: number;
@@ -186,11 +198,17 @@ export type PlanLaunchOptions = {
   /** Unstarted only: waive the funded boundary tail; all other topology checks remain required. */
   allowMissingPermanentTail?: boolean;
 };
+/** Explicit atomic final gas. Omitted price freezes this invocation's recommendation;
+ * a supplied price is replayed exactly, never refreshed or silently increased. */
+export type LifecycleFinalEnvelope = Readonly<{ gas: bigint; gasPrice?: bigint }>;
 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;
+  /** Atomic only, with no preceding approvals. Final calldata receives one exact
+   * validated replay, not a new gas recommendation or a larger rescue envelope. */
+  fixedFinalEnvelope?: LifecycleFinalEnvelope;
 };
 export type BuildLaunchTransactionsOptions = {
   plan: LaunchPlanV1; mode: LaunchExecutionMode;