perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/lighter-signer.d.ts

@@ -0,0 +1,123 @@
+export declare const LIGHTER_SIGNER_VERSION = "lighter-go v1.0.9";
+/** sha256 of vendor/lighter-signer/lighter-signer.wasm (= the v1.0.9 release asset digest). */
+export declare const LIGHTER_SIGNER_WASM_SHA256 = "781ba28b5e7fca1ea816f516f28fe2adbe704b734828e0c941025f8133bd7b4b";
+/** sha256 of vendor/lighter-signer/wasm_exec.js (= go1.25.6 lib/wasm/wasm_exec.js). */
+export declare const LIGHTER_SIGNER_WASM_EXEC_SHA256 = "0c949f4996f9a89698e4b5c586de32249c3b69b7baadb64d220073cc04acba14";
+/** Same relative depth from src/exchanges/ and dist/exchanges/ to the package root. */
+export declare function lighterSignerDir(): string;
+/** Result of every Sign* call (wasm-signer.md "Conventions"). */
+export interface LighterSignResult {
+    txType: number;
+    txInfo: string;
+    txHash: string;
+    messageToSign?: string;
+    error?: string;
+}
+interface Account {
+    apiKeyIndex: number;
+    accountIndex: number;
+}
+/** cancelAllMarketIndex meaning "all markets" (wasm-signer.md SignCancelAllOrders). */
+export declare const LIGHTER_ALL_MARKETS = 255;
+/**
+ * One Go runtime of the official signer. The Go `main` registers its functions on
+ * globalThis and then blocks; they are captured synchronously right after `go.run()`
+ * and the globals restored, so several runtimes (one per venue+network, design §10.5)
+ * never see each other's functions.
+ */
+export declare class LighterWasmSigner {
+    private readonly fn;
+    private constructor();
+    /** Load + verify the vendored files and start a fresh runtime. */
+    static load(dir?: string): Promise<LighterWasmSigner>;
+    private exited;
+    private call;
+    private tx;
+    generateAPIKey(): {
+        privateKey: string;
+        publicKey: string;
+    };
+    /** CreateClient(url = "", privateKey, chainId, apiKeyIndex, accountIndex). `url` is ignored (kept for call-site compatibility). */
+    createClient(p: {
+        url?: string;
+        privateKey: string;
+        chainId: number;
+    } & Account): void;
+    /** CreateAuthToken(deadline unix s, apiKeyIndex, accountIndex) → token string. */
+    createAuthToken(deadline: number, apiKeyIndex: number, accountIndex: number): string;
+    /** SignChangePubKey(pubKeyHex, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signChangePubKey(p: {
+        pubkey: string;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /**
+     * SignCreateOrder — 19 args. Integrator fields and self-trade modes are 0 (defaults);
+     * skipNonce 0. `orderExpiry` −1 = GTT default: now + LIGHTER_GTT_EXPIRY_MS (28 days), resolved here.
+     */
+    signCreateOrder(p: {
+        marketIndex: number;
+        clientOrderIndex: number;
+        baseAmount: number;
+        price: number;
+        isAsk: number;
+        orderType: number;
+        timeInForce: number;
+        reduceOnly: number;
+        triggerPrice: number;
+        orderExpiry: number;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /**
+     * SignModifyOrder — 15 args (lighter-go #83): marketIndex, index, baseAmount, price, triggerPrice,
+     * 0,0,0 (integrator), 0,0 (self-trade), skipNonce, nonce, orderVersion, apiKeyIndex, accountIndex.
+     * `index` = the order's client order index (or order index). orderVersion 0 = unversioned.
+     */
+    signModifyOrder(p: {
+        marketIndex: number;
+        index: number;
+        baseAmount: number;
+        price: number;
+        triggerPrice: number;
+        nonce: number;
+        orderVersion?: number;
+    } & Account): LighterSignResult;
+    /** SignCancelOrder(marketIndex, orderIndex, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signCancelOrder(p: {
+        marketIndex: number;
+        orderIndex: number;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /** SignCancelAllOrders(timeInForce, time, cancelAllMarketIndex (255 = all), skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signCancelAllOrders(p: {
+        timeInForce: number;
+        time: number;
+        marketIndex?: number;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /** SignUpdateLeverage(marketIndex, fraction, marginMode, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signUpdateLeverage(p: {
+        marketIndex: number;
+        fraction: number;
+        marginMode: number;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /** SignWithdraw(assetIndex, routeType, amount, skipNonce, nonce, apiKeyIndex, accountIndex). `usdcAmount` is already in base units. */
+    signWithdraw(p: {
+        usdcAmount: number;
+        assetIndex: number;
+        routeType: number;
+        nonce: number;
+    } & Account): LighterSignResult;
+    /** SignTransfer(toAccountIndex, assetIndex, fromRouteType, toRouteType, amount, usdcFee, memo (32-byte hex), skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signTransfer(p: {
+        toAccountIndex: number;
+        assetIndex: number;
+        fromRouteType: number;
+        toRouteType: number;
+        amount: number;
+        usdcFee: number;
+        memo: string;
+        nonce: number;
+    } & Account): LighterSignResult;
+}
+export {};

package/dist/exchanges/lighter-signer.js

@@ -0,0 +1,215 @@
+/**
+ * Official Lighter WASM signer (lighter-go release v1.0.9), vendored under
+ * vendor/lighter-signer/ and loaded directly — no lighter-ts-sdk wrapper.
+ *
+ * Why: the WASM bundled in lighter-ts-sdk (1.0.10 and 1.1.0) predates lighter-go
+ * 8854554 (#89), so it rejects market ids ≥ 4095 ("MarketIndex is not valid") and
+ * treats 2048–4094 as spot (reduce-only / trigger / margin refused). Testnet perps
+ * are 4095–4097 and Lighter RH testnet perps 2048/2049.
+ *
+ * Calls follow https://apidocs.lighter.xyz/docs/wasm-signer.md exactly: positional
+ * arguments, every one required, `url` = "" in CreateClient (the WASM cannot do
+ * HTTP), and an explicit nonce (never -1, which would make the signer fetch it).
+ *
+ * Integrity: both vendored files are sha256-pinned here and verified at load; a
+ * mismatch refuses to load (nothing can be signed).
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { PerpError } from "../errors.js";
+import { LIGHTER_GTT_EXPIRY_MS } from "./venues/lighter-family.js";
+export const LIGHTER_SIGNER_VERSION = "lighter-go v1.0.9";
+/** sha256 of vendor/lighter-signer/lighter-signer.wasm (= the v1.0.9 release asset digest). */
+export const LIGHTER_SIGNER_WASM_SHA256 = "781ba28b5e7fca1ea816f516f28fe2adbe704b734828e0c941025f8133bd7b4b";
+/** sha256 of vendor/lighter-signer/wasm_exec.js (= go1.25.6 lib/wasm/wasm_exec.js). */
+export const LIGHTER_SIGNER_WASM_EXEC_SHA256 = "0c949f4996f9a89698e4b5c586de32249c3b69b7baadb64d220073cc04acba14";
+/** Same relative depth from src/exchanges/ and dist/exchanges/ to the package root. */
+export function lighterSignerDir() {
+    return fileURLToPath(new URL("../../vendor/lighter-signer/", import.meta.url));
+}
+const EXPORTS = [
+    "GenerateAPIKey", "CreateClient", "CreateAuthToken", "SignChangePubKey", "SignCreateOrder",
+    "SignModifyOrder", "SignCancelOrder", "SignCancelAllOrders", "SignUpdateLeverage",
+    "SignWithdraw", "SignTransfer",
+];
+/** cancelAllMarketIndex meaning "all markets" (wasm-signer.md SignCancelAllOrders). */
+export const LIGHTER_ALL_MARKETS = 255;
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+/** Every numeric argument must be a finite integer: the Go side truncates silently. */
+function int(name, v) {
+    if (typeof v !== "number" || !Number.isSafeInteger(v)) {
+        throw new PerpError("SIGNATURE_FAILED", `Lighter signer: ${name} must be a safe integer (got ${String(v)})`);
+    }
+    return v;
+}
+/** Explicit nonce only: -1 would make the WASM fetch it over HTTP, which it cannot do. */
+function nonceArg(v) {
+    const n = int("nonce", v);
+    if (n < 0)
+        throw new PerpError("SIGNATURE_FAILED", `Lighter signer: nonce must be explicit and ≥ 0 (got ${n})`);
+    return n;
+}
+/**
+ * One Go runtime of the official signer. The Go `main` registers its functions on
+ * globalThis and then blocks; they are captured synchronously right after `go.run()`
+ * and the globals restored, so several runtimes (one per venue+network, design §10.5)
+ * never see each other's functions.
+ */
+export class LighterWasmSigner {
+    fn;
+    constructor(fn) {
+        this.fn = fn;
+    }
+    /** Load + verify the vendored files and start a fresh runtime. */
+    static async load(dir = lighterSignerDir()) {
+        const [wasm, execJs] = await Promise.all([
+            readFile(`${dir}/lighter-signer.wasm`),
+            readFile(`${dir}/wasm_exec.js`),
+        ]);
+        const got = { wasm: sha256(wasm), exec: sha256(execJs) };
+        if (got.wasm !== LIGHTER_SIGNER_WASM_SHA256 || got.exec !== LIGHTER_SIGNER_WASM_EXEC_SHA256) {
+            throw new PerpError("SIGNATURE_FAILED", `Lighter signer files do not match the pinned ${LIGHTER_SIGNER_VERSION} checksums (lighter-signer.wasm ${got.wasm}, wasm_exec.js ${got.exec}); refusing to load`, {
+                remediation: "Reinstall perp-cli; the vendored Lighter signer is corrupted or was modified",
+            });
+        }
+        const g = globalThis;
+        // Evaluate the VERIFIED bytes (not a second read of the file); it assigns globalThis.Go.
+        const prevGo = g.Go;
+        new Function(execJs.toString("utf8"))();
+        const Go = g.Go;
+        if (prevGo === undefined)
+            delete g.Go;
+        else
+            g.Go = prevGo;
+        if (typeof Go !== "function")
+            throw new PerpError("SIGNATURE_FAILED", "Lighter signer: wasm_exec.js did not define Go");
+        const go = new Go();
+        let exitCode = null;
+        // Go's default exit only logs; a runtime that exits can no longer sign — record it.
+        go.exit = (code) => { exitCode = code; };
+        const { instance } = await WebAssembly.instantiate(wasm, go.importObject);
+        const saved = new Map(EXPORTS.map(n => [n, g[n]]));
+        void go.run(instance).catch(() => { exitCode = exitCode ?? -1; });
+        const fn = {};
+        for (const n of EXPORTS) {
+            const f = g[n];
+            if (typeof f !== "function")
+                throw new PerpError("SIGNATURE_FAILED", `Lighter signer: WASM did not export ${n}`);
+            fn[n] = f;
+        }
+        for (const [n, v] of saved) {
+            if (v === undefined)
+                delete g[n];
+            else
+                g[n] = v;
+        }
+        const signer = new LighterWasmSigner(fn);
+        signer.exited = () => exitCode !== null;
+        return signer;
+    }
+    exited = () => false;
+    call(name, args) {
+        if (this.exited())
+            throw new PerpError("SIGNATURE_FAILED", "Lighter WASM signer runtime has exited");
+        const r = this.fn[name](...args);
+        if (r === undefined || r === null || typeof r !== "object") {
+            throw new PerpError("SIGNATURE_FAILED", `Lighter signer ${name} returned no result`);
+        }
+        return r;
+    }
+    tx(name, args) {
+        const r = this.call(name, args);
+        if (typeof r.error === "string" && r.error !== "") {
+            return { txType: NaN, txInfo: "", txHash: "", error: r.error };
+        }
+        const out = { txType: Number(r.txType), txInfo: String(r.txInfo ?? ""), txHash: String(r.txHash ?? "") };
+        if (typeof r.messageToSign === "string")
+            out.messageToSign = r.messageToSign;
+        return out;
+    }
+    generateAPIKey() {
+        const r = this.call("GenerateAPIKey", []);
+        if (typeof r.error === "string")
+            throw new PerpError("SIGNATURE_FAILED", `Lighter GenerateAPIKey: ${r.error}`);
+        if (typeof r.privateKey !== "string" || typeof r.publicKey !== "string") {
+            throw new PerpError("SIGNATURE_FAILED", "Lighter GenerateAPIKey returned no key pair");
+        }
+        return { privateKey: r.privateKey, publicKey: r.publicKey };
+    }
+    /** CreateClient(url = "", privateKey, chainId, apiKeyIndex, accountIndex). `url` is ignored (kept for call-site compatibility). */
+    createClient(p) {
+        const r = this.call("CreateClient", ["", p.privateKey, int("chainId", p.chainId), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex)]);
+        if (typeof r.error === "string" && r.error !== "")
+            throw new PerpError("SIGNATURE_FAILED", `Lighter CreateClient: ${r.error}`);
+    }
+    /** CreateAuthToken(deadline unix s, apiKeyIndex, accountIndex) → token string. */
+    createAuthToken(deadline, apiKeyIndex, accountIndex) {
+        const r = this.call("CreateAuthToken", [int("deadline", deadline), int("apiKeyIndex", apiKeyIndex), int("accountIndex", accountIndex)]);
+        if (typeof r.error === "string" && r.error !== "")
+            throw new PerpError("SIGNATURE_FAILED", `Lighter CreateAuthToken: ${r.error}`);
+        if (typeof r.authToken !== "string" || r.authToken === "")
+            throw new PerpError("SIGNATURE_FAILED", "Lighter CreateAuthToken returned no token");
+        return r.authToken;
+    }
+    /** SignChangePubKey(pubKeyHex, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signChangePubKey(p) {
+        return this.tx("SignChangePubKey", [p.pubkey, 0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex)]);
+    }
+    /**
+     * SignCreateOrder — 19 args. Integrator fields and self-trade modes are 0 (defaults);
+     * skipNonce 0. `orderExpiry` −1 = GTT default: now + LIGHTER_GTT_EXPIRY_MS (28 days), resolved here.
+     */
+    signCreateOrder(p) {
+        const expiry = p.orderExpiry === -1 ? Date.now() + LIGHTER_GTT_EXPIRY_MS : int("orderExpiry", p.orderExpiry);
+        return this.tx("SignCreateOrder", [
+            int("marketIndex", p.marketIndex), int("clientOrderIndex", p.clientOrderIndex), int("baseAmount", p.baseAmount),
+            int("price", p.price), int("isAsk", p.isAsk), int("orderType", p.orderType), int("timeInForce", p.timeInForce),
+            int("reduceOnly", p.reduceOnly), int("triggerPrice", p.triggerPrice), expiry,
+            0, 0, 0, // integratorAccountIndex, integratorTakerFee, integratorMakerFee
+            0, 0, // selfTradeBehaviorMode, selfTradeEqualityMode
+            0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex),
+        ]);
+    }
+    /**
+     * SignModifyOrder — 15 args (lighter-go #83): marketIndex, index, baseAmount, price, triggerPrice,
+     * 0,0,0 (integrator), 0,0 (self-trade), skipNonce, nonce, orderVersion, apiKeyIndex, accountIndex.
+     * `index` = the order's client order index (or order index). orderVersion 0 = unversioned.
+     */
+    signModifyOrder(p) {
+        return this.tx("SignModifyOrder", [
+            int("marketIndex", p.marketIndex), int("index", p.index), int("baseAmount", p.baseAmount), int("price", p.price),
+            int("triggerPrice", p.triggerPrice), 0, 0, 0, 0, 0, 0, nonceArg(p.nonce), int("orderVersion", p.orderVersion ?? 0),
+            int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex),
+        ]);
+    }
+    /** SignCancelOrder(marketIndex, orderIndex, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signCancelOrder(p) {
+        return this.tx("SignCancelOrder", [int("marketIndex", p.marketIndex), int("orderIndex", p.orderIndex), 0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex)]);
+    }
+    /** SignCancelAllOrders(timeInForce, time, cancelAllMarketIndex (255 = all), skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signCancelAllOrders(p) {
+        return this.tx("SignCancelAllOrders", [
+            int("timeInForce", p.timeInForce), int("time", p.time), int("cancelAllMarketIndex", p.marketIndex ?? LIGHTER_ALL_MARKETS),
+            0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex),
+        ]);
+    }
+    /** SignUpdateLeverage(marketIndex, fraction, marginMode, skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signUpdateLeverage(p) {
+        return this.tx("SignUpdateLeverage", [int("marketIndex", p.marketIndex), int("fraction", p.fraction), int("marginMode", p.marginMode), 0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex)]);
+    }
+    /** SignWithdraw(assetIndex, routeType, amount, skipNonce, nonce, apiKeyIndex, accountIndex). `usdcAmount` is already in base units. */
+    signWithdraw(p) {
+        return this.tx("SignWithdraw", [int("assetIndex", p.assetIndex), int("routeType", p.routeType), int("amount", p.usdcAmount), 0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex)]);
+    }
+    /** SignTransfer(toAccountIndex, assetIndex, fromRouteType, toRouteType, amount, usdcFee, memo (32-byte hex), skipNonce, nonce, apiKeyIndex, accountIndex). */
+    signTransfer(p) {
+        return this.tx("SignTransfer", [
+            int("toAccountIndex", p.toAccountIndex), int("assetIndex", p.assetIndex), int("fromRouteType", p.fromRouteType),
+            int("toRouteType", p.toRouteType), int("amount", p.amount), int("usdcFee", p.usdcFee), p.memo,
+            0, nonceArg(p.nonce), int("apiKeyIndex", p.apiKeyIndex), int("accountIndex", p.accountIndex),
+        ]);
+    }
+}

