@metamask-previews/perps-controller 18.0.1-preview-c92646a67 → 19.0.0-preview-cdde826

package/dist/PerpsController.js

@@ -6,16 +6,19 @@ import { VISIBLE_CANDLE_COUNT_CONFIG, } from './constants/chartConfig.js';
 import { PERPS_EVENT_PROPERTY, PERPS_EVENT_VALUE, } from './constants/eventNames.js';
 import { canonicalizeHyperLiquidDexes, MAINNET_HIP3_CONFIG, TESTNET_HIP3_CONFIG, USDC_SYMBOL, } from './constants/hyperLiquidConfig.js';
 import { PerpsMeasurementName } from './constants/performanceMetrics.js';
-import { PERPS_CONSTANTS, MARKET_SORTING_CONFIG, PROVIDER_CONFIG, buildProviderCacheKey, MAX_SLIPPAGE_BOUNDS, DEFAULT_PERPS_MODE, DEFAULT_ORDER_BOOK_PREFERENCES, DEFAULT_PRO_LAYOUT_PREFERENCES, DEFAULT_SELECTED_ORDER_TYPE, } from './constants/perpsConfig.js';
+import { PERPS_CONSTANTS, MARKET_SORTING_CONFIG, buildProviderCacheKey, MAX_SLIPPAGE_BOUNDS, DEFAULT_PERPS_MODE, DEFAULT_ORDER_BOOK_PREFERENCES, DEFAULT_PRO_LAYOUT_PREFERENCES, DEFAULT_SELECTED_ORDER_TYPE, } from './constants/perpsConfig.js';
 import { PERPS_ERROR_CODES } from './perpsErrorCodes.js';
 import { AggregatedPerpsProvider } from './providers/AggregatedPerpsProvider.js';
 import { HyperLiquidProvider } from './providers/HyperLiquidProvider.js';
 import { AccountService } from './services/AccountService.js';
+import { isMainAccountSignerReady } from './services/accountSigner.js';
+import { AgentBindings } from './services/agentSigner.js';
 import { DataLakeService } from './services/DataLakeService.js';
 import { DepositService } from './services/DepositService.js';
 import { EligibilityService } from './services/EligibilityService.js';
 import { FeatureFlagConfigurationService } from './services/FeatureFlagConfigurationService.js';
 import { MarketDataService } from './services/MarketDataService.js';
+import { isProviderOnTestnet } from './services/providerNetwork.js';
 import { RewardsIntegrationService } from './services/RewardsIntegrationService.js';
 import { TerminalMarketService } from './services/TerminalMarketService.js';
 import { TradingService } from './services/TradingService.js';
@@ -389,6 +392,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'calculateMaintenanceMargin',
     'cancelOrder',
     'cancelOrders',
+    'clearAgentSigners',
     'clearAttributionContext',
     'clearDepositResult',
     'clearPendingTradeConfiguration',
@@ -452,6 +456,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'markFirstOrderCompleted',
     'markTutorialCompleted',
     'placeOrder',
+    'prepareTradingWallet',
     'previewPositionModify',
     'reconnect',
     'recordMarketViewed',
@@ -470,6 +475,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'saveOrderBookGrouping',
     'savePendingTradeConfiguration',
     'saveTradeConfiguration',
+    'setAgentSigner',
     'setAttributionContext',
     'setLiveDataConfig',
     'setSelectedPaymentToken',
