Skip to content

feat(perps): perps-controller: let web clients load the Lighter venue - #10996

Merged
abretonc7s merged 3 commits into
mainfrom
TAT-4206-feat-perps-controller-let-web-clien
Oct 23, 2026
Merged

abretonc7s merged 3 commits into
mainfrom
TAT-4206-feat-perps-controller-let-web-clien

Conversation

@abretonc7s

@abretonc7s abretonc7s commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

Terminal (Next.js) cannot use the controller's Lighter venue. PerpsController#createProviders loads it with import(/* webpackIgnore: true */ lighterModulePath). Turbopack leaves that as a native import, the browser resolves it against the chunk URL, gets a 404 and rejects with Failed to fetch dynamically imported module. Node ESM consumers of dist/ fail the same way (ERR_MODULE_NOT_FOUND, no .js extension). handleLighterImportError only expected MODULE_NOT_FOUND, so the failure went to logger.error, Lighter was never registered and switchProvider('lighter') returned Provider lighter not available.

webpackIgnore stays. It was added (#8398, #8424, then #9889 for Lighter) so webpack never resolves the provider import, and the variable path keeps Metro from bundling it (#10405). The extension must keep bundling no Lighter code.

The fix is client injection:

  • New @metamask/perps-controller/providers/lighter export (LighterProvider only).
  • New optional providerCredentials.lighter.loadProvider. A web client passes () => import('@metamask/perps-controller/providers/lighter'), so its own bundler code-splits Lighter. Only clients that import that path bundle it.
  • Without loadProvider the controller keeps its own bundler-ignored import, unchanged. Mobile and the extension need no change.
  • A failed load now gives switchProvider('lighter') the cause instead of only Provider lighter not available, and names providerCredentials.lighter.loadProvider when the client passed none. A module that cannot be found or fetched (MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, a browser Failed to fetch dynamically imported module) is debug-logged like MODULE_NOT_FOUND was. Other load failures, such as a chunk error from the client's loader, and errors from the provider constructor still go to logger.error.

References

  • TAT-4206, unblocks TAT-4193 (Terminal Lighter wiring)

Proof (recipe on core, testnet, read-only):

  • Next.js 16.4.0 (Turbopack) production build running in headless Chrome: with loadProvider, Lighter loads from a chunk the page doesn't fetch up front, switchProvider('lighter') succeeds, and 3 Lighter testnet markets come back through getMarkets. Without a loader, the same page reproduces the reported 404 on /_next/static/chunks/providers/LighterProvider and now returns the clear switchProvider error, with no logger.error and no unhandled rejection.
  • A Node client using the built package's exports gets the same result.
  • Remote perpsLighterProviderEnabled gate: with the flag off, loadProvider is never called and Lighter stays unavailable, as before. With the flag on, Lighter loads through loadProvider.
  • Real extension production build (yarn build, LavaMoat webpack) with this package: 226 JS files, none containing Lighter provider code. The controller keeps its Lighter import ignored by the bundler.
  • Real Mobile Metro production bundle and yarn lint:tsc, with this package and with core main's: both bundles ship the controller and Lighter. Both typechecks report the same 11 errors (Mobile still targets 19.x of this package), so this change adds none.
  • Without a loader (Mobile-style resolution), Lighter still registers and reads its markets.

Not covered here: running the Mobile app or the extension. AC-2 is checked at build, bundle and typecheck level. Terminal wiring stays in TAT-4193.

Validation Recipe

recipe.json (27 nodes — Web clients load the Lighter venue — Core)
{
  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
  "title": "Web clients load the Lighter venue — Core",
  "description": "TAT-4206. A web client (Terminal, Next.js) hands PerpsController a loader for the public @metamask/perps-controller/providers/lighter export, so its own bundler code-splits Lighter, the venue registers, switchProvider('lighter') succeeds and Lighter testnet markets are read through the controller, in Node and in a Next.js 16 (Turbopack) production build running in headless Chrome. Extension-style webpack builds keep emitting no Lighter code, the bundler-ignored default import Mobile relies on is unchanged, the remote perpsLighterProviderEnabled flag still gates loading, and a failed load is handled with a clear error. Real Mobile and extension builds are declared as an unresolved sub-claim. Read-only testnet market data; no orders or funds.",
  "paramsSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "client_build_dir": {
        "type": "string",
        "default": "none",
        "description": "Directory with real client outputs built against this package: extension/ (extension production dist), mobile/ (Mobile Metro production bundle), mobile-base/ (the same bundle with core main's package) and mobile-typecheck/{head,base}.log (`yarn lint:tsc` with each). 'none' in a core-only slot without client checkouts; the real-client claim then stays unresolved for the gateway."
      }
    }
  },
  "proofTargets": [
    {
      "id": "AC-1",
      "claim": "[TAT-4206] A Next.js client with Lighter enabled gets the Lighter provider registered, and switchProvider('lighter') succeeds."
    },
    {
      "id": "AC-2",
      "claim": "[TAT-4206] Mobile and the extension still build and behave the same, and the extension bundle does not load Lighter unless it is enabled."
    },
    {
      "id": "AC-3",
      "claim": "[TAT-4206] A failed load gives a clear, handled error instead of an unhandled fetch failure."
    },
    {
      "id": "AC-4",
      "claim": "[TAT-4206] Proven end to end with a recipe on core (Lighter registered and market data read through the controller), not only unit tests."
    },
    {
      "id": "AC-1.next-runtime",
      "kind": "qa-check",
      "parentId": "AC-1",
      "claim": "In a Next.js 16 (Turbopack) production build running in Chrome, a client passing loadProvider for @metamask/perps-controller/providers/lighter gets Lighter registered from an on-demand chunk, switchProvider('lighter') succeeds and Lighter testnet markets are read."
    },
    {
      "id": "AC-1.flag-on",
      "kind": "qa-check",
      "parentId": "AC-1",
      "claim": "With Lighter enabled only by the remote perpsLighterProviderEnabled flag (client signer bridge mounted), the controller calls loadProvider, registers Lighter and switchProvider('lighter') succeeds."
    },
    {
      "id": "AC-2.flag-off",
      "kind": "qa-check",
      "parentId": "AC-2",
      "claim": "With the remote perpsLighterProviderEnabled flag off, the controller never calls loadProvider or loads Lighter, and switchProvider('lighter') reports Lighter unavailable, as before."
    },
    {
      "id": "AC-2.client-builds",
      "kind": "qa-check",
      "parentId": "AC-2",
      "claim": "Real client builds with this package: a MetaMask extension production build (LavaMoat webpack) carries the controller and no Lighter provider code; the Mobile Metro production bundle carries the controller and still ships the Lighter provider, as it does with core main's package; and the Mobile typecheck reports no error beyond those it reports with core main's package."
    }
  ],
  "workflow": {
    "entry": "setup-build-perps-controller",
    "nodes": {
      "setup-build-perps-controller": {
        "action": "command",
        "cmd": "yarn workspace @metamask/perps-controller run build",
        "timeout_ms": 300000,
        "intent": "The published build of the Perps controller matches the source under test",
        "next": "gate-dist-variable-path"
      },
      "gate-dist-variable-path": {
        "action": "assert_file",
        "path": "packages/perps-controller/dist/PerpsController.js",
        "contains": "const lighterModulePath = './providers/LighterProvider';",
        "intent": "The built controller still names the Lighter module through a variable Metro cannot resolve statically",
        "proves": [
          "AC-2"
        ],
        "next": "gate-dist-webpack-ignore"
      },
      "gate-dist-webpack-ignore": {
        "action": "assert_file",
        "path": "packages/perps-controller/dist/PerpsController.js",
        "contains": "/* webpackIgnore: true */ lighterModulePath",
        "intent": "The built controller's own Lighter import still tells webpack to leave it alone",
        "proves": [
          "AC-2"
        ],
        "next": "ac2-extension-bundle"
      },
      "ac2-extension-bundle": {
        "action": "command",
        "timeout_ms": 300000,
        "intent": "An extension-style client bundles the Perps controller with webpack",
        "next": "ac2-assert-extension-no-lighter"
      },
      "ac2-assert-extension-no-lighter": {
        "action": "assert_output",
        "source": "ac2-extension-bundle",
        "stream": "stdout",
        "contains": "CHECK bundle.extension.errors=0\nCHECK bundle.extension.assets=1\nCHECK bundle.extension.asyncChunks=0\nCHECK bundle.extension.controllerInInitial=true\nCHECK bundle.extension.initialLighterModules=0\nCHECK bundle.extension.asyncLighterModules=0\nCHECK bundle.extension.initialLighterMarker=false\nCHECK bundle.extension.asyncLighterMarker=false\nCHECK bundle.extension.nativeLighterImport=true\n",
        "intent": "The extension bundle carries the controller but no Lighter provider module, chunk or code",
        "proves": [
          "AC-2"
        ],
        "next": "ac2-mobile-default-path"
      },
      "ac2-mobile-default-path": {
        "action": "command",
        "timeout_ms": 180000,
        "intent": "A Mobile-style client enables Lighter without a loader and switches to it",
        "next": "ac2-assert-mobile-default-path"
      },
      "ac2-assert-mobile-default-path": {
        "action": "assert_output",
        "source": "ac2-mobile-default-path",
        "stream": "stdout",
        "match": "CHECK ac2\\.mobile\\.initializationState=initialized\\nCHECK ac2\\.mobile\\.switch\\.success=true\\nCHECK ac2\\.mobile\\.switch\\.error=none\\nCHECK ac2\\.mobile\\.activeProvider=lighter\\nCHECK ac2\\.mobile\\.markets\\.count=[1-9][0-9]*\\nCHECK ac2\\.mobile\\.unhandled=0\\n",
        "intent": "Without a loader, Mobile-style resolution still registers Lighter and reads its markets",
        "proves": [
          "AC-2"
        ],
        "next": "ac1-web-client-run"
      },
      "ac1-web-client-run": {
        "action": "command",
        "timeout_ms": 180000,
        "intent": "A web client loads Lighter through the public export, switches to it and reads its markets",
        "next": "ac1-assert-switch"
      },
      "ac1-assert-switch": {
        "action": "assert_output",
        "source": "ac1-web-client-run",
        "stream": "stdout",
        "match": "CHECK ac1\\.loaderCalls=[1-9][0-9]*\\nCHECK ac1\\.initializationState=initialized\\nCHECK ac1\\.switch\\.success=true\\nCHECK ac1\\.switch\\.error=none\\nCHECK ac1\\.activeProvider=lighter\\n",
        "intent": "The web client's Lighter loader ran, Lighter registered and the switch to Lighter succeeded",
        "proves": [
          "AC-1"
        ],
        "next": "ac4-assert-lighter-markets"
      },
      "ac4-assert-lighter-markets": {
        "action": "assert_output",
        "source": "ac1-web-client-run",
        "stream": "stdout",
        "match": "CHECK ac4\\.markets\\.count=[1-9][0-9]*\\nCHECK ac4\\.markets\\.providerIds=lighter\\nCHECK ac4\\.lighterMarketsRead=true\\nCHECK ac1\\.unhandled=0\\n",
        "intent": "Lighter testnet markets come back through the controller, every one stamped as Lighter",
        "proves": [
          "AC-4",
          "AC-1"
        ],
        "next": "ac1-web-bundle"
      },
      "ac1-web-bundle": {
        "action": "command",
        "timeout_ms": 300000,
        "intent": "A Terminal-style client bundles the controller plus the public Lighter export with webpack",
        "next": "ac1-assert-web-bundle-split"
      },
      "ac1-assert-web-bundle-split": {
        "action": "assert_output",
        "source": "ac1-web-bundle",
        "stream": "stdout",
        "match": "CHECK bundle\\.web-client\\.errors=0\\nCHECK bundle\\.web-client\\.assets=[2-9]\\nCHECK bundle\\.web-client\\.asyncChunks=[1-9]\\nCHECK bundle\\.web-client\\.controllerInInitial=true\\nCHECK bundle\\.web-client\\.initialLighterModules=0\\nCHECK bundle\\.web-client\\.asyncLighterModules=1\\nCHECK bundle\\.web-client\\.initialLighterMarker=false\\nCHECK bundle\\.web-client\\.asyncLighterMarker=true\\n",
        "intent": "The bundler resolves the public Lighter export into its own async chunk, outside the main bundle",
        "proves": [
          "AC-1",
          "AC-2"
        ],
        "next": "ac3-failed-load-run"
      },
      "ac3-failed-load-run": {
        "action": "command",
        "timeout_ms": 180000,
        "intent": "A web client enables Lighter but the Lighter module cannot be loaded",
        "next": "ac3-assert-default-import-failure"
      },
      "ac3-assert-default-import-failure": {
        "action": "assert_output",
        "source": "ac3-failed-load-run",
        "stream": "stdout",
        "match": "CHECK ac3\\.default\\.initializationState=initialized\\nCHECK ac3\\.default\\.switch\\.success=false\\nCHECK ac3\\.default\\.activeProvider=hyperliquid\\nCHECK ac3\\.default\\.loggerErrors=0\\nCHECK ac3\\.default\\.error=Provider lighter not available: Lighter provider failed to load \\(Cannot find module [^\\n]*\\)\\. Pass providerCredentials\\.lighter\\.loadProvider[^\\n]*\\n",
        "intent": "When the controller's own import cannot resolve, the switch to Lighter explains why and names the fix",
        "proves": [
          "AC-3"
        ],
        "next": "ac3-assert-fetch-failure"
      },
      "ac3-assert-fetch-failure": {
        "action": "assert_output",
        "source": "ac3-failed-load-run",
        "stream": "stdout",
        "match": "CHECK ac3\\.fetch\\.initializationState=initialized\\nCHECK ac3\\.fetch\\.switch\\.success=false\\nCHECK ac3\\.fetch\\.activeProvider=hyperliquid\\nCHECK ac3\\.fetch\\.loggerErrors=0\\nCHECK ac3\\.fetch\\.error=Provider lighter not available: Lighter provider failed to load \\(Failed to fetch dynamically imported module: [^\\n]*\\)\\.\\nCHECK ac3\\.unhandled=0\\n",
        "intent": "When the browser cannot fetch the module the client's loader imports, the failure is handled and the switch to Lighter explains why",
        "proves": [
          "AC-3"
        ],
        "next": "gate-client-builds"
      },
      "ac2-flag-off-run": {
        "action": "command",
        "timeout_ms": 180000,
        "intent": "A client with a signer bridge runs with the remote Lighter flag off",
        "next": "ac2-assert-flag-off"
      },
      "ac2-assert-flag-off": {
        "action": "assert_output",
        "source": "ac2-flag-off-run",
        "stream": "stdout",
        "match": "CHECK flag\\.off\\.loaderCalls=0\\nCHECK flag\\.off\\.initializationState=initialized\\nCHECK flag\\.off\\.switch\\.success=false\\nCHECK flag\\.off\\.switch\\.error=Provider lighter not available\\nCHECK flag\\.off\\.activeProvider=hyperliquid\\nCHECK flag\\.off\\.lighterMarkets=0\\nCHECK flag\\.off\\.loggerErrors=0\\nCHECK flag\\.off\\.signerBridgeCalls=0\\nCHECK flag\\.off\\.unhandled=0\\n",
        "intent": "With the flag off, Lighter is never loaded and stays unavailable",
        "proves": [
          "AC-2.flag-off"
        ],
        "next": "ac1-flag-on-run"
      },
      "ac1-flag-on-run": {
        "action": "command",
        "timeout_ms": 180000,
        "intent": "The same client runs with the remote Lighter flag on",
        "next": "ac1-assert-flag-on"
      },
      "ac1-assert-flag-on": {
        "action": "assert_output",
        "source": "ac1-flag-on-run",
        "stream": "stdout",
        "match": "CHECK flag\\.on\\.loaderCalls=[1-9][0-9]*\\nCHECK flag\\.on\\.initializationState=initialized\\nCHECK flag\\.on\\.switch\\.success=true\\nCHECK flag\\.on\\.switch\\.error=none\\nCHECK flag\\.on\\.activeProvider=lighter\\nCHECK flag\\.on\\.lighterMarkets=[1-9][0-9]*\\nCHECK flag\\.on\\.loggerErrors=0\\nCHECK flag\\.on\\.signerBridgeCalls=0\\nCHECK flag\\.on\\.unhandled=0\\n",
        "intent": "With the flag on, Lighter loads through the client's loader and the switch succeeds",
        "proves": [
          "AC-1.flag-on"
        ],
        "next": "ac1-next-run"
      },
      "ac1-next-run": {
        "action": "command",
        "timeout_ms": 900000,
        "intent": "A Next.js client is built with Turbopack and opened in Chrome",
        "next": "ac1-assert-next-build"
      },
      "ac1-assert-next-build": {
        "action": "assert_output",
        "source": "ac1-next-run",
        "stream": "stdout",
        "match": "CHECK next\\.version=16\\.4\\.0\\nCHECK next\\.build\\.exit=0\\nCHECK next\\.build\\.turbopack=true\\nCHECK next\\.lighterChunks=[1-9][0-9]*\\nCHECK next\\.initialLighterChunks=0\\nCHECK next\\.page\\.status=done\\n",
        "intent": "Turbopack builds the client and keeps Lighter out of the chunks the page loads up front",
        "proves": [
          "AC-1.next-runtime"
        ],
        "next": "ac1-assert-next-runtime"
      },
      "ac1-assert-next-runtime": {
        "action": "assert_output",
        "source": "ac1-next-run",
        "stream": "stdout",
        "match": "CHECK next\\.loader\\.loaderCalls=[1-9][0-9]*\\nCHECK next\\.loader\\.initializationState=initialized\\nCHECK next\\.loader\\.switch\\.success=true\\nCHECK next\\.loader\\.switch\\.error=none\\nCHECK next\\.loader\\.activeProvider=lighter\\nCHECK next\\.loader\\.markets\\.count=[1-9][0-9]*\\nCHECK next\\.loader\\.markets\\.providerIds=lighter\\nCHECK next\\.loader\\.lighterChunkFetched=true\\n",
        "intent": "In the browser, Lighter registers from its on-demand chunk, the switch succeeds and Lighter markets are read",
        "proves": [
          "AC-1.next-runtime",
          "AC-4"
        ],
        "next": "ac3-assert-next-fetch-failure"
      },
      "ac3-assert-next-fetch-failure": {
        "action": "assert_output",
        "source": "ac1-next-run",
        "stream": "stdout",
        "match": "CHECK next\\.default\\.lighterProvider404=true\\nCHECK next\\.default\\.initializationState=initialized\\nCHECK next\\.default\\.switch\\.success=false\\nCHECK next\\.default\\.loggerErrors=0\\nCHECK next\\.default\\.error=Provider lighter not available: Lighter provider failed to load \\(Failed to fetch dynamically imported module: [^\\n]*/_next/static/chunks/providers/LighterProvider\\)\\. Pass providerCredentials\\.lighter\\.loadProvider[^\\n]*\\nCHECK next\\.unhandled=0\\n",
        "intent": "In the browser without a loader, the 404 on the ignored import is handled and the switch to Lighter explains why",
        "proves": [
          "AC-3"
        ],
        "next": "done"
      },
      "done": {
        "action": "end",
        "status": "pass"
      },
      "gate-client-builds": {
        "action": "switch",
        "value": "{{params.client_build_dir}}",
        "equals": "none",
        "cases": {
          "match": "ac2-flag-off-run"
        },
        "default": "ac2-client-builds-run",
        "intent": "Check real client builds only when their outputs are supplied"
      },
      "ac2-client-builds-run": {
        "action": "command",
        "timeout_ms": 120000,
        "intent": "Real extension and Mobile build outputs of this package are scanned for the controller and Lighter code",
        "next": "ac2-assert-client-builds"
      },
      "ac2-assert-client-builds": {
        "action": "assert_output",
        "source": "ac2-client-builds-run",
        "stream": "stdout",
        "match": "CHECK clientBuilds\\.extension\\.files=[1-9][0-9]*\\nCHECK clientBuilds\\.extension\\.controllerPresent=true\\nCHECK clientBuilds\\.extension\\.lighterProviderFiles=0\\nCHECK clientBuilds\\.mobile\\.files=[1-9][0-9]*\\nCHECK clientBuilds\\.mobile\\.controllerPresent=true\\nCHECK clientBuilds\\.mobile\\.lighterProviderPresent=true\\nCHECK clientBuilds\\.mobileBase\\.controllerPresent=true\\nCHECK clientBuilds\\.mobileBase\\.lighterProviderPresent=true\\nCHECK clientBuilds\\.mobileTypecheck\\.headErrors=[0-9]+\\nCHECK clientBuilds\\.mobileTypecheck\\.baseErrors=[0-9]+\\nCHECK clientBuilds\\.mobileTypecheck\\.newErrors=0\\n",
        "intent": "The extension production build has no Lighter provider code, and Mobile bundles and typechecks the same as with core main's package",
        "proves": [
          "AC-2.client-builds"
        ],
        "next": "ac2-flag-off-run"
      }
    }
  }
}

