@lifi/perps-sdk 0.0.0-preview-2ac7198 → 0.0.0-preview-9c62621

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 (99) hide show
  1. package/README.md +69 -3
  2. package/dist/cjs/client/PerpsClient.d.ts +5 -5
  3. package/dist/cjs/client/PerpsClient.d.ts.map +1 -1
  4. package/dist/cjs/client/PerpsClient.js +105 -88
  5. package/dist/cjs/client/PerpsClient.js.map +1 -1
  6. package/dist/cjs/errors/PerpsExecutionError.d.ts +9 -0
  7. package/dist/cjs/errors/PerpsExecutionError.d.ts.map +1 -0
  8. package/dist/cjs/errors/PerpsExecutionError.js +29 -0
  9. package/dist/cjs/errors/PerpsExecutionError.js.map +1 -0
  10. package/dist/cjs/index.d.ts +6 -4
  11. package/dist/cjs/index.d.ts.map +1 -1
  12. package/dist/cjs/index.js +16 -12
  13. package/dist/cjs/index.js.map +1 -1
  14. package/dist/cjs/math/fills.d.ts +0 -1
  15. package/dist/cjs/math/fills.d.ts.map +1 -1
  16. package/dist/cjs/math/fills.js +0 -18
  17. package/dist/cjs/math/fills.js.map +1 -1
  18. package/dist/cjs/math/order.d.ts +5 -5
  19. package/dist/cjs/math/order.d.ts.map +1 -1
  20. package/dist/cjs/math/order.js +10 -10
  21. package/dist/cjs/math/order.js.map +1 -1
  22. package/dist/cjs/math/position.d.ts +2 -2
  23. package/dist/cjs/math/position.d.ts.map +1 -1
  24. package/dist/cjs/math/position.js +5 -5
  25. package/dist/cjs/math/position.js.map +1 -1
  26. package/dist/cjs/types/api.d.ts +1 -10
  27. package/dist/cjs/types/api.d.ts.map +1 -1
  28. package/dist/cjs/types/provider.d.ts +5 -1
  29. package/dist/cjs/types/provider.d.ts.map +1 -1
  30. package/dist/cjs/utils/actionResult.d.ts +3 -0
  31. package/dist/cjs/utils/actionResult.d.ts.map +1 -0
  32. package/dist/cjs/utils/actionResult.js +9 -0
  33. package/dist/cjs/utils/actionResult.js.map +1 -0
  34. package/dist/cjs/version.d.ts +1 -1
  35. package/dist/cjs/version.js +1 -1
  36. package/dist/esm/client/PerpsClient.d.ts +71 -50
  37. package/dist/esm/client/PerpsClient.d.ts.map +1 -1
  38. package/dist/esm/client/PerpsClient.js +174 -144
  39. package/dist/esm/client/PerpsClient.js.map +1 -1
  40. package/dist/esm/errors/PerpsExecutionError.d.ts +24 -0
  41. package/dist/esm/errors/PerpsExecutionError.d.ts.map +1 -0
  42. package/dist/esm/errors/PerpsExecutionError.js +39 -0
  43. package/dist/esm/errors/PerpsExecutionError.js.map +1 -0
  44. package/dist/esm/index.d.ts +6 -4
  45. package/dist/esm/index.d.ts.map +1 -1
  46. package/dist/esm/index.js +5 -3
  47. package/dist/esm/index.js.map +1 -1
  48. package/dist/esm/math/fills.d.ts +0 -9
  49. package/dist/esm/math/fills.d.ts.map +1 -1
  50. package/dist/esm/math/fills.js +0 -25
  51. package/dist/esm/math/fills.js.map +1 -1
  52. package/dist/esm/math/order.d.ts +6 -6
  53. package/dist/esm/math/order.d.ts.map +1 -1
  54. package/dist/esm/math/order.js +6 -6
  55. package/dist/esm/math/order.js.map +1 -1
  56. package/dist/esm/math/position.d.ts +2 -2
  57. package/dist/esm/math/position.d.ts.map +1 -1
  58. package/dist/esm/math/position.js +3 -3
  59. package/dist/esm/math/position.js.map +1 -1
  60. package/dist/esm/types/api.d.ts +1 -18
  61. package/dist/esm/types/api.d.ts.map +1 -1
  62. package/dist/esm/types/provider.d.ts +21 -4
  63. package/dist/esm/types/provider.d.ts.map +1 -1
  64. package/dist/esm/utils/actionResult.d.ts +4 -0
  65. package/dist/esm/utils/actionResult.d.ts.map +1 -0
  66. package/dist/esm/utils/actionResult.js +7 -0
  67. package/dist/esm/utils/actionResult.js.map +1 -0
  68. package/dist/esm/version.d.ts +1 -1
  69. package/dist/esm/version.js +1 -1
  70. package/dist/types/client/PerpsClient.d.ts +71 -50
  71. package/dist/types/client/PerpsClient.d.ts.map +1 -1
  72. package/dist/types/errors/PerpsExecutionError.d.ts +24 -0
  73. package/dist/types/errors/PerpsExecutionError.d.ts.map +1 -0
  74. package/dist/types/index.d.ts +6 -4
  75. package/dist/types/index.d.ts.map +1 -1
  76. package/dist/types/math/fills.d.ts +0 -9
  77. package/dist/types/math/fills.d.ts.map +1 -1
  78. package/dist/types/math/order.d.ts +6 -6
  79. package/dist/types/math/order.d.ts.map +1 -1
  80. package/dist/types/math/position.d.ts +2 -2
  81. package/dist/types/math/position.d.ts.map +1 -1
  82. package/dist/types/types/api.d.ts +1 -18
  83. package/dist/types/types/api.d.ts.map +1 -1
  84. package/dist/types/types/provider.d.ts +21 -4
  85. package/dist/types/types/provider.d.ts.map +1 -1
  86. package/dist/types/utils/actionResult.d.ts +4 -0
  87. package/dist/types/utils/actionResult.d.ts.map +1 -0
  88. package/dist/types/version.d.ts +1 -1
  89. package/package.json +2 -2
  90. package/src/client/PerpsClient.ts +222 -188
  91. package/src/errors/PerpsExecutionError.ts +54 -0
  92. package/src/index.ts +13 -8
  93. package/src/math/fills.ts +0 -29
  94. package/src/math/order.ts +11 -11
  95. package/src/math/position.ts +3 -3
  96. package/src/types/api.ts +0 -21
  97. package/src/types/provider.ts +22 -4
  98. package/src/utils/actionResult.ts +10 -0
  99. package/src/version.ts +1 -1
