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

package/dist/types/utils/wireEncoding.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+/**
+ * Lighter uses basis-points (1/10000) for margin fractions.
+ * Convert to a decimal multiplier: 1000 → 0.1 (10x leverage).
+ * @public
+ */
+export declare const marginFractionToMaxLeverage: (fraction: number) => number;
+/**
+ * Convert leverage to margin fraction in basis points for WASM signer.
+ * @public
+ */
+export declare const leverageToFraction: (leverage: number) => number;
+/**
+ * Off-grid resolution for {@link scaleToInteger}:
+ * - `truncate` — toward zero, for sizes and collateral amounts. The wire
+ *   value never exceeds the caller's intent.
+ * - `round` — half away from zero, for prices, which snap to the nearest
+ *   tick.
+ * @public
+ */
+export type ScaleToIntegerPolicy = 'truncate' | 'round';
+/**
+ * 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 declare const scaleToInteger: (value: string, decimals: number, policy: ScaleToIntegerPolicy) => number;
+/**
+ * Map our OrderType enum to Lighter's integer order type.
+ * @public
+ */
+export declare const mapOrderTypeToInt: (type?: string) => number;
+/**
+ * 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 declare const resolveTimeInForce: (orderTypeInt: number, tif?: string) => number;
+/**
+ * Map our TimeInForce enum to Lighter's integer time-in-force.
+ * @public
+ */
+export declare const mapTimeInForceToInt: (tif?: string) => number;
+/**
+ * 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 declare const orderExpiryForTif: (tifInt: number) => number;
+//# sourceMappingURL=wireEncoding.d.ts.map

package/dist/types/utils/wireEncoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireEncoding.d.ts","sourceRoot":"","sources":["../../../src/utils/wireEncoding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,MAK9D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAQrD,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,CAAA;AAEvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,EACb,UAAU,MAAM,EAChB,QAAQ,oBAAoB,KAC3B,MA0BF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MAUjD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,MAAM,EACpB,MAAM,MAAM,KACX,MAgBF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,MAOlD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAKlD,CAAA"}

package/dist/types/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/types/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"}