@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
@@ -1,6 +1,7 @@
1
1
  import type { Market, MarketsResponse } from '@lifi/perps-types'
2
2
  import { PerpsErrorCode } from '@lifi/perps-types'
3
3
  import { PerpsError } from '../errors/PerpsError.js'
4
+ import { isActiveMarket } from '../registry/marketRegistry.js'
4
5
  import { buildUrl, request } from '../transport/request.js'
5
6
  import type { SDKRequestOptions } from '../types/config.js'
6
7
  import type { PerpsSDKClient } from '../types/provider.js'
@@ -21,10 +22,11 @@ export interface GetMarketParams {
21
22
  }
22
23
 
23
24
  /**
24
- * Get a specific market by its opaque marketId. Requests the single market
25
- * from the backend `/markets` route (filtered by `marketIds`) and returns the
26
- * first match; throws a `MarketNotFound` {@link PerpsError} both when the
27
- * backend responds 404 and when it responds 200 with an empty list, matching
25
+ * Get a specific active market by its opaque marketId. Requests the single
26
+ * market from the backend `/markets` route (filtered by `marketIds`) and
27
+ * returns the first active match; throws a `MarketNotFound` {@link PerpsError}
28
+ * when the backend responds 404, returns an empty list, or returns a
29
+ * delisted market, matching
28
30
  * `MarketRegistry.require`'s miss behaviour.
29
31
  *
30
32
  * @throws {PerpsError} On backend (e.g. 404 or empty match), network, or parsing errors.
@@ -52,7 +54,7 @@ export async function getMarket(
52
54
  options
53
55
  )
54
56
  const market = markets[0]
55
- if (market === undefined) {
57
+ if (market === undefined || !isActiveMarket(market)) {
56
58
  const error = new PerpsError(
57
59
  PerpsErrorCode.MarketNotFound,
58
60
  `No ${params.provider} market found for marketId '${params.marketId}'`
@@ -1,4 +1,5 @@
1
1
  import type { MarketsResponse } from '@lifi/perps-types'
2
+ import { isActiveMarket } from '../registry/marketRegistry.js'
2
3
  import { buildUrl, request } from '../transport/request.js'
3
4
  import type { SDKRequestOptions } from '../types/config.js'
4
5
  import type { PerpsSDKClient } from '../types/provider.js'
@@ -15,9 +16,12 @@ export interface GetMarketsParams {
15
16
  }
16
17
 
17
18
  /**
18
- * Get all available markets for a provider. Thin pass-through to the LI.FI
19
- * backend's Valkey-cached `/perps/markets` route — the canonical source of
20
- * public market data for widget consumers.
19
+ * Get active markets for a provider. Delisted entries remain available to
20
+ * internal registries for historical mapping, but are excluded from this
21
+ * public market-selection surface.
22
+ *
23
+ * Thin pass-through to the LI.FI backend's Valkey-cached `/perps/markets`
24
+ * route — the canonical source of public market data for widget consumers.
21
25
  *
22
26
  * @throws {PerpsError} On backend, network, or parsing errors.
23
27
  * @example
@@ -36,5 +40,11 @@ export async function getMarkets(
36
40
  provider: params.provider,
37
41
  marketIds: params.marketIds?.join(','),
38
42
  })
39
- return request<MarketsResponse>(client.config, url, {}, options)
43
+ const response = await request<MarketsResponse>(
44
+ client.config,
45
+ url,
46
+ {},
47
+ options
48
+ )
49
+ return { markets: response.markets.filter(isActiveMarket) }
40
50
  }
package/src/types/api.ts CHANGED
@@ -209,6 +209,16 @@ export interface GetSetupParams {
209
209
  address: Address
210
210
  }
211
211
 
212
+ /**
213
+ * Parameters for {@link PerpsClient.getDepositFlow}.
214
+ *
215
+ * @public
216
+ */
217
+ export interface GetDepositFlowParams {
218
+ provider: string
219
+ address: Address
220
+ }
221
+
212
222
  /**
213
223
  * Result from {@link PerpsClient.checkSetup}.
214
224
  *
@@ -70,7 +70,10 @@ export interface SDKRequestOptions {
70
70
  * getOrder, getActivity, getAccount). Create via
71
71
  * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
72
72
  * venue endpoints, never to the LI.FI backend — read-only by design
73
- * (8h max TTL, cannot authorize writes).
73
+ * (8h max TTL, cannot authorize writes). Each call routes to a single Lighter
74
+ * instance via `params.provider`, so this token scopes to that instance's
75
+ * venue; token caches are held per `lighterProvider()` instance and do not
76
+ * cross between instances.
74
77
  */