package/dist/exchanges/lighter-spot.d.ts

@@ -6,10 +6,17 @@
  *
  * Composes with LighterAdapter for signing and API access.
  */
-import type { SpotAdapter, SpotMarketInfo, SpotBalance } from "./spot-interface.js";
+import { type SpotAdapter, type SpotMarketInfo, type SpotBalance } from "./spot-interface.js";
+import type { ResolvedSlippage } from "./slippage.js";
 import type { LighterAdapter } from "./lighter.js";
+/**
+ * `venueRaw.fillSource` of a spot IOC fill read from the order's accountOrders row
+ * (`filled_base_amount`, the venue's own field — never size − remaining).
+ */
+export declare const ACCOUNT_ORDERS_FILL_SOURCE = "account-orders";
 export declare class LighterSpotAdapter implements SpotAdapter {
-    readonly name = "lighter";
+    /** Venue id of the wrapped LighterAdapter ("lighter" | "lighter-rh"). */
+    readonly name: string;
     private _lt;
     private _spotMarketMap;
     private _spotBaseMap;
@@ -17,8 +24,9 @@ export declare class LighterSpotAdapter implements SpotAdapter {
     private _spotMinSize;
     private _spotPrices;
     private _initialized;
-    private _clientOrderCounter;
     constructor(ltAdapter: LighterAdapter);
+    /** Quote/collateral symbol of the wrapped venue ("USDC" on Lighter, "USDG" on Lighter RH). */
+    private get _quote();
     init(): Promise<void>;
     private _loadSpotMarkets;
     /** Resolve a symbol (e.g., "ETH" or "ETH/USDC") to the full spot symbol */
@@ -30,44 +38,114 @@ export declare class LighterSpotAdapter implements SpotAdapter {
         bids: [string, string][];
         asks: [string, string][];
     }>;
+    /**
+     * Spot token balances. Reads the account through the shared 15s `acct:` cache
+     * (same entry as LighterAdapter.fetchAccount()). Throws on any failure — never []
+     * (Rule #2: an empty list is indistinguishable from an empty wallet).
+     * Fill measurement / post-trade verification must use getSpotBalancesFresh().
+     */
     getSpotBalances(): Promise<SpotBalance[]>;
-    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string): Promise<unknown>;
+    /** Uncached read (always hits /account, then refreshes the shared cache entry). */
+    getSpotBalancesFresh(): Promise<SpotBalance[]>;
+    private _spotBalances;
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        slippage: ResolvedSlippage;
+    }): Promise<unknown>;
+    /** Poll /tx by hash (lighterTxState): rejected → ORDER_REJECTED; returns the last state + raw tx. */
+    private _awaitTx;
+    /**
+     * Final IOC outcome of a sent spot order (market or limit IOC) — see spotMarketOrder. Returns
+     * a final SpotOrderResult, throws ORDER_REJECTED for a zero fill, or null when neither /tx nor
+     * accountOrders settled it.
+     */
+    private _iocOutcome;
+    /** Pre-send part of spotMarketOrder: market, min size, reference price, ticks. */
+    private _prepareMarketOrder;
+    /**
+     * Final IOC fill of a spotMarketOrder / IOC spotLimitOrder result (SpotOrderResult read from
+     * the tx event_info or the accountOrders row), or null when the outcome is unknown (raw sendTx
+     * result → balance delta).
+     */
+    iocOutcomeOf(raw: unknown): {
+        filledSize: string;
+        final: true;
+    } | null;
     spotLimitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         tif?: string;
     }): Promise<unknown>;