@@ -5,6 +5,7 @@ import type {
5
5
  ActionParamsMap,
6
6
  ActionResult,
7
7
  ActionStep,
8
+ Asset,
8
9
  AvailableToTrade,
9
10
  CreateActionResponse,
10
11
  DecimalString,
@@ -34,6 +35,7 @@ import type { Address } from 'viem'
34
35
  import { isDecimalStringGreaterThan } from '../decimal/compare.js'
35
36
  import { unknownToDecimalString } from '../decimal/parse.js'
36
37
  import { PerpsError } from '../errors/PerpsError.js'
38
+ import { rethrowWithKnownResults } from '../errors/PerpsExecutionError.js'
37
39
  import { getAssetRegistry, toAssetDisplay } from '../registry/assetRegistry.js'
38
40
  import { getMarketRegistry } from '../registry/marketRegistry.js'
39
41
  import { createAction } from '../services/createAction.js'
@@ -54,8 +56,6 @@ import type {
54
56
  CancelTwapOrderParams,
55
57
  CreateReferralCodeActionParams,
56
58
  ExecuteMetaActionParams,
57
- ExecuteProviderSetupParams,
58
- ExecuteProviderSetupResult,
59
59
  GetAccountResult,
60
60
  GetDepositFlowParams,
61
61
  GetPortfolioHistoryParams,
@@ -86,12 +86,14 @@ import type {
86
86
  PerpsSDKClient,
87
87
  SignActionProgress,
88
88
  SignActionsContext,
89
+ SignActionsResult,
89
90
  } from '../types/provider.js'
90
91
  import type {
91
92
  WithdrawableBalance,
92
93
  WithdrawalSourceTypes,
93
94
  WithdrawFlow,
94
95
  } from '../types/withdrawal.js'
96
+ import { isSubmittedOrAccepted } from '../utils/actionResult.js'
95
97
  import { isUserFacingSetupStep } from '../utils/setupActions.js'
96
98
  import { signTypedDataWithSigner } from '../utils/signTypedData.js'
97
99
  import {
@@ -212,17 +214,6 @@ function currentChoiceValue(
212
214
  return value === null ? null : String(value)
213
215
  }
214
216
 
215
- /** Throw the first per-action failure a 200 OK `/executeAction` carried. */
216
- function assertAllSucceeded(results: ActionResult[]): void {
217
- const failure = results.find((r) => !r.success)
218
- if (failure) {
219
- throw new PerpsError(
220
- failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
221
- failure.error
222
- )
223
- }
224
- }
225
-
226
217
  function isNonNegativeDecimal(value: string): boolean {
227
218
  try {
228
219
  return !isDecimalStringGreaterThan(
@@ -234,6 +225,25 @@ function isNonNegativeDecimal(value: string): boolean {
234
225
  }
235
226
  }
236
227
 
228
+ /** @throws {PerpsError} When `asset.minWithdrawalAmount` is not a decimal. */
229
+ function minWithdrawalAmountOf(asset: Asset): DecimalString | undefined {
230
+ if (asset.minWithdrawalAmount === undefined) {
231
+ return undefined
232
+ }
233
+ try {
234
+ return unknownToDecimalString(
235
+ asset.minWithdrawalAmount,
236
+ 'minWithdrawalAmount',
237
+ 'perps-sdk'
238
+ )
239
+ } catch {
240
+ throw new PerpsError(
241
+ PerpsErrorCode.SDKError,
242
+ `Asset '${asset.id}' field \`minWithdrawalAmount\` is not a valid decimal.`
243
+ )
244
+ }
245
+ }
246
+
237
247
  /**
238
248
  * Look up an action's descriptor in the provider's metadata. Throws if the
239
249
  * action isn't declared — defensive: better to fail loudly than to mis-sign.
@@ -431,10 +441,13 @@ export class PerpsClient {
431
441
  * step with the signer its own descriptor declares; the signed steps come
432
442
  * back in the batch's original order. The plugin owns every signing arm and
433
443
  * branches on `signer` internally, reading the end-user's wallet from the
434
- * {@link SignActionsContext} when an arm signs as the user.
444
+ * {@link SignActionsContext} when an arm signs as the user. Signing stops
445
+ * after the first group that executed a step without an acknowledgement.
435
446
  *
436
447
  * @throws {PerpsError} When a step's action is not declared by the provider,
437
448
  * or the plugin implements no `signActions`.
449
+ * @throws {PerpsExecutionError} When a group throws after an earlier group
450
+ * executed steps.
438
451
  */
439
452
  private async delegateSignActions(
440
453
  provider: string,
@@ -442,36 +455,90 @@ export class PerpsClient {
442
455
  metadata: Provider,
443
456
  actions: ActionStep[],
444
457
  onProgress?: (progress: SignActionProgress) => void
445
- ): Promise<SignedActionStep[]> {
458
+ ): Promise<SignActionsResult> {
446
459
  const plugin = this.requireProvider(provider)
447
- if (typeof plugin.signActions !== 'function') {
460
+ const signActions = plugin.signActions?.bind(plugin)
461
+ if (signActions === undefined) {
448
462
  throw new PerpsError(
449
463
  PerpsErrorCode.SDKError,
450
464
  `Provider '${provider}' does not implement signActions.`
451
465
  )
452
466
  }
453
467
  const signed: SignedActionStep[] = []
468
+ const executed: ActionResult[] = []
454
469
  for (const group of groupStepsByDescriptor(metadata, actions)) {
455
- const userWallet = await this.resolveSigningWallet(
456
- group.descriptor,
457
- group.steps
458
- )
459
- signed.push(
460
- ...(await plugin.signActions(
470
+ try {
471
+ const userWallet = await this.resolveSigningWallet(
472
+ group.descriptor,
473
+ group.steps
474
+ )
475
+ const result = await signActions(
461
476
  group.descriptor.signingMethod,
462
477
  group.steps,
463
478
  address,
464
479
  this.buildSignActionsContext(group.descriptor, userWallet, onProgress)
465
- ))
466
- )
480
+ )
481
+ signed.push(...result.signed)
482
+ executed.push(...result.executed)
483
+ } catch (error) {
484
+ rethrowWithKnownResults(executed, error)
485
+ }
486
+ if (!executed.every(isSubmittedOrAccepted)) {
487
+ break
488
+ }
489
+ }
490
+ return { signed, executed }
491
+ }
492
+
493
+ /**
494
+ * Submit `signed` to `/executeAction` when every step the plugin executed
495
+ * while signing was acknowledged, then resolve explorer links and notify the
496
+ * plugin. Resolves to the full report: `executed`, then the `/executeAction`
497
+ * results. An empty report means nothing executed.
498
+ *
499
+ * @throws {PerpsExecutionError} When the submission or the plugin callback
500
+ * throws after a result is known.
501
+ */
502
+ private async submitSignedActions(
503
+ provider: string,
504
+ address: Address,
505
+ action: ActionType,
506
+ signerAddress: Address | undefined,
507
+ { signed, executed }: SignActionsResult
508
+ ): Promise<ActionResult[]> {
509
+ let results = executed
510
+ if (signed.length > 0 && executed.every(isSubmittedOrAccepted)) {
511
+ try {
512
+ const response = await executeAction(this.sdkClient, {
513
+ provider,
514
+ address,
515
+ // The submitting account: the plugin-resolved signer (Hyperliquid's
516
+ // agent) when present, else the end-user's address.
517
+ signerAddress: signerAddress ?? address,
518
+ action,
519
+ actions: signed,
520
+ })
521
+ results = [...executed, ...response.results]
522
+ } catch (error) {
523
+ rethrowWithKnownResults(executed, error)
524
+ }
525
+ }
526
+ if (results.length === 0) {
527
+ return results
467
528
  }
468
- return signed
529
+
530
+ try {
531
+ results = this.resolveExplorerLinks(provider, results)
532
+ await this.notifyExecuteResults(provider, address, results)
533
+ } catch (error) {
534
+ rethrowWithKnownResults(results, error)
535
+ }
536
+ return results
469
537
  }
470
538
 
471
539
  /**
472
- * Let the plugin observe `/executeAction` per-step results before the core
473
- * surfaces failures — e.g. to evict a locally stored credential the venue
474
- * rejected.
540
+ * Let the plugin observe an execution report before the core returns it —
541
+ * e.g. to evict a locally stored credential the venue refused.
475
542
  */
476
543
  private async notifyExecuteResults(
477
544
  provider: string,
@@ -485,9 +552,10 @@ export class PerpsClient {
485
552
  }
486
553
 
487
554
  /**
488
- * Attach a provider-built explorer URL to every result the backend returned a
489
- * venue `txHash` on. The provider owns its explorer target, so core only asks
490
- * — a plugin without the hook leaves results untouched.
555
+ * Attach a provider-built explorer URL to every result that carries a venue
556
+ * `txHash`, whatever its status: an unacknowledged hash is what the user
557
+ * inspects. The provider owns its explorer target, so core only asks — a
558
+ * plugin without the hook leaves results untouched.
491
559
  */
492
560
  private resolveExplorerLinks(
493
561
  provider: string,
@@ -499,7 +567,7 @@ export class PerpsClient {
499
567
  return results
500
568
  }
501
569
  return results.map((result) => {
502
- if (!result.success || result.txHash === undefined) {
570
+ if (result.txHash === undefined) {
503
571
  return result
504
572
  }
505
573
  const explorerLink = resolveLink(result.txHash)
@@ -590,30 +658,47 @@ export class PerpsClient {
590
658
  }
591
659
 
592
660
  /**
593
- * Sign a single provider setup action step by delegating to the provider
594
- * plugin, which branches on the step's signing scheme internally. Lets
595
- * consumers collect signed setup actions without embedding per-method
596
- * signing logic.
661
+ * Sign one provider setup step through the provider plugin and submit it.
662
+ * A step the plugin executed client-side (e.g. Lighter's token-authenticated
663
+ * venue mutations) reports the plugin's own result instead of an
664
+ * `/executeAction` result.
597
665
  *
598
- * Returns `undefined` when the plugin executed the action entirely
599
- * client-side (e.g. Lighter's token-authenticated venue mutations), leaving
600
- * no backend-bound step to submit.
601
- *
602
- * @throws {PerpsError} When the step's action is not declared by the provider.
666
+ * @throws {PerpsError} When the step's action is not declared by the provider,
667
+ * or signing or submission fails before any result is known.
668
+ * @throws {PerpsExecutionError} When a later stage fails after a result is
669
+ * known.
603
670
  */
604
- private async signProviderSetupAction(
671
+ private async runProviderSetupStep(
605
672
  provider: string,
606
673
  address: Address,
607
674
  step: ActionStep
608
- ): Promise<SignedActionStep | undefined> {
675
+ ): Promise<ActionResult[]> {
609
676
  const metadata = await this.getProviderMetadata(provider)
610
- const [signed] = await this.delegateSignActions(
677
+ const descriptor = findActionDescriptor(metadata, step.action)
678
+ const signResult = await this.delegateSignActions(
611
679
  provider,
612
680
  address,
613
681
  metadata,
614
682
  [step]
615
683
  )
616
- return signed
684
+ let signerAddress: Address | undefined
685
+ try {
686
+ const request = await this.resolveActionRequest(
687
+ provider,
688
+ descriptor,
689
+ address
690
+ )
691
+ signerAddress = request.signerAddress
692
+ } catch (error) {
693
+ rethrowWithKnownResults(signResult.executed, error)
694
+ }
695
+ return this.submitSignedActions(
696
+ provider,
697
+ address,
698
+ step.action,
699
+ signerAddress,
700
+ signResult
701
+ )
617
702
  }
618
703
 
619
704
  /**
@@ -886,24 +971,12 @@ export class PerpsClient {
886
971
  if (asset === undefined) {
887
972
  return []
888
973
  }
889
- const minimum = asset.minWithdrawalAmount
890
- if (minimum !== undefined) {
891
- let floor: string
892
- try {
893
- floor = unknownToDecimalString(
894
- minimum,
895
- 'minWithdrawalAmount',
896
- 'perps-sdk'
897
- )
898
- } catch {
899
- throw new PerpsError(
900
- PerpsErrorCode.SDKError,
901
- `Asset '${asset.id}' field \`minWithdrawalAmount\` is not a valid decimal.`
902
- )
903
- }
904
- if (isDecimalStringGreaterThan(floor, row.available)) {
905
- return []
906
- }
974
+ const minimum = minWithdrawalAmountOf(asset)
975
+ if (
976
+ minimum !== undefined &&
977
+ isDecimalStringGreaterThan(minimum, row.available)
978
+ ) {
979
+ return []
907
980
  }
908
981
  if (row.withdrawalFee === undefined) {
909
982
  return [
@@ -939,12 +1012,16 @@ export class PerpsClient {
939
1012
  /**
940
1013
  * The withdrawal types `params.address` can choose per holding at
941
1014
  * `params.provider`, each with its cap and the `withdrawalOptions` to pass
942
- * unchanged in `WithdrawalParams`.
1015
+ * unchanged in `WithdrawalParams`. Every option whose `max` is below the
1016
+ * source asset's core `/assets` `minWithdrawalAmount` is removed, since no
1017
+ * amount can satisfy both limits; a source asset the provider's registry
1018
+ * does not carry keeps its options.
943
1019
  *
944
1020
  * @returns `undefined` when the registered plugin declares no withdrawal
945
1021
  * types read.
946
- * @throws {PerpsError} When the provider plugin is not registered, or when
947
- * the plugin read fails.
1022
+ * @throws {PerpsError} When the provider plugin is not registered, when
1023
+ * either the plugin read or the asset sync fails, or when a source asset's
1024
+ * `minWithdrawalAmount` is not a decimal.
948
1025
  * @public
949
1026
  */
950
1027
  async getWithdrawalTypes(
@@ -952,7 +1029,30 @@ export class PerpsClient {
952
1029
  options?: SDKRequestOptions
953
1030
  ): Promise<WithdrawalSourceTypes[] | undefined> {
954
1031
  const plugin = this.requireProvider(params.provider)
955
- return plugin.getWithdrawalTypes?.({ address: params.address }, options)
1032
+ const sources = await plugin.getWithdrawalTypes?.(
1033
+ { address: params.address },
1034
+ options
1035
+ )
1036
+ if (sources === undefined) {
1037
+ return undefined
1038
+ }
1039
+
1040
+ const registry = getAssetRegistry(this.sdkClient, params.provider)
1041
+ await registry.sync()
1042
+ return sources.map((row) => {
1043
+ const asset = registry.get(row.source.asset.id)
1044
+ const minimum =
1045
+ asset === undefined ? undefined : minWithdrawalAmountOf(asset)
1046
+ if (minimum === undefined) {
1047
+ return row
1048
+ }
1049
+ return {
1050
+ ...row,
1051
+ options: row.options.filter(
1052
+ (option) => !isDecimalStringGreaterThan(minimum, option.max)
1053
+ ),
1054
+ }
1055
+ })
956
1056
  }
957
1057
 
958
1058
  /**
@@ -1107,9 +1207,9 @@ export class PerpsClient {
1107
1207
  * deferred while any staged user-facing step with a lower `sequence` is
1108
1208
  * outstanding — it cannot succeed before its prerequisite (e.g. SET_REFERRAL
1109
1209
  * authenticates with the credential REGISTER_API_KEY installs) and each
1110
- * doomed attempt is venue traffic. A drain failure is swallowed so it never
1111
- * blocks setup — the step stays unsatisfied and is retried on a later
1112
- * `checkSetup`.
1210
+ * doomed attempt is venue traffic. A drain failure, thrown or reported, is
1211
+ * swallowed so it never blocks setup — the step stays unsatisfied and is
1212
+ * retried on a later `checkSetup`.
1113
1213
  */
1114
1214
  private async drainSetup(
1115
1215
  provider: string,
@@ -1131,18 +1231,20 @@ export class PerpsClient {
1131
1231
  descriptor,
1132
1232
  ])
1133
1233
  for (const step of steps) {
1134
- const signed = await this.signProviderSetupAction(
1234
+ const results = await this.runProviderSetupStep(
1135
1235
  provider,
1136
1236
  address,
1137
1237
  step
1138
1238
  )
1139
- if (signed !== undefined) {
1140
- await this.executeProviderSetup({
1141
- provider,
1142
- address,
1143
- setup: [step],
1144
- signedActions: [signed],
1145
- })
1239
+ const failure = results.find(
1240
+ (result) => !isSubmittedOrAccepted(result)
1241
+ )
1242
+ if (failure !== undefined) {
1243
+ console.debug(
1244
+ `[perps-sdk] setup step '${descriptor.type}' for '${provider}' reported '${failure.status}'; will retry on the next checkSetup.`,
1245
+ failure
1246
+ )
1247
+ break
1146
1248
  }
1147
1249
  }
1148
1250
  } catch (error) {
@@ -1221,49 +1323,6 @@ export class PerpsClient {
1221
1323
  return { actions }
1222
1324
  }
1223
1325
 
1224
- /**
1225
- * Submit the signed setup steps returned by `checkSetup` (and signed by the
1226
- * caller / `signProviderSetupAction`). Routes the batch on the first step's
1227
- * action and lets the plugin contribute that action's `signerAddress`.
1228
- * Throws on any per-step venue rejection.
1229
- */
1230
- private async executeProviderSetup(
1231
- params: ExecuteProviderSetupParams
1232
- ): Promise<ExecuteProviderSetupResult> {
1233
- const { provider, address, setup, signedActions } = params
1234
-
1235
- if (signedActions.length === 0) {
1236
- return { results: { results: [] } }
1237
- }
1238
-
1239
- const action = setup[0]?.action ?? signedActions[0].action
1240
- const metadata = await this.getProviderMetadata(provider)
1241
- const descriptor = findActionDescriptor(metadata, action)
1242
- const { signerAddress } = await this.resolveActionRequest(
1243
- provider,
1244
- descriptor,
1245
- address
1246
- )
1247
-
1248
- const response = await executeAction(this.sdkClient, {
1249
- provider,
1250
- address,
1251
- // The submitting account: the plugin-resolved signer (Hyperliquid's
1252
- // agent) when present, else the end-user's address.
1253
- signerAddress: signerAddress ?? address,
1254
- action,
1255
- actions: signedActions,
1256
- })
1257
-
1258
- const results = this.resolveExplorerLinks(provider, response.results)
1259
-
1260
- await this.notifyExecuteResults(provider, address, results)
1261
-
1262
- assertAllSucceeded(results)
1263
-
1264
- return { results: { results } }
1265
- }
1266
-
1267
1326
  /**
1268
1327
  * Sign and submit one pre-staged setup `ActionStep` end-to-end.
1269
1328
  *
@@ -1272,9 +1331,15 @@ export class PerpsClient {
1272
1331
  * prerequisites against that same snapshot, without another `createAction`
1273
1332
  * round-trip.
1274
1333
  *
1334
+ * Resolves to the execution report. A `Failed` or `Indeterminate` action is
1335
+ * a result in the report, not an exception.
1336
+ *
1275
1337
  * @throws {PerpsError} When the step's action is not in the provider's
1276
- * `setup` descriptors, or when a lower-`sequence` step on the same
1277
- * checklist, a choice included, is still unsatisfied.
1338
+ * `setup` descriptors, when a lower-`sequence` step on the same
1339
+ * checklist, a choice included, is still unsatisfied, or when signing or
1340
+ * submission fails before any result is known.
1341
+ * @throws {PerpsExecutionError} When a later stage fails after a result is
1342
+ * known; its `response` holds the known results.
1278
1343
  * @public
1279
1344
  */
1280
1345
  async executeProviderSetupAction(params: {
@@ -1282,7 +1347,7 @@ export class PerpsClient {
1282
1347
  address: Address
1283
1348
  step: ActionStep
1284
1349
  checklist: SetupChecklistItem[]
1285
- }): Promise<void> {
1350
+ }): Promise<ExecuteActionResponse> {
1286
1351
  const { provider, address, step, checklist } = params
1287
1352
 
1288
1353
  const metadata = await this.getProviderMetadata(provider)
@@ -1305,52 +1370,35 @@ export class PerpsClient {
1305
1370
  )
1306
1371
  }
1307
1372
 
1308
- const signed = await this.signProviderSetupAction(provider, address, step)
1309
-
1310
- // A client-executed setup action (Lighter SET_REFERRAL) produces no
1311
- // backend-bound step — it already ran during signing, so there is nothing
1312
- // to submit.
1313
- if (signed === undefined) {
1314
- return
1373
+ return {
1374
+ results: await this.runProviderSetupStep(provider, address, step),
1315
1375
  }
1316
-
1317
- await this.executeProviderSetup({
1318
- provider,
1319
- address,
1320
- setup: [step],
1321
- signedActions: [signed],
1322
- })
1323
1376
  }
1324
1377
 
1325
1378
  /**
1326
1379
  * Execute one option of a choice setup step (Lighter `ACCOUNT_TYPE`,
1327
1380
  * Hyperliquid `ACCOUNT_MODE`) end-to-end with its bound `{ type, params }`,
1328
- * throwing on a venue rejection.
1381
+ * through the same {@link execute} pipeline as a trade.
1329
1382
  *
1330
- * The option runs through the same {@link execute} pipeline as a trade, but
1331
- * a per-action `success: false` (returned as a 200 OK) means the user's
1332
- * selection was rejected and must surface, not be silently dropped.
1383
+ * Resolves to the execution report. Read each result's `status`: a `Failed`
1384
+ * or `Indeterminate` selection is a result, not an exception. `Submitted` and
1385
+ * `Accepted` mean the selection took effect.
1333
1386
  *
1334
- * @throws {PerpsError} Carrying the venue error when any returned result has
1335
- * `success: false`, under that result's `errorCode` when the backend
1336
- * classified the failure and `PerpsErrorCode.ExchangeRejected` otherwise;
1337
- * also the errors `execute` itself can throw (unregistered provider, no
1338
- * signer, signing failure).
1387
+ * @throws {PerpsError} The errors {@link execute} throws.
1339
1388
  * @public
1340
1389
  */
1341
1390
  async executeProviderOption(params: {
1342
1391
  provider: string
1343
1392
  address: Address
1344
1393
  option: SetupOption
1345
- }): Promise<void> {
1394
+ }): Promise<ExecuteActionResponse> {
1346
1395
  const { provider, address, option } = params
1347
- const { results } = await this.execute({
1396
+ return this.execute({
1348
1397
  provider,
1349
1398
  address,
1350
1399
  action: option.type,
1351
1400
  params: option.params,
1352
1401
  })
1353
- assertAllSucceeded(results)
1354
1402
  }
1355
1403
 
1356
1404
  /**
@@ -1358,16 +1406,18 @@ export class PerpsClient {
1358
1406
  * create, sign and execute, signed with that action's `Provider.actions`
1359
1407
  * descriptor. The step stages again on the next {@link checkSetup}.
1360
1408
  *
1409
+ * Resolves to the execution report.
1410
+ *
1361
1411
  * @throws {PerpsError} `SDKError` when `step.revoke` is `null` or when
1362
1412
  * `createAction` stages nothing to revoke; otherwise the errors
1363
- * {@link executeProviderOption} throws.
1413
+ * {@link execute} throws.
1364
1414
  * @public
1365
1415
  */
1366
1416
  async executeProviderRevoke(params: {
1367
1417
  provider: string
1368
1418
  address: Address
1369
1419
  step: SetupAction
1370
- }): Promise<void> {
1420
+ }): Promise<ExecuteActionResponse> {
1371
1421
  const { provider, address, step } = params
1372
1422
  if (step.revoke === null) {
1373
1423
  throw new PerpsError(
@@ -1387,7 +1437,7 @@ export class PerpsClient {
1387
1437
  `Nothing to revoke for setup step '${step.type}' on '${provider}'.`
1388
1438
  )
1389
1439
  }
1390
- assertAllSucceeded(results)
1440
+ return { results }
1391
1441
  }
1392
1442
 
1393
1443
  /**
@@ -1555,8 +1605,15 @@ export class PerpsClient {
1555
1605
  * descriptor's scheme and signer internally), and submit. Core stays
1556
1606
  * signer-agnostic — the plugin owns WHO signs and HOW.
1557
1607
  *
1608
+ * Resolves to the execution report: one result per executed step, in
1609
+ * execution order, each with its own `status`. An empty report means
1610
+ * nothing executed.
1611
+ *
1558
1612
  * @throws {PerpsError} When the action is not declared by the provider,
1559
- * the plugin cannot sign it, or submission fails.
1613
+ * the plugin cannot sign it, or submission fails before any result is
1614
+ * known.
1615
+ * @throws {PerpsExecutionError} When a later stage fails after a result is
1616
+ * known; its `response` holds the known results.
1560
1617
  * @public
1561
1618
  */
1562
1619
  async execute<T extends ActionType>(params: {
@@ -1598,7 +1655,7 @@ export class PerpsClient {
1598
1655
  } as ActionParamsMap[T],
1599
1656
  })
1600
1657
 
1601
- const signedActions = await this.delegateSignActions(
1658
+ const signResult = await this.delegateSignActions(
1602
1659
  provider,
1603
1660
  address,
1604
1661
  metadata,
@@ -1606,27 +1663,13 @@ export class PerpsClient {
1606
1663
  onProgress
1607
1664
  )
1608
1665
 
1609
- // A plugin may execute an action entirely client-side (e.g. Lighter's
1610
- // token-authenticated venue mutations), leaving no backend-bound step. With
1611
- // nothing to submit, skip the `/executeAction` hop.
1612
- if (signedActions.length === 0) {
1613
- return { staged: actions, results: [] }
1614
- }
1615
-
1616
- const response = await executeAction(this.sdkClient, {
1666
+ const results = await this.submitSignedActions(
1617
1667
  provider,
1618
1668
  address,
1619
- // The submitting account: the plugin-resolved signer (Hyperliquid's
1620
- // agent) when present, else the end-user's address.
1621
- signerAddress: signerAddress ?? address,
1622
1669
  action,
1623
- actions: signedActions,
1624
- })
1625
-
1626
- const results = this.resolveExplorerLinks(provider, response.results)
1627
-
1628
- await this.notifyExecuteResults(provider, address, results)
1629
-
1670
+ signerAddress,
1671
+ signResult
1672
+ )
1630
1673
  return { staged: actions, results }
1631
1674
  }
1632
1675
 
@@ -1682,12 +1725,13 @@ export class PerpsClient {
1682
1725
  * typed data with the configured user wallet.
1683
1726
  *
1684
1727
  * The backend returns at most one step. Resolves to `{ results: [] }` when it
1685
- * returns none, meaning no consent is outstanding for this address.
1728
+ * returns none, meaning no consent is outstanding for this address. Else it
1729
+ * resolves to the backend's execution report; read each result's `status`.
1686
1730
  *
1687
1731
  * @throws {PerpsError} When no user wallet is configured, the backend returns
1688
- * more than one step or a non-EIP-712 step, or the submitted step reports a
1689
- * failed result. A signature refusal from the wallet client propagates as
1690
- * the wallet's own error.
1732
+ * more than one step or a non-EIP-712 step, or the submission fails. A
1733
+ * signature refusal from the wallet client propagates as the wallet's own
1734
+ * error.
1691
1735
  * @public
1692
1736
  */
1693
1737
  async executeMetaAction<T extends MetaActionType>(
@@ -1722,21 +1766,11 @@ export class PerpsClient {
1722
1766
  const wallet = await this.resolveMetaSigningWallet(actions)
1723
1767
  const signature = await signTypedDataWithSigner(wallet, step.typedData)
1724
1768
 
1725
- const response = await executeAction(this.sdkClient, {
1769
+ return executeAction(this.sdkClient, {
1726
1770
  provider: META_PROVIDER,
1727
1771
  address,
1728
1772
  action,
1729
1773
  actions: [{ ...step, signature }],
1730
1774
  })
1731
-
1732
- const failure = response.results.find((r) => !r.success)
1733
- if (failure) {
1734
- throw new PerpsError(
1735
- failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
1736
- failure.error
1737
- )
1738
- }
1739
-
1740
- return response
1741
1775
  }
1742
1776
  }