@lifi/perps-sdk 0.0.0-preview-142c251 → 0.0.0-preview-1edeff0

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 (198) hide show
  1. package/README.md +42 -2
  2. package/dist/cjs/client/PerpsClient.d.ts +10 -5
  3. package/dist/cjs/client/PerpsClient.d.ts.map +1 -1
  4. package/dist/cjs/client/PerpsClient.js +89 -55
  5. package/dist/cjs/client/PerpsClient.js.map +1 -1
  6. package/dist/cjs/index.d.ts +13 -8
  7. package/dist/cjs/index.d.ts.map +1 -1
  8. package/dist/cjs/index.js +20 -5
  9. package/dist/cjs/index.js.map +1 -1
  10. package/dist/cjs/registry/marketRegistry.d.ts +3 -0
  11. package/dist/cjs/registry/marketRegistry.d.ts.map +1 -1
  12. package/dist/cjs/registry/marketRegistry.js +16 -1
  13. package/dist/cjs/registry/marketRegistry.js.map +1 -1
  14. package/dist/cjs/registry/referenceDataRegistry.d.ts.map +1 -1
  15. package/dist/cjs/registry/referenceDataRegistry.js +0 -1
  16. package/dist/cjs/registry/referenceDataRegistry.js.map +1 -1
  17. package/dist/cjs/services/getGasRecommendation.d.ts +9 -0
  18. package/dist/cjs/services/getGasRecommendation.d.ts.map +1 -0
  19. package/dist/cjs/services/getGasRecommendation.js +10 -0
  20. package/dist/cjs/services/getGasRecommendation.js.map +1 -0
  21. package/dist/cjs/services/getMarket.d.ts.map +1 -1
  22. package/dist/cjs/services/getMarket.js +2 -1
  23. package/dist/cjs/services/getMarket.js.map +1 -1
  24. package/dist/cjs/services/getMarkets.d.ts.map +1 -1
  25. package/dist/cjs/services/getMarkets.js +3 -1
  26. package/dist/cjs/services/getMarkets.js.map +1 -1
  27. package/dist/cjs/types/api.d.ts +4 -0
  28. package/dist/cjs/types/api.d.ts.map +1 -1
  29. package/dist/cjs/types/config.d.ts.map +1 -1
  30. package/dist/cjs/types/deposit.d.ts +25 -0
  31. package/dist/cjs/types/deposit.d.ts.map +1 -0
  32. package/dist/cjs/types/deposit.js +3 -0
  33. package/dist/cjs/types/deposit.js.map +1 -0
  34. package/dist/cjs/types/provider.d.ts +16 -5
  35. package/dist/cjs/types/provider.d.ts.map +1 -1
  36. package/dist/cjs/utils/accountSummary.d.ts.map +1 -1
  37. package/dist/cjs/utils/accountSummary.js +10 -4
  38. package/dist/cjs/utils/accountSummary.js.map +1 -1
  39. package/dist/cjs/utils/depositAssets.d.ts +8 -0
  40. package/dist/cjs/utils/depositAssets.d.ts.map +1 -0
  41. package/dist/cjs/utils/depositAssets.js +36 -0
  42. package/dist/cjs/utils/depositAssets.js.map +1 -0
  43. package/dist/cjs/utils/explorer.d.ts +1 -0
  44. package/dist/cjs/utils/explorer.d.ts.map +1 -1
  45. package/dist/cjs/utils/explorer.js +7 -3
  46. package/dist/cjs/utils/explorer.js.map +1 -1
  47. package/dist/cjs/utils/format.d.ts +3 -0
  48. package/dist/cjs/utils/format.d.ts.map +1 -1
  49. package/dist/cjs/utils/format.js +31 -24
  50. package/dist/cjs/utils/format.js.map +1 -1
  51. package/dist/cjs/utils/scaleToInteger.d.ts +3 -0
  52. package/dist/cjs/utils/scaleToInteger.d.ts.map +1 -0
  53. package/dist/cjs/utils/scaleToInteger.js +30 -0
  54. package/dist/cjs/utils/scaleToInteger.js.map +1 -0
  55. package/dist/cjs/utils/setupActions.d.ts +3 -0
  56. package/dist/cjs/utils/setupActions.d.ts.map +1 -0
  57. package/dist/cjs/utils/setupActions.js +8 -0
  58. package/dist/cjs/utils/setupActions.js.map +1 -0
  59. package/dist/cjs/version.d.ts +1 -1
  60. package/dist/cjs/version.js +1 -1
  61. package/dist/esm/client/PerpsClient.d.ts +41 -14
  62. package/dist/esm/client/PerpsClient.d.ts.map +1 -1
  63. package/dist/esm/client/PerpsClient.js +128 -73
  64. package/dist/esm/client/PerpsClient.js.map +1 -1
  65. package/dist/esm/index.d.ts +14 -9
  66. package/dist/esm/index.d.ts.map +1 -1
  67. package/dist/esm/index.js +8 -5
  68. package/dist/esm/index.js.map +1 -1
  69. package/dist/esm/registry/marketRegistry.d.ts +15 -2
  70. package/dist/esm/registry/marketRegistry.d.ts.map +1 -1
  71. package/dist/esm/registry/marketRegistry.js +26 -2
  72. package/dist/esm/registry/marketRegistry.js.map +1 -1
  73. package/dist/esm/registry/referenceDataRegistry.d.ts +2 -1
  74. package/dist/esm/registry/referenceDataRegistry.d.ts.map +1 -1
  75. package/dist/esm/registry/referenceDataRegistry.js +2 -2
  76. package/dist/esm/registry/referenceDataRegistry.js.map +1 -1
  77. package/dist/esm/services/getGasRecommendation.d.ts +31 -0
  78. package/dist/esm/services/getGasRecommendation.d.ts.map +1 -0
  79. package/dist/esm/services/getGasRecommendation.js +22 -0
  80. package/dist/esm/services/getGasRecommendation.js.map +1 -0
  81. package/dist/esm/services/getMarket.d.ts +5 -4
  82. package/dist/esm/services/getMarket.d.ts.map +1 -1
  83. package/dist/esm/services/getMarket.js +7 -5
  84. package/dist/esm/services/getMarket.js.map +1 -1
  85. package/dist/esm/services/getMarkets.d.ts +6 -3
  86. package/dist/esm/services/getMarkets.d.ts.map +1 -1
  87. package/dist/esm/services/getMarkets.js +9 -4
  88. package/dist/esm/services/getMarkets.js.map +1 -1
  89. package/dist/esm/types/api.d.ts +9 -0
  90. package/dist/esm/types/api.d.ts.map +1 -1
  91. package/dist/esm/types/config.d.ts +4 -1
  92. package/dist/esm/types/config.d.ts.map +1 -1
  93. package/dist/esm/types/deposit.d.ts +68 -0
  94. package/dist/esm/types/deposit.d.ts.map +1 -0
  95. package/dist/esm/types/deposit.js +2 -0
  96. package/dist/esm/types/deposit.js.map +1 -0
  97. package/dist/esm/types/provider.d.ts +53 -17
  98. package/dist/esm/types/provider.d.ts.map +1 -1
  99. package/dist/esm/utils/accountSummary.d.ts.map +1 -1
  100. package/dist/esm/utils/accountSummary.js +13 -4
  101. package/dist/esm/utils/accountSummary.js.map +1 -1
  102. package/dist/esm/utils/depositAssets.d.ts +46 -0
  103. package/dist/esm/utils/depositAssets.d.ts.map +1 -0
  104. package/dist/esm/utils/depositAssets.js +71 -0
  105. package/dist/esm/utils/depositAssets.js.map +1 -0
  106. package/dist/esm/utils/explorer.d.ts +10 -0
  107. package/dist/esm/utils/explorer.d.ts.map +1 -1
  108. package/dist/esm/utils/explorer.js +16 -4
  109. package/dist/esm/utils/explorer.js.map +1 -1
  110. package/dist/esm/utils/format.d.ts +22 -0
  111. package/dist/esm/utils/format.d.ts.map +1 -1
  112. package/dist/esm/utils/format.js +57 -27
  113. package/dist/esm/utils/format.js.map +1 -1
  114. package/dist/esm/utils/scaleToInteger.d.ts +22 -0
  115. package/dist/esm/utils/scaleToInteger.d.ts.map +1 -0
  116. package/dist/esm/utils/scaleToInteger.js +34 -0
  117. package/dist/esm/utils/scaleToInteger.js.map +1 -0
  118. package/dist/esm/utils/setupActions.d.ts +17 -0
  119. package/dist/esm/utils/setupActions.d.ts.map +1 -0
  120. package/dist/esm/utils/setupActions.js +19 -0
  121. package/dist/esm/utils/setupActions.js.map +1 -0
  122. package/dist/esm/version.d.ts +1 -1
  123. package/dist/esm/version.js +1 -1
  124. package/dist/types/client/PerpsClient.d.ts +41 -14
  125. package/dist/types/client/PerpsClient.d.ts.map +1 -1
  126. package/dist/types/index.d.ts +14 -9
  127. package/dist/types/index.d.ts.map +1 -1
  128. package/dist/types/registry/marketRegistry.d.ts +15 -2
  129. package/dist/types/registry/marketRegistry.d.ts.map +1 -1
  130. package/dist/types/registry/referenceDataRegistry.d.ts +2 -1
  131. package/dist/types/registry/referenceDataRegistry.d.ts.map +1 -1
  132. package/dist/types/services/getGasRecommendation.d.ts +31 -0
  133. package/dist/types/services/getGasRecommendation.d.ts.map +1 -0
  134. package/dist/types/services/getMarket.d.ts +5 -4
  135. package/dist/types/services/getMarket.d.ts.map +1 -1
  136. package/dist/types/services/getMarkets.d.ts +6 -3
  137. package/dist/types/services/getMarkets.d.ts.map +1 -1
  138. package/dist/types/types/api.d.ts +9 -0
  139. package/dist/types/types/api.d.ts.map +1 -1
  140. package/dist/types/types/config.d.ts +4 -1
  141. package/dist/types/types/config.d.ts.map +1 -1
  142. package/dist/types/types/deposit.d.ts +68 -0
  143. package/dist/types/types/deposit.d.ts.map +1 -0
  144. package/dist/types/types/provider.d.ts +53 -17
  145. package/dist/types/types/provider.d.ts.map +1 -1
  146. package/dist/types/utils/accountSummary.d.ts.map +1 -1
  147. package/dist/types/utils/depositAssets.d.ts +46 -0
  148. package/dist/types/utils/depositAssets.d.ts.map +1 -0
  149. package/dist/types/utils/explorer.d.ts +10 -0
  150. package/dist/types/utils/explorer.d.ts.map +1 -1
  151. package/dist/types/utils/format.d.ts +22 -0
  152. package/dist/types/utils/format.d.ts.map +1 -1
  153. package/dist/types/utils/scaleToInteger.d.ts +22 -0
  154. package/dist/types/utils/scaleToInteger.d.ts.map +1 -0
  155. package/dist/types/utils/setupActions.d.ts +17 -0
  156. package/dist/types/utils/setupActions.d.ts.map +1 -0
  157. package/dist/types/version.d.ts +1 -1
  158. package/package.json +4 -3
  159. package/src/client/PerpsClient.ts +206 -106
  160. package/src/index.ts +34 -8
  161. package/src/registry/marketRegistry.ts +33 -2
  162. package/src/registry/referenceDataRegistry.ts +2 -2
  163. package/src/services/getGasRecommendation.ts +45 -0
  164. package/src/services/getMarket.ts +7 -5
  165. package/src/services/getMarkets.ts +14 -4
  166. package/src/types/api.ts +10 -0
  167. package/src/types/config.ts +4 -1
  168. package/src/types/deposit.ts +75 -0
  169. package/src/types/provider.ts +56 -25
  170. package/src/utils/accountSummary.ts +18 -5
  171. package/src/utils/depositAssets.ts +77 -0
  172. package/src/utils/explorer.ts +20 -4
  173. package/src/utils/format.ts +108 -28
  174. package/src/utils/scaleToInteger.ts +56 -0
  175. package/src/utils/setupActions.ts +24 -0
  176. package/src/version.ts +1 -1
  177. package/dist/cjs/client/clientLog.d.ts +0 -4
  178. package/dist/cjs/client/clientLog.d.ts.map +0 -1
  179. package/dist/cjs/client/clientLog.js +0 -9
  180. package/dist/cjs/client/clientLog.js.map +0 -1
  181. package/dist/cjs/utils/depositChain.d.ts +0 -6
  182. package/dist/cjs/utils/depositChain.d.ts.map +0 -1
  183. package/dist/cjs/utils/depositChain.js +0 -13
  184. package/dist/cjs/utils/depositChain.js.map +0 -1
  185. package/dist/esm/client/clientLog.d.ts +0 -16
  186. package/dist/esm/client/clientLog.d.ts.map +0 -1
  187. package/dist/esm/client/clientLog.js +0 -18
  188. package/dist/esm/client/clientLog.js.map +0 -1
  189. package/dist/esm/utils/depositChain.d.ts +0 -27
  190. package/dist/esm/utils/depositChain.d.ts.map +0 -1
  191. package/dist/esm/utils/depositChain.js +0 -23
  192. package/dist/esm/utils/depositChain.js.map +0 -1
  193. package/dist/types/client/clientLog.d.ts +0 -16
  194. package/dist/types/client/clientLog.d.ts.map +0 -1
  195. package/dist/types/utils/depositChain.d.ts +0 -27
  196. package/dist/types/utils/depositChain.d.ts.map +0 -1
  197. package/src/client/clientLog.ts +0 -20
  198. package/src/utils/depositChain.ts +0 -38
