perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/lighter.d.ts

@@ -1,7 +1,12 @@
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
-import type { WasmSignerClient as WasmSignerClientType } from "lighter-ts-sdk";
+import { PerpError } from "../errors.js";
+import type { Network, VenueNetworkConfig } from "./venue.js";
+import { LIGHTER_REFERENCE_PRICE_SOURCE } from "./venues/lighter-family.js";
+import type { LighterVenueId } from "./venues/lighter-family.js";
+import { LighterWasmSigner } from "./lighter-signer.js";
 /** Lighter trigger orderType enum (matches WASM signer). */
 export declare const LIGHTER_ORDER_TYPE: {
     readonly STOP_LOSS: 2;
@@ -22,17 +27,279 @@ export type LighterTriggerOrderType = typeof LIGHTER_ORDER_TYPE.STOP_LOSS | type
  * Tied trigger==mark is classified as STOP_LOSS — the protective default.
  */
 export declare function classifyTriggerOrderType(side: "buy" | "sell", triggerPrice: number, markPrice: number, isMarket: boolean): LighterTriggerOrderType;
+/** Lighter order time-in-force enum (lighter-go / SDK `TimeInForce`): 0 IOC, 1 GTT, 2 post-only. */
+export declare const LIGHTER_TIF: {
+    readonly IOC: 0;
+    readonly GTT: 1;
+    readonly POST_ONLY: 2;
+};
+/**
+ * CLI format rule for a Lighter client order id (§13.10 #9): the venue's
+ * `clientOrderIndex` is numeric, so the id must be a plain decimal integer string
+ * (digits only, no sign / leading zero / exponent) in 1 ≤ n ≤ 2^48 − 1.
+ * Anything else → INVALID_PARAMS before anything is sent.
+ */
+export declare function lighterClientOrderIndex(id: string): number;
+/**
+ * Generated Lighter client order index (uint48, 1 ≤ n ≤ 2^48 − 1). Layout: the low 38 bits
+ * of the millisecond timestamp (wraps every ~8.7 years) shifted left 10 bits, plus 10 random
+ * bits. Two orders collide only when sent in the same millisecond AND drawing the same
+ * random value (1/1024) — the former second-granularity timestamp + per-process counter
+ * collided across processes within the same second. Caller-given ids are validated
+ * separately (lighterClientOrderIndex).
+ */
+export declare function lighterGeneratedClientOrderIndex(): number;
+/**
+ * /tx status codes (apidocs "Data Structures, Constants and Errors" → Transaction Status
+ * Mapping): 0 Failed · 1 Pending · 2 Executed · 3 Pending - Final State.
+ */
+export declare const LIGHTER_TX_STATUS: {
+    readonly FAILED: 0;
+    readonly PENDING: 1;
+    readonly EXECUTED: 2;
+    readonly PENDING_FINAL: 3;
+};
+/**
+ * Parsed `event_info` of a /tx row (JSON string on the wire), or null when absent / unparseable.
+ * Integers of 16+ digits (order ids such as Lighter RH's 32088147345014782 > 2^53) are kept as
+ * exact decimal strings — JSON.parse would round them to another order's id.
+ */
+export declare function lighterEventInfo(eventInfo: unknown): Record<string, unknown> | null;
+/** Exact venue order id of an event_info order object's `i` (decimal string or safe integer), else null. */
+export declare function lighterEventOrderId(i: unknown): string | null;
+/** One /tx poll, classified. */
+export type LighterTxState = {
+    kind: "executed";
+    status: number;
+    eventInfo: Record<string, unknown> | null;
+} | {
+    kind: "rejected";
+    status: number;
+    reason: string;
+} | {
+    kind: "pending";
+    status: number | null;
+};
+/**
+ * Classify a /tx response: 0 → rejected; 2 / 3 with executed_at > 0 → executed, unless the
+ * event_info carries a non-empty `ae` (app error) → rejected; 1, 2 / 3 not yet executed, a
+ * missing status or an unknown code → pending (keep polling; never guessed final).
+ */
+export declare function lighterTxState(tx: unknown): LighterTxState;
+/** Order status names by code (event_info `st`; accountOrders `status` strings). */
+export declare const LIGHTER_ORDER_STATUS_NAMES: readonly ["in-progress", "pending", "open", "filled", "canceled", "canceled-post-only", "canceled-reduce-only", "canceled-position-not-allowed", "canceled-margin-not-allowed", "canceled-too-much-slippage", "canceled-not-enough-liquidity", "canceled-self-trade", "canceled-expired", "canceled-oco", "canceled-child", "canceled-liquidation", "canceled-invalid-balance"];
+/** Final outcome of a placed (non-IOC) order, attached to the raw result as `orderOutcome`. */
+export interface LighterOrderOutcome {
+    /** open = resting (or an untriggered trigger order); cancelled with a fill → partiallyFilled. */
+    status: "open" | "partiallyFilled" | "filled" | "cancelled";
+    final: true;
+    /** Venue status name, e.g. "open", "canceled-post-only". */
+    venueStatus: string;
+    /** Filled base size (decimal string). */
+    filledSize: string;
+    /** Venue order id (string; exact), when reported. */
+    orderId: string | null;
+    source: "event_info" | "accountOrders";
+}
+/**
+ * Normalized outcome from a venue order status (code or name) and its filled size, or null
+ * when not final (0 in-progress) / unknown. 1 pending = an untriggered trigger order (it
+ * exists on the venue) → open.
+ */
+export declare function lighterOrderOutcomeOf(st: number | string, filledSize: string, orderId: string | null, source: LighterOrderOutcome["source"]): LighterOrderOutcome | null;
+/**
+ * Filled base units of an event_info order object (`to` taker / `no` modified order), proven
+ * ONLY when the venue status is 3 "filled" — the whole order (`is`) filled. Any other status →
+ * null: event_info carries no filled field, and the venue zeroes `rs` when it cancels the
+ * remainder (live testnet 2026-10-02: a crossing post-only came back canceled-post-only with
+ * is 89 / rs 0 while accountOrders reported filled_base_amount "0.000"), so is − rs is never a
+ * fill. Callers read accountOrders `filled_base_amount` instead (lighterRowOutcomeOf).
+ */
+export declare function lighterEventFilledBase(o: Record<string, unknown>): number | null;
+/**
+ * Outcome of an accountOrders row from the venue's own fields: `status` and `filled_base_amount`
+ * (a plain decimal string). A missing / malformed filled amount → null (never "0", never
+ * size − remaining).
+ */
+export declare function lighterRowOutcomeOf(row: Record<string, unknown>, orderId: string | null): LighterOrderOutcome | null;
+/**
+ * Outcome of a modify (ModifyOrder, tx type 17) from its executed tx event_info: the new order
+ * `no` ({ i order id, u client index, is size, rs remaining, p price ticks, st status }). Final
+ * only when `no` is this order (i = orderId, or u = clientOrderIndex when i is not exact),
+ * carries the price ticks / base amount sent AND its status is "filled" (filled = is,
+ * lighterEventFilledBase). Any other status → null: the filled amount is read from accountOrders.
+ */
+export declare function lighterModifyOutcomeOf(eventInfo: Record<string, unknown> | null, orderId: string, clientOrderIndex: number | null, sent: {
+    baseAmount: number;
+    priceTicks: number;
+}, sizeDecimals: number): LighterOrderOutcome | null;
+/**
+ * The integer to sign a cancel / modify with, from the order's active-orders row: its client
+ * order index when set (non-zero, ≤ 2^48 − 1); else (client index 0, e.g. a front-end order)
+ * its order id — only when that decimal string is exactly representable as a JS number (the
+ * signer takes a number). Otherwise throws INVALID_PARAMS: never a different order, never cancel-all.
+ */
+export declare function lighterOrderSignIndex(row: Record<string, unknown>, venue: string): number;
+/** Venue order id of an orders row as an exact string (order_id is a string on the wire; order_index a number). */
+export declare function lighterOrderIdOf(row: Record<string, unknown>): string;
+/**
+ * Filled base amount (integer base units) from an executed tx's `event_info` taker order `to`,
+ * proven only when the venue status is "filled" and its initial size equals what was sent
+ * (lighterEventFilledBase) → the whole sent amount. Otherwise null (a cancelled remainder
+ * zeroes `rs` — is − rs is never a fill): the caller reads the venue's filled amount
+ * (accountOrders `filled_base_amount`) or measures it. Shared by the perp and spot IOC paths.
+ */
+export declare function lighterTakerFilledBase(eventInfo: unknown, sentBaseAmount: number): number | null;
+/**
+ * A required open-order row field as a string (Rule #2): missing / empty / non-finite numeric →
+ * EXCHANGE_ERROR, never listed as price / size "0" or status "open".
+ */
+export declare function lighterRowField(o: Record<string, unknown>, key: string, venue: string): string;
+/** What identifies OUR accountOrders row besides the client order index: the market sent to and the send time. */
+export interface LighterRowMatch {
+    marketIndex: number;
+    sentAtMs: number;
+}
+/** Definite IOC outcome attached to a Lighter raw order result (`raw.iocOutcome`). */
+export interface LighterIocOutcome {
+    /** Filled base size (decimal string, venue size decimals). */
+    filledSize: string;
+    /** The IOC remainder is cancelled by the venue — this fill is final. */
+    final: true;
+    /** Filled / sent base amount in integer base units. */
+    filledBase: number;
+    sentBase: number;
+    txHash: string;
+    /**
+     * /tx status of the executed tx: 2 (Executed) or 3 (Pending - Final State), with executed_at > 0;
+     * null when /tx did not settle within the poll window and the accountOrders terminal row did.
+     */
+    txStatus: number | null;
+    /** Where the fill was read: event_info (status "filled" → the whole order) or the accountOrders row's filled_base_amount. */
+    source: "event_info" | "accountOrders";
+}
+/** Slippage protection actually sent with a Lighter order (`raw.protection`). */
+export interface LighterProtection {
+    /** Declared reference source (LIGHTER_REFERENCE_PRICE_SOURCE) or "triggerPrice" for trigger orders. */
+    referenceSource: typeof LIGHTER_REFERENCE_PRICE_SOURCE | "triggerPrice";
+    referencePrice: string;
+    /** Tick-aligned toward crossing (buy → up, sell → down). */
+    protectionPrice: string;
+    slippageBps: number;
+    slippageSource: ResolvedSlippage["source"];
+    /** |protectionPrice / referencePrice − 1| in bps after tick alignment. */
+    appliedBps: number;
+}
+/** `iocOutcomeOf` parser shared by LighterAdapter and LighterSpotAdapter. */
+export declare function lighterIocOutcomeOf(raw: unknown): {
+    filledSize: string;
+    final: true;
+} | null;
+/**
+ * An explicit non-200 `code` in a /sendTx response: the venue validated the tx and refused it
+ * before execution (e.g. "invalid ToAccount", "invalid nonce") — a definite rejection, nothing
+ * executed. Orders (place / cancel / modify / trigger) → ORDER_REJECTED; account actions
+ * (transfer / withdraw / leverage) → ACTION_REJECTED; a balance / margin refusal keeps its
+ * specific (also definite) code so shortfall handling still applies. Transport failures /
+ * unreadable bodies are NOT routed here (their outcome is unknown).
+ */
+export declare function lighterSendTxRejection(venue: string, json: {
+    code?: unknown;
+    message?: string;
+}, kind: "order" | "action"): PerpError;
+/**
+ * A /sendTx `code` that says the venue VALIDATED the tx and refused it (nothing executed): the
+ * documented validation / rate-limit ranges 20000–28999 (apidocs "Data Structures, Constants and
+ * Errors": 21xxx account / collateral / tx / order-book / order / asset errors, 23xxx rate limits).
+ * NOT definite: a missing / non-numeric code, 29xxx (29500 internal server error, 29501 process
+ * timeout — the tx may still execute) and anything outside the documented ranges.
+ */
+export declare function lighterSendTxCodeIsDefinite(code: unknown): boolean;
+/**
+ * Verdict of a parsed /sendTx body: code 200 → returns; a documented validation code → definite
+ * rejection (lighterSendTxRejection); any other / missing code → ORDER_PENDING (outcome unknown).
+ */
+export declare function lighterSendTxVerdict(venue: string, json: {
+    code?: unknown;
+    message?: string;
+}, kind: "order" | "action", what: string): void;
+/** Per-request timeout of POST /sendTx (fetch + body read). */
+export declare const LIGHTER_SEND_TIMEOUT_MS = 15000;
+/**
+ * POST /sendTx (shared by the perp and spot adapters). Once the signed tx is on the wire only
+ * the venue's own answer settles it: no connection → not sent; a connection reset / timeout /
+ * HTTP 5xx / unreadable body → ORDER_PENDING; then lighterSendTxVerdict on the body.
+ */
+export declare function lighterPostSendTx(baseUrl: string, signed: {
+    txType: number;
+    txInfo: string;
+}, venue: string, kind: "order" | "action", what: string): Promise<{
+    code: number;
+    message?: string;
+    tx_hash?: string;
+}>;
+/** created_at / timestamp of an orders row in ms (the venue reports seconds; ms / µs are normalized), or null. */
+export declare function lighterRowCreatedMs(row: Record<string, unknown>): number | null;
+/**
+ * Configured leverage and margin mode of an account `positions[]` entry (GET /api/v1/account).
+ * Docs (apidocs.lighter.xyz/reference/account-1, PositionDetails): `initial_margin_fraction`
+ * "type": "string", example "20.00"; `margin_mode` "type": "integer", example 1. The fraction
+ * is a PERCENT on this read (live 2026-10-05: "5.00" on a 20x market, "6.66" after a 15x
+ * update) — the same value updateLeverage signs in basis points (`int(10_000 / leverage)`), so
+ * leverage = floor(10000 / bps), which returns the integer leverage that was set. margin_mode:
+ * 0 cross, 1 isolated (the values updateLeverage signs). Anything else throws — never a guess.
+ */
+export declare function lighterPositionSettings(p: Record<string, unknown>, venue: string): {
+    leverage: number;
+    marginMode: "cross" | "isolated";
+};
+/** Clock-skew allowance when requiring an order row to be created after the send (client vs venue clock). */
+export declare const LIGHTER_ROW_SKEW_MS = 120000;
+/**
+ * The account to use from a `/account?by=l1_address` listing. A known account index → that
+ * account or null (never another one). Unknown index: the only account; with several, the single
+ * main account (account_type 0); otherwise INVALID_PARAMS — never "the first one".
+ */
+export declare function lighterSelectAccount(accounts: Array<Record<string, unknown>> | undefined, accountIndex: number, venue: string): Record<string, unknown> | null;
+/**
+ * On-disk lifetime of the perp market list (symbol → market id, size / price decimals) read from
+ * `GET /api/v1/orderBooks`, shared by every CLI process of the same venue + network (cache.ts).
+ * Public static metadata only — account state, orders, positions, balances and nonces are never
+ * cached here. It keeps the list off the per-invocation request budget (apidocs.lighter.xyz
+ * rate-limits: "Standard Accounts: 60 requests per rolling minute"). A market listed inside this
+ * window is unknown (SYMBOL_NOT_FOUND) until the entry expires.
+ */
+export declare const LIGHTER_MARKET_LIST_TTL_MS: number;
+export interface LighterAdapterOpts {
+    apiKey?: string;
+    accountIndex?: number;
+    apiKeyIndex?: number;
+}
 export declare class LighterAdapter implements ExchangeAdapter {
-    readonly name = "lighter";
-    readonly chain = "ethereum";
-    readonly aliases: readonly ["lt"];
+    /** GTC→GTT resting-order lifetime (28 days) for the execution record (§13.10 #14). */
+    static readonly gttExpiryMs: number;
+    /** Venue id ("lighter" | "lighter-rh"). */
+    readonly name: LighterVenueId;
+    readonly venueId: LighterVenueId;
+    readonly family: "lighter";
+    /** Settlement chain of the venue network ("ethereum" for Lighter, "robinhood" for Lighter RH). */
+    readonly chain: string;
+    readonly aliases: readonly string[];
+    readonly networkName: Network;
+    private readonly _network;
     private _signer;
     private _accountIndex;
+    /**
+     * Account trading mode (`account_trading_mode`: Classic=0, Unified=1 — lighter-python
+     * models/account.py; docs.lighter.xyz "Unified Trading Accounts"). Unified: spot and perp
+     * share the USDC margin, so there is no spot↔perp transfer. Read by
+     * resolveAccountTradingMode() (LighterSpotAdapter.init); null = not read yet.
+     */
+    private _tradingMode;
     private _apiKeyIndex;
     private _address;
     private _marketMap;
     private _marketDecimals;
-    private _clientOrderCounter;
     private _evmKey;
     private _apiKey;
     private _accountIndexInit;
@@ -54,26 +321,62 @@ export declare class LighterAdapter implements ExchangeAdapter {
     /** --no-agent bypass flag. */
     private _useNoAgent;
     /**
+     * Legacy constructor: this signature DEFINES the Lighter (main) venue — it is
+     * not a default for other venues. Lighter RH (and any explicit venue) is
+     * built with `LighterAdapter.forVenue()`, which passes `venue`.
+     *
      * @param evmKey    EVM private key (0x-prefixed, 32 bytes) — for deposits & key registration
-     * @param testnet   Use testnet (chain ID 300) instead of mainnet (chain ID 304)
-     * @param opts      Optional: apiKey (40-byte Lighter signing key), accountIndex
-     */
-    constructor(evmKey: string, testnet?: boolean, opts?: {
-        apiKey?: string;
-        accountIndex?: number;
-        apiKeyIndex?: number;
-    });
-    get signer(): {
+     * @param testnet   Use the venue testnet instead of mainnet
+     * @param opts      Optional: apiKey (40-byte Lighter signing key), accountIndex, apiKeyIndex
+     * @param venue     @internal — set only by `forVenue()`; absent means the Lighter venue by definition
+     */
+    constructor(evmKey: string, testnet?: boolean, opts?: LighterAdapterOpts, venue?: LighterVenueId);
+    /** Construct an adapter for an explicit Lighter-family venue. */
+    static forVenue(venue: LighterVenueId, evmKey: string, testnet: boolean, opts?: LighterAdapterOpts): LighterAdapter;
+    /** Network config of this adapter's venue + network (SSOT: venues/lighter-family.ts). */
+    get network(): VenueNetworkConfig;
+    /** Collateral symbol of this venue on its network ("USDC" on Lighter, "USDG" on Lighter RH mainnet, "USDC" on RH testnet). */
+    get collateralSymbol(): string;
+    /** Lighter asset index of the collateral (3 on both venues). */
+    get collateralAssetIndex(): number;
+    /**
+     * Cache key prefix for account reads shared with LighterSpotAdapter.
+     * "lt" is the historical Lighter prefix (kept so existing cache keys are unchanged);
+     * other venues use their venue id so accounts never collide across venues.
+     */
+    get accountCachePrefix(): string;
+    /** Lighter RH reserves API key indexes {0,1,2,3,157} for its own interfaces. */
+    private static _assertKeyIndexAllowed;
+    get signer(): Omit<LighterWasmSigner, "createAuthToken"> & {
         createAuthToken(deadline: number): Promise<{
             authToken: string;
         }>;
-    } & WasmSignerClientType;
+    };
     get accountIndex(): number;
     get address(): string;
     /** @internal — evmKey is intentionally not exposed publicly for security */
     get isReadOnly(): boolean;
+    /**
+     * Sign an unsigned L1 transaction with the master wallet (on-chain deposit txs); the
+     * digest is derived from the tx inside the signer. Only an OWS master signer can sign
+     * L1 txs; anything else → NO_SIGNER_AVAILABLE.
+     */
+    signL1Transaction(tx: import("ethers").Transaction): Promise<string>;
     /** Inject an external EVM signer. Call before init() to skip LocalEvmSigner creation. */
     setSigner(signer: EvmSigner): void;
+    /**
+     * Set the account owner's L1 address without attaching a signer — for an agent whose master
+     * wallet is not on this machine (API key imported from the website). Account reads are keyed
+     * by this address; nothing L1 can be signed (signL1Transaction / setupApiKey still refuse).
+     */
+    setAddress(address: string): void;
+    /**
+     * Prove the loaded agent API key is the one registered at its slot: sign an auth token with it
+     * and make one authenticated read (`GET /api/v1/accountActiveOrders`). Lighter validates the
+     * token against the public key registered at (account_index, api_key_index), so a key that does
+     * not match the slot is refused. Read-only — nothing is sent. Throws on any refusal.
+     */
+    assertAgentKeyAccepted(): Promise<void>;
     /**
      * Tier 1: inject a Lighter agent's slot+L2 key (Phase 2d).
      *
@@ -103,44 +406,256 @@ export declare class LighterAdapter implements ExchangeAdapter {
      * Tier 3 (pk): active when constructor was supplied an evmKey. Same role
      *   as Tier 2 — signs L1 ChangePubKey for auto-setup.
      *
-     * Lighter is unique among the 4 DEXs in that the actual order-signing is
+     * Lighter is unique among the venues in that the actual order-signing is
      * always done by the L2 secp256k1 key (`_apiKey`), regardless of tier. The
      * tiers differ in WHICH L2 key is loaded: Tier 1 uses the agent's slot/key
      * from AgentMeta; Tier 2/3 use whatever the env/auto-setup produced.
      */
     private _resolveSigner;
+    private agentExpired;
+    /**
+     * true = Unified Trading Account (spot shares perp margin), false = Classic. Throws when the
+     * mode was not read or the read failed — never assumes either mode (SSOT Rule #2).
+     */
+    get isUnifiedAccount(): boolean;
+    /**
+     * Read `account_trading_mode` from the account (shared `acct:` cache). A failed or invalid
+     * read is kept and re-thrown by isUnifiedAccount, so callers that depend on the mode fail
+     * while public spot reads (markets, books) keep working.
+     */
+    resolveAccountTradingMode(): Promise<void>;
     init(): Promise<void>;
-    /** Populate marketMap + decimals from /orderBooks API (safe to call multiple times) */
+    /**
+     * Populate the perp market map + decimals: ONE `GET /api/v1/orderBooks` (it carries
+     * supported_size_decimals / supported_price_decimals for every market), served from the on-disk
+     * market-list cache while fresh (LIGHTER_MARKET_LIST_TTL_MS). A failed read (429, transport,
+     * no / empty list) throws the real error — never an empty map, which every later symbol lookup
+     * would report as SYMBOL_NOT_FOUND. No second endpoint and no retry: each costs a request of
+     * the 60 / minute budget.
+     */
     private _refreshMarketMap;
     getMarketIndex(symbol: string): number;
+    /**
+     * Lot step of a perp market from the loaded market list (size decimals of /orderBooks) —
+     * precision.lotStepOf uses it instead of a full getMarkets() read (/orderBookDetails +
+     * /funding-rates, two requests an order placement does not need).
+     */
+    lotStepOf(symbol: string): string;
     /** Ensure market map is populated; lazy-refresh if empty */
     private ensureMarketMap;
-    private getMarkPrice;
+    /**
+     * Reference price for slippage-bounded orders — the ONE declared source
+     * (LIGHTER_REFERENCE_PRICE_SOURCE): mid of best bid / best ask from
+     * `/orderBookOrders`. A missing side or unreadable book → PRICE_STALE (no substitute).
+     */
+    private getReferencePrice;
+    /**
+     * Protection price = reference ± slippage bps, aligned to the price tick toward
+     * crossing (buy → up, sell → down; precision.alignProtectionPrice), as signer ticks.
+     */
+    private protectionFor;
+    /** Validated caller client order index, or a generated one. */
+    private clientOrderIndexFor;
+    /**
+     * /tx poll attempts (500 ms apart). Testnet sequencing is slower, so its window is 3× longer.
+     * Public: LighterSpotAdapter polls with the same window.
+     */
+    txPollAttempts(base: number): number;
+    /**
+     * Poll /tx by hash until the tx is executed or rejected (lighterTxState), or the poll
+     * window ends → `{ kind: "pending" }`. A tx not indexed yet (HTTP 400 "transaction not
+     * found") or a transient read failure polls again.
+     */
+    private pollTx;
+    /**
+     * Definite IOC outcome (§13.10 #4) from the executed tx: poll /tx by hash. A taker order the
+     * venue reports "filled" (event_info `to.st` 3, `is` = sent) filled the whole order. Any other
+     * status (the remainder was cancelled — the venue zeroes `rs`, so is − rs is NOT a fill) →
+     * the venue's own `filled_base_amount` from accountOrders by client order index. Zero fill →
+     * ORDER_REJECTED; positive fill → the raw result carrying `iocOutcome` (final). Executed =
+     * status 2 / 3 with executed_at > 0 (lighterTxState); 1 Pending keeps polling. Status 0 or a
+     * non-empty event_info `ae` → ORDER_REJECTED. /tx not settled within the poll window → the
+     * accountOrders terminal row still settles it. No terminal row either → raw result without
+     * `iocOutcome` (outcome unknown; iocOutcomeOf() returns null).
+     */
+    private awaitIocOutcome;
+    /**
+     * Poll /tx until the tx is executed (status 2 / 3 with executed_at > 0) — used for cancels
+     * and trigger orders (TP/SL legs), which carry no fill to read. Status 0 or an event_info
+     * `ae` → ORDER_REJECTED (definite); not executed within the poll window → ORDER_PENDING.
+     */
+    awaitTxExecuted(sendResult: unknown, what: string, kind?: "order" | "action"): Promise<void>;
+    /**
+     * Orders of this account by client order index (`GET /api/v1/accountOrders`, auth token in
+     * the Authorization header; up to 20 indexes; last 10K active / 1K inactive within 24 h).
+     * Throws on a failed read or a response without an `orders` array (never "no orders").
+     */
+    getOrdersByClientIndex(clientOrderIndexes: number[]): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Our order's accountOrders row (by client order index; and order id when given) → outcome
+     * from the venue's own `status` / `filled_base_amount` (lighterRowOutcomeOf — never
+     * size − remaining). `settled` decides whether the row settles the question (e.g. a modify's
+     * open row must carry the new price / size). Up to 4 reads 500 ms apart (indexing lag); a
+     * failed read is warned. Unsettled → null. Public: LighterSpotAdapter resolves spot orders
+     * with the same read (accountOrders lists spot and perp orders alike).
+     */
+    orderRowOutcome(clientOrderIndex: number, orderId: string | null, what: string, settled?: (out: LighterOrderOutcome, row: Record<string, unknown>) => boolean, match?: LighterRowMatch | null): Promise<LighterOrderOutcome | null>;
+    /**
+     * Final outcome of a placed resting / post-only order (§13.10 #4 analogue for non-IOC): poll
+     * /tx (rejected → ORDER_REJECTED). Our order (`to`, matched by client order index) reported
+     * "filled" in event_info → filled = is (the whole order). Any other status — open, or a
+     * canceled-* whose remainder the venue zeroed (`rs` 0, so is − rs is NOT a fill) — or an
+     * unsettled event → `accountOrders?client_order_indexes=<coi>` with the venue's
+     * `filled_base_amount`. Still unknown → null.
+     */
+    private resolveOrderOutcome;
+    /**
+     * Final IOC fill reported by marketOrder (`raw.iocOutcome`), or null
+     * when the outcome is unknown (no usable /tx report). Zero fills never reach here —
+     * they throw ORDER_REJECTED.
+     */
+    iocOutcomeOf(raw: unknown): {
+        filledSize: string;
+        final: true;
+    } | null;
+    /**
+     * Integer base amount / price ticks. `size` (decimal string, "0" = none) is FLOORED to the
+     * size step with exact decimal arithmetic (floorSize) — never rounded up past the request;
+     * a size that floors to 0 → SIZE_TOO_SMALL.
+     */
     private toTicks;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
+    private get accountCacheKey();
+    /** The in-flight cached account read: parallel callers (getBalance + getPositions) share one request. */
+    private _accountInFlight;
+    /** `fresh`: always read live (write-through) — open-order listings must not see a pre-cancel / pre-place snapshot. */
     private fetchAccount;
+    /**
+     * Book from GET /orderBookOrders?market_id=<id> on this venue's host (Lighter RH: its own host
+     * and market ids, e.g. RH testnet TSLA = 112). Rule #2: an unknown symbol (SYMBOL_NOT_FOUND) or
+     * a failed read throws — it is never reported as an empty book. An empty `bids`/`asks` is the
+     * venue's real answer (no liquidity).
+     */
     getOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
     getBalance(): Promise<ExchangeBalance>;
     getPositions(): Promise<ExchangePosition[]>;
+    /**
+     * Per-market leverage / margin mode the venue exposes: every `positions[]` entry of the
+     * account (the venue keeps an entry for a market once it was traded or configured, open
+     * position or not).
+     */
+    getMarketSettings(): Promise<Array<{
+        symbol: string;
+        leverage: number;
+        marginMode: "cross" | "isolated";
+    }>>;
     private getAuthToken;
     private restGetAuth;
     getOpenOrders(): Promise<ExchangeOrder[]>;
-    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts?: {
-        reduceOnly?: boolean;
+    /** Order / trade side from Lighter's `is_ask`; a missing / non-boolean value throws (never defaults to "buy"). */
+    private sideOfIsAsk;
+    /**
+     * Slippage-bounded IOC (§13.2): protection price = orderbook mid ± opts.slippage.bps,
+     * tick-aligned toward crossing. The returned raw sendTx result carries `protection`
+     * and, when the venue reported the fill, `iocOutcome` (see iocOutcomeOf).
+     * `opts.clientOrderIndex` (optional) = caller's numeric client order id (lighterClientOrderIndex rule).
+     */
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
+        clientOrderIndex?: number;
     }): Promise<unknown>;
+    /**
+     * TIF mapping (§13.3): GTC/GTT → GTT (28-day expiry, gttExpiryMs), IOC → IOC,
+     * ALO / POST_ONLY → time-in-force 2 (POST_ONLY per apidocs trading.md and the official
+     * lighter-go signer; 28-day expiry like GTT — testnet confirmation pending, design §11).
+     * FOK and any other value → CAPABILITY_UNSUPPORTED (never silently GTT).
+     * `opts.clientOrderIndex` as in marketOrder.
+     * IOC: the same definite outcome as marketOrder (awaitIocOutcome — zero fill →
+     * ORDER_REJECTED, positive fill → `iocOutcome`, no report → unknown).
+     * GTT / post-only: the placement outcome is resolved (resolveOrderOutcome) and attached as
+     * `orderOutcome` (open / filled / cancelled, final); unresolved → no `orderOutcome` (pending).
+     */
     limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         reduceOnly?: boolean;
         tif?: string;
+        clientOrderIndex?: number;
     }): Promise<unknown>;
