@lifi/perps-sdk 0.0.0-preview-c69c4cc → 0.0.0-preview-232a40e

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 (66) hide show
  1. package/dist/cjs/client/PerpsClient.d.ts +13 -9
  2. package/dist/cjs/client/PerpsClient.d.ts.map +1 -1
  3. package/dist/cjs/client/PerpsClient.js +135 -52
  4. package/dist/cjs/client/PerpsClient.js.map +1 -1
  5. package/dist/cjs/index.d.ts +4 -4
  6. package/dist/cjs/index.d.ts.map +1 -1
  7. package/dist/cjs/index.js +2 -1
  8. package/dist/cjs/index.js.map +1 -1
  9. package/dist/cjs/types/api.d.ts +3 -6
  10. package/dist/cjs/types/api.d.ts.map +1 -1
  11. package/dist/cjs/types/provider.d.ts +5 -10
  12. package/dist/cjs/types/provider.d.ts.map +1 -1
  13. package/dist/cjs/types/withdrawal.d.ts +1 -11
  14. package/dist/cjs/types/withdrawal.d.ts.map +1 -1
  15. package/dist/cjs/utils/setupActions.d.ts +4 -2
  16. package/dist/cjs/utils/setupActions.d.ts.map +1 -1
  17. package/dist/cjs/utils/setupActions.js +9 -1
  18. package/dist/cjs/utils/setupActions.js.map +1 -1
  19. package/dist/cjs/utils/switchChain.js +1 -1
  20. package/dist/cjs/utils/switchChain.js.map +1 -1
  21. package/dist/cjs/version.d.ts +1 -1
  22. package/dist/cjs/version.js +1 -1
  23. package/dist/esm/client/PerpsClient.d.ts +63 -58
  24. package/dist/esm/client/PerpsClient.d.ts.map +1 -1
  25. package/dist/esm/client/PerpsClient.js +195 -102
  26. package/dist/esm/client/PerpsClient.js.map +1 -1
  27. package/dist/esm/index.d.ts +4 -4
  28. package/dist/esm/index.d.ts.map +1 -1
  29. package/dist/esm/index.js +1 -1
  30. package/dist/esm/index.js.map +1 -1
  31. package/dist/esm/types/api.d.ts +24 -23
  32. package/dist/esm/types/api.d.ts.map +1 -1
  33. package/dist/esm/types/provider.d.ts +17 -40
  34. package/dist/esm/types/provider.d.ts.map +1 -1
  35. package/dist/esm/types/withdrawal.d.ts +1 -30
  36. package/dist/esm/types/withdrawal.d.ts.map +1 -1
  37. package/dist/esm/utils/setupActions.d.ts +17 -8
  38. package/dist/esm/utils/setupActions.d.ts.map +1 -1
  39. package/dist/esm/utils/setupActions.js +20 -7
  40. package/dist/esm/utils/setupActions.js.map +1 -1
  41. package/dist/esm/utils/switchChain.js +1 -1
  42. package/dist/esm/utils/switchChain.js.map +1 -1
  43. package/dist/esm/version.d.ts +1 -1
  44. package/dist/esm/version.js +1 -1
  45. package/dist/types/client/PerpsClient.d.ts +63 -58
  46. package/dist/types/client/PerpsClient.d.ts.map +1 -1
  47. package/dist/types/index.d.ts +4 -4
  48. package/dist/types/index.d.ts.map +1 -1
  49. package/dist/types/types/api.d.ts +24 -23
  50. package/dist/types/types/api.d.ts.map +1 -1
  51. package/dist/types/types/provider.d.ts +17 -40
  52. package/dist/types/types/provider.d.ts.map +1 -1
  53. package/dist/types/types/withdrawal.d.ts +1 -30
  54. package/dist/types/types/withdrawal.d.ts.map +1 -1
  55. package/dist/types/utils/setupActions.d.ts +17 -8
  56. package/dist/types/utils/setupActions.d.ts.map +1 -1
  57. package/dist/types/version.d.ts +1 -1
  58. package/package.json +2 -2
  59. package/src/client/PerpsClient.ts +271 -136
  60. package/src/index.ts +4 -6
  61. package/src/types/api.ts +25 -24
  62. package/src/types/provider.ts +17 -47
  63. package/src/types/withdrawal.ts +1 -33
  64. package/src/utils/setupActions.ts +27 -13
  65. package/src/utils/switchChain.ts +1 -1
  66. package/src/version.ts +1 -1
