@black-market/sdk 0.14.1 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +9 -7
  2. package/dist/lifecycle/authors.js +2 -2
  3. package/dist/lifecycle/authors.js.map +1 -1
  4. package/dist/lifecycle/auto-compound.d.ts +21 -0
  5. package/dist/lifecycle/auto-compound.d.ts.map +1 -0
  6. package/dist/lifecycle/auto-compound.js +34 -0
  7. package/dist/lifecycle/auto-compound.js.map +1 -0
  8. package/dist/lifecycle/calibration.d.ts +2 -4
  9. package/dist/lifecycle/calibration.d.ts.map +1 -1
  10. package/dist/lifecycle/calibration.js +1 -26
  11. package/dist/lifecycle/calibration.js.map +1 -1
  12. package/dist/lifecycle/deployments/auto-compound-dynamic-pool-v1-20261028.d.ts +73 -0
  13. package/dist/lifecycle/deployments/auto-compound-dynamic-pool-v1-20261028.d.ts.map +1 -0
  14. package/dist/lifecycle/deployments/auto-compound-dynamic-pool-v1-20261028.js +75 -0
  15. package/dist/lifecycle/deployments/auto-compound-dynamic-pool-v1-20261028.js.map +1 -0
  16. package/dist/lifecycle/deployments/auto-compound-static-pool-v1-20261028.d.ts +73 -0
  17. package/dist/lifecycle/deployments/auto-compound-static-pool-v1-20261028.d.ts.map +1 -0
  18. package/dist/lifecycle/deployments/auto-compound-static-pool-v1-20261028.js +75 -0
  19. package/dist/lifecycle/deployments/auto-compound-static-pool-v1-20261028.js.map +1 -0
  20. package/dist/lifecycle/gas-profile.d.ts +39 -0
  21. package/dist/lifecycle/gas-profile.d.ts.map +1 -0
  22. package/dist/lifecycle/gas-profile.js +193 -0
  23. package/dist/lifecycle/gas-profile.js.map +1 -0
  24. package/dist/lifecycle/index.d.ts +6 -4
  25. package/dist/lifecycle/index.d.ts.map +1 -1
  26. package/dist/lifecycle/index.js +6 -4
  27. package/dist/lifecycle/index.js.map +1 -1
  28. package/dist/lifecycle/markets.d.ts +2 -0
  29. package/dist/lifecycle/markets.d.ts.map +1 -1
  30. package/dist/lifecycle/markets.js +30 -3
  31. package/dist/lifecycle/markets.js.map +1 -1
  32. package/dist/lifecycle/opening-buys.d.ts +13 -0
  33. package/dist/lifecycle/opening-buys.d.ts.map +1 -0
  34. package/dist/lifecycle/opening-buys.js +171 -0
  35. package/dist/lifecycle/opening-buys.js.map +1 -0
  36. package/dist/lifecycle/planner.d.ts +6 -9
  37. package/dist/lifecycle/planner.d.ts.map +1 -1
  38. package/dist/lifecycle/planner.js +175 -265
  39. package/dist/lifecycle/planner.js.map +1 -1
  40. package/dist/lifecycle/presets.d.ts +10 -3
  41. package/dist/lifecycle/presets.d.ts.map +1 -1
  42. package/dist/lifecycle/presets.js +13 -1
  43. package/dist/lifecycle/presets.js.map +1 -1
  44. package/dist/lifecycle/progress.d.ts +1 -1
  45. package/dist/lifecycle/progress.d.ts.map +1 -1
  46. package/dist/lifecycle/progress.js +21 -20
  47. package/dist/lifecycle/progress.js.map +1 -1
  48. package/dist/lifecycle/rpc.d.ts +25 -30
  49. package/dist/lifecycle/rpc.d.ts.map +1 -1
  50. package/dist/lifecycle/rpc.js +63 -81
  51. package/dist/lifecycle/rpc.js.map +1 -1
  52. package/dist/lifecycle/snapshot.d.ts.map +1 -1
  53. package/dist/lifecycle/snapshot.js +2 -4
  54. package/dist/lifecycle/snapshot.js.map +1 -1
  55. package/dist/lifecycle/transactions.d.ts +29 -6
  56. package/dist/lifecycle/transactions.d.ts.map +1 -1
  57. package/dist/lifecycle/transactions.js +62 -27
  58. package/dist/lifecycle/transactions.js.map +1 -1
  59. package/dist/lifecycle/types.d.ts +55 -122
  60. package/dist/lifecycle/types.d.ts.map +1 -1
  61. package/dist/lifecycle/types.js +3 -3
  62. package/dist/lifecycle/types.js.map +1 -1
  63. package/dist/lifecycle/ufg.d.ts +1 -1
  64. package/dist/lifecycle/ufg.d.ts.map +1 -1
  65. package/dist/lifecycle/ufg.js +4 -8
  66. package/dist/lifecycle/ufg.js.map +1 -1
  67. package/docs/launch-lifecycle.md +110 -78
  68. package/docs/lifecycle-gas-profiles.md +90 -0
  69. package/docs/reference.md +99 -47
  70. package/examples/.env.example +0 -3
  71. package/examples/README.md +14 -11
  72. package/examples/launch-example-support.ts +4 -9
  73. package/examples/launch-example.ts +30 -36
  74. package/examples/launch-lifecycle-smoke.ts +11 -21
  75. package/examples/launch.ts +8 -11
  76. package/package.json +1 -1
  77. package/src/lifecycle/authors.ts +2 -2
  78. package/src/lifecycle/auto-compound.ts +38 -0
  79. package/src/lifecycle/calibration.ts +3 -23
  80. package/src/lifecycle/deployments/auto-compound-dynamic-pool-v1-20261028.ts +77 -0
  81. package/src/lifecycle/deployments/auto-compound-static-pool-v1-20261028.ts +77 -0
  82. package/src/lifecycle/gas-profile.ts +186 -0
  83. package/src/lifecycle/index.ts +6 -4
  84. package/src/lifecycle/markets.ts +25 -3
  85. package/src/lifecycle/opening-buys.ts +157 -0
  86. package/src/lifecycle/planner.ts +168 -247
  87. package/src/lifecycle/presets.ts +15 -1
  88. package/src/lifecycle/progress.ts +19 -20
  89. package/src/lifecycle/rpc.ts +58 -68
  90. package/src/lifecycle/snapshot.ts +2 -4
  91. package/src/lifecycle/transactions.ts +69 -27
  92. package/src/lifecycle/types.ts +60 -99
  93. package/src/lifecycle/ufg.ts +4 -8
  94. package/dist/lifecycle/fork.d.ts +0 -15
  95. package/dist/lifecycle/fork.d.ts.map +0 -1
  96. package/dist/lifecycle/fork.js +0 -36
  97. package/dist/lifecycle/fork.js.map +0 -1
  98. package/dist/lifecycle/simulation.d.ts +0 -18
  99. package/dist/lifecycle/simulation.d.ts.map +0 -1
  100. package/dist/lifecycle/simulation.js +0 -754
  101. package/dist/lifecycle/simulation.js.map +0 -1
  102. package/src/lifecycle/fork.ts +0 -36
  103. package/src/lifecycle/simulation.ts +0 -689
