@relayprotocol/relay-lighter-wallet-adapter 0.1.1

package/_types/src/adapter.d.ts

@@ -0,0 +1,181 @@
+import { type AdaptedWallet } from '@relayprotocol/relay-sdk';
+export declare const LIGHTER_CHAIN_ID = 3586256;
+/**
+ * Minimal L1 signer shape the adapter passes into `transfer()`. The real
+ * Lighter SDK accepts `string | ethers.Signer`; we only ever use
+ * `signMessage`, so that's all we require structurally.
+ */
+export type LighterEthSigner = {
+    signMessage: (message: string) => Promise<string>;
+};
+export type LighterTransferParams = {
+    toAccountIndex: number;
+    assetIndex: number;
+    fromRouteType: number;
+    toRouteType: number;
+    amount: number;
+    usdcFee: number;
+    memo: string;
+    /**
+     * L1 signer used for the per-transfer authorization. Only omitted when
+     * the caller's `signerClient` handles L1 signing internally — the stock
+     * `@relay-protocol/lighter-ts-sdk` `SignerClient` requires it.
+     */
+    ethSigner?: LighterEthSigner;
+    nonce?: number;
+};
+/** Subset of the SDK's `Transaction` shape that the adapter actually reads. */
+export type LighterTransaction = {
+    hash: string;
+    status: number | 'pending' | 'confirmed' | 'failed';
+    block_height?: number;
+    message?: string;
+};
+/**
+ * Minimal Lighter signer contract the adapter depends on. Integrators
+ * passing a pre-built signer only need to implement these two methods;
+ * the full `@relay-protocol/lighter-ts-sdk` `SignerClient` satisfies this
+ * structurally and can be passed directly.
+ */
+export type LighterSigner = {
+    transfer: (params: LighterTransferParams) => Promise<[unknown, string, string | null]>;
+    getTransaction: (txHash: string) => Promise<LighterTransaction>;
+};
+/**
+ * Optional per-origin persistent storage for the generated API key. If
+ * omitted the adapter regenerates a fresh key on every page load (the
+ * conservative default — key never leaves memory). If you want to skip the
+ * per-session `changeApiKey` signature prompt, plug in something like
+ * `localStorage` or IndexedDB.
+ */
+export type LighterKeyStorage = {
+    get: (storageKey: string) => Promise<string | null> | string | null;
+    set: (storageKey: string, value: string) => Promise<void> | void;
+};
+/** Callback that signs a plain-text L1 authorization message. */
+export type LighterSignL1Message = (message: string) => Promise<string>;
+type AdaptLighterWalletBaseOptions = {
+    /**
+     * The user's L1 (EVM) wallet address. Used to resolve their Lighter
+     * account index and to key the optional persistent storage.
+     */
+    l1Address: `0x${string}`;
+    /**
+     * Callback that signs an L1 authorization message with the user's
+     * connected wallet. Typically a thin wrapper around a viem
+     * `WalletClient.signMessage` call.
+     *
+     * Required unless `signerClient` is supplied — when the integrator
+     * provides their own signer, it's assumed to handle L1 signing
+     * internally (or to accept `signL1Message` as a separate concern).
+     *
+     * When both are supplied, `signL1Message` is still forwarded to the
+     * signer's `transfer()` calls via the `ethSigner` param.
+     *
+     * Not invoked for the bootstrap step when `accountApiKey` or
+     * `signerClient` is supplied — only for per-transfer authorization.
+     */
+    signL1Message?: LighterSignL1Message;
+    apiUrl?: string;
+    apiKeyIndex?: number;
+    /** Paths to the Lighter WASM signer + Go runtime shim. Default: jsDelivr CDN. */
+    wasmConfig?: {
+        wasmPath?: string;
+        wasmExecPath?: string;
+    };
+    /**
+     * Pre-registered Lighter account API key (hex-encoded, with or without
+     * `0x` prefix). This is the Lighter protocol's session key — not a
+     * wallet private key. When supplied, the adapter skips the
+     * `generateAPIKey` + `changeApiKey` bootstrap entirely (no signature
+     * prompt, no on-chain key-rotation wait) and uses this key directly for
+     * the `SignerClient`.
+     *
+     * The caller is responsible for:
+     *   - Having already registered the corresponding public key on the
+     *     user's Lighter account at `apiKeyIndex`
+     *   - Storing the key securely
+     *
+     * Use this when you've built your own API-key lifecycle (e.g. a
+     * backend service that provisions keys, or a wallet-level integration
+     * that manages keys outside this adapter). Mutually exclusive with
+     * `storage` — if both are set, `accountApiKey` wins and `storage` is
+     * ignored.
+     */
+    accountApiKey?: string;
+    /**
+     * Optional API-key persistence. When provided, the adapter reuses the
+     * stored key across sessions instead of re-running `changeApiKey`.
+     * Ignored when `accountApiKey` or `signerClient` is supplied.
+     */
+    storage?: LighterKeyStorage;
+    /** Confirmation poll interval. Default: 2000ms. */
+    pollIntervalMs?: number;
+    /** Confirmation timeout. Default: 120000ms. */
+    timeoutMs?: number;
+};
+/**
+ * Pre-built-signer path. `signerClient` and `accountIndex` must be paired
+ * — the adapter can't pull account index out of a `SignerClient` instance
+ * (the SDK's config is private), and it needs the value for
+ * `AdaptedWallet.address()`. Pairing them lets the adapter run with
+ * zero runtime dependency on `@relay-protocol/lighter-ts-sdk`.
+ */
+type AdaptLighterWalletPreBuiltOptions = AdaptLighterWalletBaseOptions & {
+    /**
+     * Pre-built Lighter signer. When supplied, the adapter bypasses the
+     * `generateAPIKey` / `changeApiKey` bootstrap entirely and uses this
+     * signer for all `transfer()` and `getTransaction()` calls.
+     *
+     * The caller is responsible for ensuring the signer is ready to use
+     * (initialized, WASM loaded, API key registered) and for caching it
+     * if desired. A full `SignerClient` from `@relay-protocol/lighter-ts-sdk`
+     * satisfies `LighterSigner` structurally and can be passed directly.
+     *
+     * When set, `apiUrl`, `apiKeyIndex`, `wasmConfig`, `accountApiKey`,
+     * and `storage` are all ignored (baked into the signer).
+     */
+    signerClient: LighterSigner;
+    /** The user's Lighter account index. Required when `signerClient` is set. */
+    accountIndex: number;
+};
+/** Bootstrap path — the adapter owns the signer lifecycle. */
+type AdaptLighterWalletBootstrapOptions = AdaptLighterWalletBaseOptions & {
+    signerClient?: never;
+    accountIndex?: never;
+};
+export type AdaptLighterWalletOptions = AdaptLighterWalletBootstrapOptions | AdaptLighterWalletPreBuiltOptions;
+/**
+ * Adapts a Lighter wallet to work with the Relay SDK.
+ *
+ * The adapter owns the full Lighter session lifecycle so integrators only
+ * have to provide the user's L1 address and a message-signing callback:
+ *
+ *   ```ts
+ *   const wallet = adaptLighterWallet({
+ *     l1Address: account.address,
+ *     signL1Message: (msg) =>
+ *       walletClient.signMessage({ account, message: msg })
+ *   })
+ *   ```
+ *
+ * On construction the adapter does nothing interactive — no network calls,
+ * no signature prompts. The first call into `handleSendTransactionStep`
+ * triggers the lazy bootstrap, which:
+ *   1. Resolves the user's Lighter `accountIndex` from their L1 address.
+ *   2. Either loads a persisted API key (if `storage` is provided) or
+ *      generates a fresh keypair in memory.
+ *   3. For a fresh key, prompts the user to sign an L1 authorization and
+ *      calls `changeApiKey` to register it against the account.
+ *   4. Waits for the key rotation to execute on Lighter.
+ *   5. Constructs the real `SignerClient` backed by the new key.
+ *
+ * Subsequent transactions reuse the cached session (in-memory at minimum).
+ *
+ * Passing `signerClient` skips the entire bootstrap and avoids any runtime
+ * dependency on `@relay-protocol/lighter-ts-sdk`.
+ *
+ */
+export declare const adaptLighterWallet: (options: AdaptLighterWalletOptions) => AdaptedWallet;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/_types/src/adapter.d.ts.map

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

package/_types/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/_types/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}