docs(perps): explain Lighter API key slots for local setup

[abretonc7s]

Description

Lighter orders are signed by a trading key (Lighter's "API key") that the embedded signer registers in a numbered slot of the account, with one personal_sign from the wallet. A key only works on the device that created it, so simulators, devices and scripts sharing an account need different slots. When the configured slot already holds another device's key, the app stops with "Lighter API key slot N already contains a different key", which is hard to understand without context.

This adds docs/perps/lighter-api-keys.md (what a slot is, local setup, how to check a free slot, the error and its fix, testnet resets) and points the MM_PERPS_LIGHTER_API_KEY_INDEX comment in .js.env.example to it. The perps-controller README gets the same explanation in MetaMask/core#10559.

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#10559

Manual testing steps

N/A: documentation only. The fix it describes was checked on an iOS simulator against Lighter testnet: with the configured slot held by another device's key the app stopped with the error above, and with MM_PERPS_LIGHTER_API_KEY_INDEX set to a free slot the app registered its own key there.

Screenshots/Recordings

N/A: documentation only.

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Low Risk
Documentation and env example comments only; no runtime or security logic changes.

Overview
Adds docs/perps/lighter-api-keys.md so developers understand Lighter trading key slots: how signing works vs the wallet, local env setup (MM_PERPS_LIGHTER_PROVIDER_ENABLED, MM_PERPS_LIGHTER_API_KEY_INDEX, account index), one slot per device/simulator/script, curl checks for free slots, what to do when "Lighter API key slot N already contains a different key" appears, and account index behavior after testnet resets.

Updates the MM_PERPS_LIGHTER_API_KEY_INDEX comment in .js.env.example to call it a Lighter trading key slot, note the controller default (7), and link to the new doc.

^{Reviewed by Cursor Bugbot for commit ec3ad2a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[metamask-ci]

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

• Pre-merge author checklist has unchecked items (e.g. "I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards."). Every box must be consciously checked — see docs/readme/ready-for-review.md.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

[github-actions]

Smart E2E Test Selection

AI Confidence: 98

E2E reasoning

Expand to read

This PR contains only two files, both of which are documentation/comment-only changes with zero functional impact on the app:

1. .js.env.example — A comment clarification for the MM_PERPS_LIGHTER_API_KEY_INDEX environment variable. The comment was expanded to mention the default value (7) and link to the new docs file. This is a comment-only change in an example env file — it is cosmetic per the COSMETIC CHANGES rule and has no runtime effect. Grep searches confirmed this env var is not referenced in any app source, test, or CI files in a way that would be affected by this comment change.

2. docs/perps/lighter-api-keys.md — A new developer documentation file (38 lines) explaining Lighter API key slot management for local development. It contains no app code, no test code, no configuration that affects runtime behavior. find_related_files confirmed no files import or reference this doc. It is purely a developer guide.

No app source code, test infrastructure, controllers, hooks, components, navigation, or CI workflows were modified. No E2E smoke tests or performance tests are warranted.

Performance reasoning

Expand to read

No app code was changed. Both files are documentation/comment-only. The .js.env.example change is a comment clarification (cosmetic). The docs/perps/lighter-api-keys.md is a new developer documentation file. Neither affects any runtime behavior, rendering path, or performance scenario.

View run

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud