@lifi/perps-sdk 0.0.0-preview-13dcf3c7 → 0.0.0-preview-e0a0e165

package/src/client/PerpsClient.ts

@@ -30,6 +30,7 @@ import {
   PerpsErrorCode,
   PerpsSigner,
   SigningMethod,
+  UserActionStatus,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { isDecimalStringGreaterThan } from '../decimal/compare.js'
@@ -494,7 +495,8 @@ export class PerpsClient {
    * Submit `signed` to `/executeAction` when every step the plugin executed
    * while signing was acknowledged, then resolve explorer links and notify the
    * plugin. Resolves to the full report: `executed`, then the `/executeAction`
-   * results. An empty report means nothing executed.
+   * results, with `retry` set when the plugin asked for one more attempt. An
+   * empty report means nothing executed.
    *
    * @throws {PerpsExecutionError} When the submission or the plugin callback
    *   throws after a result is known.
@@ -505,7 +507,7 @@ export class PerpsClient {
     action: ActionType,
     signerAddress: Address | undefined,
     { signed, executed }: SignActionsResult
-  ): Promise<ActionResult[]> {
+  ): Promise<{ results: ActionResult[]; retry: boolean }> {
     let results = executed
     if (signed.length > 0 && executed.every(isSubmittedOrAccepted)) {
       try {
@@ -524,31 +526,34 @@ export class PerpsClient {
       }
     }
     if (results.length === 0) {
-      return results
+      return { results, retry: false }
     }
 
+    let retry = false
     try {
       results = this.resolveExplorerLinks(provider, results)
-      await this.notifyExecuteResults(provider, address, results)
+      retry = await this.notifyExecuteResults(provider, address, results)
     } catch (error) {
       rethrowWithKnownResults(results, error)
     }
-    return results
+    return { results, retry }
   }
 
   /**
    * Let the plugin observe an execution report before the core returns it —
-   * e.g. to evict a locally stored credential the venue refused.
+   * e.g. to evict a locally stored credential the venue refused. Resolves
+   * `true` when the plugin asks for one more attempt.
    */
   private async notifyExecuteResults(
     provider: string,
     address: Address,
     results: ActionResult[]
-  ): Promise<void> {
+  ): Promise<boolean> {
     const plugin = this.requireProvider(provider)
-    if (typeof plugin.onExecuteResults === 'function') {
-      await plugin.onExecuteResults(address, results)
+    if (typeof plugin.onExecuteResults !== 'function') {
+      return false
     }
+    return (await plugin.onExecuteResults(address, results)) === 'retry'
   }
 
   /**
@@ -692,13 +697,14 @@ export class PerpsClient {
     } catch (error) {
       rethrowWithKnownResults(signResult.executed, error)
     }
-    return this.submitSignedActions(
+    const { results } = await this.submitSignedActions(
       provider,
       address,
       step.action,
       signerAddress,
       signResult
     )
+    return results
   }
 
   /**
@@ -1629,7 +1635,11 @@ export class PerpsClient {
     return { results }
   }
 
-  /** {@link execute}, also returning the steps `createAction` staged. */
+  /**
+   * {@link execute}, also returning the steps `createAction` staged. Runs the
+   * action once more when the plugin asks for it and nothing took effect; the
+   * second attempt's report is the answer.
+   */
   private async runAction<T extends ActionType>(params: {
     provider: string
     address: Address
@@ -1637,6 +1647,27 @@ export class PerpsClient {
     params: ActionParamsMap[T]
     onProgress?: (progress: SignActionProgress) => void
   }): Promise<{ staged: ActionStep[]; results: ActionResult[] }> {
+    const first = await this.attemptAction(params)
+    const nothingApplied = first.results.every(
+      (result) => result.status === UserActionStatus.Failed
+    )
+    const { staged, results } =
+      first.retry && nothingApplied ? await this.attemptAction(params) : first
+    return { staged, results }
+  }
+
+  /** Create, sign and submit `action` once. */
+  private async attemptAction<T extends ActionType>(params: {
+    provider: string
+    address: Address
+    action: T
+    params: ActionParamsMap[T]
+    onProgress?: (progress: SignActionProgress) => void
+  }): Promise<{
+    staged: ActionStep[]
+    results: ActionResult[]
+    retry: boolean
+  }> {
     const { provider, address, action, onProgress } = params
     const metadata = await this.getProviderMetadata(provider)
     const descriptor = findActionDescriptor(metadata, action)
@@ -1663,14 +1694,14 @@ export class PerpsClient {
       onProgress
     )
 
-    const results = await this.submitSignedActions(
+    const { results, retry } = await this.submitSignedActions(
       provider,
       address,
       action,
       signerAddress,
       signResult
     )
-    return { staged: actions, results }
+    return { staged: actions, results, retry }
   }
 
   /**

package/src/services/getMeta.ts

@@ -4,9 +4,12 @@ import type { SDKRequestOptions } from '../types/config.js'
 import type { PerpsSDKClient } from '../types/provider.js'
 
 /**
- * Get platform metadata: the API version and any active platform-level notices.
+ * Get platform metadata: the API version and the notices the backend serves.
+ * A notice without `providerKeys` is global; a notice with `providerKeys` is
+ * scoped to those providers. The SDK returns notices as served and does not
+ * filter them by `validFrom` / `validTo`.
  *
- * @returns Platform version and the list of active notices
+ * @returns Platform version and the global and provider-scoped notices
  * @throws {PerpsError} On API error responses
  * @throws {PerpsError} On network or parsing errors
  *

package/src/types/provider.ts

@@ -758,9 +758,14 @@ export interface PerpsProviderPlugin {
    * Observe the execution report of each `execute` call: the results of the
    * steps the plugin executed while signing, then the `/executeAction`
    * results. Lets a provider react to structured statuses — e.g. evicting a
-   * locally stored credential the venue refused.
+   * locally stored credential the venue refused. Resolve to `'retry'` to have
+   * core create, sign and execute the action once more; core retries at most
+   * once per `execute`, and only when every result is `Failed`.
    */
-  onExecuteResults?(address: Address, results: ActionResult[]): Promise<void>
+  onExecuteResults?(
+    address: Address,
+    results: ActionResult[]
+  ): Promise<'retry' | void>
 
   /**
    * Resolve a venue transaction hash to a block-explorer URL. Core calls it for

package/src/types/withdrawal.ts

@@ -16,7 +16,13 @@ import type { Address } from 'viem'
 export interface ProviderWithdrawableBalance {
   /** Provider-native `Asset.id`; never a display symbol. */
   assetId: string
-  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  /**
+   * The withdrawal route: the provider category that a withdrawal from this row
+   * names. On a pooled account, a row can name a category that has no `Balance`
+   * row of the same asset. For example, a pooled collateral asset is one `spot`
+   * `Balance` row, but its withdrawable row names a `perps` or `hyperliquid`
+   * route. Do not join a withdrawable row to a `Balance` row by this value.
+   */
   categoryId: string
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
   available: DecimalString
@@ -49,7 +55,13 @@ export interface ProviderWithdrawableBalance {
  */
 export interface WithdrawableBalance {
   asset: Asset
-  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  /**
+   * The withdrawal route: the provider category that a withdrawal from this row
+   * names. On a pooled account, a row can name a category that has no `Balance`
+   * row of the same asset. For example, a pooled collateral asset is one `spot`
+   * `Balance` row, but its withdrawable row names a `perps` or `hyperliquid`
+   * route. Do not join a withdrawable row to a `Balance` row by this value.
+   */
   categoryId: string
   /** Withdrawable amount in the asset's own units. */
   available: DecimalString

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '0.0.0-preview-13dcf3c7'
+export const version = '0.0.0-preview-e0a0e165'