+    /** Final placement outcome attached by limitOrder (`raw.orderOutcome`), or null when unresolved. */
+    orderOutcomeOf(raw: unknown): LighterOrderOutcome | null;
+    /**
+     * The open order `orderId` (exact venue id string) of `symbol`, from a live authenticated
+     * `/accountActiveOrders` read. Not listed open → ORDER_NOT_FOUND (nothing is sent).
+     */
+    private activeOrderRow;
+    /**
+     * A failure before a cancel / modify / leverage tx was sent: orderNotSent (definite — a 429 or
+     * transport failure on the nonce / active-orders read is never an unknown write outcome). The
+     * lookup's own verdict ORDER_NOT_FOUND keeps its code (nothing was sent either).
+     */
+    private notSent;
+    /**
+     * Cancel one open order. The order is looked up among the market's open orders and the
+     * cancel is signed with its client order index (or its order id when that is 0 and exactly
+     * representable — lighterOrderSignIndex); otherwise refused. Never falls back to cancel-all.
+     */
     cancelOrder(symbol: string, orderId: string): Promise<unknown>;
+    /**
+     * Cancel the PERP open orders (of `symbol`, or of every perp market) one by one, each cancel
+     * polled to executed (awaitTxExecuted: rejected → ORDER_REJECTED, not executed in the poll
+     * window → ORDER_PENDING). Never the account-wide CancelAllOrders tx (market 255): that also
+     * cancels the account's SPOT orders, which a perp cancel-all / bot / plan must not touch.
+     */
     cancelAllOrders(symbol?: string): Promise<unknown>;
     modifyOrder(symbol: string, orderId: string, price: string, size: string): Promise<unknown>;