@@ -5,13 +5,10 @@ import type {
5
5
  MarketLiveStateV1, PreparedMarketV1, ProfileRegistrationV1, ProfileTopologyV1, LaunchEnvelopeV2, LifecycleDeveloperTerms,
6
6
  } from "./schema.js";
7
7
 
8
- /** Local opt-in timing only: never contains request arguments, addresses, results or errors.
9
- * Since 0.14.0, removed replay/envelope stages are represented by simulation.measure,
10
- * which includes the final validated execution at the returned gas envelope. */
8
+ /** Local opt-in timing only: never contains request arguments, addresses, results or errors. */
11
9
  export type LifecycleDiagnosticStage =
12
10
  | "plan" | "plan.context" | "plan.domain" | "plan.progress" | "plan.inputs" | "rpc"
13
- | "profile.certification" | "simulation.context" | "simulation.nitro"
14
- | "simulation.poster" | "simulation.measure" | "session-cache";
11
+ | "profile.certification" | "session-cache";
15
12
  export type LifecycleDiagnosticEvent = {
16
13
  stage: LifecycleDiagnosticStage;
17
14
  phase: "queued" | "start" | "success" | "failure" | "reuse";
@@ -31,13 +28,13 @@ export type LifecycleRpcClient = {
31
28
  request(args: { method: string; params?: readonly unknown[] }): Promise<unknown>;
32
29
  /** Opt in to bounded parallel reads only when the supplied transport batches concurrent requests. */
33
30
  supportsReadBatching?: boolean;
34
- /** Optional local observer. Listener failures cannot change execution or admission. */
31
+ /** Optional local observer. Listener failures cannot change planning or sending. */
35
32
  onDiagnostic?: LifecycleDiagnosticListener;
36
33
  /** Caller-owned, opt-in static observations; create with createLifecycleSessionCache(). */
37
34
  sessionCache?: LifecycleSessionCache;
38
35
  };
39
36
  export type LifecycleBlock = { number: bigint; hash: Hash; timestamp: bigint; gasLimit: bigint; baseFeePerGas?: bigint };
40
- /** A session retains pinned static reads and deployment/backend capability observations. */
37
+ /** A session retains pinned static reads and deployment metadata observations. */
41
38
  export type LifecycleSessionCache = {
42
39
  readonly block: Readonly<Pick<LifecycleBlock, "number" | "hash">> | undefined;
43
40
  /** Call on wallet/chain changes and after every confirmed transaction. */
@@ -48,29 +45,19 @@ export type LifecycleLimits = {
48
45
  /** Optional tightening caps on the complete transaction gas envelope, including Nitro poster gas. */
49
46
  headroomBps?: number; chainGasLimit?: bigint; rpcGasLimit?: bigint; accountGasLimit?: bigint;
50
47
  maxCalldataBytes?: number;
51
- /** Aggregate gas-used budget for one simulation request; defaults to 50M on chain 4663. */
52
- maxSimulationGas?: bigint;
53
48
  chainId?: bigint; orchestrator?: Address; account?: Address; observedBlockNumber?: bigint; observedBlockHash?: Hash;
54
49
  /** External data fee not already charged in gas, called with exact calldata and the pinned block.
55
- * Nitro poster fees are included in gas and use the native NodeInterface instead. */
50
+ * Nitro poster fees are already included in gas, bounded locally from same-review ArbGasInfo prices. */
56
51
  estimateDataFee?: (transaction: LifecycleTransaction, context: LifecycleLimitContext) => Promise<bigint>;
57
52
  };
58
53
  export type LifecycleLimitSource = LifecycleLimits | ((context: LifecycleLimitContext) => Promise<LifecycleLimits>);
59
54
  export type ResolvedLifecycleLimits = {
60
- /** Generic EVM gas ceiling; on Nitro this is the pinned compute ceiling, not total gas. */
55
+ /** Fixed native transaction ceiling, including poster gas; caller caps may refuse but never resize it. */
61
56
  executionGasCeiling: bigint; transactionGasCeiling?: bigint; protocol: "evm" | "nitro";
62
- arbOSVersion?: bigint; maxTxComputeGas?: bigint; maxBlockComputeGas?: bigint;
63
- headroomBps: number; maxCalldataBytes?: number; maxSimulationGas?: bigint;
57
+ headroomBps: number; maxCalldataBytes?: number;
64
58
  blockGasLimit: bigint; chainGasLimit?: bigint; rpcGasLimit?: bigint; accountGasLimit?: bigint;
65
59
  unknownExecutionConstraints: readonly string[]; unknownConstraints: readonly string[];
66
60
  };
67
- /** Only explicitly disposable RPCs may execute snapshot-isolated simulation transactions. */
68
- export type ControlledLifecycleFork = {
69
- client: LifecycleRpcClient; isolation: "disposable"; allowTransactions: true;
70
- expectedChainId?: bigint; expectedBlockHash?: Hash; impersonation?: "anvil" | "hardhat" | "none";
71
- receiptTimeoutMs?: number;
72
- sourceRpcUrl: string; forkRpcUrl: string; resetMethod?: "anvil_reset" | "hardhat_reset";
73
- };
74
61
  export type LifecycleTransactionKind = "approve-reset" | "approve" | "atomic" | "begin" | "prepare" | "activate" | "cancel";
75
62
  export type LifecyclePostcondition =
76
63
  | { kind: "allowance"; asset: Address; spender: Address; minimum: bigint; exact?: bigint }
@@ -78,60 +65,45 @@ export type LifecyclePostcondition =
78
65
  export type LifecycleTransaction = {
79
66
  id: string; kind: LifecycleTransactionKind; chainId: number; from: Address; to: Address; data: Hex; value: bigint;
80
67
  dependencies: readonly string[]; postconditions: readonly LifecyclePostcondition[];
81
- marketStart?: number; marketCount?: number; gas?: bigint; gasPrice?: bigint; nonce?: bigint;
68
+ marketStart?: number; marketCount?: number; gas?: bigint; gasPrice?: bigint;
82
69
  /** Exact encoded byte count; populated on SDK-built commands, including approvals. */
83
70
  calldataBytes?: number;
84
- /** Only the immediate command receives exact gas/price/estimate/admission.
85
- * Future commands must be re-sized and proved by buildNextTransaction. */
86
- admission?: LifecycleAdmission;
71
+ /** Only the immediate command receives current planning checks and fees.
72
+ * Launch gas is the native ceiling; approvals leave gas to the wallet. */
73
+ assessment?: LifecyclePlanningAssessment;
87
74
  estimate?: LifecycleTransactionEstimate;
88
75
  };
89
76
  export type LifecycleTransactionEstimate = {
90
- gasUsed: bigint; gasLimit: bigint; gasPrice: bigint; executionFee: bigint; dataFee?: bigint; totalFee?: bigint;
91
- /** Estimated poster allocation within gasLimit, never an exact compute measurement or an extra fee. */
77
+ gasLimit: bigint; gasPrice: bigint; executionFee: bigint; dataFee?: bigint; totalFee?: bigint;
78
+ /** Estimated poster allocation within gasLimit, never a measured or additional fee. */
92
79
  posterGas?: bigint; posterFee?: bigint; dataFeeIncludedInGas: boolean;
93
- feeConfidence: "execution-and-data" | "execution-only";
94
- };
95
- /** Proof scopes are independent: current execution is not guaranteed wallet submission. */
96
- export type LifecycleProofOutcomes = {
97
- executionProof: "proved" | "failed" | "unavailable";
98
- protocolFit: "proved" | "failed" | "unknown";
99
- transportPreflight: "not-requested" | "passed" | "failed";
100
- };
101
- export type LifecycleAdmission = LifecycleProofOutcomes & {
102
- admitted: boolean; confidence: "stateful" | "provisional";
103
- blockNumber: bigint; blockHash: Hash; account: Address; chainId: bigint;
104
- reason?: string; limits: ResolvedLifecycleLimits;
105
- };
106
- export type LifecycleFailureCategory = "semantic" | "capacity" | "opaque" | "source" | "postcondition" | "affordability";
107
- export type LifecycleCapacityConstraint = "compute" | "gas-envelope" | "calldata" | "simulation-gas";
108
- export type LifecycleSimulationStep = {
109
- transactionId: string; success: boolean; gasUsed?: bigint; gasLimit?: bigint; gasRequired?: bigint;
110
- /** Compute-only sizing observation, excluding Nitro poster gas; not admission. */
111
- computeGasRequired?: bigint;
112
- returnData?: Hex; error?: string; estimate?: LifecycleTransactionEstimate;
113
- /** Suffix feasibility budget only, not a transaction estimate or execution admission.
114
- * buildNextTransaction obtains a fresh poster quote and exact envelope at its turn. */
115
- provisional?: boolean;
116
- failureCategory?: LifecycleFailureCategory; decodedError?: string;
117
- /** Safe failed-call facts only; native messages and error-data bytes are never copied here. */
118
- nativeErrorCode?: number;
119
- nativeErrorKind?: "out-of-gas" | "execution-reverted" | "vm-error" | "other" | "missing";
120
- nativeErrorDataBytes?: number;
121
- /** Explicit native simulator report, not inferred from gas consumption or the requested limit. */
122
- nativeGasCapped?: boolean;
123
- };
124
- export type LifecycleSimulation = LifecycleProofOutcomes & {
125
- backend: "eth_simulateV1" | "controlled-fork" | "unavailable";
126
- /** Full successful prefix feasibility; only its immediate envelope is final. */
127
- confidence: "stateful" | "provisional"; admitted: boolean;
80
+ feeConfidence: "native-ceiling-and-data" | "native-ceiling-only";
81
+ };
82
+ export type LifecycleFailureCategory = "semantic" | "capacity" | "affordability";
83
+ export type LifecycleCapacityConstraint = "gas-envelope" | "calldata" | "activation" | "preparation";
84
+ export type LifecycleOpeningBuyQuote = {
85
+ buyIndex: number; marketIndex: number; quoteAmountIn: bigint; quoteSpent: bigint;
86
+ tokenOut: bigint; sqrtPriceAfterX96: bigint;
87
+ };
88
+ /** Versioned compute budgets with headroom, never transaction gas-limit sizing.
89
+ * Atomic budget is absent when conversion work is outside the template model. */
90
+ export type LifecycleLaunchGasBounds = {
91
+ atomicComputeGasUpperBound?: bigint; activationComputeGasUpperBound: bigint;
92
+ };
93
+ export type LifecycleGasProfile = {
94
+ version: string; bounds: LifecycleLaunchGasBounds;
95
+ initialBuys: readonly LifecycleOpeningBuyQuote[];
96
+ };
97
+ /** Pinned input and gas-budget checks only. No transaction is simulated or proved. */
98
+ export type LifecyclePlanningAssessment = {
99
+ ready: boolean;
128
100
  blockNumber: bigint; blockHash: Hash; account: Address; chainId: bigint;
129
- steps: readonly LifecycleSimulationStep[]; limits: ResolvedLifecycleLimits;
130
- /** Unproved suffix. These transactions receive no gas, price, estimate or admission. */
131
- deferredTransactionIds: readonly string[];
132
- reason?: string; failedTransactionId?: string;
133
- /** Affordability can mean insufficient sizing margin, even if smaller exact
134
- * envelopes could fit. A refused RPC exposes no prefix results to refine them. */
101
+ limits: ResolvedLifecycleLimits;
102
+ /** Immediate native-ceiling fee budget; absent for wallet-prepared approvals. */
103
+ estimate?: LifecycleTransactionEstimate;
104
+ gasProfile?: LifecycleGasProfile;
105
+ /** Controlled SDK code and user-safe actionable reason, never raw provider errors. */
106
+ code?: string; reason?: string; failedTransactionId?: string;
135
107
  failureCategory?: LifecycleFailureCategory; capacityConstraint?: LifecycleCapacityConstraint;
136
108
  };
137
109
  export type LifecycleFundingPrerequisite = {
@@ -152,15 +124,18 @@ export type LifecycleMarketProgress = {
152
124
  export type LifecycleReceiptReference = {
153
125
  transactionHash: Hash; replacementHash?: Hash; confirmations?: number;
154
126
  observedBlockNumber?: bigint; observedBlockHash?: Hash;
127
+ /** Actual submitted nonce from the wallet/transaction observation, never a planning guess. */
128
+ nonce?: bigint;
155
129
  };
156
130
  export type LifecycleReceiptStatus = {
157
131
  transactionHash: Hash; effectiveHash: Hash; status: "pending" | "confirmed" | "reverted" | "reorged" | "unconfirmed" | "replacement-cancelled";
158
- blockNumber?: bigint; blockHash?: Hash; confirmations?: bigint; replaced: boolean;
132
+ blockNumber?: bigint; blockHash?: Hash; confirmations?: bigint; replaced: boolean; nonce?: bigint;
159
133
  };
160
134
  export type CanonicalLaunchProgress = {
161
135
  canonical: LaunchProgressV1; blockNumber: bigint; blockHash: Hash; chainId: bigint;
162
136
  head: LaunchProgressV1; confirmationDepth: number; confirmedBlockNumber: bigint; confirmedBlockHash: Hash;
163
- confirmedAccountNonce: bigint; headAccountNonce: bigint; pendingAccountNonce: bigint; confirmationSafe: boolean;
137
+ /** Confirmed launch state only; unrelated account pending transactions do not block it. */
138
+ confirmationSafe: boolean;
164
139
  markets: readonly LifecycleMarketProgress[]; receipts: readonly LifecycleReceiptStatus[];
165
140
  token: Address; planHash: Hash; launchId: Hash;
166
141
  };
@@ -174,22 +149,24 @@ export type PlannedLaunch = {
174
149
  account: Address; chainId: bigint; mode: LaunchExecutionMode; confirmations: number;
175
150
  /** Opt-in proxy routing; the committed creator remains the proxy, account is its principal. */
176
151
  ufg?: { config: UfgLaunchConfig; configHash: Hash };
177
- /** With admitted exact proof, transactions[0] is the immediate reviewed envelope,
178
- * including nonce, gas and gasPrice. Deferred commands have no execution admission. */
152
+ /** Only transactions[0] has fresh immediate planning checks/fees. Launch gas is
153
+ * the native ceiling; wallet-assigned nonce and approval gas are omitted. */
179
154
  transactions: readonly LifecycleTransaction[]; prerequisites: readonly LifecycleFundingPrerequisite[];
180
155
  /** Sum of exact calldata bytes across the returned remaining commands, including approvals. */
181
156
  totalCalldataBytes: number;
182
- profiles: readonly (LifecycleProfile | LifecycleConstructionProfile)[]; simulation: LifecycleSimulation;
157
+ profiles: readonly (LifecycleProfile | LifecycleConstructionProfile)[]; assessment: LifecyclePlanningAssessment;
183
158
  /** Exact CREATE2 metadata captured from the final committed bound markets. */
184
159
  hookDeployments: readonly LifecyclePoolBoundHookDeployment[];
185
160
  progress: CanonicalLaunchProgress;
186
161
  limits?: LifecycleLimitSource;
187
- /** Unstarted-launch admission choices only; never part of the committed plan or calldata. */
162
+ /** Unstarted-launch construction choices; never part of committed calldata. */
188
163
  allowTopologyGaps?: boolean; allowMissingPermanentTail?: boolean;
189
164
  };
190
165
  export type PlanLaunchOptions = {
191
- client: LifecycleRpcClient; account: Address; plan: LaunchPlanV1; mode: LaunchExecutionMode;
192
- limits?: LifecycleLimitSource; fork?: ControlledLifecycleFork; receipts?: readonly LifecycleReceiptReference[];
166
+ client: LifecycleRpcClient; account: Address; plan: LaunchPlanV1;
167
+ /** Atomic requires one market, no conversion and a known budget fitting with headroom.
168
+ * All other unstarted launches are staged; started launches retain canonical mode. */
169
+ mode: LaunchExecutionMode; limits?: LifecycleLimitSource; receipts?: readonly LifecycleReceiptReference[];
193
170
  confirmations?: number; signal?: AbortSignal;
194
171
  /** Opt in to the pinned UFG proxy; sender must match the nonce's principal namespace. */
195
172
  ufg?: { config: UfgLaunchConfig };
@@ -198,48 +175,32 @@ export type PlanLaunchOptions = {
198
175
  /** Unstarted only: waive the funded boundary tail; all other topology checks remain required. */
199
176
  allowMissingPermanentTail?: boolean;
200
177
  };
201
- /** Explicit atomic final gas. Omitted price freezes this invocation's recommendation;
202
- * a supplied price is replayed exactly, never refreshed or silently increased. */
203
- export type LifecycleFinalEnvelope = Readonly<{ gas: bigint; gasPrice?: bigint }>;
204
178
  export type PrepareAndPlanLifecycleLaunchOptions = PlanLaunchOptions & {
205
179
  onProgress?: (progress: PoolBoundLifecyclePreparationProgress) => void;
206
- /** Protect every ordered buy from its actual diagnostic receipt output, rounded down.
207
- * Omitted preserves the caller's committed minima. Only an unstarted launch may be protected. */
180
+ /** Protect ordered buys from exact local curve outputs, rounded down.
181
+ * Omitted preserves committed minima; unstarted launches only. */
208
182
  buySlippageBps?: number;
209
- /** Atomic only, with no preceding approvals. Final calldata receives one exact
210
- * validated replay, not a new gas recommendation or a larger rescue envelope. */
211
- fixedFinalEnvelope?: LifecycleFinalEnvelope;
212
183
  };
213
184
  export type BuildLaunchTransactionsOptions = {
214
185
  plan: LaunchPlanV1; mode: LaunchExecutionMode;
215
186
  /** Positive ordered preparation counts covering every market exactly. Staged only. */
216
187
  preparationBatches?: readonly number[];
217
188
  };
218
- export type SimulateLaunchPlanOptions = {
219
- client: LifecycleRpcClient; planned: PlannedLaunch; limits?: LifecycleLimitSource; fork?: ControlledLifecycleFork;
220
- /** Submitted receipt evidence and confirmation depth are inherited from the
221
- * stored plan when omitted, exactly as build-next consumes them; resimulation
222
- * never silently drops submitted-transaction context. */
223
- receipts?: readonly LifecycleReceiptReference[]; confirmations?: number;
224
- signal?: AbortSignal;
225
- };
226
189
  export type ReadLaunchProgressOptions = {
227
190
  client: LifecycleRpcClient; planned: Pick<PlannedLaunch, "plan" | "planHash" | "launchId" | "predictedToken" | "account" | "mode" | "confirmations" | "ufg">;
228
191
  receipts?: readonly LifecycleReceiptReference[]; confirmations?: number;
229
192
  signal?: AbortSignal;
230
193
  };
231
194
  export type BuildNextTransactionOptions = ReadLaunchProgressOptions & {
232
- planned: PlannedLaunch; action?: "continue" | "cancel"; limits?: LifecycleLimitSource; fork?: ControlledLifecycleFork;
233
- /** Optional active submission RPC. Only the immediate next exact transaction is estimated, read-only. */
234
- submissionClient?: LifecycleRpcClient;
235
- /** Untrusted reviewed next envelope. Canonical identity and direct exact replay
236
- * prove only this immediate transaction at its held gas and gasPrice. */
195
+ planned: PlannedLaunch; action?: "continue" | "cancel"; limits?: LifecycleLimitSource;
196
+ /** Untrusted reviewed intent/fee. Gas differing from the native ceiling is stale;
197
+ * never resize it, bump a held fee or assign a wallet nonce. */
237
198
  reviewedTransaction?: LifecycleTransaction;
238
199
  };
239
200
  export class LifecyclePlanningError extends Error {
240
201
  readonly code: string;
241
- readonly simulation?: LifecycleSimulation;
242
- constructor(code: string, message: string, simulation?: LifecycleSimulation) {
243
- super(message); this.name = "LifecyclePlanningError"; this.code = code; this.simulation = simulation;
202
+ readonly assessment?: LifecyclePlanningAssessment;
203
+ constructor(code: string, message: string, assessment?: LifecyclePlanningAssessment) {
204
+ super(message); this.name = "LifecyclePlanningError"; this.code = code; this.assessment = assessment;
244
205
  }
245
206
  }
@@ -1,16 +1,16 @@
1
1
  import { decodeFunctionResult, encodeFunctionData, keccak256, stringToHex, zeroAddress, type Address } from "viem";
2
2
  import { lifecycleErc20Abi } from "./abi.js";
3
3
  import { ufgLaunchProxyV1Abi, ufgTreasuryFactoryV1Abi } from "./ufg-abi.js";
4
- import { buildLaunchTransactions } from "./transactions.js";
4
+ import { buildLifecycleCommands } from "./transactions.js";
5
5
  import { decodeAbyssLifecycleMarketConfig, encodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
6
6
  import { getKnownLifecycleProfile, KnownLifecycleProfile } from "./presets.js";
7
- import { LifecycleFundingKind, LifecycleTokenKind, LifecycleRewardMode, LifecycleMode, type LaunchPlanV1 } from "./schema.js";
7
+ import { LifecycleFundingKind, LifecycleTokenKind, LifecycleRewardMode, type LaunchPlanV1 } from "./schema.js";
8
8
  import { LifecyclePlanningError, type BuildLaunchTransactionsOptions, type LifecycleRpcClient, type LifecycleTransaction } from "./types.js";
9
9
  import { buildUfgFeeAssetPolicies, encodeUfgLaunchConfig, hashUfgLaunchConfig, isUfgProfile, UFG_DYNAMIC_ADAPTER_ID, UFG_FIXED_ADAPTER_ID, UFG_FIXED_PROFILE_ID, UFG_LAUNCH_PROXY_ADDRESS, UFG_TREASURY_FACTORY_ADDRESS, ufgPlanPrincipal, type UfgLaunchConfig } from "./ufg-config.js";
10
10
 
11
11
  export { UFG_LAUNCH_PROXY_ADDRESS, UFG_TREASURY_FACTORY_ADDRESS, UFG_UPSTREAM_FACTORY_ADDRESS, UFG_ORCHESTRATOR_ADDRESS, UFG_FIXED_PROFILE_ID, UFG_DYNAMIC_PROFILE_ID, UFG_FIXED_ADAPTER_ID, UFG_DYNAMIC_ADAPTER_ID, isUfgProfile, ufgLaunchConfigComponents, encodeUfgLaunchConfig, decodeUfgLaunchConfig, hashUfgLaunchConfig, validateUfgLaunchConfig, ufgLaunchNonce, buildUfgFeeAssetPolicies, type UfgLaunchConfig } from "./ufg-config.js";
12
12
 
13
- /** Offline proxy-specific admission. Live token/reserve code, registry and transfer checks still require simulation. */
13
+ /** Offline proxy-specific intent checks. Registry, transfers and reserve behavior are enforced on-chain. */
14
14
  export function validateUfgLaunchPlan(plan: LaunchPlanV1, config: UfgLaunchConfig, predictedToken: Address): void {
15
15
  try {
16
16
  ufgPlanPrincipal(plan);
@@ -49,11 +49,7 @@ export function buildUfgLaunchTransactions(options: BuildUfgLaunchTransactionsOp
49
49
  const { plan, config } = options;
50
50
  const principal = ufgPlanPrincipal(plan);
51
51
  encodeUfgLaunchConfig(config);
52
- return buildLaunchTransactions(options).map((transaction) => {
53
- const data = transaction.kind === "atomic" ? encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "launchAtomic", args: [plan, config] })
54
- : transaction.kind === "begin" ? encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "beginLaunch", args: [plan, LifecycleMode.Staged, config] }) : transaction.data;
55
- return { ...transaction, from: principal, to: UFG_LAUNCH_PROXY_ADDRESS, data, calldataBytes: (data.length - 2) / 2 };
56
- });
52
+ return buildLifecycleCommands(options, { account: principal, config });
57
53
  }
58
54
  export function buildUfgCancelTransaction({ plan, preparedMarkets = 0 }: { plan: LaunchPlanV1; preparedMarkets?: number }): LifecycleTransaction {
59
55
  const data = encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "cancelLaunch", args: [plan] });
@@ -1,15 +0,0 @@
1
- import { type ControlledLifecycleFork } from "./types.js";
2
- /**
3
- * Connects an explicitly disposable loopback fork. Only the fork receives resets/transactions;
4
- * sourceRpcUrl is used by the fork node for read-only canonical state synchronization.
5
- */
6
- export declare function createControlledLifecycleFork(options: {
7
- sourceRpcUrl: string;
8
- forkRpcUrl: string;
9
- allowTransactions: true;
10
- fetch?: typeof globalThis.fetch;
11
- impersonation?: "anvil" | "hardhat" | "none";
12
- resetMethod?: "anvil_reset" | "hardhat_reset";
13
- receiptTimeoutMs?: number;
14
- }): ControlledLifecycleFork;
15
- //# sourceMappingURL=fork.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/lifecycle/fork.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,uBAAuB,EAA2B,MAAM,YAAY,CAAC;AAG3G;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IACrD,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,IAAI,CAAC;IAClE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9E,WAAW,CAAC,EAAE,aAAa,GAAG,eAAe,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1E,GAAG,uBAAuB,CAwB1B"}
@@ -1,36 +0,0 @@
1
- import { LifecyclePlanningError } from "./types.js";
2
- import { rpcObject } from "./rpc.js";
3
- /**
4
- * Connects an explicitly disposable loopback fork. Only the fork receives resets/transactions;
5
- * sourceRpcUrl is used by the fork node for read-only canonical state synchronization.
6
- */
7
- export function createControlledLifecycleFork(options) {
8
- const source = new URL(options.sourceRpcUrl);
9
- const fork = new URL(options.forkRpcUrl);
10
- if (!["http:", "https:"].includes(source.protocol) || !["http:", "https:"].includes(fork.protocol))
11
- throw new LifecyclePlanningError("UNSAFE_FORK", "Controlled fork RPCs must use HTTP(S)");
12
- const loopback = ["localhost", "127.0.0.1", "[::1]", "::1"];
13
- const sourcePort = source.port || (source.protocol === "https:" ? "443" : "80");
14
- const forkPort = fork.port || (fork.protocol === "https:" ? "443" : "80");
15
- if (!loopback.includes(fork.hostname) || (loopback.includes(source.hostname) && sourcePort === forkPort) || source.href === fork.href || options.allowTransactions !== true)
16
- throw new LifecyclePlanningError("UNSAFE_FORK", "Controlled fork must be an explicit, distinct disposable loopback RPC, not a localhost/IP alias of the source");
17
- const fetch = options.fetch ?? globalThis.fetch;
18
- let id = 0;
19
- const client = {
20
- async request({ method, params }) {
21
- const response = await fetch(fork.href, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params: params ?? [] }) });
22
- if (!response.ok)
23
- throw new LifecyclePlanningError("FORK_RPC_ERROR", `Disposable fork RPC returned HTTP ${response.status}`);
24
- const result = rpcObject(await response.json(), "fork JSON-RPC envelope");
25
- if (result.error !== undefined) {
26
- const error = rpcObject(result.error, "fork JSON-RPC error");
27
- throw new LifecyclePlanningError("FORK_RPC_ERROR", typeof error.message === "string" ? error.message : "Disposable fork RPC returned an error");
28
- }
29
- if (!("result" in result))
30
- throw new LifecyclePlanningError("INVALID_RPC_RESPONSE", "Disposable fork RPC omitted its result");
31
- return result.result;
32
- },
33
- };
34
- return { client, isolation: "disposable", allowTransactions: true, sourceRpcUrl: source.href, forkRpcUrl: fork.href, resetMethod: options.resetMethod ?? "anvil_reset", impersonation: options.impersonation ?? "anvil", receiptTimeoutMs: options.receiptTimeoutMs };
35
- }
36
- //# sourceMappingURL=fork.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"fork.js","sourceRoot":"","sources":["../../src/lifecycle/fork.ts"],"names":[],"mappings":"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"}
@@ -1,18 +0,0 @@
1
- import { type LifecycleBlock, type LifecycleSimulation, type LifecycleTransaction, type SimulateLaunchPlanOptions } from "./types.js";
2
- /** Internal, operation-local fee envelope for the already matched immediate step. */
3
- export type NextTransactionEnvelope = Readonly<{
4
- gas: bigint;
5
- gasPrice: bigint;
6
- }>;
7
- /** Compute-only sizing observations; native poster charges are never included. */
8
- export type GasSizingHints = ReadonlyMap<string, bigint>;
9
- export type PreparedLaunchSimulation = ((transactions: readonly LifecycleTransaction[], nextEnvelope?: NextTransactionEnvelope) => Promise<LifecycleSimulation>) & {
10
- /** Unadmitted diagnostic results only; final measurement validates exact calldata. */
11
- measure(transactions: readonly LifecycleTransaction[]): Promise<LifecycleSimulation>;
12
- close(): void;
13
- };
14
- /** Internal continuation owned by one SDK read invocation. Only its positive
15
- * capability proof is reused; every candidate executes its entire economic sequence. */
16
- export declare function prepareLaunchSimulation(options: SimulateLaunchPlanOptions, block: LifecycleBlock, hasTransactions?: boolean, reviewedEnvelope?: NextTransactionEnvelope, selectedGasPrice?: bigint, sizing?: GasSizingHints): PreparedLaunchSimulation;
17
- export declare function simulateLaunchTransactions(options: SimulateLaunchPlanOptions, transactions: readonly LifecycleTransaction[], pinnedBlock?: LifecycleBlock, nextEnvelope?: NextTransactionEnvelope, sizing?: GasSizingHints): Promise<LifecycleSimulation>;
18
- //# sourceMappingURL=simulation.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/lifecycle/simulation.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwD,KAAK,cAAc,EAAoF,KAAK,mBAAmB,EAAgC,KAAK,oBAAoB,EAAoD,KAAK,yBAAyB,EAAE,MAAM,YAAY,CAAC;AA+S9V,qFAAqF;AACrF,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAClF,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACzD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,EAAE,YAAY,CAAC,EAAE,uBAAuB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG;IACjK,sFAAsF;IACtF,OAAO,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrF,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAQF;wFACwF;AACxF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,yBAAyB,EAAE,KAAK,EAAE,cAAc,EAAE,eAAe,UAAO,EAAE,gBAAgB,CAAC,EAAE,uBAAuB,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,wBAAwB,CAgHnP;AAED,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,yBAAyB,EAAE,YAAY,EAAE,SAAS,oBAAoB,EAAE,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,uBAAuB,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAO/P"}