Validation Logs

Run: cac1d604-d181-4af5-8d90-f9486a518e24

Runner: @metamask/recipe-runner

Runner revision: unknown

Recipe digest: sha256:c1d8da0896b357f0e6c9a0ffa7ad1400af668bd10a53f011a8b844d085dc518a

Full output (27/27 passed, pass)
# MetaMask Recipe Run

Status: pass
Duration: 75s
Nodes: 27/27 passed

## Steps
- PASS setup-build-perps-controller (command, 3.3s): exitCode=0
- PASS gate-dist-variable-path (assert_file, 174ms): path=packages/perps-controller/dist/PerpsController.js
- PASS gate-dist-webpack-ignore (assert_file, 129ms): path=packages/perps-controller/dist/PerpsController.js
- PASS ac2-extension-bundle (command, 10s): exitCode=0, stdout=CHECK bundle.extension.errors=0
CHECK bundle.extension.assets=1
CHECK bundle.extension.asyncChunks=0
CHECK bundle.extension.controllerInInitial=true
CHECK bundle.extension.initialLighterModules=0
CHECK bundle.extension.asyncLighterModules=0
CHECK bundle.extension.initialLighterMarker=false
CHECK bundle.extension.asyncLighterMarker=false
CHECK bundle.extension.nativeLighterImport=true