@@ -1,4 +1,5 @@
1
1
  import type {
2
+ AccountConfigSetting,
2
3
  AccountResponse,
3
4
  AccountSummary,
4
5
  ActionParamsMap,
@@ -16,9 +17,12 @@ import type {
16
17
  Position,
17
18
  Provider,
18
19
  ProviderAction,
20
+ SetupAction,
21
+ SetupOption,
19
22
  SignedActionStep,
20
23
  } from '@lifi/perps-types'
21
24
  import {
25
+ ActionRelay,
22
26
  ActionType,
23
27
  META_PROVIDER,
24
28
  PerpsErrorCode,
@@ -55,7 +59,6 @@ import type {
55
59
  GetPortfolioHistoryParams,
56
60
  GetSetupParams,
57
61
  GetWithdrawableBalancesParams,
58
- GetWithdrawFlowParams,
59
62
  ModifyOrdersParams,
60
63
  PerpsClientOptions,
61
64
  PlaceOrderParams,
@@ -79,7 +82,8 @@ import type {
79
82
  SignActionProgress,
80
83
  SignActionsContext,
81
84
  } from '../types/provider.js'
82
- import type { WithdrawableBalance, WithdrawFlow } from '../types/withdrawal.js'
85
+ import type { WithdrawableBalance } from '../types/withdrawal.js'
86
+ import { isUserFacingSetupStep } from '../utils/setupActions.js'
83
87
  import { signTypedDataWithSigner } from '../utils/signTypedData.js'
84
88
  import {
85
89
  eip712DomainChainId,
@@ -89,6 +93,103 @@ import {
89
93
  import { createPerpsClient } from './createPerpsClient.js'
90
94
  import { requireProvider as resolveProvider } from './requireProvider.js'
91
95
 
96
+ /** Absent `sequence` sorts last, so an unordered step gates nothing. */
97
+ function sequenceOf(descriptor: ProviderAction): number {
98
+ return descriptor.sequence ?? Number.MAX_SAFE_INTEGER
99
+ }
100
+
101
+ const SIGNERS: ReadonlySet<string> = new Set(Object.values(PerpsSigner))
102
+ const RELAYS: ReadonlySet<string> = new Set(Object.values(ActionRelay))
103
+
104
+ /**
105
+ * Reject provider metadata whose steps the SDK cannot classify. A step with no
106
+ * known `signer`, `relay`, `options` or `revoke` would otherwise read as
107
+ * satisfied and report a not-onboarded account as ready.
108
+ */
109
+ function assertSetupContract(metadata: Provider): void {
110
+ const reject = (step: ActionType, problem: string): never => {
111
+ throw new PerpsError(
112
+ PerpsErrorCode.SDKError,
113
+ `Provider '${metadata.key}' step '${step}' ${problem}; this SDK needs a ` +
114
+ `backend that emits signer, relay, options and revoke.`
115
+ )
116
+ }
117
+ for (const descriptor of [...metadata.setup, ...metadata.actions]) {
118
+ if (!SIGNERS.has(descriptor.signer)) {
119
+ reject(descriptor.type, 'declares no known signer')
120
+ }
121
+ if (!RELAYS.has(descriptor.relay)) {
122
+ reject(descriptor.type, 'declares no known relay')
123
+ }
124
+ }
125
+ const actionTypes = new Set(metadata.actions.map((d) => d.type))
126
+ for (const descriptor of metadata.setup) {
127
+ if (descriptor.options === undefined) {
128
+ reject(descriptor.type, 'declares no options')
129
+ }
130
+ if (descriptor.revoke === undefined) {
131
+ reject(descriptor.type, 'declares no revoke')
132
+ }
133
+ if (descriptor.revoke !== null && !actionTypes.has(descriptor.revoke)) {
134
+ reject(
135
+ descriptor.type,
136
+ `revokes with '${descriptor.revoke}', which Provider.actions does not declare`
137
+ )
138
+ }
139
+ const defaults = (descriptor.options ?? []).filter(
140
+ (option) => option.default === true
141
+ )
142
+ if (defaults.length > 1) {
143
+ reject(descriptor.type, 'marks more than one option default')
144
+ }
145
+ }
146
+ }
147
+
148
+ /** Only a USER-signed non-choice step is staged for the user to sign. */
149
+ function isStageable(descriptor: SetupAction): boolean {
150
+ return descriptor.options === null && descriptor.signer === PerpsSigner.USER
151
+ }
152
+
153
+ function satisfiedTypes(settings: AccountConfigSetting[]): Set<ActionType> {
154
+ return new Set(
155
+ settings.filter((setting) => setting.satisfied).map((s) => s.type)
156
+ )
157
+ }
158
+
159
+ /** The choice option whose every bound param equals the projected value. */
160
+ function selectedOption(
161
+ descriptor: SetupAction,
162
+ settings: AccountConfigSetting[]
163
+ ): SetupOption | null {
164
+ if (descriptor.options === null) {
165
+ return null
166
+ }
167
+ const values =
168
+ settings.find((setting) => setting.type === descriptor.type)?.values ?? []
169
+ return (
170
+ descriptor.options.find((option) => {
171
+ const bound = Object.entries(option.params)
172
+ return (
173
+ bound.length > 0 &&
174
+ bound.every(([name, value]) =>
175
+ values.some((v) => v.name === name && v.value === value)
176
+ )
177
+ )
178
+ }) ?? null
179
+ )
180
+ }
181
+
182
+ /** Throw the first per-action failure a 200 OK `/executeAction` carried. */
183
+ function assertAllSucceeded(results: ActionResult[]): void {
184
+ const failure = results.find((r) => !r.success)
185
+ if (failure) {
186
+ throw new PerpsError(
187
+ failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
188
+ failure.error
189
+ )
190
+ }
191
+ }
192
+
92
193
  function isNonNegativeDecimal(value: string): boolean {
93
194
  try {
94
195
  return new Big(value).gte(0)
@@ -105,11 +206,9 @@ function findActionDescriptor(
105
206
  metadata: Provider,
106
207
  action: ActionType
107
208
  ): ProviderAction {
108
- const descriptor = [
109
- ...metadata.setup,
110
- ...metadata.options,
111
- ...metadata.actions,
112
- ].find((d) => d.type === action)
209
+ const descriptor = [...metadata.setup, ...metadata.actions].find(
210
+ (d) => d.type === action
211
+ )
113
212
  if (!descriptor) {
114
213
  throw new PerpsError(
115
214
  PerpsErrorCode.SDKError,
@@ -171,7 +270,7 @@ export class PerpsClient {
171
270
 
172
271
  /**
173
272
  * Set or update the end-user's wallet. Used whenever an action's descriptor
174
- * names the user wallet in its `signers` list. Pass undefined to clear.
273
+ * names `PerpsSigner.USER` as its `signer`. Pass undefined to clear.
175
274
  *
176
275
  * @public
177
276
  */
@@ -205,17 +304,15 @@ export class PerpsClient {
205
304
  }
206
305
 
207
306
  private async getProviderMetadata(provider: string): Promise<Provider> {
208
- const cached = this.providerMetadataCache.get(provider)
209
- if (cached) {
210
- return cached
211
- }
212
-
213
- const { providers } = await getProviders(this.sdkClient)
214
- for (const d of providers) {
215
- this.providerMetadataCache.set(d.key, d)
307
+ let metadata = this.providerMetadataCache.get(provider)
308
+ if (!metadata) {
309
+ const { providers } = await getProviders(this.sdkClient)
310
+ for (const d of providers) {
311
+ this.providerMetadataCache.set(d.key, d)
312
+ }
313
+ metadata = this.providerMetadataCache.get(provider)
216
314
  }
217
315
 
218
- const metadata = this.providerMetadataCache.get(provider)
219
316
  if (!metadata) {
220
317
  const error = new PerpsError(
221
318
  PerpsErrorCode.SDKError,
@@ -224,6 +321,7 @@ export class PerpsClient {
224
321
  error.tool = '@lifi/perps-sdk'
225
322
  throw error
226
323
  }
324
+ assertSetupContract(metadata)
227
325
  return metadata
228
326
  }
229
327
 
@@ -256,7 +354,7 @@ export class PerpsClient {
256
354
  * Ask the provider plugin for the signer-bearing wire fields of `action` —
257
355
  * the on-wire `signerAddress` and any signer-derived params (e.g.
258
356
  * Hyperliquid's `agentAddress` for `APPROVE_AGENT`). Forwards the descriptor's
259
- * `signers` so the plugin can branch on signer role. Returns empty when the
357
+ * `signer` so the plugin can branch on signer role. Returns empty when the
260
358
  * plugin signs as the user or with a non-EVM credential. Core constructs no
261
359
  * `signerAddress` itself; signer identity is plugin-owned.
262
360
  */
@@ -272,17 +370,17 @@ export class PerpsClient {
272
370
  return plugin.resolveActionRequest(
273
371
  descriptor.type,
274
372
  address,
275
- descriptor.signers
373
+ descriptor.signer
276
374
  )
277
375
  }
278
376
 
279
377
  /**
280
378
  * Delegate signing of `actions` to the provider plugin, one call per
281
379
  * consecutive run of steps sharing a descriptor. Each call carries that
282
- * descriptor's `signingMethod` and `signers`, so a mixed batch signs every
380
+ * descriptor's `signingMethod` and `signer`, so a mixed batch signs every
283
381
  * step with the signer its own descriptor declares; the signed steps come
284
382
  * back in the batch's original order. The plugin owns every signing arm and
285
- * branches on `signers` internally, reading the end-user's wallet from the
383
+ * branches on `signer` internally, reading the end-user's wallet from the
286
384
  * {@link SignActionsContext} when an arm signs as the user.
287
385
  *
288
386
  * @throws {PerpsError} When a step's action is not declared by the provider,
@@ -405,9 +503,9 @@ export class PerpsClient {
405
503
 
406
504
  /**
407
505
  * Assemble the per-call context the provider plugin needs in order to sign:
408
- * the end-user's wallet and the descriptor's declared `signers`. Core
409
- * forwards `signers` as data so the plugin can pick WHO signs; it does not
410
- * branch on them. Provider-owned session credentials (the Hyperliquid agent
506
+ * the end-user's wallet and the descriptor's declared `signer`. Core
507
+ * forwards `signer` as data so the plugin can pick WHO signs; it does not
508
+ * branch on it. Provider-owned session credentials (the Hyperliquid agent
411
509
  * keypair, Lighter's API key) are resolved inside the provider's
412
510
  * `signActions`, not threaded through here.
413
511
  *
@@ -425,7 +523,7 @@ export class PerpsClient {
425
523
  userWallet?: PerpsClientSigner,
426
524
  onProgress?: (progress: SignActionProgress) => void
427
525
  ): SignActionsContext {
428
- const ctx: SignActionsContext = { signers: descriptor.signers }
526
+ const ctx: SignActionsContext = { signer: descriptor.signer }
429
527
  if (onProgress !== undefined) {
430
528
  ctx.onProgress = onProgress
431
529
  }
@@ -501,7 +599,7 @@ export class PerpsClient {
501
599
  /**
502
600
  * Fetch the user's account state from the backend and attach the
503
601
  * SDK-projected `settings` array — one `AccountConfigSetting` per
504
- * descriptor on `Provider.setup` + `Provider.options`. Callers read
602
+ * descriptor on `Provider.setup`. Callers read
505
603
  * `result.settings` directly without re-deriving values from the typed
506
604
  * `AccountConfig`.
507
605
  *
@@ -518,11 +616,7 @@ export class PerpsClient {
518
616
  fetchAccount(this.sdkClient, params),
519
617
  this.getProviderMetadata(params.provider),
520
618
  ])
521
- const settings = plugin.projectConfig(
522
- response.config,
523
- metadata.setup,
524
- metadata.options
525
- )
619
+ const settings = plugin.projectConfig(response.config, metadata.setup)
526
620
  return { ...response, settings }
527
621
  }
528
622
 
@@ -662,23 +756,6 @@ export class PerpsClient {
662
756
  return plugin.getDepositFlow?.({ address: params.address })
663
757
  }
664
758
 
665
- /**
666
- * The withdrawal flow for `params.address` at `params.provider`, delegated to
667
- * the provider plugin — the withdrawal destination and any setup gate before
668
- * it are venue-owned.
669
- *
670
- * @returns `undefined` when the registered plugin declares no withdrawal flow.
671
- * @throws {PerpsError} When the provider plugin is not registered, or the
672
- * plugin's flow resolution fails.
673
- * @public
674
- */
675
- async getWithdrawFlow(
676
- params: GetWithdrawFlowParams
677
- ): Promise<WithdrawFlow | undefined> {
678
- const plugin = this.requireProvider(params.provider)
679
- return plugin.getWithdrawFlow?.({ address: params.address })
680
- }
681
-
682
759
  /**
683
760
  * The `(asset, route)` selections `params.address` can actually withdraw at
684
761
  * `params.provider`. The venue owns how its balances split across routes;
@@ -773,15 +850,17 @@ export class PerpsClient {
773
850
  }
774
851
 
775
852
  /**
776
- * Return the unsatisfied entries on `Provider.setup` for this account as a
777
- * flat, self-describing list. Trading is gated on `isReady === true`.
778
- * `checklist` carries the renderable onboarding list: every USER-signed
779
- * descriptor with its satisfied state, with not-required conditional steps
780
- * omitted.
853
+ * Return the setup steps this account must still sign as a flat,
854
+ * self-describing list. Trading is gated on `isReady === true`.
855
+ * `checklist` carries the renderable onboarding list: every choice step and
856
+ * every `USER`-signed step with its satisfied state, with not-required
857
+ * conditional steps omitted.
781
858
  *
782
- * `Provider.options` descriptors are NEVER returned here — options are
783
- * post-setup tunables and never gate trading. Option state is surfaced
784
- * separately via `getAccount().settings`.
859
+ * A non-choice `SDK`-signed step is NEVER returned here — the SDK drains it
860
+ * with the provider's own credentials. A choice is listed but never staged
861
+ * or executed, whatever its `signer`: the user picks an option through
862
+ * {@link executeProviderOption}, and `isReady` stays `false` until every
863
+ * choice on `checklist` is satisfied.
785
864
  *
786
865
  * @public
787
866
  */
@@ -807,19 +886,15 @@ export class PerpsClient {
807
886
  }
808
887
  }
809
888
 
810
- const satisfiedSetup = await this.resolveSatisfiedSetup(provider, address)
889
+ const settings = await this.resolveSetupSettings(provider, address)
890
+ const satisfiedSetup = satisfiedTypes(settings)
811
891
  const pendingSetup = metadata.setup.filter(
812
892
  (descriptor) => !satisfiedSetup.has(descriptor.type)
813
893
  )
814
894
 
815
895
  const plugin = this.sdkClient.getProvider(provider)
816
- const internalTypes = new Set(plugin?.internalSetupActions ?? [])
817
- const isInternal = (descriptor: ProviderAction): boolean =>
818
- internalTypes.has(descriptor.type) &&
819
- !descriptor.signers.includes(PerpsSigner.USER)
820
- const visibleSetup = pendingSetup.filter(
821
- (descriptor) => !isInternal(descriptor)
822
- )
896
+
897
+ const stageable = pendingSetup.filter(isStageable)
823
898
 
824
899
  // The backend filters already-satisfied setup actions and returns typed
825
900
  // data for those still outstanding; each plugin contributes its own
@@ -827,7 +902,7 @@ export class PerpsClient {
827
902
  const actions = await this.buildProviderSetupActions(
828
903
  provider,
829
904
  address,
830
- visibleSetup
905
+ stageable
831
906
  )
832
907
 
833
908
  // A staged step is one the build produced actions for — a pending
@@ -835,10 +910,8 @@ export class PerpsClient {
835
910
  // (backend-gated) or not applicable to this account.
836
911
  const stagedTypes = new Set(actions.map((step) => step.action))
837
912
  const conditionalTypes = new Set(plugin?.conditionalSetupActions ?? [])
838
- const sequenceOf = (descriptor: ProviderAction): number =>
839
- descriptor.sequence ?? Number.MAX_SAFE_INTEGER
840
913
  const checklist = metadata.setup
841
- .filter((descriptor) => descriptor.signers.includes(PerpsSigner.USER))
914
+ .filter(isUserFacingSetupStep)
842
915
  .filter(
843
916
  (descriptor) =>
844
917
  !conditionalTypes.has(descriptor.type) ||
@@ -847,57 +920,52 @@ export class PerpsClient {
847
920
  .sort((a, b) => sequenceOf(a) - sequenceOf(b))
848
921
  .map((descriptor) => ({
849
922
  descriptor,
850
- satisfied: !stagedTypes.has(descriptor.type),
923
+ satisfied:
924
+ descriptor.options !== null
925
+ ? satisfiedSetup.has(descriptor.type)
926
+ : !stagedTypes.has(descriptor.type),
927
+ selected: selectedOption(descriptor, settings),
851
928
  }))
852
929
 
853
- await this.drainInternalSetup(
930
+ await this.drainSetup(
854
931
  provider,
855
932
  address,
856
- pendingSetup.filter(isInternal),
857
- visibleSetup.filter((descriptor) => stagedTypes.has(descriptor.type))
933
+ pendingSetup.filter(
934
+ (descriptor) =>
935
+ descriptor.options === null && descriptor.signer === PerpsSigner.SDK
936
+ ),
937
+ stageable.filter((descriptor) => stagedTypes.has(descriptor.type))
858
938
  )
859
939
 
860
940
  return {
861
941
  accountExists: true,
862
942
  setup: actions,
863
- isReady: actions.length === 0,
943
+ isReady:
944
+ actions.length === 0 && checklist.every((item) => item.satisfied),
864
945
  checklist,
865
946
  }
866
947
  }
867
948
 
868
949
  /**
869
- * Resolve setup descriptors already satisfied from the provider's own typed
870
- * account config projection. This catches client-held auth state (e.g. Ondo
871
- * SIWE/JWT) that the backend cannot observe.
950
+ * Project the provider's own typed account config onto its setup steps. This
951
+ * catches client-held auth state (e.g. Ondo SIWE/JWT) that the backend
952
+ * cannot observe, and carries the current value of each choice.
872
953
  */
873
- private async resolveSatisfiedSetup(
954
+ private async resolveSetupSettings(
874
955
  provider: string,
875
956
  address: Address
876
- ): Promise<Set<ActionType>> {
957
+ ): Promise<AccountConfigSetting[]> {
877
958
  const metadata = await this.getProviderMetadata(provider)
878
959
  const plugin = this.sdkClient.getProvider(provider)
879
960
  if (!plugin || typeof plugin.getAccount !== 'function') {
880
- return new Set()
961
+ return []
881
962
  }
882
963
  const account = await plugin.getAccount({ address })
883
- const settings = plugin.projectConfig(
884
- account.config,
885
- metadata.setup,
886
- metadata.options
887
- )
888
- const setupTypes = new Set(
889
- metadata.setup.map((descriptor) => descriptor.type)
890
- )
891
- return new Set(
892
- settings
893
- .filter((setting) => setting.satisfied && setupTypes.has(setting.type))
894
- .map((setting) => setting.type)
895
- )
964
+ return plugin.projectConfig(account.config, metadata.setup)
896
965
  }
897
966
 
898
967
  /**
899
- * Drain the pending setup steps the provider declares as internal via
900
- * `PerpsProviderPlugin.internalSetupActions`. Each step is built, signed,
968
+ * Drain the pending `SDK`-signed non-choice steps: each is built, signed,
901
969
  * and executed in place with the provider's own credentials. A step is
902
970
  * deferred while any staged user-facing step with a lower `sequence` is
903
971
  * outstanding — it cannot succeed before its prerequisite (e.g. SET_REFERRAL
@@ -906,17 +974,15 @@ export class PerpsClient {
906
974
  * blocks setup — the step stays unsatisfied and is retried on a later
907
975
  * `checkSetup`.
908
976
  */
909
- private async drainInternalSetup(
977
+ private async drainSetup(
910
978
  provider: string,
911
979
  address: Address,
912
- internalPending: ProviderAction[],
913
- stagedVisible: ProviderAction[]
980
+ drainable: SetupAction[],
981
+ stagedVisible: SetupAction[]
914
982
  ): Promise<void> {
915
- const sequenceOf = (descriptor: ProviderAction): number =>
916
- descriptor.sequence ?? Number.MAX_SAFE_INTEGER
917
- for (const descriptor of internalPending) {
983
+ for (const descriptor of drainable) {
918
984
  // A tie (equal sequences, or both absent) declares no order, so the
919
- // internal step defers to the next checkSetup rather than racing.
985
+ // drained step defers to the next checkSetup rather than racing.
920
986
  const blocked = stagedVisible.some(
921
987
  (staged) => sequenceOf(staged) <= sequenceOf(descriptor)
922
988
  )
@@ -944,7 +1010,7 @@ export class PerpsClient {
944
1010
  }
945
1011
  } catch (error) {
946
1012
  console.debug(
947
- `[perps-sdk] internal setup step '${descriptor.type}' for '${provider}' did not complete; will retry on the next checkSetup.`,
1013
+ `[perps-sdk] setup step '${descriptor.type}' for '${provider}' did not drain; will retry on the next checkSetup.`,
948
1014
  error
949
1015
  )
950
1016
  }
@@ -958,7 +1024,7 @@ export class PerpsClient {
958
1024
  private async buildProviderSetupActions(
959
1025
  provider: string,
960
1026
  address: Address,
961
- descriptors: ProviderAction[]
1027
+ descriptors: SetupAction[]
962
1028
  ): Promise<ActionStep[]> {
963
1029
  const setupPriority = (descriptor: ProviderAction): number =>
964
1030
  descriptor.signingMethod === SigningMethod.SIWE ? 0 : 1
@@ -996,9 +1062,11 @@ export class PerpsClient {
996
1062
 
997
1063
  /**
998
1064
  * Build the unsigned setup `ActionStep`s still outstanding for an account,
999
- * ordered by descriptor `sequence`. The backend filters already-satisfied
1000
- * setup; each plugin contributes its own signer-bearing request fields and
1001
- * any local-state params (e.g. Lighter's known pubkey).
1065
+ * ordered by descriptor `sequence`. Only a `USER`-signed non-choice step is
1066
+ * staged: an `SDK`-signed non-choice step drains inside {@link checkSetup}
1067
+ * and a choice executes the option the user picks. The backend filters
1068
+ * already-satisfied setup; each plugin contributes its own signer-bearing
1069
+ * request fields and any local-state params (e.g. Lighter's known pubkey).
1002
1070
  *
1003
1071
  * @public
1004
1072
  */
@@ -1011,7 +1079,7 @@ export class PerpsClient {
1011
1079
  const actions = await this.buildProviderSetupActions(
1012
1080
  provider,
1013
1081
  address,
1014
- metadata.setup
1082
+ metadata.setup.filter(isStageable)
1015
1083
  )
1016
1084
  return { actions }
1017
1085
  }
@@ -1054,15 +1122,49 @@ export class PerpsClient {
1054
1122
 
1055
1123
  await this.notifyExecuteResults(provider, address, results)
1056
1124
 
1057
- const failure = results.find((r) => !r.success)
1058
- if (failure) {
1059
- throw new PerpsError(
1060
- failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
1061
- failure.error
1125
+ assertAllSucceeded(results)
1126
+
1127
+ return { results: { results } }
1128
+ }
1129
+
1130
+ /**
1131
+ * The lowest-`sequence` visible setup step that runs before `descriptor` and
1132
+ * is not satisfied, or `undefined` when nothing blocks it. A choice reads its
1133
+ * satisfied state from the plugin projection; a non-choice step is satisfied
1134
+ * once the provider stages no action for it, so only the earlier steps are
1135
+ * staged here.
1136
+ */
1137
+ private async findBlockingSetupStep(
1138
+ provider: string,
1139
+ address: Address,
1140
+ descriptor: SetupAction
1141
+ ): Promise<SetupAction | undefined> {
1142
+ const metadata = await this.getProviderMetadata(provider)
1143
+ const earlier = metadata.setup
1144
+ .filter(
1145
+ (d) =>
1146
+ isUserFacingSetupStep(d) && sequenceOf(d) < sequenceOf(descriptor)
1062
1147
  )
1148
+ .sort((a, b) => sequenceOf(a) - sequenceOf(b))
1149
+ if (earlier.length === 0) {
1150
+ return undefined
1063
1151
  }
1064
1152
 
1065
- return { results: { results } }
1153
+ const satisfiedSetup = satisfiedTypes(
1154
+ await this.resolveSetupSettings(provider, address)
1155
+ )
1156
+ const pending = earlier.filter((d) => !satisfiedSetup.has(d.type))
1157
+ if (pending.length === 0) {
1158
+ return undefined
1159
+ }
1160
+
1161
+ const stageable = pending.filter(isStageable)
1162
+ const staged =
1163
+ stageable.length === 0
1164
+ ? []
1165
+ : await this.buildProviderSetupActions(provider, address, stageable)
1166
+ const stagedTypes = new Set(staged.map((action) => action.action))
1167
+ return pending.find((d) => d.options !== null || stagedTypes.has(d.type))
1066
1168
  }
1067
1169
 
1068
1170
  /**
@@ -1078,7 +1180,8 @@ export class PerpsClient {
1078
1180
  * retries with a fresh step.
1079
1181
  *
1080
1182
  * @throws {PerpsError} When the step's action is not in the provider's
1081
- * `setup` descriptors.
1183
+ * `setup` descriptors, or when a lower-`sequence` step on the same
1184
+ * checklist, a choice included, is still unsatisfied.
1082
1185
  * @public
1083
1186
  */
1084
1187
  async executeProviderSetupAction(params: {
@@ -1097,6 +1200,18 @@ export class PerpsClient {
1097
1200
  )
1098
1201
  }
1099
1202
 
1203
+ const blocking = await this.findBlockingSetupStep(
1204
+ provider,
1205
+ address,
1206
+ descriptor
1207
+ )
1208
+ if (blocking) {
1209
+ throw new PerpsError(
1210
+ PerpsErrorCode.SDKError,
1211
+ `Setup step '${step.action}' for '${provider}' is blocked: '${blocking.type}' runs first and is not satisfied.`
1212
+ )
1213
+ }
1214
+
1100
1215
  const signed = await this.signProviderSetupAction(provider, address, step)
1101
1216
 
1102
1217
  // A client-executed setup action (Lighter SET_REFERRAL) produces no
@@ -1115,22 +1230,13 @@ export class PerpsClient {
1115
1230
  }
1116
1231
 
1117
1232
  /**
1118
- * Sign and submit a single provider-option change (a `Provider.options`
1119
- * tunable such as Lighter `ACCOUNT_TYPE` or Hyperliquid `ACCOUNT_MODE`)
1120
- * end-to-end, throwing on a venue rejection.
1233
+ * Execute one option of a choice setup step (Lighter `ACCOUNT_TYPE`,
1234
+ * Hyperliquid `ACCOUNT_MODE`) end-to-end with its bound `{ type, params }`,
1235
+ * throwing on a venue rejection.
1121
1236
  *
1122
- * Options are dispatched through the same {@link execute} pipeline as
1123
- * trades, but unlike a trade an option change is a single mandatory action:
1237
+ * The option runs through the same {@link execute} pipeline as a trade, but
1124
1238
  * a per-action `success: false` (returned as a 200 OK) means the user's
1125
- * selection was rejected and must surface, not be silently dropped. This
1126
- * wrapper inspects the result and throws a {@link PerpsError} carrying the
1127
- * venue `error`, giving options the same throw contract that setup has via
1128
- * {@link executeProviderSetupAction}. The only structural difference is that
1129
- * an option carries `params` (the selected value) rather than a pre-staged
1130
- * step.
1131
- *
1132
- * `execute` itself is unchanged — it still returns results without throwing,
1133
- * which the trade hooks rely on for partial-fill handling.
1239
+ * selection was rejected and must surface, not be silently dropped.
1134
1240
  *
1135
1241
  * @throws {PerpsError} Carrying the venue error when any returned result has
1136
1242
  * `success: false`, under that result's `errorCode` when the backend
@@ -1139,20 +1245,49 @@ export class PerpsClient {
1139
1245
  * signer, signing failure).
1140
1246
  * @public
1141
1247
  */
1142
- async executeProviderOption<T extends ActionType>(params: {
1248
+ async executeProviderOption(params: {
1143
1249
  provider: string
1144
1250
  address: Address
1145
- action: T
1146
- params: ActionParamsMap[T]
1251
+ option: SetupOption
1147
1252
  }): Promise<void> {
1148
- const { results } = await this.execute(params)
1149
- const failure = results.find((r) => !r.success)
1150
- if (failure) {
1253
+ const { provider, address, option } = params
1254
+ const { results } = await this.execute({
1255
+ provider,
1256
+ address,
1257
+ action: option.type,
1258
+ params: option.params,
1259
+ })
1260
+ assertAllSucceeded(results)
1261
+ }
1262
+
1263
+ /**
1264
+ * Undo a satisfied setup step by executing its `revoke` action through
1265
+ * create, sign and execute, signed with that action's `Provider.actions`
1266
+ * descriptor. The step stages again on the next {@link checkSetup}.
1267
+ *
1268
+ * @throws {PerpsError} `SDKError` when `step.revoke` is `null`; otherwise
1269
+ * the errors {@link executeProviderOption} throws.
1270
+ * @public
1271
+ */
1272
+ async executeProviderRevoke(params: {
1273
+ provider: string
1274
+ address: Address
1275
+ step: SetupAction
1276
+ }): Promise<void> {
1277
+ const { provider, address, step } = params
1278
+ if (step.revoke === null) {
1151
1279
  throw new PerpsError(
1152
- failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
1153
- failure.error
1280
+ PerpsErrorCode.SDKError,
1281
+ `Setup step '${step.type}' for '${provider}' declares no revoke.`
1154
1282
  )
1155
1283
  }
1284
+ const { results } = await this.execute({
1285
+ provider,
1286
+ address,
1287
+ action: step.revoke,
1288
+ params: {},
1289
+ })
1290
+ assertAllSucceeded(results)
1156
1291
  }
1157
1292
 
1158
1293
  /**