@@ -513,6 +519,8 @@ export class PerpsController extends BaseController {
     providers;
     isInitialized = false;
     #initializationPromise = null;
+    // Actions that saw a disconnect wait here for the client's follow-up init().
+    #initializationStartWaiters = new Set();
     #isReinitializing = false;
     #reinitializationOperationPromise = null;
     #disconnectOperationPromise = null;
@@ -588,6 +596,9 @@ export class PerpsController extends BaseController {
      */
     #standaloneProvider = null;
     #handlersRegistered = false;
+    // HyperLiquid agent bindings made through setAgentSigner, kept across
+    // provider instances; they answer before the host's getAgentSigner.
+    #agentBindings;
     #standaloneProviderIsTestnet = null;
     #standaloneProviderHip3Version = null;
     #standaloneProviderOperations = new Map();
@@ -636,6 +647,7 @@ export class PerpsController extends BaseController {
             clientConfig,
             infrastructure,
         };
+        this.#agentBindings = new AgentBindings(clientConfig?.providerCredentials?.hyperliquid?.getAgentSigner);
         // Instantiate services with platform dependencies
         // Services that need cross-controller access receive the messenger
         this.#tradingService = new TradingService(infrastructure);
@@ -1392,8 +1404,30 @@ export class PerpsController extends BaseController {
             return this.#initializationPromise;
         }
         this.#initializationPromise = this.#performInitialization();
+        this.#initializationStartWaiters.forEach((notifyStarted) => notifyStarted());
         return this.#initializationPromise;
     }
+    /**
+     * Resolve once a new initialization starts, or after the timeout.
+     *
+     * @param timeoutMs - Longest time to wait for init() to be called.
+     * @returns A promise that resolves when init starts or the timeout elapses.
+     */
+    async #waitForInitializationStart(timeoutMs) {
+        let notifyStarted = () => undefined;
+        const started = new Promise((resolve) => {
+            notifyStarted = resolve;
+        });
+        this.#initializationStartWaiters.add(notifyStarted);
+        const timeout = setTimeout(notifyStarted, timeoutMs);
+        try {
+            await started;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.#initializationStartWaiters.delete(notifyStarted);
+        }
+    }
     /**
      * Track a network or provider reinitialization so disconnect can serialize
      * behind the whole operation, including work before and after init().
@@ -1544,6 +1578,11 @@ export class PerpsController extends BaseController {
             subscriptionBuilderAddressMainnet: this.#options.clientConfig?.providerCredentials?.hyperliquid
                 ?.subscriptionBuilderAddressMainnet,
             onChaseOrderMaxDistanceReached: this.#publishChaseOrderMaxDistanceReached,
+            getAgentSigner: this.#agentBindings.resolve,
+            onAgentRejected: (account, agentAddress) => {
+                this.#agentBindings.release(account, agentAddress);
+                this.#options.clientConfig?.providerCredentials?.hyperliquid?.onAgentRejected?.(account, agentAddress);
+            },
         });
         this.providers.set('hyperliquid', hyperLiquidProvider);
         // Register Lighter provider if enabled (POC). Dynamic import so clients
@@ -1576,7 +1615,7 @@ export class PerpsController extends BaseController {
      * @param LighterProviderClass - Constructor class for the Lighter provider.
      */
     registerLighterProvider(LighterProviderClass) {
-        const lighterIsTestnet = PROVIDER_CONFIG.LIGHTER_TESTNET_ONLY || this.state.isTestnet;
+        const lighterIsTestnet = isProviderOnTestnet('lighter', this.state.isTestnet);
         const lighter = this.#options.clientConfig?.providerCredentials?.lighter ?? {};
         const lighterProvider = new LighterProviderClass({
             isTestnet: lighterIsTestnet,
@@ -1628,6 +1667,7 @@ export class PerpsController extends BaseController {
                 providers: this.providers,
                 defaultProvider: 'hyperliquid',
                 infrastructure: this.#options.infrastructure,
+                isTestnet: this.state.isTestnet,
             });
             this.#debugLog('PerpsController: Using aggregated provider (multi-provider)', { registeredProviders: Array.from(this.providers.keys()) });
         }
@@ -1812,9 +1852,16 @@ export class PerpsController extends BaseController {
      * @returns The active provider once initialization completes.
      */
     async #getActiveProviderWhenReady() {
+        // The context the action was issued under. A client reconnect
+        // (disconnect then init) that switches account, network or provider must
+        // not carry the action into the new context.
+        const issuedContext = this.#getActionContext();
+        let awaitedDisconnect = false;
+        let awaitedInitializationStart = false;
         while (true) {
             const pendingDisconnect = this.#disconnectOperationPromise;
             if (pendingDisconnect) {
+                awaitedDisconnect = true;
                 await pendingDisconnect;
                 continue;
             }
@@ -1829,9 +1876,37 @@ export class PerpsController extends BaseController {
                 await pendingInitialization;
                 continue;
             }
+            // Clients reconnect with disconnect() followed by init(), and the
+            // disconnect settles before init() is called. Give that init a bounded
+            // window to start rather than failing an action the reconnect will
+            // serve. Nothing here starts a connection the client did not ask for.
+            if (awaitedDisconnect &&
+                !awaitedInitializationStart &&
+                !this.isInitialized &&
+                !pendingInitialization) {
+                awaitedInitializationStart = true;
+                await this.#waitForInitializationStart(PERPS_CONSTANTS.ConnectionTimeoutMs);
+                continue;
+            }
+            if (awaitedDisconnect && this.#getActionContext() !== issuedContext) {
+                throw new Error(PERPS_ERROR_CODES.PROVIDER_LIFECYCLE_STALE);
+            }
             return this.getActiveProvider();
         }
     }
+    /**
+     * Identify the account, network and provider an action runs under.
+     *
+     * @returns A key that changes when any of them changes.
+     */
+    #getActionContext() {
+        const address = getSelectedEvmAccountFromMessenger(this.messenger)?.address;
+        return [
+            address?.toLowerCase() ?? '',
+            this.state.isTestnet ? 'testnet' : 'mainnet',
+            this.state.activeProvider,
+        ].join('|');
+    }
     /**
      * Get the currently active provider, returning null if not available
      * Use this method when the caller can gracefully handle a missing provider
@@ -4428,6 +4503,110 @@ export class PerpsController extends BaseController {
         });
         return this.#marketDataService.calculateFees({ provider, params, context });
     }
+    /**
+     * Sign HyperLiquid L1 actions (orders, cancels, leverage, ...) for a main
+     * account on a network with an approved agent, or pin them to the main
+     * account with null (`getAgentSigner` is then not asked for that account and
+     * network until `clearAgentSigners`). User-signed actions stay on the main
+     * account, and the agent is never used for another account or network. The
+     * controller keeps the binding across provider re-creation (a provider or
+     * network switch, or re-initialization), so it can also be set before
+     * `init`. Like every controller action, it is available through the
+     * messenger once `init` has run.
+     *
+     * @param account - The main account and network the agent is approved for.
+     * @param agentSigner - The host-owned agent signer, or null to pin the main
+     * account.
+     */
+    setAgentSigner(account, agentSigner) {
+        this.#agentBindings.set(account, agentSigner);
+        // Drop agents the providers already resolved so the binding applies to
+        // the next L1 action.
+        this.#clearProviderAgentSigners();
+    }
+    /**
+     * Forget every HyperLiquid agent, set or resolved, so the next L1 action
+     * asks `providerCredentials.hyperliquid.getAgentSigner` again; an answer
+     * still pending is discarded too. Call it when the wallet locks (with
+     * `getAgentSigner` returning null while locked) and nothing signs with an
+     * agent until it returns one again. Like every controller action, it is
+     * available through the messenger once `init` has run.
+     */
+    clearAgentSigners() {
+        this.#agentBindings.clear();
+        this.#clearProviderAgentSigners();
+    }
+    /**
+     * Drop the agents every provider resolved.
+     */
+    #clearProviderAgentSigners() {
+        for (const provider of this.providers.values()) {
+            provider.clearAgentSigners?.();
+        }
+    }
+    /**
+     * Run the active provider's deferred trading setup ahead of the first order
+     * (HyperLiquid account migration, builder fee and referral; Lighter
+     * venue-key registration), so its signatures happen in one guided session,
+     * such as agent setup, instead of at order time. The builder fee and
+     * Lighter's registration are signed by the main account; with an agent,
+     * the referral and the account migration are L1 actions the agent signs.
+     *
+     * @returns `ready: true` when none of these steps will need a signature
+     * again before the first order, and only while an account is selected and
+     * the main account can sign, whichever provider answered (including
+     * providers without deferred setup, for example in aggregated mode). A
+     * HyperLiquid referral whose MetaMask referral code is not ready yet is
+     * checked again at the next call, not before orders, so it does not hold
+     * it back. Otherwise `ready: false`, without an error while a step will
+     * be asked again (a declined HyperLiquid migration, builder fee or Lighter
+     * registration, or a step the agent could not sign), or with:
+     * - `KEYRING_LOCKED` when the main account cannot sign, before or during
+     * setup;
+     * - `EXCHANGE_ACCOUNT_NOT_FOUND` for a wallet with no account on the venue
+     * yet;
+     * - `NO_ACCOUNT_SELECTED` when no account is selected;
+     * - `PROVIDER_LIFECYCLE_STALE` when the provider disconnected or the account
+     * changed during setup;
+     * - otherwise the message of the error that stopped setup, which is logged.
+     * @throws Like the other provider-backed actions, `CLIENT_NOT_INITIALIZED`
+     * before `init`, and `CLIENT_REINITIALIZING` or `PROVIDER_NOT_AVAILABLE`
+     * when no active provider is available.
+     */
+    async prepareTradingWallet() {
+        const provider = await this.#getActiveProviderWhenReady();
+        // With nothing selected, the AccountsController answers an empty account.
+        const readSelectedAddress = () => {
+            const address = getSelectedEvmAccountFromMessenger(this.messenger)?.address;
+            return address ? address.toLowerCase() : undefined;
+        };
+        const addressAtStart = readSelectedAddress();
+        const result = (await provider.prepareTradingWallet?.()) ?? {
+            ready: true,
+        };
+        const address = readSelectedAddress();
+        // The steps ran for the account selected when they started (in aggregated
+        // mode, one provider after another), so their result is not the current
+        // account's.
+        if (address !== addressAtStart) {
+            return {
+                ready: false,
+                error: PERPS_ERROR_CODES.PROVIDER_LIFECYCLE_STALE,
+            };
+        }
+        if (!result.ready) {
+            return result;
+        }
+        // A provider with nothing to prepare, alone or aggregated, checks neither
+        // the signer nor the selected account.
+        if (!isMainAccountSignerReady(this.#options.infrastructure.accountSigner, () => this.messenger.call('KeyringController:getState').isUnlocked)) {
+            return { ready: false, error: PERPS_ERROR_CODES.KEYRING_LOCKED };
+        }
+        if (!address) {
+            return { ready: false, error: PERPS_ERROR_CODES.NO_ACCOUNT_SELECTED };
+        }
+        return result;
+    }
     /**
      * Approve the dedicated subscription builder outside order submission.
      *