@@ -2,19 +2,22 @@ import type {
2
2
  AccountResponse,
3
3
  AccountSummary,
4
4
  ActionParamsMap,
5
+ ActionResult,
5
6
  ActionStep,
6
7
  CreateActionResponse,
7
- DepositAsset,
8
- DepositMethod,
9
8
  ExecuteActionResponse,
10
9
  MarketRef,
11
10
  Position,
12
11
  Provider,
13
12
  ProviderAction,
14
- RestCallSignedActionStep,
15
13
  SignedActionStep,
16
14
  } from '@lifi/perps-types'
17
- import { ActionType, PerpsErrorCode, SigningMethod } from '@lifi/perps-types'
15
+ import {
16
+ ActionType,
17
+ PerpsErrorCode,
18
+ PerpsSigner,
19
+ SigningMethod,
20
+ } from '@lifi/perps-types'
18
21
  import type { Address } from 'viem'
19
22
  import { PerpsError } from '../errors/PerpsError.js'
20
23
  import { createAction } from '../services/createAction.js'
@@ -27,6 +30,7 @@ import type {
27
30
  ExecuteProviderSetupParams,
28
31
  ExecuteProviderSetupResult,
29
32
  GetAccountResult,
33
+ GetDepositFlowParams,
30
34
  GetSetupParams,
31
35
  ModifyOrdersParams,
32
36
  PerpsClientOptions,
@@ -37,17 +41,18 @@ import type {
37
41
  WithdrawParams,
38
42
  } from '../types/api.js'
39
43
  import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
44
+ import type { DepositFlow } from '../types/deposit.js'
40
45
  import type {
41
46
  ActionSignerContribution,
42
47
  PerpsProvider,
43
48
  PerpsSDKClient,
49
+ SignActionProgress,
44
50
  SignActionsContext,
45
51
  } from '../types/provider.js'
46
52
  import {
47
53
  switchSigningChain,
48
54
  userEip712TargetChainId,
49
55
  } from '../utils/switchChain.js'
50
- import { clientLog } from './clientLog.js'
51
56
  import { createPerpsClient } from './createPerpsClient.js'
52
57
  import { requireProvider as resolveProvider } from './requireProvider.js'
53
58
 
@@ -198,7 +203,8 @@ export class PerpsClient {
198
203
  provider: string,
199
204
  address: Address,
200
205
  descriptor: ProviderAction,
201
- actions: ActionStep[]
206
+ actions: ActionStep[],
207
+ onProgress?: (progress: SignActionProgress) => void
202
208
  ): Promise<SignedActionStep[]> {
203
209
  const plugin = this.requireProvider(provider)
204
210
  if (typeof plugin.signActions !== 'function') {
@@ -213,10 +219,26 @@ export class PerpsClient {
213
219
  descriptor.signingMethod,
214
220
  actions,
215
221
  address,
216
- this.buildSignActionsContext(descriptor, userWallet)
222
+ this.buildSignActionsContext(descriptor, userWallet, onProgress)
217
223
  )
218
224
  }
219
225
 
226
+ /**
227
+ * Let the plugin observe `/executeAction` per-step results before the core
228
+ * surfaces failures — e.g. to evict a locally stored credential the venue
229
+ * rejected.
230
+ */
231
+ private async notifyExecuteResults(
232
+ provider: string,
233
+ address: Address,
234
+ results: ActionResult[]
235
+ ): Promise<void> {
236
+ const plugin = this.requireProvider(provider)
237
+ if (typeof plugin.onExecuteResults === 'function') {
238
+ await plugin.onExecuteResults(address, results)
239
+ }
240
+ }
241
+
220
242
  /**
221
243
  * Resolve the wallet that signs `actions`. For a USER-signed EIP-712 batch,
222
244
  * switch the configured wallet to the action's target chain via the
@@ -258,9 +280,13 @@ export class PerpsClient {
258
280
  */
259
281
  private buildSignActionsContext(
260
282
  descriptor: ProviderAction,
261
- userWallet?: PerpsClientSigner
283
+ userWallet?: PerpsClientSigner,
284
+ onProgress?: (progress: SignActionProgress) => void
262
285
  ): SignActionsContext {
263
286
  const ctx: SignActionsContext = { signers: descriptor.signers }
287
+ if (onProgress !== undefined) {
288
+ ctx.onProgress = onProgress
289
+ }
264
290
  const wallet = userWallet ?? this.sdkClient.userWallet
265
291
  if (wallet !== undefined) {
266
292
  ctx.userWallet = wallet
@@ -389,21 +415,20 @@ export class PerpsClient {
389
415
  }
390
416
 
391
417
  /**
392
- * Resolve provider-owned funding methods for a wallet address and source
393
- * asset. Providers that do not implement discovery return an empty list.
418
+ * The deposit flow for `params.address` at `params.provider`, delegated to the
419
+ * provider plugin — every deposit decision (the collateral destination, the
420
+ * account-opening pipeline, an outstanding setup gate) is venue-owned.
394
421
  *
422
+ * @returns `undefined` when the registered plugin declares no deposit flow.
423
+ * @throws {PerpsError} When the provider plugin is not registered, or the
424
+ * plugin's flow resolution fails.
395
425
  * @public
396
426
  */
397
- async getProviderDepositMethods(
398
- provider: string,
399
- address: Address,
400
- sourceAsset: DepositAsset
401
- ): Promise<DepositMethod[]> {
402
- const plugin = this.requireProvider(provider)
403
- if (typeof plugin.getDepositMethods !== 'function') {
404
- return []
405
- }
406
- return plugin.getDepositMethods({ address, sourceAsset })
427
+ async getDepositFlow(
428
+ params: GetDepositFlowParams
429
+ ): Promise<DepositFlow | undefined> {
430
+ const plugin = this.requireProvider(params.provider)
431
+ return plugin.getDepositFlow?.({ address: params.address })
407
432
  }
408
433
 
409
434
  /**
@@ -419,16 +444,42 @@ export class PerpsClient {
419
444
  async checkSetup(params: GetSetupParams): Promise<ProviderSetup> {
420
445
  const { provider, address } = params
421
446
 
447
+ const metadata = await this.getProviderMetadata(provider)
448
+ const hasSiweSetup = metadata.setup.some(
449
+ (descriptor) => descriptor.signingMethod === SigningMethod.SIWE
450
+ )
451
+
422
452
  // Gate on existence first: an unfunded account has no setup, so short-circuit
423
453
  // before any createAction round-trip and let the consumer prompt a deposit.
424
- if (!(await this.accountExists(provider, address))) {
454
+ //
455
+ // SIWE-first providers (Ondo) are the exception: they cannot reliably probe
456
+ // account existence before the user signs in, so setup must still stage.
457
+ if (!hasSiweSetup && !(await this.accountExists(provider, address))) {
425
458
  return { accountExists: false, setup: [], isReady: false }
426
459
  }
427
460
 
461
+ const satisfiedSetup = await this.resolveSatisfiedSetup(provider, address)
462
+ const pendingSetup = metadata.setup.filter(
463
+ (descriptor) => !satisfiedSetup.has(descriptor.type)
464
+ )
465
+
466
+ const hiddenSetup = await this.resolveInternalSetup(
467
+ provider,
468
+ address,
469
+ pendingSetup
470
+ )
471
+ const visibleSetup = pendingSetup.filter(
472
+ (descriptor) => !hiddenSetup.has(descriptor.type)
473
+ )
474
+
428
475
  // The backend filters already-satisfied setup actions and returns typed
429
476
  // data for those still outstanding; each plugin contributes its own
430
477
  // signer-bearing request fields.
431
- const { actions } = await this.buildProviderSetup({ provider, address })
478
+ const actions = await this.buildProviderSetupActions(
479
+ provider,
480
+ address,
481
+ visibleSetup
482
+ )
432
483
 
433
484
  return {
434
485
  accountExists: true,
@@ -438,23 +489,109 @@ export class PerpsClient {
438
489
  }
439
490
 
440
491
  /**
441
- * Build the unsigned setup `ActionStep`s still outstanding for an account,
442
- * ordered by descriptor `sequence`. The backend filters already-satisfied
443
- * setup; each plugin contributes its own signer-bearing request fields and
444
- * any local-state params (e.g. Lighter's known pubkey).
445
- *
446
- * @public
492
+ * Resolve setup descriptors already satisfied from the provider's own typed
493
+ * account config projection. This catches client-held auth state (e.g. Ondo
494
+ * SIWE/JWT) that the backend cannot observe.
447
495
  */
448
- async buildProviderSetup(
449
- params: BuildProviderSetupParams
450
- ): Promise<CreateActionResponse> {
451
- const { provider, address } = params
452
-
496
+ private async resolveSatisfiedSetup(
497
+ provider: string,
498
+ address: Address
499
+ ): Promise<Set<ActionType>> {
453
500
  const metadata = await this.getProviderMetadata(provider)
454
- const orderedSetup = [...metadata.setup].sort(
501
+ const plugin = this.sdkClient.getProvider(provider)
502
+ if (!plugin || typeof plugin.getAccount !== 'function') {
503
+ return new Set()
504
+ }
505
+ const account = await plugin.getAccount({ address })
506
+ const settings = plugin.projectConfig(
507
+ account.config,
508
+ metadata.setup,
509
+ metadata.options
510
+ )
511
+ const setupTypes = new Set(
512
+ metadata.setup.map((descriptor) => descriptor.type)
513
+ )
514
+ return new Set(
515
+ settings
516
+ .filter((setting) => setting.satisfied && setupTypes.has(setting.type))
517
+ .map((setting) => setting.type)
518
+ )
519
+ }
520
+
521
+ /**
522
+ * Drain the pending setup steps the provider declares as internal via
523
+ * `PerpsProviderPlugin.internalSetupActions`, returning the set of action
524
+ * types to omit from the caller-facing setup list. Each such step is built,
525
+ * signed, and executed in place with the provider's own credentials. A
526
+ * descriptor whose `signers` include {@link PerpsSigner.USER} is left to
527
+ * render as a normal step. A drain failure is swallowed so it never blocks
528
+ * setup — the step stays unsatisfied and is retried on a later `checkSetup`.
529
+ */
530
+ private async resolveInternalSetup(
531
+ provider: string,
532
+ address: Address,
533
+ pending: ProviderAction[]
534
+ ): Promise<Set<ActionType>> {
535
+ const plugin = this.sdkClient.getProvider(provider)
536
+ const internal = plugin?.internalSetupActions
537
+ if (!internal || internal.length === 0) {
538
+ return new Set()
539
+ }
540
+ const internalTypes = new Set(internal)
541
+ const hidden = new Set<ActionType>()
542
+ for (const descriptor of pending) {
543
+ if (
544
+ !internalTypes.has(descriptor.type) ||
545
+ descriptor.signers.includes(PerpsSigner.USER)
546
+ ) {
547
+ continue
548
+ }
549
+ hidden.add(descriptor.type)
550
+ try {
551
+ const steps = await this.buildProviderSetupActions(provider, address, [
552
+ descriptor,
553
+ ])
554
+ for (const step of steps) {
555
+ const signed = await this.signProviderSetupAction(
556
+ provider,
557
+ address,
558
+ step
559
+ )
560
+ if (signed !== undefined) {
561
+ await this.executeProviderSetup({
562
+ provider,
563
+ address,
564
+ setup: [step],
565
+ signedActions: [signed],
566
+ })
567
+ }
568
+ }
569
+ } catch (error) {
570
+ console.debug(
571
+ `[perps-sdk] internal setup step '${descriptor.type}' for '${provider}' did not complete; will retry on the next checkSetup.`,
572
+ error
573
+ )
574
+ }
575
+ }
576
+ return hidden
577
+ }
578
+
579
+ /**
580
+ * Build unsigned setup steps for the supplied descriptor subset, preserving
581
+ * provider sequence order with SIWE descriptors prioritized.
582
+ */
583
+ private async buildProviderSetupActions(
584
+ provider: string,
585
+ address: Address,
586
+ descriptors: ProviderAction[]
587
+ ): Promise<ActionStep[]> {
588
+ const setupPriority = (descriptor: ProviderAction): number =>
589
+ descriptor.signingMethod === SigningMethod.SIWE ? 0 : 1
590
+ const orderedSetup = [...descriptors].sort(
455
591
  (a, b) =>
592
+ setupPriority(a) - setupPriority(b) ||
456
593
  (a.sequence ?? Number.MAX_SAFE_INTEGER) -
457
- (b.sequence ?? Number.MAX_SAFE_INTEGER)
594
+ (b.sequence ?? Number.MAX_SAFE_INTEGER)
458
595
  )
459
596
 
460
597
  const plugin = this.sdkClient.getProvider(provider)
@@ -479,7 +616,29 @@ export class PerpsClient {
479
616
  allActions.push(...actions)
480
617
  }
481
618
 
482
- return { actions: allActions }
619
+ return allActions
620
+ }
621
+
622
+ /**
623
+ * Build the unsigned setup `ActionStep`s still outstanding for an account,
624
+ * ordered by descriptor `sequence`. The backend filters already-satisfied
625
+ * setup; each plugin contributes its own signer-bearing request fields and
626
+ * any local-state params (e.g. Lighter's known pubkey).
627
+ *
628
+ * @public
629
+ */
630
+ async buildProviderSetup(
631
+ params: BuildProviderSetupParams
632
+ ): Promise<CreateActionResponse> {
633
+ const { provider, address } = params
634
+
635
+ const metadata = await this.getProviderMetadata(provider)
636
+ const actions = await this.buildProviderSetupActions(
637
+ provider,
638
+ address,
639
+ metadata.setup
640
+ )
641
+ return { actions }
483
642
  }
484
643
 
485
644
  /**
@@ -516,6 +675,8 @@ export class PerpsClient {
516
675
  actions: signedActions,
517
676
  })
518
677
 
678
+ await this.notifyExecuteResults(provider, address, results.results)
679
+
519
680
  const failure = results.results.find((r) => !r.success)
520
681
  if (failure) {
521
682
  throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error)
@@ -754,8 +915,11 @@ export class PerpsClient {
754
915
  address: Address
755
916
  action: T
756
917
  params: ActionParamsMap[T]
918
+ /** Progress sink for on-chain legs (e.g. a native deposit's approve then
919
+ * deposit); called as each leg is submitted and confirmed. */
920
+ onProgress?: (progress: SignActionProgress) => void
757
921
  }): Promise<ExecuteActionResponse> {
758
- const { provider, address, action } = params
922
+ const { provider, address, action, onProgress } = params
759
923
  const metadata = await this.getProviderMetadata(provider)
760
924
  const descriptor = findActionDescriptor(metadata, action)
761
925
 
@@ -777,19 +941,10 @@ export class PerpsClient {
777
941
  provider,
778
942
  address,
779
943
  descriptor,
780
- actions
944
+ actions,
945
+ onProgress
781
946
  )
782
947
 
783
- if (descriptor.signingMethod === SigningMethod.AUTH_TOKEN) {
784
- return this.executeAuthTokenActions(
785
- provider,
786
- address,
787
- signerAddress ?? address,
788
- action,
789
- signedActions
790
- )
791
- }
792
-
793
948
  // A plugin may execute an action entirely client-side (e.g. Lighter's
794
949
  // token-authenticated venue mutations), leaving no backend-bound step. With
795
950
  // nothing to submit, skip the `/executeAction` hop.
@@ -797,7 +952,7 @@ export class PerpsClient {
797
952
  return { results: [] }
798
953
  }
799
954
 
800
- return executeAction(this.sdkClient, {
955
+ const response = await executeAction(this.sdkClient, {
801
956
  provider,
802
957
  address,
803
958
  // The submitting account: the plugin-resolved signer (Hyperliquid's
@@ -806,64 +961,9 @@ export class PerpsClient {
806
961
  action,
807
962
  actions: signedActions,
808
963
  })
809
- }
810
-
811
- /**
812
- * The `AUTH_TOKEN` arm of {@link execute}: the venue call runs client-side
813
- * via the plugin's `executeRestCallActions` because the credential headers
814
- * must never transit the LI.FI backend. The venue's results are what the
815
- * caller gets; the backend `executeAction` submission that follows is
816
- * bookkeeping only, sent with `headers` stripped.
817
- */
818
- private async executeAuthTokenActions(
819
- provider: string,
820
- address: Address,
821
- signerAddress: Address,
822
- action: ActionType,
823
- signedActions: SignedActionStep[]
824
- ): Promise<ExecuteActionResponse> {
825
- const plugin = this.requireProvider(provider)
826
- if (typeof plugin.executeRestCallActions !== 'function') {
827
- throw new PerpsError(
828
- PerpsErrorCode.SDKError,
829
- `Provider '${provider}' does not implement executeRestCallActions ` +
830
- `for signingMethod 'authToken'.`
831
- )
832
- }
833
-
834
- const restCallSteps = signedActions.map(
835
- (step): RestCallSignedActionStep => {
836
- if (!('request' in step) || !('headers' in step)) {
837
- throw new PerpsError(
838
- PerpsErrorCode.SDKError,
839
- `Provider '${provider}' signed action '${step.action}' with a ` +
840
- `non-rest-call step for signingMethod 'authToken'.`
841
- )
842
- }
843
- return step
844
- }
845
- )
846
964
 
847
- const results = await plugin.executeRestCallActions(restCallSteps, address)
965
+ await this.notifyExecuteResults(provider, address, response.results)
848
966
 
849
- try {
850
- await executeAction(this.sdkClient, {
851
- provider,
852
- address,
853
- signerAddress,
854
- action,
855
- actions: restCallSteps.map((step) => ({
856
- action: step.action,
857
- request: step.request,
858
- headers: {},
859
- })),
860
- })
861
- } catch (error) {
862
- // The venue call already succeeded above — a failed bookkeeping
863
- // submission must not mask a landed order, so it is logged, not thrown.
864
- clientLog.bookkeepingFailure(provider, error)
865
- }
866
-
867
- return { results }
967
+ return response
868
968
  }
869
969
  }
package/src/index.ts CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  /**
5
5
  * `@lifi/perps-sdk` — the public entry point. Exports `createPerpsClient` and
6
- * `PerpsClient` (the primary API), the realtime `PerpsWsClient`, the pure
6
+ * `PerpsClient` (the primary API), the WebSocket `PerpsWsClient`, the pure
7
7
  * calculation/parsing/order helpers, and re-exports the shared `@lifi/perps-types`.
8
8
  *
9
9
  * @packageDocumentation
@@ -22,6 +22,7 @@ export { PerpsError } from './errors/PerpsError.js'
22
22
  export { AssetRegistry, getAssetRegistry } from './registry/assetRegistry.js'
23
23
  export {
24
24
  getMarketRegistry,
25
+ isActiveMarket,
25
26
  MarketRegistry,
26
27
  toMarketDisplay,
27
28
  } from './registry/marketRegistry.js'
@@ -38,6 +39,11 @@ export type { GetAssetsParams } from './services/getAssets.js'
38
39
  export { getAssets } from './services/getAssets.js'
39
40
  export type { GetFillsParams } from './services/getFills.js'
40
41
  export { getFills } from './services/getFills.js'
42
+ export type { GetGasRecommendationParams } from './services/getGasRecommendation.js'
43
+ export {
44
+ getGasRecommendation,
45
+ LIFI_API_URL,
46
+ } from './services/getGasRecommendation.js'
41
47
  export type { GetMarketParams } from './services/getMarket.js'
42
48
  export { getMarket } from './services/getMarket.js'
43
49
  export type { GetMarketsParams } from './services/getMarkets.js'
@@ -92,6 +98,7 @@ export type {
92
98
  BuildProviderSetupParams,
93
99
  CancelOrdersParams,
94
100
  GetAccountResult,
101
+ GetDepositFlowParams,
95
102
  GetSetupParams,
96
103
  ModifyOrdersParams,
97
104
  PerpsClientOptions,
@@ -112,6 +119,13 @@ export type {
112
119
  SDKRequestOptions,
113
120
  SwitchChainHook,
114
121
  } from './types/config.js'
122
+ export type {
123
+ DeclaredDepositAsset,
124
+ DepositFlow,
125
+ DepositFlowFirstDepositPipeline,
126
+ DepositFlowLifiSwap,
127
+ DepositFlowSetupRequired,
128
+ } from './types/deposit.js'
115
129
  export type {
116
130
  ActionSignerContribution,
117
131
  LiquidationEstimateParams,
@@ -121,13 +135,14 @@ export type {
121
135
  ProviderAccountExistsParams,
122
136
  ProviderGetAccountParams,
123
137
  ProviderGetActivityParams,
124
- ProviderGetDepositMethodsParams,
138
+ ProviderGetDepositFlowParams,
125
139
  ProviderGetFillsParams,
126
140
  ProviderGetOrderParams,
127
141
  ProviderGetOrdersParams,
128
142
  ProviderGetPositionsParams,
129
143
  ProviderGetQuoteParams,
130
144
  QuoteListener,
145
+ SignActionProgress,
131
146
  SignActionsContext,
132
147
  } from './types/provider.js'
133
148
  export {
@@ -153,16 +168,24 @@ export {
153
168
  removableMargin,
154
169
  walkOrderbook,
155
170
  } from './utils/calculations.js'
156
- export type { DepositProviderKey } from './utils/depositChain.js'
157
171
  export {
158
- LIFI_DEPOSIT_CHAIN_BY_PROVIDER,
159
- lifiDepositChainForProvider,
160
- } from './utils/depositChain.js'
161
- export { ExplorerChainId, explorerTxUrl } from './utils/explorer.js'
172
+ ETHEREUM_NATIVE_GAS,
173
+ ETHEREUM_USDC,
174
+ HYPERLIQUID_USDC,
175
+ LIGHTER_USDC,
176
+ ROBINHOOD_NATIVE_GAS,
177
+ ROBINHOOD_USDG,
178
+ } from './utils/depositAssets.js'
179
+ export {
180
+ ExplorerChainId,
181
+ explorerTxUrl,
182
+ explorerTxUrlFromBase,
183
+ } from './utils/explorer.js'
162
184
  export { classifyFillFromPosition } from './utils/fillClassification.js'
163
- export type { FormatOptions } from './utils/format.js'
185
+ export type { FormatOptions, RoundingMode } from './utils/format.js'
164
186
  export {
165
187
  formatCompactUsd,
188
+ formatNumber,
166
189
  formatPrice,
167
190
  formatSignedPercent,
168
191
  formatSignedUsd,
@@ -192,6 +215,9 @@ export {
192
215
  predictUnrealizedPnl,
193
216
  realizedPnlOnClose,
194
217
  } from './utils/positionMath.js'
218
+ export type { ScaleToIntegerPolicy } from './utils/scaleToInteger.js'
219
+ export { scaleToInteger } from './utils/scaleToInteger.js'
220
+ export { selectUserSetupActions } from './utils/setupActions.js'
195
221
  export {
196
222
  signTypedData,
197
223
  signTypedDataWithSigner,
@@ -23,10 +23,16 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
23
23
  return this.items
24
24
  }
25
25
 
26
+ /** The synced markets that are available for live and write operations. */
27
+ get activeMarkets(): readonly Market[] {
28
+ return this.items.filter(isActiveMarket)
29
+ }
30
+
26
31
  /**
27
32
  * Lookup by `Market.id`, throwing when the backend list does not know the
28
- * id. The list is the source of truth for every tradable market, so an id
29
- * the venue references but the backend does not know is a hard error —
33
+ * id. The list is the source of truth for enriched historical and live
34
+ * market metadata, so an id the venue references but the backend does not
35
+ * know is a hard error —
30
36
  * never a silent fallback to an unenriched stand-in.
31
37
  *
32
38
  * @throws {PerpsError} `MarketNotFound`.
@@ -44,6 +50,26 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
44
50
  return market
45
51
  }
46
52
 
53
+ /**
54
+ * Lookup a market for live or write use. Delisted markets remain resolvable
55
+ * through {@link require} for historical display mapping, but this method
56
+ * rejects them.
57
+ *
58
+ * @throws {PerpsError} `MarketNotFound` when the market is absent or delisted.
59
+ */
60
+ requireActive(marketId: string): Market {
61
+ const market = this.require(marketId)
62
+ if (!isActiveMarket(market)) {
63
+ const error = new PerpsError(
64
+ PerpsErrorCode.MarketNotFound,
65
+ `Market '${marketId}' is not available for live use`
66
+ )
67
+ error.tool = this.provider
68
+ throw error
69
+ }
70
+ return market
71
+ }
72
+
47
73
  protected fetchItems(): Promise<Market[]> {
48
74
  const url = buildUrl(`${this.client.config.apiUrl}/markets`, {
49
75
  provider: this.provider,
@@ -60,6 +86,10 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
60
86
 
61
87
  const registries = new WeakMap<PerpsSDKClient, Map<string, MarketRegistry>>()
62
88
 
89
+ /** A market is active unless the provider explicitly marks it delisted. */
90
+ export const isActiveMarket = (market: Market): boolean =>
91
+ market.isDelisted !== true
92
+
63
93
  /**
64
94
  * The stable {@link MarketRegistry} for `(client, provider)`.
65
95
  *
@@ -95,4 +125,5 @@ export const toMarketDisplay = (market: Market): MarketDisplay => ({
95
125
  categoryId: market.categoryId,
96
126
  baseAsset: market.baseAsset,
97
127
  quoteAsset: market.quoteAsset,
128
+ ...(market.isDelisted === undefined ? {} : { isDelisted: market.isDelisted }),
98
129
  })
@@ -7,7 +7,8 @@ import type { PerpsSDKClient } from '../types/provider.js'
7
7
  * NOT a cache: it holds no freshness policy of its own. Every {@link sync}
8
8
  * refetches through the HTTP layer, whose `cache-control` headers decide
9
9
  * whether the response comes from disk or the network. A lookup miss warns
10
- * once and returns `undefined`; the next {@link sync} reconciles the index.
10
+ * once per id and returns `undefined`; subsequent syncs reconcile the index
11
+ * without replaying the warning for an id that remains absent.
11
12
  *
12
13
  * @internal
13
14
  */
@@ -65,7 +66,6 @@ export abstract class ReferenceDataRegistry<T> {
65
66
  const items = await this.fetchItems()
66
67
  this.index = new Map(items.map((item) => [this.keyOf(item), item]))
67
68
  this.current = items
68
- this.warnedIds.clear()
69
69
  return items
70
70
  }
71
71
  }
@@ -0,0 +1,45 @@
1
+ import type { GasRecommendationResponse } from '@lifi/types'
2
+ import { request } from '../transport/request.js'
3
+ import type { SDKRequestOptions } from '../types/config.js'
4
+ import type { PerpsSDKClient } from '../types/provider.js'
5
+
6
+ /**
7
+ * LI.FI API base URL for reads the user's client makes directly, without the
8
+ * perps backend in the path.
9
+ *
10
+ * @public
11
+ */
12
+ export const LIFI_API_URL = 'https://li.quest/v1'
13
+
14
+ /**
15
+ * Parameters for {@link getGasRecommendation}.
16
+ *
17
+ * @public
18
+ */
19
+ export interface GetGasRecommendationParams {
20
+ /** Chain to hold native gas on — a `firstDepositPipeline` flow's `chainId`. */
21
+ chainId: number
22
+ }
23
+
24
+ /**
25
+ * How much native gas LI.FI suggests holding on `params.chainId` to transact
26
+ * there, for seeding the gas leg of a first-deposit pipeline. Read straight
27
+ * from the LI.FI API by the user's client.
28
+ *
29
+ * @returns The suggestion, with `available: false` and no amounts on a chain
30
+ * LI.FI cannot source gas for.
31
+ * @throws {PerpsError} On API error responses, or network/parsing errors.
32
+ * @public
33
+ */
34
+ export async function getGasRecommendation(
35
+ client: PerpsSDKClient,
36
+ params: GetGasRecommendationParams,
37
+ options?: SDKRequestOptions
38
+ ): Promise<GasRecommendationResponse> {
39
+ return request<GasRecommendationResponse>(
40
+ client.config,
41
+ `${LIFI_API_URL}/gas/suggestion/${params.chainId}`,
42
+ {},
43
+ options
44
+ )
45
+ }