- PASS ac2-assert-extension-no-lighter (assert_output, 93ms): source=ac2-extension-bundle, stream=stdout, contains=CHECK bundle.extension.errors=0
CHECK bundle.extension.assets=1
CHECK bundle.extension.asyncChunks=0
CHECK bundle.extension.controllerInInitial=true
CHECK bundle.extension.initialLighterModules=0
CHECK bundle.extension.asyncLighterModules=0
CHECK bundle.extension.initialLighterMarker=false
CHECK bundle.extension.asyncLighterMarker=false
CHECK bundle.extension.nativeLighterImport=true

- PASS ac2-mobile-default-path (command, 5.1s): exitCode=0, stdout=CHECK ac2.mobile.initializationState=initialized
CHECK ac2.mobile.switch.success=true
CHECK ac2.mobile.switch.error=none
CHECK ac2.mobile.activeProvider=lighter
CHECK ac2.mobile.markets.count=3
CHECK ac2.mobile.unhandled=0
RESULT {"checks":{"ac2.mobile.initializationState":"initialized","ac2.mobile.switch.success":true,"ac2.mobile.switch.error":"none","ac2.mobile.activeProvider":"lighter","ac2.mobile.markets.count":3,"ac2.mobile.unhandled":0},"unhandled":[],"result":{"errors":[],"debugLogs":["[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","PerpsController: Using direct provider (lighter)"],"initializationState":"initialized","switch":{"success":true,"providerId":"lighter"},"activeProvider":"lighter","markets":{"count":3,"providerIds":["lighter"],"sampleSymbols":["ETH","BTC","SOL"]}}}

