perp-cli 0.12.15 → 0.14.0

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

@@ -0,0 +1,43 @@
+/**
+ * Lighter-family public market data (`lighter`, `lighter-rh`) — design §10.6.
+ *
+ * Sources (REST base from venues/lighter-family.ts, per venue + network):
+ *   GET /api/v1/orderBookDetails  → perps in `order_book_details` (decimals, min
+ *       amounts, status, mark/index price, IMF, OI, volume). It carries every
+ *       field /orderBooks has, so /orderBooks is not fetched (one fewer call
+ *       under the 60 req/min standard limit).
+ *   GET /api/v1/funding-rates     → MULTI-EXCHANGE aggregate (binance/bybit/
+ *       hyperliquid/lighter). Only rows with exchange === "lighter" are the
+ *       venue's own; the RH host labels its own rows "lighter" too (live
+ *       2026-09-30: 57 "lighter" rows = RH's 57 perps, matched by market_id).
+ *
+ * FUNDING: basis 8h per quoted rate, hourly settlement (design §10.1, Lighter
+ * and Lighter RH identical).
+ *
+ * ASSET CLASS: the API has no asset-class field (the undocumented
+ * `strategy_index` groups markets on Lighter main but is 0 for every RH market),
+ * so classification is an explicit per-venue table built from live listings on
+ * 2026-09-30:
+ *   - lighter-rh: every listed perp is in RH_CLASS. An unlisted symbol is
+ *     excluded with a warning until it is classified (RH lists mostly equities,
+ *     so no class can be assumed).
+ *   - lighter: crypto-centric venue. LIGHTER_NON_CRYPTO lists every non-crypto
+ *     perp; any other symbol is crypto by this venue's definition.
+ *     LIGHTER_AMBIGUOUS tickers are excluded with a warning so they cannot
+ *     produce a false cross-venue match.
+ *
+ * OPEN INTEREST: `open_interest` in base units (same value legacy getMarkets reports).
+ */
+import { PerpError } from "../errors.js";
+import type { VenuePublicData } from "./venue.js";
+import type { LighterVenueId } from "./venues/lighter-family.js";
+/**
+ * The venue's firewall answering instead of the API: HTTP 405 / 403 with a non-JSON (HTML
+ * "Human Verification") body → typed RATE_LIMITED, never the HTML in the message; null for any
+ * other response. Live 2026-10-05: after a burst Lighter mainnet answers EVERY request (public
+ * GET /orderBooks included) this way for 1–2 minutes. Docs (apidocs.lighter.xyz/docs/rate-limits):
+ * a breached limit answers "HTTP 429, or HTTP 405"; cooldown "Firewall: 60 seconds, static".
+ * The API's own answers are JSON, so a JSON 405 / 403 is not a challenge.
+ */
+export declare function lighterWafChallenge(venue: string, status: number, body: string): PerpError | null;
+export declare function lighterPublicData(venue: LighterVenueId): VenuePublicData;

package/dist/exchanges/lighter-public.js

