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

package/dist/esm/LighterProvider.js

@@ -0,0 +1,684 @@
+import { ExplorerChainId, explorerTxUrl, getAssetRegistry, getMarketRegistry, PerpsError, resolveQuote, resolveRetryPolicy, } from '@lifi/perps-sdk';
+import { ActionType, ActivityType, PerpsErrorCode } from '@lifi/perps-types';
+import { projectLighterConfigSettings } from './accountConfig.js';
+import { summarizeLighterAccount } from './accountSummary.js';
+import { DEFAULT_API_KEY_INDEX, DEFAULT_LIGHTER_REST_URL, DEFAULT_TRADES_LIMIT, LIGHTER_ALL_MARKETS_WILDCARD, LIGHTER_BASE_FEE_TIER, LIGHTER_FEE_TICK_SCALE, LIGHTER_HISTORY_PAGE_SIZE, LIGHTER_PROVIDER_KEY, } from './constants.js';
+import { createAuthToken } from './signers/createAuthToken.js';
+import { LighterReadOnlyTokenManager } from './signers/LighterReadOnlyTokenManager.js';
+import { lighterSignActions } from './signers/signActions.js';
+import { decodeActivityCursor, encodeActivityCursor, } from './utils/activityCursor.js';
+import { LIGHTER_RETRY_DEFAULTS, LighterApiClient, LighterAuthRejectedError, } from './utils/apiClient.js';
+import { classifyAndMapOrders, estimateLiquidationPrice, fetchDetailedAccount, formatOrderPrice, formatOrderSize, lighterAsset, mapFill, mapOpenPositions, mapOrderDetail, toIsoFromMs, toIsoFromSeconds, } from './utils/index.js';
+const ZERO_FEE_TIER = { maker: '0', taker: '0' };
+const tickToFeeString = (tick) => String(tick / LIGHTER_FEE_TICK_SCALE);
+const projectFeeTier = (limits) => ({
+    maker: tickToFeeString(limits.current_maker_fee_tick),
+    taker: tickToFeeString(limits.current_taker_fee_tick),
+});
+const orderCountFor = (p) => (p.open_order_count ?? 0) +
+    (p.pending_order_count ?? 0) +
+    (p.position_tied_order_count ?? 0);
+/**
+ * Lighter `sendTx` returns a bare lowercase-hex tx hash (40 bytes → 80 hex
+ * chars). `Order.order_id` is a different identifier the matching engine
+ * assigns later. The strict 80-char shape lets `getOrder` route freshly
+ * submitted IDs to the tx-hash branch without false positives.
+ */
+const TX_HASH_PATTERN = /^[0-9a-f]{80}$/;
+const INACTIVE_ORDERS_LOOKUP_LIMIT = 100;
+/**
+ * Expiry requested when the SDK lazily creates a Lighter read-only token for
+ * authenticated reads. 10 years — Lighter caps read-only tokens at the
+ * venue's maximum, so a single token covers the account's lifetime.
+ */
+const DEFAULT_READ_ONLY_TOKEN_LIFETIME_SECONDS = 10 * 365 * 24 * 60 * 60;
+/** Compare Lighter public keys irrespective of `0x` prefix / casing. */
+const normalizeLighterPublicKey = (key) => key.replace(/^0x/i, '').toLowerCase();
+/**
+ * Lighter provider plugin factory. Returns an object implementing
+ * {@link PerpsProviderPlugin}, mirroring the `EthereumProvider()` / `hyperliquidProvider()`
+ * shape used by the rest of the LI.FI SDK family.
+ *
+ * Read functions call Lighter's REST API directly with no LI.FI backend hop.
+ * Auth-gated reads resolve their token via the order documented on
+ * {@link LighterProviderOptions}.
+ *
+ * Write actions (`WASM_BLOB` and `EVM_TX` signing) are dispatched via
+ * `signActions` — `PerpsClient.execute` delegates those arms here.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({
+ *   integrator: 'my-app',
+ *   providers: [lighterProvider()],
+ * })
+ * ```
+ * @public
+ */
+export const lighterProvider = (options = {}) => {
+    // Late-bind slot: the factory runs before the client exists, so `bind`
+    // assigns this once during createPerpsClient and the read methods read it.
+    let boundClient;
+    const requireClient = () => {
+        if (boundClient === undefined) {
+            throw new PerpsError(PerpsErrorCode.SDKError, 'lighterProvider used before binding. Register it via ' +
+                'createPerpsClient({ providers: [lighterProvider()] }).');
+        }
+        return boundClient;
+    };
+    const restUrl = options.restUrl ?? DEFAULT_LIGHTER_REST_URL;
+    const authTokenSource = typeof options.authToken === 'function'
+        ? options.authToken
+        : options.authToken !== undefined
+            ? () => options.authToken
+            : undefined;
+    const signer = options.signer;
+    const keyStore = options.keyStore;
+    const readOnlyTokenManager = new LighterReadOnlyTokenManager({
+        lighterApiUrl: restUrl,
+        ...options.readOnlyTokenOptions,
+    });
+    const tokenLifetimeSeconds = options.tokenLifetimeSeconds ?? 60 * 60;
+    const tokenRenewBufferSeconds = options.tokenRenewBufferSeconds ?? 60;
+    const standardTokenByAddress = new Map();
+    // Single-flight + failure-cache for lazy read-only token creation. Without
+    // these, concurrent reads on first load all race `tokens/create`, and any
+    // sustained failure (CORS preflight, body validation, etc.) is retried on
+    // every subsequent read — flooding the endpoint. Keyed by lowercase address.
+    const readOnlyCreationInFlight = new Map();
+    const readOnlyCreationFailed = new Set();
+    const apiClient = (opts) => {
+        const client = requireClient();
+        return new LighterApiClient(restUrl, {
+            signal: opts?.signal,
+            policy: resolveRetryPolicy(LIGHTER_RETRY_DEFAULTS, client.config.retry, LIGHTER_PROVIDER_KEY),
+            fetchImpl: client.config.fetch,
+        });
+    };
+    const getStandardAuthToken = async (address, apiKeyPrivateKey, indices) => {
+        if (signer === undefined) {
+            throw new PerpsError(PerpsErrorCode.SDKError, 'lighterProvider: getStandardAuthToken called without a configured signer.');
+        }
+        const cacheKey = address.toLowerCase();
+        const nowSec = Math.floor(Date.now() / 1000);
+        const cached = standardTokenByAddress.get(cacheKey);
+        if (cached !== undefined &&
+            cached.expiresAt - nowSec > tokenRenewBufferSeconds) {
+            return cached.token;
+        }
+        const token = await createAuthToken({
+            signer,
+            apiKey: {
+                apiKeyPrivateKey,
+                apiKeyIndex: indices.apiKeyIndex,
+                accountIndex: indices.accountIndex,
+            },
+            lifetimeSeconds: tokenLifetimeSeconds,
+        });
+        const expiresAt = nowSec + tokenLifetimeSeconds;
+        standardTokenByAddress.set(cacheKey, { token, expiresAt });
+        return token;
+    };
+    /**
+     * Resolve the bearer token for auth-gated reads. Priority:
+     *   1. Per-call override (`options.lighterAuthToken`).
+     *   2. Constructor-supplied token source.
+     *   3. A stored read-only token — preferred for reads: it is read-only, so
+     *      forwarding it (incl. to the backend) cannot authorise writes.
+     *   4. A read-only token created on first use (via signer + registered API
+     *      key) and persisted for reuse.
+     *   5. A standard auth token (read+write, 8h max) as a last resort — used
+     *      both as the fallback when creation is unavailable/failed and as the
+     *      credential that authorises read-only token creation.
+     * Returns `undefined` when no source can produce a token — reads degrade
+     * gracefully.
+     */
+    const resolveAuthToken = async (opts, address) => {
+        if (opts?.lighterAuthToken !== undefined) {
+            return opts.lighterAuthToken;
+        }
+        if (authTokenSource !== undefined) {
+            return authTokenSource();
+        }
+        if (address === undefined || keyStore === undefined) {
+            return undefined;
+        }
+        const apiKey = await keyStore.get(address);
+        if (apiKey === null || signer === undefined) {
+            return undefined;
+        }
+        const standardToken = () => getStandardAuthToken(address, apiKey.apiKeyPrivateKey, {
+            apiKeyIndex: apiKey.apiKeyIndex,
+            accountIndex: apiKey.accountIndex,
+        });
+        const stored = await readOnlyTokenManager.get(address, apiKey.accountIndex);
+        if (stored !== undefined) {
+            return stored.token;
+        }
+        const flightKey = address.toLowerCase();
+        if (readOnlyCreationFailed.has(flightKey)) {
+            return standardToken();
+        }
+        const inFlight = readOnlyCreationInFlight.get(flightKey);
+        if (inFlight !== undefined) {
+            return inFlight;
+        }
+        // No read-only token yet — create and persist one. The standard token
+        // (API-key-signed) authorises Lighter's `tokens/create`; the returned
+        // read-only bearer is what we forward on reads. On failure we mark this
+        // address as "skip ro creation for the session" so subsequent reads use
+        // the standard token directly instead of hammering `tokens/create`.
+        const attempt = (async () => {
+            try {
+                const { token } = await readOnlyTokenManager.approve(await standardToken(), {
+                    address,
+                    accountIndex: apiKey.accountIndex,
+                    expirySeconds: Math.floor(Date.now() / 1000) +
+                        DEFAULT_READ_ONLY_TOKEN_LIFETIME_SECONDS,
+                    scope: 'all',
+                });
+                return token.token;
+            }
+            catch (err) {
+                readOnlyCreationFailed.add(flightKey);
+                console.warn('[lighter] read-only token creation failed; ' +
+                    'falling back to standard auth tokens for this session.', err);
+                return standardToken();
+            }
+            finally {
+                readOnlyCreationInFlight.delete(flightKey);
+            }
+        })();
+        readOnlyCreationInFlight.set(flightKey, attempt);
+        return attempt;
+    };
+    const evictReadOnlyToken = async (address) => {
+        readOnlyCreationFailed.delete(address.toLowerCase());
+        const apiKey = keyStore ? await keyStore.get(address) : null;
+        if (apiKey !== null) {
+            await readOnlyTokenManager.remove(address, apiKey.accountIndex);
+        }
+    };
+    /**
+     * Run an auth-gated read; if Lighter rejects the token (revoked server-side —
+     * invisible to `checkSetup`, since the read-only token is a client-only
+     * concern), evict the stored read-only token and retry once with a freshly
+     * resolved one. Only self-heals tokens the SDK itself resolved — a
+     * caller-supplied `lighterAuthToken`/`authToken` source is the caller's to fix.
+     */
+    const retryOnRevoked = async (opts, address, token, run) => {
+        try {
+            return await run(token);
+        }
+        catch (err) {
+            const sdkOwnsToken = opts?.lighterAuthToken === undefined && authTokenSource === undefined;
+            if (!(err instanceof LighterAuthRejectedError) || !sdkOwnsToken) {
+                throw err;
+            }
+            await evictReadOnlyToken(address);
+            const fresh = await resolveAuthToken(opts, address);
+            if (fresh === undefined || fresh === token) {
+                throw err;
+            }
+            return await run(fresh);
+        }
+    };
+    const fetchRegisteredApiKey = async (client, accountIndex, apiKeyIndex) => {
+        const response = await client.get('/api/v1/apikeys', { account_index: accountIndex });
+        return response.api_keys?.find((k) => k.api_key_index === apiKeyIndex);
+    };
+    const fetchAccountLimits = (client, accountIndex, authToken) => client.getAuthed('/api/v1/accountLimits', authToken, {
+        account_index: accountIndex,
+    });
+    const fetchActiveOrdersForMarket = (client, authToken, accountIndex, marketId) => client.getAuthed('/api/v1/accountActiveOrders', authToken, { account_index: accountIndex, market_id: marketId });
+    const deriveOrderBearingMarketIds = (account) => account.positions
+        .filter((p) => orderCountFor(p) > 0)
+        .map((p) => p.market_id);
+    const fetchAllHistory = async (client, token, accountIndex, l1Address, requested, inputCursor) => {
+        const wantsType = (t) => requested === undefined || requested.includes(t);
+        const shouldFetch = (t, key) => {
+            if (!wantsType(t)) {
+                return false;
+            }
+            if (inputCursor === undefined) {
+                return true;
+            }
+            const v = inputCursor[key];
+            return typeof v === 'string' && v.length > 0;
+        };
+        const cursorParam = (key) => {
+            const v = inputCursor?.[key];
+            return typeof v === 'string' && v.length > 0 ? { cursor: v } : {};
+        };
+        const empty = (payload) => payload;
+        const [deposits, withdraws, fundings, liquidations, transfers] = await Promise.all([
+            shouldFetch(ActivityType.DEPOSIT, 'deposits')
+                ? client.getAuthed('/api/v1/deposit/history', token, {
+                    account_index: accountIndex,
+                    l1_address: l1Address,
+                    ...cursorParam('deposits'),
+                })
+                : Promise.resolve(empty({ code: 0, deposits: [] })),
+            shouldFetch(ActivityType.WITHDRAWAL, 'withdraws')
+                ? client.getAuthed('/api/v1/withdraw/history', token, { account_index: accountIndex, ...cursorParam('withdraws') })
+                : Promise.resolve(empty({ code: 0, withdraws: [] })),
+            shouldFetch(ActivityType.FUNDING, 'fundings')
+                ? client.getAuthed('/api/v1/positionFunding', token, {
+                    account_index: accountIndex,
+                    market_id: LIGHTER_ALL_MARKETS_WILDCARD,
+                    limit: LIGHTER_HISTORY_PAGE_SIZE,
+                    ...cursorParam('fundings'),
+                })
+                : Promise.resolve(empty({ code: 0, position_fundings: [] })),
+            shouldFetch(ActivityType.LIQUIDATION, 'liquidations')
+                ? client.getAuthed('/api/v1/liquidations', token, {
+                    account_index: accountIndex,
+                    market_id: LIGHTER_ALL_MARKETS_WILDCARD,
+                    limit: LIGHTER_HISTORY_PAGE_SIZE,
+                    ...cursorParam('liquidations'),
+                })
+                : Promise.resolve(empty({ code: 0, liquidations: [] })),
+            shouldFetch(ActivityType.TRANSFER, 'transfers')
+                ? client.getAuthed('/api/v1/transfer/history', token, { account_index: accountIndex, ...cursorParam('transfers') })
+                : Promise.resolve(empty({ code: 0, transfers: [] })),
+        ]);
+        return { deposits, withdraws, fundings, liquidations, transfers };
+    };
+    return {
+        type: LIGHTER_PROVIDER_KEY,
+        bind(client) {
+            boundClient = client;
+        },
+        resolveAuthToken(address) {
+            return resolveAuthToken(undefined, address);
+        },
+        async getAccount(params, opts) {
+            const client = apiClient(opts);
+            const [account, token] = await Promise.all([
+                fetchDetailedAccount(client, params.address),
+                resolveAuthToken(opts, params.address),
+            ]);
+            const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [, registeredKey, limitsResult, localKey, storedReadOnlyToken] = await Promise.all([
+                registry.sync(),
+                fetchRegisteredApiKey(client, account.index, DEFAULT_API_KEY_INDEX),
+                // No token is a legitimate unauthenticated read → undefined → zero fee
+                // tier. A fetch error is NOT: it must propagate, never be coerced to a
+                // fabricated 0%/0% fee tier.
+                token === undefined
+                    ? Promise.resolve(undefined)
+                    : retryOnRevoked(opts, params.address, token, (t) => fetchAccountLimits(client, account.index, t)),
+                keyStore ? keyStore.get(params.address) : Promise.resolve(null),
+                readOnlyTokenManager.get(params.address, account.index),
+            ]);
+            // REGISTER_API_KEY is satisfied only when the locally-held keypair
+            // matches the key registered on-chain at this slot — existence alone is
+            // insufficient (a stale/rotated local key can't sign valid auth tokens).
+            const apiKeyRegistered = registeredKey !== undefined &&
+                localKey !== null &&
+                normalizeLighterPublicKey(localKey.apiKeyPublicKey) ===
+                    normalizeLighterPublicKey(registeredKey.public_key);
+            const positions = mapOpenPositions(account.positions, (id) => registry.require(String(id)));
+            const totalMarginUsed = positions.reduce((sum, p) => sum + Number.parseFloat(p.marginUsed), 0);
+            const totalUnrealizedPnl = positions.reduce((sum, p) => sum + Number.parseFloat(p.unrealizedPnl), 0);
+            // USDC collateral is the category quote asset → collateralBalances.
+            // `available_balance` is the free collateral (Lighter's `collateral` is
+            // gross, i.e. includes margin locked in positions); the locked portion is
+            // carried by the positions' `marginUsed`.
+            const collateralBalances = [
+                {
+                    categoryId: LIGHTER_PROVIDER_KEY,
+                    asset: lighterAsset('USDC', 'USDC'),
+                    units: account.available_balance,
+                    valueUsd: account.available_balance,
+                },
+            ];
+            // Spot token holdings — non-collateral. USDC value is 1:1; other tokens
+            // have no price source at this boundary, so their USD value is unknown.
+            const balances = account.assets.map((a) => ({
+                categoryId: LIGHTER_PROVIDER_KEY,
+                asset: lighterAsset(String(a.asset_id), a.symbol),
+                units: a.balance,
+                valueUsd: a.symbol === 'USDC' ? a.balance : '0',
+            }));
+            const config = {
+                provider: LIGHTER_PROVIDER_KEY,
+                accountIndex: account.index,
+                apiKeyIndex: DEFAULT_API_KEY_INDEX,
+                apiKeyRegistered,
+                accountType: account.account_type,
+                // Satisfied when a non-expired read-only token is stored locally
+                // (`readOnlyTokenManager.get` filters out expired ones).
+                readOnlyTokenApproved: storedReadOnlyToken !== undefined,
+                readOnlyTokenExpiry: storedReadOnlyToken?.expiry,
+                readOnlyTokenScope: storedReadOnlyToken?.scope,
+            };
+            return {
+                provider: LIGHTER_PROVIDER_KEY,
+                address: params.address,
+                balances,
+                collateralBalances,
+                marginUsed: totalMarginUsed.toString(),
+                unrealizedPnl: totalUnrealizedPnl.toString(),
+                feeTier: limitsResult === undefined
+                    ? ZERO_FEE_TIER
+                    : projectFeeTier(limitsResult),
+                config,
+            };
+        },
+        async getPositions(params, opts) {
+            const client = apiClient(opts);
+            const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [account] = await Promise.all([
+                fetchDetailedAccount(client, params.address),
+                registry.sync(),
+            ]);
+            let positions = mapOpenPositions(account.positions, (id) => registry.require(String(id)));
+            if (params.marketId !== undefined) {
+                positions = positions.filter((p) => p.market.id === params.marketId);
+            }
+            return {
+                provider: LIGHTER_PROVIDER_KEY,
+                positions,
+                pagination: { limit: params.limit ?? positions.length, hasMore: false },
+            };
+        },
+        async getOrders(params, opts) {
+            const token = await resolveAuthToken(opts, params.address);
+            if (token === undefined) {
+                return {
+                    provider: LIGHTER_PROVIDER_KEY,
+                    openOrders: [],
+                    triggerOrders: [],
+                    pagination: { limit: params.limit ?? 0, hasMore: false },
+                };
+            }
+            const client = apiClient(opts);
+            const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [account] = await Promise.all([
+                fetchDetailedAccount(client, params.address),
+                registry.sync(),
+            ]);
+            const marketIds = params.marketId === undefined
+                ? deriveOrderBearingMarketIds(account)
+                : [Number(params.marketId)];
+            const responses = await retryOnRevoked(opts, params.address, token, (t) => Promise.all(marketIds.map((id) => fetchActiveOrdersForMarket(client, t, account.index, id))));
+            const { openOrders, triggerOrders } = classifyAndMapOrders(responses.flatMap((r) => r.orders), (marketIndex) => registry.require(String(marketIndex)));
+            const total = openOrders.length + triggerOrders.length;
+            const limit = params.limit ?? total;
+            return {
+                provider: LIGHTER_PROVIDER_KEY,
+                openOrders,
+                triggerOrders,
+                pagination: { limit, hasMore: total > limit },
+            };
+        },
+        async getOrder(params, opts) {
+            const token = await resolveAuthToken(opts, params.address);
+            if (token === undefined) {
+                throw new PerpsError(PerpsErrorCode.SDKError, 'Lighter order lookup requires an auth token. Pass `authToken` to ' +
+                    'lighterProvider, register an API key + signer for on-demand creation, or ' +
+                    'forward `options.lighterAuthToken` on the call.');
+            }
+            const client = apiClient(opts);
+            const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [account] = await Promise.all([
+                fetchDetailedAccount(client, params.address),
+                registry.sync(),
+            ]);
+            // Native `order_index` route only. The cross-provider `Order.orderId`
+            // for Lighter is `String(order_index)` — see `mapOrder`. A tx-hash route
+            // would require mapping the caller's executeAction tx hash → wasm nonce
+            // → matching order, which the LI.FI backend did via its `UserAction`
+            // table; the SDK has no equivalent persistence, so we refuse rather
+            // than mis-resolve.
+            if (TX_HASH_PATTERN.test(params.id)) {
+                throw new PerpsError(PerpsErrorCode.OrderNotFound, `Lighter order id "${params.id}" looks like a tx hash. The SDK ` +
+                    `resolves orders by Lighter \`order_index\` only — surface the orderId ` +
+                    `from the orderUpdates / fills WS stream and pass it here.`);
+            }
+            const predicate = (o) => String(o.order_index) === params.id;
+            const marketIds = deriveOrderBearingMarketIds(account);
+            const activeResponses = await retryOnRevoked(opts, params.address, token, (t) => Promise.all(marketIds.map((id) => fetchActiveOrdersForMarket(client, t, account.index, id))));
+            for (const response of activeResponses) {
+                const hit = response.orders.find(predicate);
+                if (hit !== undefined) {
+                    return mapOrderDetail(hit, registry.require(String(hit.market_index)));
+                }
+            }
+            const inactive = await retryOnRevoked(opts, params.address, token, (t) => client.getAuthed('/api/v1/accountInactiveOrders', t, {
+                account_index: account.index,
+                market_id: LIGHTER_ALL_MARKETS_WILDCARD,
+                limit: INACTIVE_ORDERS_LOOKUP_LIMIT,
+            }));
+            const hit = inactive.orders.find(predicate);
+            if (hit !== undefined) {
+                return mapOrderDetail(hit, registry.require(String(hit.market_index)));
+            }
+            throw new PerpsError(PerpsErrorCode.OrderNotFound, `Lighter order ${params.id} not found for ${params.address}`);
+        },
+        async getFills(params, opts) {
+            const token = await resolveAuthToken(opts, params.address);
+            if (token === undefined) {
+                return {
+                    provider: LIGHTER_PROVIDER_KEY,
+                    items: [],
+                    pagination: { limit: params.limit ?? 0, hasMore: false },
+                };
+            }
+            const client = apiClient(opts);
+            const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [account] = await Promise.all([
+                fetchDetailedAccount(client, params.address),
+                registry.sync(),
+            ]);
+            const queryParams = {
+                account_index: account.index,
+                sort_by: 'timestamp',
+                sort_dir: 'desc',
+                limit: params.limit ?? DEFAULT_TRADES_LIMIT,
+            };
+            if (params.cursor !== undefined) {
+                queryParams.cursor = params.cursor;
+            }
+            const response = await retryOnRevoked(opts, params.address, token, (tok) => client.getAuthed('/api/v1/trades', tok, queryParams));
+            const items = response.trades.map((t) => mapFill(t, account.index, registry.require(String(t.market_id))));
+            return {
+                provider: LIGHTER_PROVIDER_KEY,
+                items,
+                pagination: {
+                    limit: params.limit ?? items.length,
+                    hasMore: (response.next_cursor ?? '') !== '',
+                    cursor: response.next_cursor || undefined,
+                },
+            };
+        },
+        async getActivity(params, opts) {
+            const token = await resolveAuthToken(opts, params.address);
+            if (token === undefined) {
+                return {
+                    provider: LIGHTER_PROVIDER_KEY,
+                    items: [],
+                    pagination: { limit: params.limit ?? 0, hasMore: false },
+                };
+            }
+            const inputCursor = decodeActivityCursor(params.cursor);
+            const client = apiClient(opts);
+            const account = await fetchDetailedAccount(client, params.address);
+            const marketRegistry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const assetRegistry = getAssetRegistry(requireClient(), LIGHTER_PROVIDER_KEY);
+            const [history] = await Promise.all([
+                retryOnRevoked(opts, params.address, token, (t) => fetchAllHistory(client, t, account.index, params.address, params.type, inputCursor)),
+                marketRegistry.sync(),
+                assetRegistry.sync(),
+            ]);
+            const items = [
+                ...history.deposits.deposits.map((d) => ({
+                    id: d.id,
+                    provider: LIGHTER_PROVIDER_KEY,
+                    timestamp: toIsoFromMs(d.timestamp),
+                    type: ActivityType.DEPOSIT,
+                    amount: d.amount,
+                    explorerLink: d.l1_tx_hash
+                        ? `https://scan.li.fi/tx/${d.l1_tx_hash}`
+                        : undefined,
+                })),
+                ...history.withdraws.withdraws.map((w) => ({
+                    id: w.id,
+                    provider: LIGHTER_PROVIDER_KEY,
+                    timestamp: toIsoFromMs(w.timestamp),
+                    type: ActivityType.WITHDRAWAL,
+                    amount: w.amount,
+                    fee: '0',
+                    explorerLink: w.l1_tx_hash
+                        ? `https://scan.li.fi/tx/${w.l1_tx_hash}`
+                        : undefined,
+                })),
+                ...history.fundings.position_fundings.map((f) => ({
+                    id: `funding-${f.funding_id}`,
+                    provider: LIGHTER_PROVIDER_KEY,
+                    timestamp: toIsoFromSeconds(f.timestamp),
+                    type: ActivityType.FUNDING,
+                    market: marketRegistry.require(String(f.market_id)),
+                    amount: f.change,
+                    positionSize: f.position_size,
+                    fundingRate: f.rate,
+                })),
+                ...history.liquidations.liquidations.map((l) => ({
+                    id: `liquidation-${l.id}`,
+                    provider: LIGHTER_PROVIDER_KEY,
+                    timestamp: toIsoFromMs(l.executed_at),
+                    type: ActivityType.LIQUIDATION,
+                    liquidatedNotionalPosition: '0',
+                    accountValue: '0',
+                    leverageType: l.type,
+                    liquidatedPositions: [
+                        {
+                            market: marketRegistry.require(String(l.market_id)),
+                            size: '0',
+                        },
+                    ],
+                })),
+                ...history.transfers.transfers.map((t) => {
+                    const direction = t.from_account_index === account.index ? 'OUT' : 'IN';
+                    const counterpartyAccountIndex = direction === 'OUT' ? t.to_account_index : t.from_account_index;
+                    return {
+                        id: t.id,
+                        provider: LIGHTER_PROVIDER_KEY,
+                        timestamp: toIsoFromMs(t.timestamp),
+                        type: ActivityType.TRANSFER,
+                        direction,
+                        counterpartyAccountIndex,
+                        asset: assetRegistry.get(String(t.asset_id))?.displaySymbol ??
+                            String(t.asset_id),
+                        amount: t.amount,
+                        explorerLink: explorerTxUrl(ExplorerChainId.LIGHTER, t.tx_hash),
+                        meta: {
+                            transferType: t.type,
+                            txHash: t.tx_hash,
+                            fromRoute: t.from_route,
+                            toRoute: t.to_route,
+                            fee: t.fee,
+                        },
+                    };
+                }),
+            ];
+            const merged = [...(inputCursor?.overflow ?? []), ...items];
+            const filtered = merged.filter((it) => {
+                const ts = new Date(it.timestamp).getTime();
+                if (params.startTime !== undefined && ts < params.startTime) {
+                    return false;
+                }
+                if (params.endTime !== undefined && ts > params.endTime) {
+                    return false;
+                }
+                return true;
+            });
+            filtered.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+            const limit = params.limit ?? filtered.length;
+            const emitted = filtered.slice(0, limit);
+            const overflow = filtered.slice(limit);
+            const nextCursorEnvelope = {
+                deposits: history.deposits.cursor,
+                withdraws: history.withdraws.cursor,
+                fundings: history.fundings.next_cursor,
+                liquidations: history.liquidations.next_cursor,
+                transfers: history.transfers.cursor,
+                overflow,
+            };
+            const responseCursor = encodeActivityCursor(nextCursorEnvelope);
+            const hasMore = responseCursor !== undefined;
+            return {
+                provider: LIGHTER_PROVIDER_KEY,
+                items: emitted,
+                pagination: {
+                    limit,
+                    hasMore,
+                    ...(responseCursor === undefined ? {} : { cursor: responseCursor }),
+                },
+            };
+        },
+        getQuote(params, opts) {
+            return resolveQuote(requireClient(), LIGHTER_PROVIDER_KEY, params, LIGHTER_BASE_FEE_TIER, opts);
+        },
+        getPortfolioSummary(account, positions) {
+            return summarizeLighterAccount(account, positions);
+        },
+        formatOrderPrice,
+        formatOrderSize,
+        estimateLiquidationPrice,
+        projectConfig(config, setup, options) {
+            if (config.provider !== LIGHTER_PROVIDER_KEY) {
+                throw new PerpsError(PerpsErrorCode.SDKError, `lighterProvider.projectConfig received config for provider ` +
+                    `'${config.provider}'.`);
+            }
+            return projectLighterConfigSettings(config, setup, options);
+        },
+        /**
+         * Hand the backend the local pubkey for REGISTER_API_KEY so its
+         * idempotency check can compare against the on-chain slot. No keystore
+         * configured, or no key stored for this address → omit the field;
+         * backend stages a fresh registration.
+         */
+        async resolveSetupParams(action, address) {
+            if (action !== ActionType.REGISTER_API_KEY) {
+                return {};
+            }
+            if (keyStore === undefined) {
+                return {};
+            }
+            const local = await keyStore.get(address);
+            if (local === null) {
+                return {};
+            }
+            return { knownPublicKey: local.apiKeyPublicKey };
+        },
+        async signActions(method, steps, address, ctx) {
+            if (signer === undefined || keyStore === undefined) {
+                throw new PerpsError(PerpsErrorCode.SDKError, 'lighterProvider.signActions requires `signer` and `keyStore` to be ' +
+                    'configured at construction.');
+            }
+            const signerRef = signer;
+            const keyStoreRef = keyStore;
+            return lighterSignActions({
+                signer: signerRef,
+                keyStore: keyStoreRef,
+                resolveAccountIndex: async (addr) => {
+                    const apiKey = await keyStoreRef.get(addr);
+                    if (apiKey !== null) {
+                        return apiKey.accountIndex;
+                    }
+                    const account = await fetchDetailedAccount(apiClient(), addr);
+                    return account.index;
+                },
+            }, method, steps, address, ctx);
+        },
+    };
+};
+/**
+ * Alias matching `@lifi/sdk`'s capitalised factory naming (`EVM()`, `EthereumProvider()`).
+ *
+ * @public
+ */
+export const Lighter = lighterProvider;
+//# sourceMappingURL=LighterProvider.js.map