- PASS ac2-assert-mobile-default-path (assert_output, 73ms): source=ac2-mobile-default-path, stream=stdout, match=CHECK ac2\.mobile\.initializationState=initialized\nCHECK ac2\.mobile\.switch\.success=true\nCHECK ac2\.mobile\.switch\.error=none\nCHECK ac2\.mobile\.activeProvider=lighter\nCHECK ac2\.mobile\.markets\.count=[1-9][0-9]*\nCHECK ac2\.mobile\.unhandled=0\n
- PASS ac1-web-client-run (command, 6.6s): exitCode=0, stdout=CHECK ac1.loaderCalls=2
CHECK ac1.initializationState=initialized
CHECK ac1.switch.success=true
CHECK ac1.switch.error=none
CHECK ac1.activeProvider=lighter
CHECK ac4.markets.count=3
CHECK ac4.markets.providerIds=lighter
CHECK ac4.lighterMarketsRead=true
CHECK ac1.unhandled=0
RESULT {"scenario":"loader","checks":{"ac1.loaderCalls":2,"ac1.initializationState":"initialized","ac1.switch.success":true,"ac1.switch.error":"none","ac1.activeProvider":"lighter","ac4.markets.count":3,"ac4.markets.providerIds":"lighter","ac4.lighterMarketsRead":true,"ac1.unhandled":0},"unhandled":[],"result":{"errors":[],"debugLogs":["[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","PerpsController: Using direct provider (lighter)"],"initializationState":"initialized","switch":{"success":true,"providerId":"lighter"},"activeProvider":"lighter","markets":{"count":3,"providerIds":["lighter"],"sampleSymbols":["ETH","BTC","SOL"]}}}

