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

package/dist/esm/signers/LighterReadOnlyTokenManager.d.ts

@@ -0,0 +1,157 @@
+import { type StorageAdapter } from '@lifi/perps-sdk';
+import type { ApproveReadOnlyTokenParams, LighterAccountConfig } from '@lifi/perps-types';
+import type { Address } from 'viem';
+/**
+ * Default Lighter HTTP host the SDK posts the create request to. Callers
+ * pointing at testnet pass an override via {@link LighterReadOnlyTokenManagerOptions.lighterApiUrl}.
+ * @public
+ */
+export declare const DEFAULT_LIGHTER_API_URL = "https://mainnet.zklighter.elliot.ai";
+/**
+ * Default token name persisted alongside Lighter's `tokens/create` row.
+ * Lighter requires a non-empty `name` form field; the literal here is what
+ * surfaces in Lighter's UI listing under `app.lighter.xyz/read-only-tokens`.
+ * @public
+ */
+export declare const DEFAULT_READ_ONLY_TOKEN_NAME = "LI.FI Perps";
+/**
+ * Persisted shape of a Lighter read-only token. The `token` string is
+ * Lighter's opaque `ro:{accountIndex}:{scope}:{expiry}:{rand}` bearer; the
+ * SDK never parses it — `expiry`/`scope`/`accountIndex` are create-time inputs
+ * we keep alongside so consumers can render expiry UX without re-fetching.
+ * @public
+ */
+export interface LighterReadOnlyToken {
+    /** Opaque bearer string — never parse client-side. */
+    token: string;
+    /** Unix seconds. The SDK's source of truth for expiry. */
+    expiry: number;
+    /** Lighter's `single | all` scope literal recorded at create time. */
+    scope: 'single' | 'all';
+    /** Lighter L2 account index the token authorises. */
+    accountIndex: number;
+}
+/**
+ * Lighter `POST /api/v1/tokens/create` response shape (subset). Lighter's
+ * OpenAPI documents additional fields (`token_id`, `name`, `revoked`, etc.)
+ * we don't need client-side.
+ * @public
+ */
+export interface LighterCreateTokenResponse {
+    api_token: string;
+    account_index: number;
+    expiry: number;
+    scopes: string;
+}
+/**
+ * Function injected for the HTTP boundary against Lighter's `tokens/create`
+ * endpoint. Returning a parsed {@link LighterCreateTokenResponse} keeps the
+ * create code free of fetch/multipart plumbing and lets tests drop a fixture
+ * in without spinning a mock server.
+ * @public
+ */
+export type LighterTokenFetcher = (params: {
+    url: string;
+    authorization: string;
+    name: string;
+    accountIndex: number;
+    expiry: number;
+    subAccountAccess: boolean;
+    scopes: string;
+}) => Promise<LighterCreateTokenResponse>;
+/** @public */
+export interface LighterReadOnlyTokenManagerOptions {
+    storage?: StorageAdapter;
+    /** Lighter API host. Defaults to {@link DEFAULT_LIGHTER_API_URL}. */
+    lighterApiUrl?: string;
+    /** Override the multipart POST. Defaults to a `fetch`-based implementation. */
+    fetcher?: LighterTokenFetcher;
+    /** Clock injection for testing expiry logic. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** @public */
+export interface ApproveReadOnlyTokenInputs extends ApproveReadOnlyTokenParams {
+    /** L1 wallet address that signs the create message. */
+    address: Address;
+}
+/** @public */
+export interface ApproveReadOnlyTokenResult {
+    token: LighterReadOnlyToken;
+    /** Projection of the post-create Lighter account state. */
+    config: Pick<LighterAccountConfig, 'provider' | 'accountIndex' | 'readOnlyTokenApproved' | 'readOnlyTokenExpiry' | 'readOnlyTokenScope'>;
+}
+/**
+ * Manage the per-account Lighter read-only token alongside the existing
+ * `(L1 address, account index)`-scoped storage adapter pattern. Takes an
+ * injectable `StorageAdapter` so callers can share one storage backend across
+ * the SDK's session stores. The token is opaque — never parsed client-side;
+ * `expiry`/`scope` recorded at create time are the source of truth.
+ *
+ * The L1 wallet signer and the HTTP fetcher are both injectable so unit
+ * tests don't need a real wallet or network.
+ * @public
+ */
+export declare class LighterReadOnlyTokenManager {
+    private readonly storage;
+    private readonly lighterApiUrl;
+    private readonly fetcher;
+    private readonly now;
+    private readonly cache;
+    constructor(options?: LighterReadOnlyTokenManagerOptions);
+    private storageKey;
+    private isExpired;
+    /**
+     * Return the stored token for the `(address, accountIndex)` pair, or
+     * `undefined` if absent or past its `expiry`. Never surfaces an expired
+     * token — consumers can rely on the return value being usable as-is.
+     */
+    get(address: Address, accountIndex: number): Promise<LighterReadOnlyToken | undefined>;
+    /**
+     * `true` when a stored token exists AND its `expiry` falls within
+     * `thresholdDays` of now. `false` when no token exists, when the token is
+     * already expired (caller should treat that as "no token"), or when it
+     * has more than `thresholdDays` of life left.
+     */
+    isReadOnlyTokenExpiringSoon(address: Address, accountIndex: number, thresholdDays?: number): Promise<boolean>;
+    /**
+     * Persist `token` for the `(address, accountIndex)` pair. Overwrites any
+     * prior stored token under the same key — used both by the approve flow
+     * and by the renewal flow.
+     */
+    set(address: Address, accountIndex: number, token: LighterReadOnlyToken): Promise<void>;
+    remove(address: Address, accountIndex: number): Promise<void>;
+    /**
+     * Create and persist a new Lighter read-only token.
+     *
+     * POSTs to Lighter's `/api/v1/tokens/create` (via the injected `fetcher`)
+     * and persists the returned `ro:` bearer alongside its
+     * `expiry`/`scope`/`accountIndex`.
+     *
+     * `authorization` MUST be a **standard** Lighter auth token — one created by
+     * the account's API key (`createAuthToken` / the WASM signer), NOT an L1
+     * wallet signature. Lighter authenticates the create request with that token
+     * and rejects anything else as `invalid auth string` (code 20013).
+     *
+     * `expirySeconds` is the absolute unix-seconds expiry Lighter records on
+     * the row. Lighter enforces 1 day ≤ lifetime ≤ 10 years server-side; the
+     * SDK does NOT pre-validate and surfaces Lighter's 400 verbatim.
+     *
+     * `scope` selects sub-account coverage: `'all'` sets `sub_account_access`
+     * (read access to every sub-account of the owner); `'single'` scopes to the
+     * one account. The permission set (`scopes` form field) is always read-only
+     * (`read.*`).
+     *
+     * @param authorization Standard (API-key-signed) Lighter auth token.
+     * @param inputs Token-create parameters plus the owning `address`.
+     */
+    approve(authorization: string, inputs: ApproveReadOnlyTokenInputs): Promise<ApproveReadOnlyTokenResult>;
+}
+/**
+ * Default fetcher: posts a multipart/form-data request to Lighter's
+ * `tokens/create` endpoint and returns the parsed response. Throws a
+ * {@link PerpsError} with the Lighter-side body when the response is
+ * non-2xx.
+ * @public
+ */
+export declare const defaultLighterTokenFetcher: LighterTokenFetcher;
+//# sourceMappingURL=LighterReadOnlyTokenManager.d.ts.map

package/dist/esm/signers/LighterReadOnlyTokenManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LighterReadOnlyTokenManager.d.ts","sourceRoot":"","sources":["../../../src/signers/LighterReadOnlyTokenManager.ts"],"names":[],"mappings":"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"}

package/dist/esm/signers/LighterReadOnlyTokenManager.js

@@ -0,0 +1,194 @@
+import { localStorageAdapter, PerpsError, readValidatedRecord, } from '@lifi/perps-sdk';
+import { PerpsErrorCode } from '@lifi/perps-types';
+const STORAGE_PREFIX = 'lifi:perps:lighter:rotoken';
+/**
+ * Default Lighter HTTP host the SDK posts the create request to. Callers
+ * pointing at testnet pass an override via {@link LighterReadOnlyTokenManagerOptions.lighterApiUrl}.
+ * @public
+ */
+export const DEFAULT_LIGHTER_API_URL = 'https://mainnet.zklighter.elliot.ai';
+/**
+ * Default token name persisted alongside Lighter's `tokens/create` row.
+ * Lighter requires a non-empty `name` form field; the literal here is what
+ * surfaces in Lighter's UI listing under `app.lighter.xyz/read-only-tokens`.
+ * @public
+ */
+export const DEFAULT_READ_ONLY_TOKEN_NAME = 'LI.FI Perps';
+const SECONDS_PER_DAY = 86_400;
+const isLighterReadOnlyToken = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { token, expiry, scope, accountIndex } = value;
+    return (typeof token === 'string' &&
+        token.length > 0 &&
+        typeof expiry === 'number' &&
+        Number.isFinite(expiry) &&
+        (scope === 'single' || scope === 'all') &&
+        typeof accountIndex === 'number' &&
+        Number.isFinite(accountIndex));
+};
+/**
+ * Manage the per-account Lighter read-only token alongside the existing
+ * `(L1 address, account index)`-scoped storage adapter pattern. Takes an
+ * injectable `StorageAdapter` so callers can share one storage backend across
+ * the SDK's session stores. The token is opaque — never parsed client-side;
+ * `expiry`/`scope` recorded at create time are the source of truth.
+ *
+ * The L1 wallet signer and the HTTP fetcher are both injectable so unit
+ * tests don't need a real wallet or network.
+ * @public
+ */
+export class LighterReadOnlyTokenManager {
+    storage;
+    lighterApiUrl;
+    fetcher;
+    now;
+    cache = new Map();
+    constructor(options = {}) {
+        this.storage = options.storage ?? localStorageAdapter;
+        this.lighterApiUrl = options.lighterApiUrl ?? DEFAULT_LIGHTER_API_URL;
+        this.fetcher = options.fetcher ?? defaultLighterTokenFetcher;
+        this.now = options.now ?? (() => Date.now());
+    }
+    storageKey(address, accountIndex) {
+        return `${STORAGE_PREFIX}:${address.toLowerCase()}:${accountIndex}`;
+    }
+    isExpired(token) {
+        return token.expiry * 1000 <= this.now();
+    }
+    /**
+     * Return the stored token for the `(address, accountIndex)` pair, or
+     * `undefined` if absent or past its `expiry`. Never surfaces an expired
+     * token — consumers can rely on the return value being usable as-is.
+     */
+    async get(address, accountIndex) {
+        const key = this.storageKey(address, accountIndex);
+        const cached = this.cache.get(key);
+        if (cached) {
+            return this.isExpired(cached) ? undefined : cached;
+        }
+        const parsed = await readValidatedRecord(this.storage, key, isLighterReadOnlyToken);
+        if (!parsed || this.isExpired(parsed)) {
+            return undefined;
+        }
+        this.cache.set(key, parsed);
+        return parsed;
+    }
+    /**
+     * `true` when a stored token exists AND its `expiry` falls within
+     * `thresholdDays` of now. `false` when no token exists, when the token is
+     * already expired (caller should treat that as "no token"), or when it
+     * has more than `thresholdDays` of life left.
+     */
+    async isReadOnlyTokenExpiringSoon(address, accountIndex, thresholdDays = 30) {
+        const key = this.storageKey(address, accountIndex);
+        const token = this.cache.get(key) ??
+            (await readValidatedRecord(this.storage, key, isLighterReadOnlyToken));
+        if (!token) {
+            return false;
+        }
+        const remainingSeconds = token.expiry - Math.floor(this.now() / 1000);
+        if (remainingSeconds <= 0) {
+            return false;
+        }
+        return remainingSeconds <= thresholdDays * SECONDS_PER_DAY;
+    }
+    /**
+     * Persist `token` for the `(address, accountIndex)` pair. Overwrites any
+     * prior stored token under the same key — used both by the approve flow
+     * and by the renewal flow.
+     */
+    async set(address, accountIndex, token) {
+        const key = this.storageKey(address, accountIndex);
+        this.cache.set(key, token);
+        await this.storage.set(key, JSON.stringify(token));
+    }
+    async remove(address, accountIndex) {
+        const key = this.storageKey(address, accountIndex);
+        this.cache.delete(key);
+        await this.storage.remove(key);
+    }
+    /**
+     * Create and persist a new Lighter read-only token.
+     *
+     * POSTs to Lighter's `/api/v1/tokens/create` (via the injected `fetcher`)
+     * and persists the returned `ro:` bearer alongside its
+     * `expiry`/`scope`/`accountIndex`.
+     *
+     * `authorization` MUST be a **standard** Lighter auth token — one created by
+     * the account's API key (`createAuthToken` / the WASM signer), NOT an L1
+     * wallet signature. Lighter authenticates the create request with that token
+     * and rejects anything else as `invalid auth string` (code 20013).
+     *
+     * `expirySeconds` is the absolute unix-seconds expiry Lighter records on
+     * the row. Lighter enforces 1 day ≤ lifetime ≤ 10 years server-side; the
+     * SDK does NOT pre-validate and surfaces Lighter's 400 verbatim.
+     *
+     * `scope` selects sub-account coverage: `'all'` sets `sub_account_access`
+     * (read access to every sub-account of the owner); `'single'` scopes to the
+     * one account. The permission set (`scopes` form field) is always read-only
+     * (`read.*`).
+     *
+     * @param authorization Standard (API-key-signed) Lighter auth token.
+     * @param inputs Token-create parameters plus the owning `address`.
+     */
+    async approve(authorization, inputs) {
+        const { address, accountIndex, expirySeconds, scope } = inputs;
+        const response = await this.fetcher({
+            url: `${this.lighterApiUrl}/api/v1/tokens/create`,
+            authorization,
+            name: DEFAULT_READ_ONLY_TOKEN_NAME,
+            accountIndex,
+            expiry: expirySeconds,
+            subAccountAccess: scope === 'all',
+            scopes: 'read.*',
+        });
+        const token = {
+            token: response.api_token,
+            expiry: response.expiry,
+            // Persist the values we requested, not Lighter's echoed ones: `scope`
+            // keeps the typed discriminator, and `accountIndex` must match the key
+            // `get()` looks up by, else a divergent echo orphans the token and re-creates every read.
+            scope,
+            accountIndex,
+        };
+        await this.set(address, token.accountIndex, token);
+        return {
+            token,
+            config: {
+                provider: 'lighter',
+                accountIndex: token.accountIndex,
+                readOnlyTokenApproved: true,
+                readOnlyTokenExpiry: token.expiry,
+                readOnlyTokenScope: token.scope,
+            },
+        };
+    }
+}
+/**
+ * Default fetcher: posts a multipart/form-data request to Lighter's
+ * `tokens/create` endpoint and returns the parsed response. Throws a
+ * {@link PerpsError} with the Lighter-side body when the response is
+ * non-2xx.
+ * @public
+ */
+export const defaultLighterTokenFetcher = async ({ url, authorization, name, accountIndex, expiry, subAccountAccess, scopes, }) => {
+    const form = new FormData();
+    form.set('name', name);
+    form.set('account_index', String(accountIndex));
+    form.set('expiry', String(expiry));
+    form.set('sub_account_access', String(subAccountAccess));
+    form.set('scopes', scopes);
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { authorization },
+        body: form,
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new PerpsError(PerpsErrorCode.ServerError, `Lighter tokens/create returned ${response.status}: ${body || '<empty>'}`);
+    }
+    return (await response.json());
+};
+//# sourceMappingURL=LighterReadOnlyTokenManager.js.map