@@ -0,0 +1,276 @@
+/**
+ * Lighter-family public market data (`lighter`, `lighter-rh`) — design §10.6.
+ *
+ * Sources (REST base from venues/lighter-family.ts, per venue + network):
+ *   GET /api/v1/orderBookDetails  → perps in `order_book_details` (decimals, min
+ *       amounts, status, mark/index price, IMF, OI, volume). It carries every
+ *       field /orderBooks has, so /orderBooks is not fetched (one fewer call
+ *       under the 60 req/min standard limit).
+ *   GET /api/v1/funding-rates     → MULTI-EXCHANGE aggregate (binance/bybit/
+ *       hyperliquid/lighter). Only rows with exchange === "lighter" are the
+ *       venue's own; the RH host labels its own rows "lighter" too (live
+ *       2026-09-30: 57 "lighter" rows = RH's 57 perps, matched by market_id).
+ *
+ * FUNDING: basis 8h per quoted rate, hourly settlement (design §10.1, Lighter
+ * and Lighter RH identical).
+ *
+ * ASSET CLASS: the API has no asset-class field (the undocumented
+ * `strategy_index` groups markets on Lighter main but is 0 for every RH market),
+ * so classification is an explicit per-venue table built from live listings on
+ * 2026-09-30:
+ *   - lighter-rh: every listed perp is in RH_CLASS. An unlisted symbol is
+ *     excluded with a warning until it is classified (RH lists mostly equities,
+ *     so no class can be assumed).
+ *   - lighter: crypto-centric venue. LIGHTER_NON_CRYPTO lists every non-crypto
+ *     perp; any other symbol is crypto by this venue's definition.
+ *     LIGHTER_AMBIGUOUS tickers are excluded with a warning so they cannot
+ *     produce a false cross-venue match.
+ *
+ * OPEN INTEREST: `open_interest` in base units (same value legacy getMarkets reports).
+ */
+import { PerpError } from "../errors.js";
+import { venueRateField } from "../utils/numeric.js";
+import { acquireRate, rateLimitedError } from "./rate-limiter.js";
+import { canonicalFor } from "./canonical-symbols.js";
+import { lighterFamilyNetworks, lighterFamilyRateLimit } from "./venues/lighter-family.js";
+const BASIS_8H = { kind: "perHours", hours: 8 };
+const SETTLEMENT_INTERVAL_HOURS = 1;
+// ── Classification tables (live listings 2026-09-30) ──
+const RH_CLASS = {
+    // crypto
+    BTC: "crypto", ETH: "crypto", SOL: "crypto", HYPE: "crypto", ZEC: "crypto", LIT: "crypto",
+    VVV: "crypto", SUI: "crypto", NEAR: "crypto", XRP: "crypto", CASHCAT: "crypto", PONS: "crypto",
+    // commodity (canonical via EXPLICIT_CANONICAL: XAU → GOLD, XAG → SILVER)
+    XAU: "commodity", XAG: "commodity",
+    // etf
+    SPY: "etf", QQQ: "etf", SOXL: "etf", SLV: "etf", USO: "etf", SGOV: "etf",
+    // equity
+    AAPL: "equity", AMZN: "equity", GOOGL: "equity", META: "equity", MSFT: "equity", NVDA: "equity",
+    TSLA: "equity", AMD: "equity", INTC: "equity", MU: "equity", TSM: "equity", ORCL: "equity",
+    PLTR: "equity", COIN: "equity", CRCL: "equity", CRWV: "equity", BABA: "equity", SNDK: "equity",
+    SMCI: "equity", SOFI: "equity", AMC: "equity", RGTI: "equity", QBTS: "equity", CLSK: "equity",
+    IREN: "equity", WULF: "equity", LUNR: "equity", ASTS: "equity", BE: "equity", USAR: "equity",
+    SPCX: "equity", SKHY: "equity",
+    // pre-IPO / private (explicit-only canonical → null unless mapped)
+    OPENAI: "preIpo", ANTHROPIC: "preIpo", SHEIN: "preIpo", ANSEM: "preIpo", AI: "preIpo",
+};
+const LIGHTER_NON_CRYPTO = {
+    // commodity
+    XAU: "commodity", XAG: "commodity", XPD: "commodity", XPT: "commodity", XCU: "commodity",
+    WTI: "commodity", BRENTOIL: "commodity", NATGAS: "commodity", WHEAT: "commodity", URA: "commodity",
+    H100: "commodity",
+    // fx
+    EURUSD: "fx", GBPUSD: "fx", AUDUSD: "fx", NZDUSD: "fx", USDJPY: "fx", USDCAD: "fx",
+    USDCHF: "fx", USDHKD: "fx", USDKRW: "fx",
+    // index
+    US500: "index", US100: "index", US10Y: "index", KRCOMP: "index",
+    // etf
+    SPY: "etf", QQQ: "etf", IWM: "etf", DIA: "etf", SOXL: "etf", SOXS: "etf", SOXX: "etf",
+    BOTZ: "etf", MAGS: "etf", EWY: "etf", KORU: "etf",
+    // equity (US)
+    AAPL: "equity", AMZN: "equity", GOOGL: "equity", META: "equity", MSFT: "equity", NVDA: "equity",
+    TSLA: "equity", AMD: "equity", INTC: "equity", MU: "equity", TSM: "equity", ORCL: "equity",
+    PLTR: "equity", COIN: "equity", CRCL: "equity", CRWV: "equity", BABA: "equity", SNDK: "equity",
+    MSTR: "equity", ARM: "equity", NBIS: "equity", BMNR: "equity", CBRS: "equity", AVGO: "equity",
+    IBM: "equity", GEV: "equity", MRVL: "equity", HOOD: "equity", LITE: "equity", QCOM: "equity",
+    BE: "equity", AAOI: "equity", AXTI: "equity", GME: "equity", NOK: "equity", TTWO: "equity",
+    RKLB: "equity", MRNA: "equity", DELL: "equity", NOW: "equity", ASML: "equity", STRC: "equity",
+    SPCX: "equity", DRAM: "equity", WDC: "equity",
+    // equity (Asia)
+    SAMSUNG: "equity", SAMSUNGUSD: "equity", HYUNDAI: "equity", HYUNDAIUSD: "equity", HANMI: "equity",
+    SKHYNIX: "equity", SKHYNIXUSD: "equity", SKHY: "equity", BYD: "equity", TENCENT: "equity",
+    POPMART: "equity", KIOXIA: "equity", SMIC: "equity", XIAOMI: "equity",
+    // pre-IPO / private / unclear listing status (explicit-only canonical)
+    OPENAI: "preIpo", ANTHROPIC: "preIpo", SPACEX: "preIpo", SHEIN: "preIpo", CXMT: "preIpo",
+    ZHIPU: "preIpo", UNITREE: "preIpo", MINIMAX: "preIpo", AI: "preIpo", ANSEM: "preIpo",
+    STABLECOINX: "preIpo", OURA: "preIpo", PRL: "preIpo", ADI: "preIpo",
+};
+/**
+ * Excluded from cross-venue data until mapped explicitly:
+ * - BB, BOT, WEN, QNT: Lighter groups them with US equities, but each is also a live crypto ticker elsewhere.
+ * - SPX: the SPX6900 token on Lighter; its ticker equals the canonical key of the S&P 500 index ("SPX").
+ */
+const LIGHTER_AMBIGUOUS = new Set(["BB", "BOT", "WEN", "QNT", "SPX"]);
+/** Asset class for a venue symbol, or null when it must be excluded (unclassified / ambiguous). */
+function classify(venue, symbol) {
+    const up = symbol.toUpperCase();
+    switch (venue) {
+        case "lighter-rh":
+            return RH_CLASS[up] ?? null;
+        case "lighter":
+            if (LIGHTER_AMBIGUOUS.has(up))
+                return null;
+            return LIGHTER_NON_CRYPTO[up] ?? "crypto"; // crypto-centric venue: non-crypto is listed explicitly
+    }
+}
+function warnExcluded(venue, what, symbols) {
+    if (symbols.length > 0) {
+        console.warn(`[${venue}] excluded ${symbols.length} ${what}: ${symbols.join(", ")}`);
+    }
+}
+// ── HTTP ──
+/**
+ * The venue's firewall answering instead of the API: HTTP 405 / 403 with a non-JSON (HTML
+ * "Human Verification") body → typed RATE_LIMITED, never the HTML in the message; null for any
+ * other response. Live 2026-10-05: after a burst Lighter mainnet answers EVERY request (public
+ * GET /orderBooks included) this way for 1–2 minutes. Docs (apidocs.lighter.xyz/docs/rate-limits):
+ * a breached limit answers "HTTP 429, or HTTP 405"; cooldown "Firewall: 60 seconds, static".
+ * The API's own answers are JSON, so a JSON 405 / 403 is not a challenge.
+ */
+export function lighterWafChallenge(venue, status, body) {
+    if (status !== 405 && status !== 403)
+        return null;
+    try {
+        JSON.parse(body);
+        return null;
+    }
+    catch { /* not JSON: the firewall's page */ }
+    return new PerpError("RATE_LIMITED", `${venue}: blocked by the venue's WAF challenge (HTTP ${status} Human Verification) — wait 1–2 minutes`, {
+        exchange: venue, retryAfterMs: 60_000,
+        remediation: `Wait 1–2 minutes before the next ${venue} request, then retry at a lower request rate (standard accounts: 60 requests per rolling minute)`,
+    });
+}
+async function getJson(venue, net, path, endpoint) {
+    await acquireRate(`${venue}:${net}`, lighterFamilyRateLimit(venue), endpoint);
+    const base = lighterFamilyNetworks(venue)[net].restUrl;
+    const res = await fetch(`${base}/api/v1${path}`, { signal: AbortSignal.timeout(15_000) });
+    const text = await res.text();
+    if (res.status === 429)
+        throw rateLimitedError(venue, res.headers.get("retry-after"), text);
+    const waf = lighterWafChallenge(venue, res.status, text);
+    if (waf !== null)
+        throw waf;
+    if (!res.ok) {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} GET ${path} HTTP ${res.status}`, { body: text.slice(0, 500) });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} GET ${path}: invalid JSON`, { body: text.slice(0, 500) });
+    }
+}
+function isNumStr(v) {
+    return typeof v === "string" && v.length > 0 && Number.isFinite(Number(v));
+}
+function validDetail(d) {
+    return typeof d.symbol === "string" && Number.isInteger(d.market_id)
+        && Number.isInteger(d.price_decimals) && d.price_decimals >= 0
+        && Number.isInteger(d.size_decimals) && d.size_decimals >= 0
+        && isNumStr(d.min_base_amount) && isNumStr(d.min_quote_amount)
+        && typeof d.min_initial_margin_fraction === "number" && d.min_initial_margin_fraction > 0
+        && isNumStr(d.mark_price) && typeof d.status === "string";
+}
+async function fetchPerpDetails(venue, net) {
+    const json = await getJson(venue, net, "/orderBookDetails", "orderBookDetails");
+    const list = json.order_book_details;
+    if (!Array.isArray(list)) {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} orderBookDetails: missing order_book_details array`);
+    }
+    const out = [];
+    const malformed = [];
+    for (const d of list) {
+        if (d.market_type !== "perp")
+            continue;
+        if (!validDetail(d)) {
+            malformed.push(String(d.symbol));
+            continue;
+        }
+        out.push(d);
+    }
+    warnExcluded(venue, "malformed market(s)", malformed);
+    return out;
+}
+/** The venue's own funding rows, keyed by market_id. */
+async function fetchOwnFunding(venue, net) {
+    const json = await getJson(venue, net, "/funding-rates", "funding-rates");
+    const list = json.funding_rates;
+    if (!Array.isArray(list)) {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} funding-rates: missing funding_rates array`);
+    }
+    const map = new Map();
+    for (const r of list) {
+        if (r.exchange !== "lighter")
+            continue; // other exchanges' rates in the aggregate
+        if (!Number.isInteger(r.market_id) || typeof r.symbol !== "string" || typeof r.rate !== "number" || !Number.isFinite(r.rate)) {
+            throw new PerpError("EXCHANGE_ERROR", `${venue} funding-rates: malformed own row ${JSON.stringify(r).slice(0, 200)}`);
+        }
+        map.set(r.market_id, r);
+    }
+    return map;
+}
+function stepFromDecimals(d) {
+    return d === 0 ? "1" : `0.${"0".repeat(d - 1)}1`;
+}
+function toMarket(venue, net, d, assetClass, fr) {
+    const settle = lighterFamilyNetworks(venue)[net].collateral[0];
+    if (!settle)
+        throw new PerpError("INVALID_PARAMS", `${venue} ${net} network config has no collateral`);
+    return {
+        venue,
+        venueSymbol: String(d.market_id),
+        symbol: d.symbol,
+        canonical: canonicalFor(venue, d.symbol, assetClass),
+        assetClass,
+        settle,
+        quoteAsset: null,
+        markPrice: d.mark_price,
+        indexPrice: isNumStr(d.index_price) ? d.index_price : null,
+        fundingRate: fr ? venueRateField(fr.rate, "funding-rates rate", venue) : null,
+        fundingRateBasis: BASIS_8H,
+        settlementIntervalHours: SETTLEMENT_INTERVAL_HOURS,
+        openInterest: typeof d.open_interest === "number" ? String(d.open_interest) : null,
+        volume24h: typeof d.daily_quote_token_volume === "number" ? String(d.daily_quote_token_volume) : null,
+        tickSize: stepFromDecimals(d.price_decimals),
+        stepSize: stepFromDecimals(d.size_decimals),
+        minSize: d.min_base_amount,
+        minNotional: d.min_quote_amount,
+        maxLeverage: Math.floor(10000 / d.min_initial_margin_fraction),
+        marginTiers: null,
+        session: null, // RH: 24/7, no session info published
+        tradable: d.status === "active" && d.is_frozen !== true,
+    };
+}
+export function lighterPublicData(venue) {
+    return {
+        async fetchMarkets(net) {
+            const [details, funding] = await Promise.all([fetchPerpDetails(venue, net), fetchOwnFunding(venue, net)]);
+            const out = [];
+            const unclassified = [];
+            for (const d of details) {
+                const cls = classify(venue, d.symbol);
+                if (cls === null) {
+                    unclassified.push(d.symbol);
+                    continue;
+                }
+                out.push(toMarket(venue, net, d, cls, funding.get(d.market_id)));
+            }
+            warnExcluded(venue, "unclassified/ambiguous market(s)", unclassified);
+            return out;
+        },
+        async fetchFundingRates(net) {
+            const funding = await fetchOwnFunding(venue, net);
+            const out = [];
+            const unclassified = [];
+            for (const r of funding.values()) {
+                const cls = classify(venue, r.symbol);
+                if (cls === null) {
+                    unclassified.push(r.symbol);
+                    continue;
+                }
+                out.push({
+                    venue,
+                    venueSymbol: String(r.market_id),
+                    symbol: r.symbol,
+                    canonical: canonicalFor(venue, r.symbol, cls),
+                    rate: venueRateField(r.rate, "funding-rates rate", venue),
+                    basis: BASIS_8H,
+                    markPrice: null, // /funding-rates carries no mark price
+                    nextFundingTime: null, // not published
+                });
+            }
+            warnExcluded(venue, "unclassified/ambiguous market(s)", unclassified);
+            return out;
+        },
+    };
+}