+    /**
+     * Final outcome of a modify: poll /tx (rejected → ORDER_REJECTED, the order is unchanged);
+     * once executed, the new order `no` from event_info — final there only when it is "filled"
+     * with the sent price / size (lighterModifyOutcomeOf). Otherwise `accountOrders?client_order_indexes=<coi>`: a terminal
+     * row (filled / canceled-*) is final as is; an open row only with the new price and size.
+     * Still unknown → null (pending).
+     */
+    private resolveModifyOutcome;
+    /**
+     * After a cancel tx EXECUTED (awaitTxExecuted): confirm the order is gone. With a client
+     * order index (attached by cancelOrder as `cancelTarget`), its accountOrders row: canceled-*
+     * → "cancelled", filled → "filled", still open → "open". Without one, the market's open
+     * orders: absent → "cancelled" (gone), listed → "open". Unreadable / not indexed after a
+     * few reads → null (unknown).
+     */
+    cancelOutcome(sendResult: unknown, symbol: string, orderId: string): Promise<"cancelled" | "filled" | "open" | null>;
+    /**
+     * One order's venue row, for a per-order status query. Client order index →
+     * `accountOrders?client_order_indexes=<coi>` (active and inactive within 24 h). Order id →
+     * the market's `/accountActiveOrders`, then its `/accountInactiveOrders` (latest 100).
+     * A failed read throws; not listed → ORDER_NOT_FOUND (never "cancelled").
+     */
+    orderStatusRow(symbol: string, ref: {
+        kind: "orderId" | "clientOrderId";
+        value: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Trigger order. Market trigger (no limitPrice): execution price bound = trigger price ±
+     * `opts.slippage` bps (the caller's resolveSlippage() output — required; the adapter never
+     * reads settings, §13.10 #1), tick-aligned toward crossing (§13.10 #3), recorded in the
+     * result as `protection`. Accepted risk: a fast move through the bound leaves the
+     * triggered order unfilled.
+     * TP vs SL: `opts.kind` given (TP/SL legs) → that type as given (a trigger already crossed
+     * is left for the venue to reject); omitted (plain `trade stop`) → classified from the
+     * trigger vs the declared reference price (orderbook mid).
+     * `size` must be a positive size (never "0" = "whole position", which Lighter does not have).
+     * `opts.clientOrderIndex` as in marketOrder; the result carries the `clientOrderIndex` sent
+     * and, once resolved (resolveOrderOutcome), the final `orderOutcome` (untriggered → open).
+     */
     stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
         limitPrice?: string;
         reduceOnly?: boolean;
+        slippage?: ResolvedSlippage;
+        clientOrderIndex?: number;
+        kind?: "tp" | "sl";
     }): Promise<unknown>;
     updateLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
     withdraw(amount: string, destination: string, opts?: {
@@ -157,8 +672,45 @@ export declare class LighterAdapter implements ExchangeAdapter {
         price: string | null;
     }[]>;
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    /**
+     * Account-wide history: ONE request per 100 rows, whatever the number of markets (the former
+     * per-market fan-out sent one request per perp market — 235 on Lighter mainnet — against
+     * rate-limits "Standard Accounts: 60 requests per rolling minute", and dropped every failed
+     * market). Docs (apidocs.lighter.xyz/reference): `limit` "minimum": 1, "maximum": 100 and a
+     * `cursor` request parameter / `next_cursor` response field on accountInactiveOrders, trades
+     * and positionFunding. Reads ⌈want / 100⌉ pages at most; a failed page throws — a partial
+     * history is never returned (SSOT Rule #2).
+     */
+    private historyRows;
+    /** Symbol of a history row's market id; a market no longer in the loaded perp list is named by its id. */
+    private historySymbol;
+    /**
+     * Order history: `GET /accountInactiveOrders` for the whole account. Docs (reference/
+     * accountinactiveorders): account_index and limit are the only required parameters; market_id
+     * is optional ("default": "255"), market_type is "all" | "spot" | "perp".
+     */
     getOrderHistory(limit?: number): Promise<ExchangeOrder[]>;
+    /**
+     * Trade history: `GET /trades` for the whole account, newest first. Docs (reference/trades):
+     * "Get trades for lighter accounts, including sub-accounts and public pools."; sort_by and
+     * limit are the only required parameters, account_index / market_id are optional filters and
+     * the endpoint lists no authorization parameter.
+     * Row (Trade schema + live rows 2026-10-05): no `is_ask` / `symbol` / fee amount — the account
+     * is `ask_account_id` (sold) or `bid_account_id` (bought); `timestamp` is unix milliseconds
+     * (live 1791168722794); `taker_fee` / `maker_fee` are integers "omitted if zero" (websocket
+     * reference, Trade JSON). The docs do not state their unit; live rows read as a RATE in 1e-6
+     * of `usd_amount` (a liquidation row carries 10000 = 1%, maker 28–32 on unrelated notionals),
+     * so the fee is usd_amount × fee / 1e6 for the side this account took.
+     */
     getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
+    /**
+     * Funding payments: `GET /positionFunding` for the whole account, newest first. Docs
+     * (reference/positionfunding): account_index and limit are the only required parameters;
+     * `market_ids` ("comma-separated int64s") is an optional filter. `authorization` "is required
+     * when fetching an account_index linked to a main account or a sub-account". Row (live public
+     * pool read 2026-10-05): `timestamp` unix SECONDS (1791169200), `market_id`, `change` (signed
+     * quote amount: a short at a positive rate has a positive change).
+     */
     getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
     /**
      * Get funding rates for all markets.
@@ -166,24 +718,12 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     getFundingRates(): Promise<Map<string, {
         rate: string;
-        markPrice: string;
+        markPrice: string | null;
     }>>;
     /**
      * Get candle data for a market.
      */
     getCandles(symbol: string, resolution: string, startTime: number, endTime: number, countBack?: number): Promise<unknown>;
-    /**
-     * Get order history (inactive orders) — raw response.
-     */
-    private _getOrderHistoryRaw;
-    /**
-     * Get trade history — raw response.
-     */
-    private _getTradeHistoryRaw;
-    /**
-     * Get position funding history — raw response.
-     */
-    private _getPositionFundingRaw;
     /**
      * Get PnL chart data.
      */
@@ -217,7 +757,8 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     createIntentAddress(chainId: number): Promise<unknown>;
     /**
-     * Use a referral code.
+     * Use a referral code (signed auth + POST). Called only from the explicit
+     * `wallet manage referral set` command — never on adapter creation.
      */
     useReferralCode(code: string): Promise<unknown>;
     /**
@@ -225,21 +766,52 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     private getNextNonce;
     private signOrder;
+    /**
+     * Lighter RH REST budget (standard account: 60 req/min, rate-limits.md):
+     * every RH trading/account REST call and sendTx takes a token from the
+     * `${venueId}:${network}` bucket first. Venue "lighter" is not metered here.
+     */
+    /** Take a token from the Lighter RH rate-limit bucket (no-op for venue "lighter"). Also used by LighterSpotAdapter. */
+    rhRate(endpoint: string): Promise<void>;
     private sendTx;
     private restGet;
     /** Generate a unique client order index (uint48). */
     private nextClientOrderIndex;
     private ensureSigner;
-    private static _wasmClient;
-    private static getWasmClient;
     /**
-     * Generate a new Lighter API key pair using the WASM signer.
-     * Returns { privateKey, publicKey } (both 0x-prefixed, 40 bytes).
+     * One WASM signer (one Go runtime) per `${venueId}:${network}` (design §10.5).
+     * lighter-go keys its clients by (accountIndex, apiKeyIndex) only and keeps a
+     * package-global chainId for L1 messages, so two venues must never share a
+     * runtime. Keyed by venue+network rather than chainId because Lighter testnet
+     * and Lighter RH testnet both use chainId 300.
      */
-    static generateApiKey(): Promise<{
+    private static _wasmClients;
+    private get _wasmKey();
+    private _getWasmClient;
+    /**
+     * Load one official signer runtime (vendored lighter-go v1.0.9 WASM, sha256-verified;
+     * see lighter-signer.ts). The Go exports are captured synchronously right after go.run(),
+     * so concurrent creations cannot overwrite each other's functions.
+     */
+    private static _createWasmClient;
+    /**
+     * Generate a new Lighter API key pair using this venue's WASM signer
+     * (key generation is chain-independent). Returns { privateKey, publicKey }.
+     */
+    generateApiKey(): Promise<{
         privateKey: string;
         publicKey: string;
     }>;
+    /**
+     * Read every API-key slot registered on this account (`GET /api/v1/apikeys`).
+     * Used before a ChangePubKey (approve must not overwrite an in-use slot) and after
+     * one (revoke must confirm the slot's public key actually changed). Throws on a
+     * malformed response — callers must never treat an unreadable list as "all free".
+     */
+    listApiKeys(): Promise<Array<{
+        apiKeyIndex: number;
+        publicKey: string;
+    }>>;
     /**
      * Generate an API key and register it on-chain via ChangePubKey.
      * Uses WASM signer to sign + ETH key for L1 signature.