package/dist/esm/signers/LighterReadOnlyTokenManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LighterReadOnlyTokenManager.js","sourceRoot":"","sources":["../../../src/signers/LighterReadOnlyTokenManager.ts"],"names":[],"mappings":"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"}

package/dist/esm/signers/LighterSigner.d.ts

@@ -0,0 +1,94 @@
+import { ActionType } from '@lifi/perps-types';
+import { type LoadLighterWasmOptions } from './wasmLoader.js';
+/** @public */
+export interface LighterSignerContext {
+    /** Lighter-native private key (from GenerateAPIKey, NOT an Ethereum key). */
+    apiKeyPrivateKey: string;
+    /** API key slot registered on-chain (0-255). */
+    apiKeyIndex: number;
+    /** Lighter account index — looked up from the user's L1 Ethereum address. */
+    accountIndex: number;
+}
+/** @public */
+export interface LighterSignerConfig extends LoadLighterWasmOptions {
+    /** Lighter REST API base URL. */
+    apiUrl?: string;
+    /** Lighter chain ID (304 = mainnet). */
+    chainId?: number;
+}
+/** @public */
+export interface LighterSignedBlob {
+    txType: number;
+    txInfo: string;
+    txHash: string;
+}
+/** @public */
+export interface ChangePubKeyResult extends LighterSignedBlob {
+    /** EIP-191 message the L1 Ethereum wallet must sign to authorize the key rotation. */
+    messageToSign: string;
+}
+/** @public */
+export interface ApiKeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+/** @public */
+export declare class LighterSigner {
+    private readonly apiUrl;
+    private readonly chainId;
+    private readonly loaderOptions;
+    private wasm;
+    private readonly registeredClients;
+    constructor(config?: LighterSignerConfig);
+    initialize(): Promise<void>;
+    /**
+     * Generate a fresh Lighter API keypair. Pass an optional 32-byte hex seed
+     * for deterministic generation (used in tests); omit for a random key.
+     */
+    generateAPIKey(seed?: string): Promise<ApiKeyPair>;
+    /**
+     * Sign an action blob with the provided (apiKeyPrivateKey, apiKeyIndex,
+     * accountIndex) context. `wasmSignParams` comes straight from the backend's
+     * `WasmBlobActionStep`. Returns the signed `{ txType, txInfo, txHash }`
+     * triple the backend forwards to Lighter's `sendTx` endpoint.
+     *
+     * For REGISTER_API_KEY use `signChangePubKey` instead — it returns an
+     * additional `messageToSign` the L1 wallet must countersign.
+     */
+    sign(action: ActionType, wasmSignParams: Record<string, unknown>, context: LighterSignerContext): Promise<LighterSignedBlob>;
+    /**
+     * Step 1 of the REGISTER_API_KEY flow. Generates the WASM blob for a
+     * ChangePubKey tx with `L1Sig` left empty, plus the canonical EIP-191
+     * message the L1 Ethereum wallet must sign next.
+     *
+     * Requires the freshly-generated `privateKey` (returned by
+     * {@link generateAPIKey}) — the Go WASM signer registers a per-slot client
+     * keyed on `(apiKeyIndex, accountIndex)` before it'll sign anything for
+     * that slot, including the ChangePubKey that's about to register the key
+     * on-chain. This is purely client-side bookkeeping; it does not touch the
+     * Lighter API.
+     */
+    signChangePubKey(pubKeyHex: string, privateKey: string, nonce: number, apiKeyIndex: number, accountIndex: number, skipNonce?: 0 | 1): Promise<ChangePubKeyResult>;
+    /**
+     * Step 2 of REGISTER_API_KEY — inject the L1 signature produced by the
+     * user's Ethereum wallet into the ChangePubKey txInfo JSON. `L1Sig` is the
+     * only field in txInfo that depends on the L1 signature; txHash does NOT
+     * include it (so we do not recompute it).
+     */
+    embedL1Signature(txInfo: string, l1Signature: string): string;
+    /**
+     * Create an auth token for authenticated WebSocket subscriptions.
+     * `deadline` is a Unix timestamp in seconds — tokens have an 8h hard cap.
+     */
+    createAuthToken(deadline: number, context: LighterSignerContext): Promise<string>;
+    private ensureLoaded;
+    private ensureClient;
+    /**
+     * Map an ActionType + backend-provided params object to the positional-arg
+     * WASM call. The Go signer exports take primitives in order, not an object
+     * — so we pick fields in the exact order the Go side expects. Unknown
+     * fields (e.g. backend's integrator_* hints) are ignored.
+     */
+    private dispatch;
+}
+//# sourceMappingURL=LighterSigner.d.ts.map

package/dist/esm/signers/LighterSigner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LighterSigner.d.ts","sourceRoot":"","sources":["../../../src/signers/LighterSigner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAEL,KAAK,sBAAsB,EAG5B,MAAM,iBAAiB,CAAA;AAOxB,cAAc;AACd,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAA;IACxB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,cAAc;AACd,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,cAAc;AACd,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,cAAc;AACd,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAKD,cAAc;AACd,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwB;IACtD,OAAO,CAAC,IAAI,CAAgC;IAC5C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;gBAE1C,MAAM,GAAE,mBAAwB;IAUtC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;OAGG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAYxD;;;;;;;;OAQG;IACG,IAAI,CACR,MAAM,EAAE,UAAU,EAClB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAa7B;;;;;;;;;;;OAWG;IACG,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,CAAC,GAAG,CAAK,GACnB,OAAO,CAAC,kBAAkB,CAAC;IAsC9B;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAa7D;;;OAGG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC;YAiBJ,YAAY;YAOZ,YAAY;IAmB1B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CAsGjB"}