package/dist/exchanges/lighter-rh-deposit.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Lighter RH deposit on Robinhood Chain (apidocs.rh.lighter.xyz
+ * "Deposits, Transfers, and Withdrawals" + apidocs.lighter.xyz/docs/lighter-rh):
+ *
+ *   ERC-20 approve(ZkLighterContract, amount) → deposit(_to, _assetIndex, _routeType, _amount)
+ *
+ * Contract, chain id and token are PINNED in the venue definition (networks.<net>.depositPins,
+ * verified against the official docs) and cross-checked against the live venue API — any
+ * disagreement is EXCHANGE_ERROR before anything is signed (a compromised/misconfigured API
+ * cannot redirect the approve or the deposit):
+ *   - contract  — GET /api/v1/layer1BasicInfo  contract_addresses[name=ZkLighterContract] == pins.contract
+ *   - L1 chain  — GET /api/v1/layer1BasicInfo  l1_providers[0].chainId == pins.chainId == RPC eth_chainId
+ *   - token     — GET /api/v1/assetDetails?asset_id=<collateralAssetIndex>  l1_address == pins.token,
+ *                 symbol must equal the venue collateral (USDG); l1_decimals read live
+ *   - RPC       — venue definition networks.<net>.rpcUrl
+ * Minimum 1 USDG per deposit (docs). Only USDG may be routed to perps (route 0).
+ *
+ * Testnet: the RH testnet L1 (chainId 123456) has no documented RPC → CAPABILITY_UNSUPPORTED.
+ * Transactions are signed by the master wallet through a transaction signer (the digest is
+ * derived from the unsigned tx inside the signer — no raw-digest API).
+ */
+import { Transaction } from "ethers";
+import type { Network } from "./venue-types.js";
+/** Docs: "There is a minimum of 1 USDG, and equivalent for other ERC20s, per deposit." */
+export declare const LIGHTER_RH_MIN_DEPOSIT = 1;
+export interface LighterRhDepositPlan {
+    network: Network;
+    rpcUrl: string;
+    chainId: number;
+    contract: string;
+    asset: string;
+    assetIndex: number;
+    token: string;
+    decimals: number;
+    amount: string;
+    amountRaw: bigint;
+    routeType: 0 | 1;
+    depositor: string;
+    tokenBalance: bigint;
+    allowance: bigint;
+    needsApprove: boolean;
+}
+export interface LighterRhDepositResult {
+    approveTxHash: string | null;
+    depositTxHash: string;
+}
+/** Signs an unsigned tx (hashing internally) and returns the 65-byte 0x signature. */
+export type TxSigner = (tx: Transaction) => Promise<string>;
+/** Deposit is offered on mainnet only; testnet → uniform CAPABILITY_UNSUPPORTED. */
+export declare function requireLighterRhDepositNetwork(net: Network): void;
+/**
+ * Read-only: resolve contract / token / chain from the venue API and the depositor's
+ * balance + allowance from the RPC. Throws before anything is signed.
+ */
+export declare function planLighterRhDeposit(p: {
+    network: Network;
+    amount: string;
+    depositor: string;
+    routeType: 0 | 1;
+}): Promise<LighterRhDepositPlan>;
+/** Sends approve (only when the allowance is short — exact amount, not unlimited) then deposit. */
+export declare function executeLighterRhDeposit(plan: LighterRhDepositPlan, sign: TxSigner): Promise<LighterRhDepositResult>;