+    /**
+     * TIF mapping, as perps (§13.3): GTC/GTT → GTT, IOC → IOC, ALO / POST_ONLY → post-only (2).
+     * FOK and anything else → CAPABILITY_UNSUPPORTED (never silently GTT).
+     */
+    private _limitTif;
+    /**
+     * Final placement outcome of a resting (GTT / post-only) spot limit, as perps
+     * (LighterAdapter.resolveOrderOutcome): /tx rejected → ORDER_REJECTED; the executed tx's
+     * event_info taker order (this client order index) "filled" → filled; otherwise the order's
+     * accountOrders row by client order index (status + filled_base_amount: open, filled,
+     * canceled-* — e.g. a crossing post-only). Unresolved → null (pending).
+     */
+    private _placementOutcome;
     spotCancelOrder(symbol: string, orderId: string): Promise<unknown>;
-    /** Cancel all orders across all markets (spot + perp) */
-    spotCancelAllOrders(_symbol?: string): Promise<unknown>;
+    /**
+     * Venue-final outcome of a sent spot cancel, as perps (awaitTxExecuted + cancelOutcome): /tx
+     * rejected → ORDER_REJECTED (the order is untouched). Then the order's own row — by client
+     * order index (accountOrders), else by order id among the market's active, then latest 100
+     * inactive orders: canceled-* → cancelled (a fill before the cancel → partial, filledSize from
+     * filled_base_amount), filled → filled (it filled before the cancel landed). Still open / not
+     * readable after a few reads → finality "pending" (do NOT resubmit).
+     */
+    private _cancelOutcome;
+    /** The order's venue row: accountOrders by client order index, else active → latest 100 inactive by order id; not listed → null. */
+    private _orderRow;
+    /**
+     * Cancel the SPOT open orders (of `symbol`, or of every spot market) one by one. Never the
+     * account-wide CancelAllOrders tx (market 255): it would also cancel the account's perp orders.
+     */
+    spotCancelAllOrders(symbol?: string | null): Promise<unknown>;
     /** Transfer USDC from perp account to spot account (required before spot buys) */
     transferUsdcToSpot(amount: number): Promise<unknown>;
     /** Transfer USDC from spot account back to perp account */
     transferUsdcToPerp(amount: number): Promise<unknown>;