- PASS ac1-assert-switch (assert_output, 115ms): source=ac1-web-client-run, stream=stdout, match=CHECK ac1\.loaderCalls=[1-9][0-9]*\nCHECK ac1\.initializationState=initialized\nCHECK ac1\.switch\.success=true\nCHECK ac1\.switch\.error=none\nCHECK ac1\.activeProvider=lighter\n
- PASS ac4-assert-lighter-markets (assert_output, 104ms): source=ac1-web-client-run, stream=stdout, match=CHECK ac4\.markets\.count=[1-9][0-9]*\nCHECK ac4\.markets\.providerIds=lighter\nCHECK ac4\.lighterMarketsRead=true\nCHECK ac1\.unhandled=0\n
- PASS ac1-web-bundle (command, 8.9s): exitCode=0, stdout=CHECK bundle.web-client.errors=0
CHECK bundle.web-client.assets=2
CHECK bundle.web-client.asyncChunks=1
CHECK bundle.web-client.controllerInInitial=true
CHECK bundle.web-client.initialLighterModules=0
CHECK bundle.web-client.asyncLighterModules=1
CHECK bundle.web-client.initialLighterMarker=false
CHECK bundle.web-client.asyncLighterMarker=true
CHECK bundle.web-client.nativeLighterImport=true