75
78
  lighterAuthToken?: string
76
79
  }
@@ -0,0 +1,75 @@
1
+ import type { ActionType } from '@lifi/perps-types'
2
+ import type { Address } from 'viem'
3
+
4
+ /**
5
+ * A token the SDK declares as part of a deposit flow, by full on-chain
6
+ * identity. Matched by `chainId` + `address`: a symbol is not identity — the
7
+ * Hyperliquid venue chain lists two `USDC` contracts with different decimals.
8
+ *
9
+ * @public
10
+ */
11
+ export interface DeclaredDepositAsset {
12
+ chainId: number
13
+ /** EIP-55 checksummed address; the zero address denotes the chain's native gas token. */
14
+ address: Address
15
+ decimals: number
16
+ }
17
+
18
+ /**
19
+ * Fund the account by swapping whatever the user holds into `destination`
20
+ * through the LI.FI surface. The source token is picked inside that surface, so
21
+ * it is not part of the flow; LI.FI routing owns whether that resolves to a
22
+ * same-chain swap or a bridge.
23
+ *
24
+ * @public
25
+ */
26
+ export interface DepositFlowLifiSwap {
27
+ kind: 'lifiSwap'
28
+ destination: DeclaredDepositAsset
29
+ /**
30
+ * Credited address when it is not the user's own — a venue-provisioned
31
+ * deposit address. Absent means the user's address receives the deposit.
32
+ */
33
+ toAddress?: Address
34
+ }
35
+
36
+ /**
37
+ * Fund an address that has no venue account yet. Collateral and the native gas
38
+ * to broadcast with are both needed on `chainId`, where the venue's
39
+ * {@link ActionType.DEPOSIT} action stages the on-chain legs that open the
40
+ * account.
41
+ *
42
+ * @public
43
+ */
44
+ export interface DepositFlowFirstDepositPipeline {
45
+ kind: 'firstDepositPipeline'
46
+ /** Chain the deposit legs broadcast on; the user's wallet must be switched to it. */
47
+ chainId: number
48
+ gasAsset: DeclaredDepositAsset
49
+ collateral: DeclaredDepositAsset
50
+ bridgeAction: ActionType.DEPOSIT
51
+ }
52
+
53
+ /**
54
+ * The venue cannot name a deposit destination until the listed setup actions
55
+ * are satisfied — Ondo provisions its deposit address behind a signed-in
56
+ * session.
57
+ *
58
+ * @public
59
+ */
60
+ export interface DepositFlowSetupRequired {
61
+ kind: 'setupRequired'
62
+ /** Outstanding `Provider.setup` action types, in the order they must be run. */
63
+ setup: ActionType[]
64
+ }
65
+
66
+ /**
67
+ * The single deposit flow a venue offers one address, resolved from the venue's
68
+ * account and setup state.
69
+ *
70
+ * @public
71
+ */
72
+ export type DepositFlow =
73
+ | DepositFlowLifiSwap
74
+ | DepositFlowFirstDepositPipeline
75
+ | DepositFlowSetupRequired
@@ -8,8 +8,6 @@ import type {
8
8
  ActionType,
9
9
  ActivitiesResponse,
10
10
  ActivityType,
11
- DepositAsset,
12
- DepositMethod,
13
11
  FillsResponse,
14
12
  Market,
15
13
  Order,
@@ -21,7 +19,6 @@ import type {
21
19
  ProviderAction,
22
20
  Quote,
23
21
  QuoteSide,
24
- RestCallSignedActionStep,
25
22
  SignedActionStep,
26
23
  SigningMethod,
27
24
  TradeType,
@@ -32,6 +29,7 @@ import type {
32
29
  PerpsClientSigner,
33
30
  SDKRequestOptions,
34
31
  } from './config.js'
32
+ import type { DepositFlow } from './deposit.js'
35
33
 
36
34
  /**
37
35
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -58,6 +56,27 @@ export interface PerpsSDKClient {
58
56
  *
59
57
  * @public
60
58
  */
59
+ /**
60
+ * Progress for one on-chain leg of an `EVM_TX` batch (e.g. a native deposit's
61
+ * `approve` then `deposit`). Emitted twice per leg: `submitted` once the wallet
62
+ * broadcasts and the hash is known, then `confirmed` once the receipt mines. A
63
+ * consumer can render a live per-transaction stepper from these.
64
+ *
65
+ * @public
66
+ */
67
+ export interface SignActionProgress {
68
+ /** 0-based index of this leg within the batch. */
69
+ index: number
70
+ /** Total legs in the batch. */
71
+ total: number
72
+ action: ActionType
73
+ /** Contract function the leg invokes, e.g. `"approve"` or the deposit method. */
74
+ functionName: string
75
+ chainId: number
76
+ status: 'submitted' | 'confirmed'
77
+ txHash: string
78
+ }
79
+
61
80
  export interface SignActionsContext {
62
81
  userWallet?: PerpsClientSigner
63
82
  /**
@@ -78,6 +97,13 @@ export interface SignActionsContext {
78
97
  * absent (local/private-key signer, or no hook).
79
98
  */
80
99
  switchToChain?: (chainId: number) => Promise<PerpsClientSigner>
100
+ /**
101
+ * Optional progress sink for on-chain legs. A plugin whose legs broadcast
102
+ * transactions (Lighter's `EVM_TX`) calls it as each leg is submitted and
103
+ * confirmed, so a consumer can show a live per-transaction stepper. Bound by
104
+ * core from the `onProgress` passed to {@link PerpsClient.execute}.
105
+ */
106
+ onProgress?: (progress: SignActionProgress) => void
81
107
  }
82
108
 
83
109
  /**
@@ -138,13 +164,12 @@ export interface ProviderAccountExistsParams {
138
164
  }
139
165
 
140
166
  /**
141
- * Read params for {@link PerpsProviderPlugin.getDepositMethods}.
167
+ * Read params for {@link PerpsProviderPlugin.getDepositFlow}.
142
168
  *
143
169
  * @public
144
170
  */
145
- export interface ProviderGetDepositMethodsParams {
171
+ export interface ProviderGetDepositFlowParams {
146
172
  address: Address
147
- sourceAsset: DepositAsset
148
173
  }
149
174
 
150
175
  /**
@@ -269,6 +294,17 @@ export interface PerpsProviderPlugin {
269
294
  */
270
295
  readonly type: string
271
296
 
297
+ /**
298
+ * Setup actions the provider completes on its own, without surfacing a card
299
+ * to the caller. `PerpsClient.checkSetup` drains each such pending step in
300
+ * place — building, signing, and executing it with the provider's own
301
+ * credentials — and omits it from the returned `setup` list. A descriptor
302
+ * whose `signers` include {@link PerpsSigner.USER} is never treated as
303
+ * internal, even when named here. Omit when the provider has no
304
+ * self-completed setup steps.
305
+ */
306
+ readonly internalSetupActions?: readonly ActionType[]
307
+
272
308
  /**
273
309
  * Inject the runtime {@link PerpsSDKClient} into the plugin once, during
274
310
  * {@link createPerpsClient}. The plugin captures it (config, fetch, retry,
@@ -296,14 +332,18 @@ export interface PerpsProviderPlugin {
296
332
  ): Promise<boolean>
297
333
 
298
334
  /**
299
- * Resolve funding methods for the wallet address and selected source asset.
300
- * Providers own account-state and route decisions; the consumer owns live
301
- * balance checks.
335
+ * The deposit flow this venue offers `params.address`, resolved from the
336
+ * venue's own account and setup state — which collateral token a deposit must
337
+ * land in, whether the address first needs the account-opening pipeline, and
338
+ * whether venue setup gates naming a destination at all.
339
+ *
340
+ * Optional: a provider that cannot be funded through the SDK omits it, and
341
+ * `PerpsClient.getDepositFlow` then resolves `undefined`.
302
342
  */
303
- getDepositMethods?(
304
- params: ProviderGetDepositMethodsParams,
343
+ getDepositFlow?(
344
+ params: ProviderGetDepositFlowParams,
305
345
  options?: SDKRequestOptions
306
- ): Promise<DepositMethod[]>
346
+ ): Promise<DepositFlow>
307
347
 
308
348
  getPositions(
309
349
  params: ProviderGetPositionsParams,
@@ -472,20 +512,11 @@ export interface PerpsProviderPlugin {
472
512
  ): Promise<SignedActionStep[]>
473
513
 
474
514
  /**
475
- * Execute credential-bearing rest-call steps directly against the venue.
476
- * Required for providers whose descriptors declare
477
- * `SigningMethod.AUTH_TOKEN`: the client-held credential (attached by
478
- * `signActions` as `headers`) must never transit the LI.FI backend, so the
479
- * venue call happens SDK-side. The provider owns base-URL resolution and
480
- * mapping the venue response onto {@link ActionResult}s — these results are
481
- * authoritative for the caller; `PerpsClient.execute` submits the steps to
482
- * the backend afterwards for bookkeeping only, with `headers` stripped.
515
+ * Observe the per-step results of an `/executeAction` round trip before the
516
+ * core surfaces failures. Lets a provider react to structured failure codes
517
+ * — e.g. evicting a locally stored credential the venue no longer accepts.
483
518
  */
484
- executeRestCallActions?(
485
- steps: RestCallSignedActionStep[],
486
- address: Address,
487
- options?: SDKRequestOptions
488
- ): Promise<ActionResult[]>
519
+ onExecuteResults?(address: Address, results: ActionResult[]): Promise<void>
489
520
  }
490
521
 
491
522
  /**
@@ -8,6 +8,12 @@ import { stringToFloat } from './parse.js'
8
8
  const sumValueUsd = (balances: AccountResponse['balances']): number =>
9
9
  balances.reduce((sum, b) => sum + stringToFloat(b.valueUsd), 0)
10
10
 
11
+ const sumMarginUsd = (balances: AccountResponse['balances']): number =>
12
+ balances.reduce(
13
+ (sum, b) => sum + stringToFloat(b.valueUsd) * (b.collateralWeight ?? 1),
14
+ 0
15
+ )
16
+
11
17
  /**
12
18
  * What the summed `collateralBalances` rows already contain, relative to the
13
19
  * positions' locked margin and unrealized PnL:
@@ -51,12 +57,17 @@ export function summarizeAccount(
51
57
  }
52
58
 
53
59
  const collateral = sumValueUsd(account.collateralBalances)
60
+ // Margin-eligible collateral: each row's value scaled by its loan-to-value
61
+ // weight (1 when unset), so a haircut asset backs buying power at less than
62
+ // face while `portfolioValue` still reflects its full value.
63
+ const marginCollateral = sumMarginUsd(account.collateralBalances)
54
64
  const balances = sumValueUsd(account.balances)
55
65
 
56
- const grossCollateral =
57
- semantics === 'free' || semantics === 'net'
58
- ? collateral + marginUsed
59
- : collateral
66
+ const withLocked = semantics === 'free' || semantics === 'net'
67
+ const grossCollateral = withLocked ? collateral + marginUsed : collateral
68
+ const grossMarginCollateral = withLocked
69
+ ? marginCollateral + marginUsed
70
+ : marginCollateral
60
71
  const equity =
61
72
  semantics === 'equity' || semantics === 'net'
62
73
  ? grossCollateral
@@ -66,7 +77,9 @@ export function summarizeAccount(
66
77
  // toward it. The `'free'` rows exclude uPnL from available margin, holding
67
78
  // it purely as free collateral.
68
79
  const availableMargin =
69
- semantics === 'free' ? grossCollateral - marginUsed : equity - marginUsed
80
+ grossMarginCollateral +
81
+ (semantics === 'gross' ? unrealizedPnl : 0) -
82
+ marginUsed
70
83
 
71
84
  return {
72
85
  portfolioValue: (balances + equity).toString(),
@@ -0,0 +1,77 @@
1
+ import { ChainId } from '@lifi/types'
2
+ import { zeroAddress } from 'viem'
3
+ import type { DeclaredDepositAsset } from '../types/deposit.js'
4
+
5
+ /**
6
+ * USDC on Ethereum mainnet — the collateral leg of Lighter's first-deposit
7
+ * pipeline, and the token Ondo's provisioned deposit address is funded in.
8
+ *
9
+ * @public
10
+ */
11
+ export const ETHEREUM_USDC: DeclaredDepositAsset = {
12
+ chainId: ChainId.ETH,
13
+ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
14
+ decimals: 6,
15
+ }
16
+
17
+ /**
18
+ * Ether on Ethereum mainnet, to broadcast the first-deposit pipeline's legs
19
+ * with.
20
+ *
21
+ * @public
22
+ */
23
+ export const ETHEREUM_NATIVE_GAS: DeclaredDepositAsset = {
24
+ chainId: ChainId.ETH,
25
+ address: zeroAddress,
26
+ decimals: 18,
27
+ }
28
+
29
+ /**
30
+ * USDC on the Hyperliquid venue chain: the 6-decimal perps contract. The same
31
+ * chain also lists an 8-decimal spot `USDC` at
32
+ * `0x6d1e7cde53bA9467B783Cb7c530CE05400000000`, so a deposit destination
33
+ * resolved by symbol lands on the wrong token and the wrong scale.
34
+ *
35
+ * @public
36
+ */
37
+ export const HYPERLIQUID_USDC: DeclaredDepositAsset = {
38
+ chainId: ChainId.HPL,
39
+ address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
40
+ decimals: 6,
41
+ }
42
+
43
+ /**
44
+ * USDC on the Lighter venue chain. The venue chain reuses the mainnet USDC
45
+ * address, so `chainId` is what distinguishes it from {@link ETHEREUM_USDC}.
46
+ *
47
+ * @public
48
+ */
49
+ export const LIGHTER_USDC: DeclaredDepositAsset = {
50
+ chainId: ChainId.LTR,
51
+ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
52
+ decimals: 6,
53
+ }
54
+
55
+ /**
56
+ * USDG on Robinhood Chain — the collateral the Lighter Robinhood instance is
57
+ * funded in.
58
+ *
59
+ * @public
60
+ */
61
+ export const ROBINHOOD_USDG: DeclaredDepositAsset = {
62
+ chainId: ChainId.OUT,
63
+ address: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168',
64
+ decimals: 6,
65
+ }
66
+
67
+ /**
68
+ * Ether on Robinhood Chain, to broadcast the Robinhood first-deposit pipeline's
69
+ * legs with.
70
+ *
71
+ * @public
72
+ */
73
+ export const ROBINHOOD_NATIVE_GAS: DeclaredDepositAsset = {
74
+ chainId: ChainId.OUT,
75
+ address: zeroAddress,
76
+ decimals: 18,
77
+ }
@@ -33,6 +33,25 @@ const TX_BASE_URL_BY_CHAIN: Record<ExplorerChainId, string> = {
33
33
  [ExplorerChainId.HYPERLIQUID]: 'https://app.hyperliquid.xyz/explorer/tx/',
34
34
  }
35
35
 
36
+ /**
37
+ * Build a fully-resolved block-explorer URL from an explicit base URL, for
38
+ * settling venues whose explorer is not one of the {@link ExplorerChainId}
39
+ * entries (e.g. a second provider instance carrying its own base).
40
+ *
41
+ * @returns The explorer URL, or `undefined` when either the base or the hash is
42
+ * absent (no explorer configured, or no on-chain tx to link).
43
+ * @public
44
+ */
45
+ export function explorerTxUrlFromBase(
46
+ baseUrl: string | undefined,
47
+ txHash: string | undefined
48
+ ): string | undefined {
49
+ if (!baseUrl || !txHash) {
50
+ return undefined
51
+ }
52
+ return `${baseUrl}${txHash}`
53
+ }
54
+
36
55
  /**
37
56
  * Build a fully-resolved block-explorer URL for a tx on a known chain.
38
57
  *
@@ -44,8 +63,5 @@ export function explorerTxUrl(
44
63
  chainId: ExplorerChainId,
45
64
  txHash: string | undefined
46
65
  ): string | undefined {
47
- if (!txHash) {
48
- return undefined
49
- }
50
- return `${TX_BASE_URL_BY_CHAIN[chainId]}${txHash}`
66
+ return explorerTxUrlFromBase(TX_BASE_URL_BY_CHAIN[chainId], txHash)
51
67
  }