+    /** SpotTransferCapable (§12.4 #4): only the venue collateral (USDC on Lighter, USDG on Lighter RH). */
+    transferToSpot(amount: string, asset: string): Promise<unknown>;
+    transferToPerp(amount: string, asset: string): Promise<unknown>;
+    private _transferAmount;
     /**
-     * Internal self-transfer using raw WASM signTransfer.
-     * TS SDK's is_spot_account mapping is buggy (sets both fromRoute and toRoute
-     * to the same value), so we call the WASM module directly with explicit routes.
-     * Route types: 0 = Perp, 1 = Spot
+     * Internal self-transfer (same account, perp ↔ spot route) signed with the official
+     * WASM SignTransfer and explicit routes. Route types: 0 = Perp, 1 = Spot. Same-owner
+     * transfer → no L1 signature needed (wasm-signer.md).
      */
     private _selfTransfer;
     /** Get the spot market ID for a symbol */
     getSpotMarketId(symbol: string): number | undefined;
     /** Check if a base token has a spot market */
     hasSpotMarket(base: string): boolean;
-    /** Query open orders across all spot markets (market_id ≥ 2048). */
-    getSpotOpenOrders(): Promise<Array<{
+    /** Query open orders across all spot markets (the market_type "spot" markets loaded at init). */
+    getSpotOpenOrders(symbol?: string | null): Promise<Array<{
         orderId: string;
         symbol: string;
         side: "buy" | "sell";
         price: string;
         size: string;
+        filled: string;
         clientOrderIndex?: number;
     }>>;
     /** Cancel a spot order by clientOrderIndex (safe integer, avoids order_id overflow). */
     spotCancelByClientIndex(symbol: string, clientOrderIndex: number): Promise<unknown>;
     private _placeOrder;
-    /** Generate a unique client order index (uint48). Uses timestamp + counter. */
+    private _signOrder;
+    /** Generated client order index (uint48): ms timestamp + random bits — see lighterGeneratedClientOrderIndex. */
     private _nextClientOrderIndex;
     private _getNextNonce;
+    /**
+     * POST /sendTx. `kind` "place" (order placement): failures are typed (design
+     * §12.3): before the request → ORDER_REJECTED; transport error, HTTP 5xx or an
+     * unreadable body after it → ORDER_PENDING (the tx may have been accepted — never
+     * resubmit); an explicit non-200 code → ORDER_REJECTED. "order" (cancels) / "action"
+     * (transfers): an explicit non-200 code → ORDER_REJECTED / ACTION_REJECTED
+     * (lighterSendTxRejection — validated and refused before execution).
+     */
     private _sendTx;
     private _restGet;
     private _restGetAuth;