- PASS ac1-assert-web-bundle-split (assert_output, 143ms): source=ac1-web-bundle, stream=stdout, match=CHECK bundle\.web-client\.errors=0\nCHECK bundle\.web-client\.assets=[2-9]\nCHECK bundle\.web-client\.asyncChunks=[1-9]\nCHECK bundle\.web-client\.controllerInInitial=true\nCHECK bundle\.web-client\.initialLighterModules=0\nCHECK bundle\.web-client\.asyncLighterModules=1\nCHECK bundle\.web-client\.initialLighterMarker=false\nCHECK bundle\.web-client\.asyncLighterMarker=true\n
- PASS ac3-failed-load-run (command, 2.3s): exitCode=0, stdout=CHECK ac3.default.initializationState=initialized
CHECK ac3.default.switch.success=false
CHECK ac3.default.activeProvider=hyperliquid
CHECK ac3.default.loggerErrors=0
CHECK ac3.default.error=Provider lighter not available: Lighter provider failed to load (Cannot find module '/Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/providers/LighterProvider' imported from /Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/PerpsController.js). Pass providerCredentials.lighter.loadProvider to load it from @metamask/perps-controller/providers/lighter.
CHECK ac3.fetch.initializationState=initialized
CHECK ac3.fetch.switch.success=false
CHECK ac3.fetch.activeProvider=hyperliquid
CHECK ac3.fetch.loggerErrors=0
CHECK ac3.fetch.error=Provider lighter not available: Lighter provider failed to load (Failed to fetch dynamically imported module: http://localhost:3000/_next/static/chunks/providers/LighterProvider).
CHECK ac3.unhandled=0
RESULT {"scenario":"failed-load","checks":{"ac3.default.initializationState":"initialized","ac3.default.switch.success":false,"ac3.default.activeProvider":"hyperliquid","ac3.default.loggerErrors":0,"ac3.default.error":"Provider lighter not available: Lighter provider failed to load (Cannot find module '/Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/providers/LighterProvider' imported from /Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/PerpsController.js). Pass providerCredentials.lighter.loadProvider to load it from @metamask/perps-controller/providers/lighter.","ac3.fetch.initializationState":"initialized","ac3.fetch.switch.success":false,"ac3.fetch.activeProvider":"hyperliquid","ac3.fetch.loggerErrors":0,"ac3.fetch.error":"Provider lighter not available: Lighter provider failed to load (Failed to fetch dynamically imported module: http://localhost:3000/_next/static/chunks/providers/LighterProvider).","ac3.unhandled":0},"unhandled":[],"result":{"defaultImport":{"errors":[],"debugLogs":["PerpsController: Lighter provider module not available, skipping registration"],"initializationState":"initialized","switch":{"success":false,"providerId":"hyperliquid","error":"Provider lighter not available: Lighter provider failed to load (Cannot find module '/Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/providers/LighterProvider' imported from /Users/deeeed/dev/metamask/core-3/packages/perps-controller/dist/PerpsController.js). Pass providerCredentials.lighter.loadProvider to load it from @metamask/perps-controller/providers/lighter."},"activeProvider":"hyperliquid"},"fetchFailure":{"errors":[],"debugLogs":["PerpsController: Lighter provider module not available, skipping registration"],"initializationState":"initialized","switch":{"success":false,"providerId":"hyperliquid","error":"Provider lighter not available: Lighter provider failed to load (Failed to fetch dynamically imported module: http://localhost:3000/_next/static/chunks/providers/LighterProvider)."},"activeProvider":"hyperliquid"}}}

- PASS ac3-assert-default-import-failure (assert_output, 110ms): source=ac3-failed-load-run, stream=stdout, match=CHECK ac3\.default\.initializationState=initialized\nCHECK ac3\.default\.switch\.success=false\nCHECK ac3\.default\.activeProvider=hyperliquid\nCHECK ac3\.default\.loggerErrors=0\nCHECK ac3\.default\.error=Provider lighter not available: Lighter provider failed to load \(Cannot find module [^\n]*\)\. Pass providerCredentials\.lighter\.loadProvider[^\n]*\n
- PASS ac3-assert-fetch-failure (assert_output, 151ms): source=ac3-failed-load-run, stream=stdout, match=CHECK ac3\.fetch\.initializationState=initialized\nCHECK ac3\.fetch\.switch\.success=false\nCHECK ac3\.fetch\.activeProvider=hyperliquid\nCHECK ac3\.fetch\.loggerErrors=0\nCHECK ac3\.fetch\.error=Provider lighter not available: Lighter provider failed to load \(Failed to fetch dynamically imported module: [^\n]*\)\.\nCHECK ac3\.unhandled=0\n
- PASS ac2-client-builds-run (command, 767ms): exitCode=0, stdout=CHECK clientBuilds.extension.files=226
CHECK clientBuilds.extension.controllerPresent=true
CHECK clientBuilds.extension.lighterProviderFiles=0
CHECK clientBuilds.mobile.files=1
CHECK clientBuilds.mobile.controllerPresent=true
CHECK clientBuilds.mobile.lighterProviderPresent=true
CHECK clientBuilds.mobileBase.controllerPresent=true
CHECK clientBuilds.mobileBase.lighterProviderPresent=true
CHECK clientBuilds.mobileTypecheck.headErrors=11
CHECK clientBuilds.mobileTypecheck.baseErrors=11
CHECK clientBuilds.mobileTypecheck.newErrors=0

- PASS ac2-assert-client-builds (assert_output, 247ms): source=ac2-client-builds-run, stream=stdout, match=CHECK clientBuilds\.extension\.files=[1-9][0-9]*\nCHECK clientBuilds\.extension\.controllerPresent=true\nCHECK clientBuilds\.extension\.lighterProviderFiles=0\nCHECK clientBuilds\.mobile\.files=[1-9][0-9]*\nCHECK clientBuilds\.mobile\.controllerPresent=true\nCHECK clientBuilds\.mobile\.lighterProviderPresent=true\nCHECK clientBuilds\.mobileBase\.controllerPresent=true\nCHECK clientBuilds\.mobileBase\.lighterProviderPresent=true\nCHECK clientBuilds\.mobileTypecheck\.headErrors=[0-9]+\nCHECK clientBuilds\.mobileTypecheck\.baseErrors=[0-9]+\nCHECK clientBuilds\.mobileTypecheck\.newErrors=0\n
- PASS ac2-flag-off-run (command, 2.0s): exitCode=0, stdout=CHECK flag.off.loaderCalls=0
CHECK flag.off.initializationState=initialized
CHECK flag.off.switch.success=false
CHECK flag.off.switch.error=Provider lighter not available
CHECK flag.off.activeProvider=hyperliquid
CHECK flag.off.lighterMarkets=0
CHECK flag.off.loggerErrors=0
CHECK flag.off.signerBridgeCalls=0
CHECK flag.off.unhandled=0
RESULT {"scenario":"flag-off","checks":{"flag.off.loaderCalls":0,"flag.off.initializationState":"initialized","flag.off.switch.success":false,"flag.off.switch.error":"Provider lighter not available","flag.off.activeProvider":"hyperliquid","flag.off.lighterMarkets":0,"flag.off.loggerErrors":0,"flag.off.signerBridgeCalls":0,"flag.off.unhandled":0},"unhandled":[],"result":{"errors":[],"debugLogs":[],"initializationState":"initialized","switch":{"success":false,"providerId":"hyperliquid","error":"Provider lighter not available"},"activeProvider":"hyperliquid"}}

- PASS ac2-assert-flag-off (assert_output, 55ms): source=ac2-flag-off-run, stream=stdout, match=CHECK flag\.off\.loaderCalls=0\nCHECK flag\.off\.initializationState=initialized\nCHECK flag\.off\.switch\.success=false\nCHECK flag\.off\.switch\.error=Provider lighter not available\nCHECK flag\.off\.activeProvider=hyperliquid\nCHECK flag\.off\.lighterMarkets=0\nCHECK flag\.off\.loggerErrors=0\nCHECK flag\.off\.signerBridgeCalls=0\nCHECK flag\.off\.unhandled=0\n
- PASS ac1-flag-on-run (command, 5.4s): exitCode=0, stdout=CHECK flag.on.loaderCalls=2
CHECK flag.on.initializationState=initialized
CHECK flag.on.switch.success=true
CHECK flag.on.switch.error=none
CHECK flag.on.activeProvider=lighter
CHECK flag.on.lighterMarkets=3
CHECK flag.on.loggerErrors=0
CHECK flag.on.signerBridgeCalls=0
CHECK flag.on.unhandled=0
RESULT {"scenario":"flag-on","checks":{"flag.on.loaderCalls":2,"flag.on.initializationState":"initialized","flag.on.switch.success":true,"flag.on.switch.error":"none","flag.on.activeProvider":"lighter","flag.on.lighterMarkets":3,"flag.on.loggerErrors":0,"flag.on.signerBridgeCalls":0,"flag.on.unhandled":0},"unhandled":[],"result":{"errors":[],"debugLogs":["[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","[LighterProvider] Constructor complete","PerpsController: Lighter provider registered","PerpsController: Using direct provider (lighter)"],"initializationState":"initialized","switch":{"success":true,"providerId":"lighter"},"activeProvider":"lighter","markets":{"count":3,"providerIds":["lighter"],"sampleSymbols":["BTC","SOL","ETH"]}}}

- PASS ac1-assert-flag-on (assert_output, 115ms): source=ac1-flag-on-run, stream=stdout, match=CHECK flag\.on\.loaderCalls=[1-9][0-9]*\nCHECK flag\.on\.initializationState=initialized\nCHECK flag\.on\.switch\.success=true\nCHECK flag\.on\.switch\.error=none\nCHECK flag\.on\.activeProvider=lighter\nCHECK flag\.on\.lighterMarkets=[1-9][0-9]*\nCHECK flag\.on\.loggerErrors=0\nCHECK flag\.on\.signerBridgeCalls=0\nCHECK flag\.on\.unhandled=0\n
- PASS ac1-next-run (command, 26s): exitCode=0, stdout=CHECK next.version=16.4.0
CHECK next.build.exit=0
CHECK next.build.turbopack=true
CHECK next.lighterChunks=1
CHECK next.initialLighterChunks=0
CHECK next.page.status=done
CHECK next.loader.loaderCalls=2
CHECK next.loader.initializationState=initialized
CHECK next.loader.switch.success=true
CHECK next.loader.switch.error=none
CHECK next.loader.activeProvider=lighter
CHECK next.loader.markets.count=3
CHECK next.loader.markets.providerIds=lighter
CHECK next.loader.lighterChunkFetched=true
CHECK next.default.lighterProvider404=true
CHECK next.default.initializationState=initialized
CHECK next.default.switch.success=false
CHECK next.default.loggerErrors=0
CHECK next.default.error=Provider lighter not available: Lighter provider failed to load (Failed to fetch dynamically imported module: http://127.0.0.1:56290/_next/static/chunks/providers/LighterProvider). Pass providerCredentials.lighter.loadProvider to load it from @metamask/perps-controller/providers/lighter.
CHECK next.unhandled=0

- PASS ac1-assert-next-build (assert_output, 129ms): source=ac1-next-run, stream=stdout, match=CHECK next\.version=16\.4\.0\nCHECK next\.build\.exit=0\nCHECK next\.build\.turbopack=true\nCHECK next\.lighterChunks=[1-9][0-9]*\nCHECK next\.initialLighterChunks=0\nCHECK next\.page\.status=done\n
- PASS ac1-assert-next-runtime (assert_output, 138ms): source=ac1-next-run, stream=stdout, match=CHECK next\.loader\.loaderCalls=[1-9][0-9]*\nCHECK next\.loader\.initializationState=initialized\nCHECK next\.loader\.switch\.success=true\nCHECK next\.loader\.switch\.error=none\nCHECK next\.loader\.activeProvider=lighter\nCHECK next\.loader\.markets\.count=[1-9][0-9]*\nCHECK next\.loader\.markets\.providerIds=lighter\nCHECK next\.loader\.lighterChunkFetched=true\n
- PASS ac3-assert-next-fetch-failure (assert_output, 91ms): source=ac1-next-run, stream=stdout, match=CHECK next\.default\.lighterProvider404=true\nCHECK next\.default\.initializationState=initialized\nCHECK next\.default\.switch\.success=false\nCHECK next\.default\.loggerErrors=0\nCHECK next\.default\.error=Provider lighter not available: Lighter provider failed to load \(Failed to fetch dynamically imported module: [^\n]*/_next/static/chunks/providers/LighterProvider\)\. Pass providerCredentials\.lighter\.loadProvider[^\n]*\nCHECK next\.unhandled=0\n
- PASS done (end, 0ms)

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them
Full evidence gallery and publication receipt

Publication approval

farm-automation · service · farm-automation · 2026-10-22T10:50:46.820Z
Package: bc4da604efdc7449474244689f056d05514002831810fa17af9323600e9b2095. Visual receipts: none.


Note

Medium Risk
Changes provider registration and dynamic import paths for an optional venue; misconfiguration could block Lighter in web clients, but default bundler behavior for extension/Mobile is preserved.

Overview
Adds a public @metamask/perps-controller/providers/lighter export and optional providerCredentials.lighter.loadProvider, so web clients (e.g. Next.js/Turbopack) can bundle and dynamically import Lighter themselves instead of relying on the controller’s webpackIgnore import that fails at runtime.

When loadProvider is omitted, behavior stays the same for extension/Mobile: the controller still uses its internal ignored import and does not pull Lighter into clients that don’t opt in.

switchProvider('lighter') now returns the underlying load failure (and hints at loadProvider when none was passed). Missing/unfetchable modules (MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, browser “failed to fetch dynamically imported module”) are debug-logged instead of logger.error; other load/registration failures still error-report.

Reviewed by Cursor Bugbot for commit 06042f3. Bugbot is set up for automated code reviews on this repo. Configure here.

Add the @metamask/perps-controller/providers/lighter export and an
optional providerCredentials.lighter.loadProvider. A web client whose
bundler cannot load the controller's bundler-ignored Lighter import
(Next.js) passes a loader for that export and bundles Lighter itself.
Without a loader the default import is unchanged, so the extension
still bundles no Lighter code and Mobile keeps its path.

A Lighter module that cannot be found or fetched is debug-logged like
MODULE_NOT_FOUND; other load failures still reach logger.error. Either
way switchProvider('lighter') now returns the cause.
@abretonc7s abretonc7s changed the title chore: prepare farmslot publication pkg-9edc7021-mvjc4dat feat(perps): perps-controller: let web clients load the Lighter venue Oct 22, 2026
@abretonc7s
abretonc7s marked this pull request as ready for review October 22, 2026 10:57
@abretonc7s
abretonc7s requested review from a team as code owners October 22, 2026 10:57
@abretonc7s
abretonc7s enabled auto-merge October 22, 2026 13:22
@abretonc7s
abretonc7s added this pull request to the merge queue Oct 23, 2026
Merged via the queue into main with commit 5080b95 Oct 23, 2026
50 checks passed
@abretonc7s
abretonc7s deleted the TAT-4206-feat-perps-controller-let-web-clien branch October 23, 2026 00:13
This was referenced Oct 23, 2026
SnowingFox pushed a commit to SnowingFox/core-1 that referenced this pull request Oct 24, 2026
## Explanation

Major release of `@metamask/perps-controller` (`21.0.0` → `22.0.0`).

- **Breaking:** testnet deposit and withdrawal routes use Arbitrum
Sepolia USDC2 (`0x1baAbB04529D43a73232B713C0FE471f7c7334d5`).
`USDC_ARBITRUM_TESTNET_ADDRESS` and
`HYPERLIQUID_ASSET_CONFIGS.usdc.testnet` change to that address, and
`withdraw` rejects the previous testnet asset ID.
`depositWithConfirmation` prepares an Arbitrum Sepolia transfer to the
Hyperliquid testnet bridge.
([MetaMask#10991](MetaMask#10991))
- `TrackingData`, `TPSLTrackingData`, and `WithdrawParams` accept an
optional `environmentType`. Events that already copy attribution include
`environment_type` when it is set.
([MetaMask#10899](MetaMask#10899))
- New export `@metamask/perps-controller/providers/lighter`, plus
optional `LighterCredentials.loadProvider`, so a web client can bundle
Lighter itself. `switchProvider('lighter')` reports why the provider
failed to load. A missing Lighter module is debug-logged instead of sent
through `logger.error`.
([MetaMask#10996](MetaMask#10996))
- The `closePositions` summary event includes `order_type: 'market'`.
([MetaMask#11027](MetaMask#11027))
- Engines allow Node.js 26.
([MetaMask#10981](MetaMask#10981))

## References

- [MetaMask#10991](MetaMask#10991)
- [MetaMask#10899](MetaMask#10899)
- [MetaMask#10996](MetaMask#10996)
- [MetaMask#11027](MetaMask#11027)
- [MetaMask#10981](MetaMask#10981)

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Major perps-controller release with breaking testnet token/bridge
behavior; this PR only bumps versions but consumers picking up 22.0.0
inherit that risk.
> 
> **Overview**
> **Monorepo release 1359.0.0** that publishes
**`@metamask/perps-controller` 22.0.0** and bumps
**`@metamask/transaction-pay-middleware`** to depend on `^22.0.0` (plus
`yarn.lock` and root package version).
> 
> The diff is mostly versioning and changelog housekeeping; the shipped
**22.0.0** behavior (already merged) includes a **breaking testnet USDC2
/ Arbitrum Sepolia deposit path** change, optional **`environmentType`**
on perps tracking/withdraw params, **Lighter** `loadProvider` + public
provider export, **`closePositions`** analytics `order_type: 'market'`,
and **Node.js 26** engine support.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8356d7d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants