@lifi/perps-sdk-provider-lighter 0.2.0-alpha.0

package/dist/esm/utils/wireEncoding.js

@@ -0,0 +1,129 @@
+/**
+ * Lighter wire encoding for the WASM signer: scaled-integer decimal values,
+ * basis-point margin fractions, and order-type/TIF/expiry resolution
+ * mirroring the lighter-go signer's rules.
+ */
+import { PerpsError } from '@lifi/perps-sdk';
+import { PerpsErrorCode } from '@lifi/perps-types';
+import Big from 'big.js';
+import { LT_DEFAULT_ORDER_EXPIRY, LT_ORDER_TYPE_LIMIT, LT_ORDER_TYPE_MARKET, LT_ORDER_TYPE_STOP_LOSS, LT_ORDER_TYPE_STOP_LOSS_LIMIT, LT_ORDER_TYPE_TAKE_PROFIT, LT_ORDER_TYPE_TAKE_PROFIT_LIMIT, LT_TIME_IN_FORCE_GTC, LT_TIME_IN_FORCE_IOC, LT_TIME_IN_FORCE_POST_ONLY, } from '../types/action.js';
+/**
+ * Lighter uses basis-points (1/10000) for margin fractions.
+ * Convert to a decimal multiplier: 1000 → 0.1 (10x leverage).
+ * @public
+ */
+export const marginFractionToMaxLeverage = (fraction) => {
+    if (!Number.isFinite(fraction) || fraction <= 0) {
+        return 1;
+    }
+    return Math.floor(10_000 / fraction);
+};
+/**
+ * Convert leverage to margin fraction in basis points for WASM signer.
+ * @public
+ */
+export const leverageToFraction = (leverage) => {
+    if (leverage <= 0) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid leverage: ${leverage}`);
+    }
+    return Math.round(10_000 / leverage);
+};
+/**
+ * Scale a human-readable decimal string to a scaled integer for the WASM
+ * signer, in exact decimal arithmetic — an on-grid input maps to its exact
+ * scaled integer with no binary float artifacts (`'0.29'` at 2 decimals is
+ * 29, never 28). Off-grid input resolves per `policy`; there is no silent
+ * default.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal
+ *   numeric string, `decimals` is not a non-negative integer, or the scaled
+ *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export const scaleToInteger = (value, decimals, policy) => {
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid decimals for Lighter integer scaling: ${decimals}`);
+    }
+    let parsed;
+    try {
+        parsed = new Big(value);
+    }
+    catch {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Invalid decimal string for Lighter integer scaling: '${value}'`);
+    }
+    const scaled = parsed
+        .times(new Big(10).pow(decimals))
+        .round(0, policy === 'truncate' ? Big.roundDown : Big.roundHalfUp);
+    if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
+        throw new PerpsError(PerpsErrorCode.ValidationError, `Scaled value ${scaled.toFixed()} exceeds Number.MAX_SAFE_INTEGER and cannot be encoded exactly.`);
+    }
+    return scaled.toNumber();
+};
+/**
+ * Map our OrderType enum to Lighter's integer order type.
+ * @public
+ */
+export const mapOrderTypeToInt = (type) => {
+    const map = {
+        LIMIT: LT_ORDER_TYPE_LIMIT,
+        MARKET: LT_ORDER_TYPE_MARKET,
+        STOP_MARKET: LT_ORDER_TYPE_STOP_LOSS,
+        STOP_LIMIT: LT_ORDER_TYPE_STOP_LOSS_LIMIT,
+        TAKE_PROFIT_MARKET: LT_ORDER_TYPE_TAKE_PROFIT,
+        TAKE_PROFIT_LIMIT: LT_ORDER_TYPE_TAKE_PROFIT_LIMIT,
+    };
+    return map[type ?? 'LIMIT'] ?? LT_ORDER_TYPE_LIMIT;
+};
+/**
+ * Lighter pairs each `order_type` with a permitted set of `time_in_force`
+ * values: market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are
+ * IOC by definition; limit-style orders may carry any TIF. The Go WASM
+ * signer rejects mismatches with `OrderTimeInForce is not valid`. Resolve
+ * the caller's optional `timeInForce` against the order type so unspecified
+ * values land on the correct default and explicit values are validated up
+ * front.
+ * @public
+ */
+export const resolveTimeInForce = (orderTypeInt, tif) => {
+    const requested = tif === undefined ? undefined : mapTimeInForceToInt(tif);
+    const isMarketStyle = orderTypeInt === LT_ORDER_TYPE_MARKET ||
+        orderTypeInt === LT_ORDER_TYPE_STOP_LOSS ||
+        orderTypeInt === LT_ORDER_TYPE_TAKE_PROFIT;
+    if (isMarketStyle) {
+        if (requested !== undefined && requested !== LT_TIME_IN_FORCE_IOC) {
+            throw new PerpsError(PerpsErrorCode.ValidationError, `Lighter market-style orders only accept IOC (got tif=${tif}).`);
+        }
+        return LT_TIME_IN_FORCE_IOC;
+    }
+    return requested ?? LT_TIME_IN_FORCE_GTC;
+};
+/**
+ * Map our TimeInForce enum to Lighter's integer time-in-force.
+ * @public
+ */
+export const mapTimeInForceToInt = (tif) => {
+    const map = {
+        IOC: LT_TIME_IN_FORCE_IOC,
+        GTC: LT_TIME_IN_FORCE_GTC,
+        POST_ONLY: LT_TIME_IN_FORCE_POST_ONLY,
+    };
+    return map[tif ?? 'GTC'] ?? LT_TIME_IN_FORCE_GTC;
+};
+/**
+ * Pick the `order_expiry` value Lighter expects for a given TIF on a
+ * regular limit order. `lighter-go/types/txtypes/create_order.go:121-128`
+ * enforces:
+ *   - IOC limit orders → `OrderExpiry == NilOrderExpiry (0)`
+ *   - non-IOC limit orders → `OrderExpiry != NilOrderExpiry`
+ * For non-IOC we pass the `-1` sentinel, which the WASM signer rewrites
+ * to `now + 28d` (absolute ms). Trigger orders take a different rule —
+ * see {@link LT_DEFAULT_ORDER_EXPIRY} call sites.
+ * @public
+ */
+export const orderExpiryForTif = (tifInt) => {
+    if (tifInt === LT_TIME_IN_FORCE_IOC) {
+        return 0;
+    }
+    return LT_DEFAULT_ORDER_EXPIRY;
+};
+//# sourceMappingURL=wireEncoding.js.map

package/dist/esm/utils/wireEncoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireEncoding.js","sourceRoot":"","sources":["../../../src/utils/wireEncoding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,GAAG,MAAM,QAAQ,CAAA;AACxB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,QAAgB,EAAU,EAAE;IACtE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAChD,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAA;AACtC,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAU,EAAE;IAC7D,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,qBAAqB,QAAQ,EAAE,CAChC,CAAA;IACH,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAA;AACtC,CAAC,CAAA;AAYD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAa,EACb,QAAgB,EAChB,MAA4B,EACpB,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,iDAAiD,QAAQ,EAAE,CAC5D,CAAA;IACH,CAAC;IACD,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,wDAAwD,KAAK,GAAG,CACjE,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM;SAClB,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;SAChC,KAAK,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IACpE,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,gBAAgB,MAAM,CAAC,OAAO,EAAE,iEAAiE,CAClG,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAA;AAC1B,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAa,EAAU,EAAE;IACzD,MAAM,GAAG,GAA2B;QAClC,KAAK,EAAE,mBAAmB;QAC1B,MAAM,EAAE,oBAAoB;QAC5B,WAAW,EAAE,uBAAuB;QACpC,UAAU,EAAE,6BAA6B;QACzC,kBAAkB,EAAE,yBAAyB;QAC7C,iBAAiB,EAAE,+BAA+B;KACnD,CAAA;IACD,OAAO,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,mBAAmB,CAAA;AACpD,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,YAAoB,EACpB,GAAY,EACJ,EAAE;IACV,MAAM,SAAS,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAA;IAC1E,MAAM,aAAa,GACjB,YAAY,KAAK,oBAAoB;QACrC,YAAY,KAAK,uBAAuB;QACxC,YAAY,KAAK,yBAAyB,CAAA;IAC5C,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,oBAAoB,EAAE,CAAC;YAClE,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,eAAe,EAC9B,wDAAwD,GAAG,IAAI,CAChE,CAAA;QACH,CAAC;QACD,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IACD,OAAO,SAAS,IAAI,oBAAoB,CAAA;AAC1C,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAY,EAAU,EAAE;IAC1D,MAAM,GAAG,GAA2B;QAClC,GAAG,EAAE,oBAAoB;QACzB,GAAG,EAAE,oBAAoB;QACzB,SAAS,EAAE,0BAA0B;KACtC,CAAA;IACD,OAAO,GAAG,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,oBAAoB,CAAA;AAClD,CAAC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAU,EAAE;IAC1D,IAAI,MAAM,KAAK,oBAAoB,EAAE,CAAC;QACpC,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,uBAAuB,CAAA;AAChC,CAAC,CAAA"}

package/dist/esm/websocket/LighterWsProvider.d.ts

@@ -0,0 +1,97 @@
+import { type PerpsSDKClient, type ProviderGetQuoteParams, type QuoteListener, WsProviderBase, type WsProviderFactory } from '@lifi/perps-sdk';
+import type { Subscription } from '@lifi/perps-types';
+import type { Address } from 'viem';
+/**
+ * Creates a fresh Lighter auth token for the given L1 address, or returns
+ * `undefined` if no API key is registered. Called both on initial subscribe
+ * and on every reconnect, so it must always return a token valid for at
+ * least the next few minutes.
+ *
+ * @public
+ */
+export type LighterAuthProvider = (address: Address) => Promise<string | undefined>;
+interface SubState {
+    /** Raw Lighter WS channel name (e.g. `order_book/5`, `account_all_orders/42`). */
+    channel: string;
+    /** L1 address that triggered this sub (auth channels only). */
+    address?: Address;
+    /** Whether this channel needs an `auth` field on each subscribe send. */
+    needsAuth: boolean;
+}
+/**
+ * Options for {@link lighterWsProvider} / {@link LighterWsProvider}.
+ *
+ * @public
+ */
+export interface LighterWsProviderOptions {
+    /** REST base URL for `/api/v1/account` lookups. Defaults to mainnet. */
+    restUrl?: string;
+    /**
+     * Async function returning a Lighter auth token for an address. Required
+     * for authenticated channels (orderUpdates, positions). Without it those
+     * subscriptions will throw at subscribe time.
+     */
+    authProvider?: LighterAuthProvider;
+}
+/**
+ * Lighter realtime WS provider (extends {@link WsProviderBase}): subscribes to
+ * Lighter's WS channels (orderbook, prices, orders, positions), attaching auth
+ * tokens to gated channels. Construct via {@link lighterWsProvider}.
+ *
+ * @public
+ */
+export declare class LighterWsProvider extends WsProviderBase<SubState> {
+    private readonly api;
+    private readonly authProvider;
+    private readonly client;
+    private readonly orderbooks;
+    private lastPricesByAssetId;
+    /**
+     * `address → market_id → Position`. `subscribed/...` frames reseed it and
+     * `update/...` frames upsert into it (zero size deletes), so every emission
+     * is a full open-position snapshot per the `PositionsEvent` contract.
+     */
+    private readonly positionsByAddress;
+    private readonly registry;
+    private readonly accountIndexCache;
+    private readonly accountIndexPromises;
+    constructor(wsUrl?: string, providerKey?: string, options?: LighterWsProviderOptions, client?: PerpsSDKClient);
+    subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    protected openChannel(sub: Subscription): Promise<() => void>;
+    protected onClose(): void;
+    protected sendSubscribe({ channel, needsAuth, address, }: SubState): Promise<void>;
+    protected toKey(sub: Subscription): string;
+    private resolveChannel;
+    private resolveAccountIndex;
+    private fetchAccountIndex;
+    protected handleMessage(raw: string): void;
+    private dispatch;
+    private handleAccountOrders;
+    private handleAccountTrades;
+    private handleAccountPositions;
+    /**
+     * Reverse-lookup the L1 address from an auth-channel message. The subscribe
+     * payload uses `/` (e.g. `account_all_orders/42`) but the server sends
+     * responses with `:` (e.g. `account_all_orders:42`) — both forms are
+     * accepted here so reconnect resubscriptions and live updates both route
+     * correctly.
+     */
+    private addressFromChannel;
+    private handleMarketStats;
+    private handleOrderBook;
+    private marketIdFromChannel;
+}
+/**
+ * `WsProviderFactory` constructor for Lighter — pass to
+ * `new PerpsWsClient(client, { wsProviders: { lighter: lighterWsProvider({ authProvider }) } })`.
+ *
+ * Closes over the per-instance options (auth provider, restUrl override) so
+ * `PerpsWsClient` can call the returned factory with just
+ * `({ provider, wsUrl, markets })` at subscribe time. `markets` is
+ * unused — Lighter advertises a single venue, no sub-DEX filtering.
+ *
+ * @public
+ */
+export declare const lighterWsProvider: (options?: LighterWsProviderOptions) => WsProviderFactory;
+export {};
+//# sourceMappingURL=LighterWsProvider.d.ts.map

package/dist/esm/websocket/LighterWsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LighterWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/LighterWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAIlB,cAAc,EACd,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAkEnC;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhC,UAAU,QAAQ;IAChB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAA;CACnB;AAQD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAA;CACnC;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,mBAAmB,CAA6B;IAExD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2C;IAE9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;gBAGxE,KAAK,GAAE,MAAuB,EAC9B,WAAW,SAAY,EACvB,OAAO,GAAE,wBAA6B,EACtC,MAAM,CAAC,EAAE,cAAc;IAmBnB,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;cA4ChD,OAAO,IAAI,IAAI;cAMlB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,OAAO,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB3B,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;YAqB5B,cAAc;YAmDd,mBAAmB;YAqBnB,iBAAiB;IAK/B,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAqB1C,OAAO,CAAC,QAAQ;IA+DhB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,sBAAsB;IAiC9B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,mBAAmB;CAW5B;AA4FD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC3B,UAAU,wBAAwB,KAAG,iBAEmB,CAAA"}