package/dist/exchanges/lighter-rh-deposit.js

@@ -0,0 +1,185 @@
+/**
+ * Lighter RH deposit on Robinhood Chain (apidocs.rh.lighter.xyz
+ * "Deposits, Transfers, and Withdrawals" + apidocs.lighter.xyz/docs/lighter-rh):
+ *
+ *   ERC-20 approve(ZkLighterContract, amount) → deposit(_to, _assetIndex, _routeType, _amount)
+ *
+ * Contract, chain id and token are PINNED in the venue definition (networks.<net>.depositPins,
+ * verified against the official docs) and cross-checked against the live venue API — any
+ * disagreement is EXCHANGE_ERROR before anything is signed (a compromised/misconfigured API
+ * cannot redirect the approve or the deposit):
+ *   - contract  — GET /api/v1/layer1BasicInfo  contract_addresses[name=ZkLighterContract] == pins.contract
+ *   - L1 chain  — GET /api/v1/layer1BasicInfo  l1_providers[0].chainId == pins.chainId == RPC eth_chainId
+ *   - token     — GET /api/v1/assetDetails?asset_id=<collateralAssetIndex>  l1_address == pins.token,
+ *                 symbol must equal the venue collateral (USDG); l1_decimals read live
+ *   - RPC       — venue definition networks.<net>.rpcUrl
+ * Minimum 1 USDG per deposit (docs). Only USDG may be routed to perps (route 0).
+ *
+ * Testnet: the RH testnet L1 (chainId 123456) has no documented RPC → CAPABILITY_UNSUPPORTED.
+ * Transactions are signed by the master wallet through a transaction signer (the digest is
+ * derived from the unsigned tx inside the signer — no raw-digest API).
+ */
+import { Interface, JsonRpcProvider, Network as EthersNetwork, parseUnits } from "ethers";
+import { sendMasterTx } from "../evm-master-tx.js";
+import { PerpError } from "../errors.js";
+import { unsupported } from "./trading-v2.js";
+import { LIGHTER_RH_NETWORKS } from "./venues/lighter-family.js";
+/** Docs: "There is a minimum of 1 USDG, and equivalent for other ERC20s, per deposit." */
+export const LIGHTER_RH_MIN_DEPOSIT = 1;
+const erc20 = new Interface([
+    "function balanceOf(address) view returns (uint256)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "function approve(address spender, uint256 amount) returns (bool)",
+]);
+const zkLighter = new Interface([
+    "function deposit(address _to, uint16 _assetIndex, uint8 _routeType, uint256 _amount) payable",
+]);
+async function getJson(url) {
+    const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    const text = await res.text();
+    if (!res.ok)
+        throw new PerpError("EXCHANGE_ERROR", `GET ${url} HTTP ${res.status}`, { exchange: "lighter-rh", body: text.slice(0, 300) });
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new PerpError("EXCHANGE_ERROR", `GET ${url}: invalid JSON`, { exchange: "lighter-rh", body: text.slice(0, 300) });
+    }
+}
+function venueError(msg) {
+    return new PerpError("EXCHANGE_ERROR", `lighter-rh: ${msg}`, { exchange: "lighter-rh" });
+}
+function provider(rpcUrl, chainId) {
+    const net = EthersNetwork.from(chainId);
+    return new JsonRpcProvider(rpcUrl, net, { staticNetwork: net });
+}
+/** Deposit is offered on mainnet only; testnet → uniform CAPABILITY_UNSUPPORTED. */
+export function requireLighterRhDepositNetwork(net) {
+    if (net === "testnet") {
+        throw unsupported("Lighter RH", "deposit", "the RH testnet L1 (chainId 123456) has no documented RPC; testnet collateral comes from the faucet", "Use the faucet in the Lighter RH testnet app");
+    }
+}
+/**
+ * Read-only: resolve contract / token / chain from the venue API and the depositor's
+ * balance + allowance from the RPC. Throws before anything is signed.
+ */
+export async function planLighterRhDeposit(p) {
+    requireLighterRhDepositNetwork(p.network);
+    const cfg = LIGHTER_RH_NETWORKS[p.network];
+    if (cfg.rpcUrl === null)
+        throw new Error(`lighter-rh ${p.network} venue definition is missing rpcUrl`);
+    const assetIndex = cfg.collateralAssetIndex;
+    const asset = cfg.collateral[0];
+    if (assetIndex === null || asset === undefined)
+        throw new Error(`lighter-rh ${p.network} venue definition has no collateral asset`);
+    const pins = cfg.depositPins;
+    if (pins === null) {
+        throw new PerpError("NOT_IMPLEMENTED", `Lighter RH ${p.network} deposit has no pinned contract/token addresses`, {
+            remediation: "Deposit from the Lighter RH web app; the CLI only deposits to officially verified, pinned addresses",
+        });
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(p.depositor)) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", "Lighter RH deposit needs the master wallet address", {
+            remediation: "Run with the master wallet: perp -e lighter-rh --ows <wallet> funds deposit lighter-rh <amount>",
+        });
+    }
+    if (!/^\d+(\.\d+)?$/.test(p.amount) || !(Number(p.amount) > 0)) {
+        throw new PerpError("INVALID_PARAMS", `Deposit amount must be a positive decimal (got "${p.amount}")`);
+    }
+    if (Number(p.amount) < LIGHTER_RH_MIN_DEPOSIT) {
+        throw new PerpError("SIZE_TOO_SMALL", `Lighter RH minimum deposit is ${LIGHTER_RH_MIN_DEPOSIT} ${asset} (got ${p.amount})`);
+    }
+    const base = `${cfg.restUrl}/api/v1`;
+    const [l1, details] = await Promise.all([
+        getJson(`${base}/layer1BasicInfo`),
+        getJson(`${base}/assetDetails?asset_id=${assetIndex}`),
+    ]);
+    const contracts = l1.contract_addresses;
+    if (!Array.isArray(contracts))
+        throw venueError("layer1BasicInfo: missing contract_addresses");
+    const zk = contracts.find(c => c.name === "ZkLighterContract");
+    if (zk === undefined || typeof zk.address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(zk.address)) {
+        throw venueError("layer1BasicInfo: no ZkLighterContract address");
+    }
+    const providers = l1.l1_providers;
+    const l1ChainId = Array.isArray(providers) ? providers[0]?.chainId : undefined;
+    if (typeof l1ChainId !== "number" || !Number.isInteger(l1ChainId))
+        throw venueError("layer1BasicInfo: missing l1_providers[0].chainId");
+    const list = details.asset_details;
+    if (!Array.isArray(list))
+        throw venueError("assetDetails: missing asset_details");
+    const a = list.find(x => x.asset_id === assetIndex);
+    if (a === undefined)
+        throw venueError(`assetDetails: asset ${assetIndex} not listed`);
+    if (a.symbol !== asset)
+        throw venueError(`assetDetails: asset ${assetIndex} is ${String(a.symbol)}, expected ${asset}`);
+    if (typeof a.l1_address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(a.l1_address))
+        throw venueError(`assetDetails: ${asset} has no l1_address`);
+    if (typeof a.l1_decimals !== "number" || !Number.isInteger(a.l1_decimals))
+        throw venueError(`assetDetails: ${asset} has no l1_decimals`);
+    const same = (x, y) => x.toLowerCase() === y.toLowerCase();
+    if (!same(zk.address, pins.contract)) {
+        throw venueError(`layer1BasicInfo ZkLighterContract ${zk.address} != pinned ${pins.contract} — refusing to approve/deposit (verify at ${pins.sources[0]})`);
+    }
+    if (l1ChainId !== pins.chainId) {
+        throw venueError(`layer1BasicInfo chainId ${l1ChainId} != pinned ${pins.chainId} — refusing to deposit`);
+    }
+    if (!same(a.l1_address, pins.token)) {
+        throw venueError(`assetDetails ${asset} l1_address ${a.l1_address} != pinned ${pins.token} — refusing to approve/deposit`);
+    }
+    const rpc = provider(cfg.rpcUrl, l1ChainId);
+    const rpcChain = BigInt(await rpc.send("eth_chainId", []));
+    if (rpcChain !== BigInt(l1ChainId)) {
+        throw venueError(`RPC ${cfg.rpcUrl} serves chainId ${rpcChain}, venue L1 is ${l1ChainId}`);
+    }
+    let amountRaw;
+    try {
+        amountRaw = parseUnits(p.amount, a.l1_decimals);
+    }
+    catch (e) {
+        throw new PerpError("INVALID_PARAMS", `Lighter RH deposit amount "${p.amount}" is not a decimal ${asset} amount with at most ${a.l1_decimals} decimals: ${e instanceof Error ? e.message : String(e)}`, {
+            exchange: "lighter-rh", remediation: `Pass a plain decimal amount with at most ${a.l1_decimals} decimals, e.g. 10 or 10.5`,
+        });
+    }
+    if (amountRaw <= 0n) {
+        throw new PerpError("INVALID_PARAMS", `Lighter RH deposit amount must be positive (got "${p.amount}")`, { exchange: "lighter-rh" });
+    }
+    const [balRaw, allowRaw] = await Promise.all([
+        rpc.call({ to: a.l1_address, data: erc20.encodeFunctionData("balanceOf", [p.depositor]) }),
+        rpc.call({ to: a.l1_address, data: erc20.encodeFunctionData("allowance", [p.depositor, zk.address]) }),
+    ]);
+    const tokenBalance = erc20.decodeFunctionResult("balanceOf", balRaw)[0];
+    const allowance = erc20.decodeFunctionResult("allowance", allowRaw)[0];
+    if (tokenBalance < amountRaw) {
+        throw new PerpError("INSUFFICIENT_BALANCE", `Wallet ${p.depositor} holds ${tokenBalance} raw ${asset} on Robinhood Chain; deposit needs ${amountRaw}`, {
+            exchange: "lighter-rh", remediation: `Fund ${p.depositor} with ${asset} on Robinhood Chain (chainId ${l1ChainId}) first`,
+        });
+    }
+    return {
+        network: p.network, rpcUrl: cfg.rpcUrl, chainId: pins.chainId, contract: pins.contract,
+        asset, assetIndex, token: pins.token, decimals: a.l1_decimals,
+        amount: p.amount, amountRaw, routeType: p.routeType, depositor: p.depositor,
+        tokenBalance, allowance, needsApprove: allowance < amountRaw,
+    };
+}
+/**
+ * Simulate, sign, broadcast one tx and wait for a successful receipt (shared master-tx path:
+ * once broadcast, a lost response / receipt timeout is ORDER_PENDING carrying the tx hash).
+ */
+async function sendTx(rpc, plan, to, data, label, sign) {
+    const { txHash } = await sendMasterTx(rpc, {
+        venue: "lighter-rh", chainLabel: "Robinhood Chain", chainId: plan.chainId, from: plan.depositor, to, data, value: 0n, label,
+    }, sign);
+    return txHash;
+}
+/** Sends approve (only when the allowance is short — exact amount, not unlimited) then deposit. */
+export async function executeLighterRhDeposit(plan, sign) {
+    const rpc = provider(plan.rpcUrl, plan.chainId);
+    let approveTxHash = null;
+    if (plan.needsApprove) {
+        approveTxHash = await sendTx(rpc, plan, plan.token, erc20.encodeFunctionData("approve", [plan.contract, plan.amountRaw]), `${plan.asset} approve`, sign);
+    }
+    const data = zkLighter.encodeFunctionData("deposit", [plan.depositor, plan.assetIndex, plan.routeType, plan.amountRaw]);
+    const depositTxHash = await sendTx(rpc, plan, plan.contract, data, "Lighter RH deposit", sign);
+    return { approveTxHash, depositTxHash };
+}