@solana/kit-plugin-wallet 0.0.0 → 0.12.0

package/src/types/global.d.ts

@@ -0,0 +1,6 @@
+declare const __BROWSER__: boolean;
+declare const __ESM__: boolean;
+declare const __NODEJS__: boolean;
+declare const __REACTNATIVE__: boolean;
+declare const __TEST__: boolean;
+declare const __VERSION__: string;

package/src/types.ts

@@ -0,0 +1,358 @@
+import type { MessageSigner, SignatureBytes, TransactionSigner } from '@solana/kit';
+import type { SolanaChain } from '@solana/wallet-standard-chains';
+import type { SolanaSignInInput, SolanaSignInOutput } from '@solana/wallet-standard-features';
+import type { IdentifierString } from '@wallet-standard/base';
+import type { UiWallet, UiWalletAccount } from '@wallet-standard/ui';
+
+/**
+ * The signer type for a connected wallet account.
+ *
+ * Always satisfies `TransactionSigner`. Additionally implements `MessageSigner`
+ * when the wallet supports `solana:signMessage`.
+ */
+export type WalletSigner = TransactionSigner | (MessageSigner & TransactionSigner);
+
+// -- Public types -----------------------------------------------------------
+
+/**
+ * The connection status of the wallet plugin.
+ *
+ * - `pending` — not yet initialized. Initial state on both server and browser.
+ *   On the server — and in React Native, which is treated the same way — this
+ *   state is permanent. In the browser it resolves to `disconnected` or
+ *   `reconnecting` once the storage check completes.
+ * - `disconnected` — initialized, no wallet connected.
+ * - `connecting` — a user-initiated connection request is in progress. When
+ *   connecting to a different wallet while one is already connected, the
+ *   existing connection is preserved until the new one succeeds — so
+ *   {@link WalletState.connected} can be non-null during this state, and a
+ *   failed attempt reverts to the previous connection.
+ * - `connected` — a wallet is connected.
+ * - `disconnecting` — a user-initiated disconnection request is in progress.
+ * - `reconnecting` — auto-connect in progress (connecting to persisted wallet).
+ */
+export type WalletStatus = 'connected' | 'connecting' | 'disconnected' | 'disconnecting' | 'pending' | 'reconnecting';
+
+/**
+ * A snapshot of the wallet plugin state at a point in time.
+ *
+ * Returned by {@link WalletNamespace.getState}. The same object reference
+ * is returned on successive calls as long as nothing has changed — a new
+ * object is only created when a field actually changes. This ensures
+ * `useSyncExternalStore` only triggers re-renders on meaningful state changes.
+ *
+ * @see {@link WalletNamespace.getState}
+ */
+export type WalletState = {
+    /**
+     * The active connection, or `null` when disconnected.
+     *
+     * `signer` is `null` for read-only / watch-only wallets that do not
+     * support any signing feature.
+     *
+     * Independent of {@link status}: when {@link connect} or {@link signIn} is
+     * called for a different wallet while one is already connected, `connected`
+     * keeps describing the existing connection while `status` is `'connecting'`,
+     * and a failed attempt leaves it in place.
+     */
+    readonly connected: {
+        readonly account: UiWalletAccount;
+        /** The signer for the active account, or `null` for read-only wallets. */
+        readonly signer: WalletSigner | null;
+        readonly wallet: UiWallet;
+    } | null;
+    /** The current connection status. */
+    readonly status: WalletStatus;
+    /** All discovered wallets matching the configured chain and filter. */
+    readonly wallets: readonly UiWallet[];
+};
+
+/**
+ * Options accepted by each async wallet action.
+ *
+ * Currently only carries an `abortSignal`, but is kept as an object for
+ * consistency with the rest of the Kit ecosystem and to allow future
+ * additions without breaking the call-site shape.
+ *
+ * @see {@link WalletNamespace.connect}
+ * @see {@link WalletNamespace.disconnect}
+ * @see {@link WalletNamespace.signMessage}
+ * @see {@link WalletNamespace.signIn}
+ */
+export type WalletActionOptions = {
+    /**
+     * An optional `AbortSignal` used to cancel the operation.
+     *
+     * Cancellation is pre-call only: the plugin calls
+     * `abortSignal.throwIfAborted()` at the start of each action and bails
+     * out before invoking the wallet. Once the underlying wallet-standard
+     * call has been dispatched, its result is returned even if the signal
+     * is aborted mid-flight — the wallet's side effect (an approved
+     * signature, a live connection, a broadcast transaction) is the source
+     * of truth, and throwing here would discard real user work without
+     * undoing what the wallet already did.
+     */
+    abortSignal?: AbortSignal;
+};
+
+/**
+ * A pluggable storage adapter for persisting the selected wallet account.
+ *
+ * Follows the Web Storage API shape (`getItem`/`setItem`/`removeItem`).
+ * `localStorage` and `sessionStorage` satisfy this interface directly.
+ * Async backends (IndexedDB, encrypted storage) may return `Promise`s.
+ *
+ * Writes are fire-and-forget: the plugin does not await `setItem`/`removeItem`
+ * and swallows any rejection (the live wallet connection is the source of
+ * truth, so a failed persist is non-fatal). A resolved action therefore does
+ * not guarantee the write has landed, and rapid successive writes are not
+ * ordered. This is intentional — persistence only records which account to
+ * silently reconnect to on the next load.
+ *
+ * @example
+ * ```ts
+ * // Use sessionStorage
+ * walletSigner({ chain: 'solana:mainnet', storage: sessionStorage });
+ *
+ * // Custom async adapter
+ * walletSigner({
+ *   chain: 'solana:mainnet',
+ *   storage: {
+ *     getItem: (key) => myStore.get(key),
+ *     setItem: (key, value) => myStore.set(key, value),
+ *     removeItem: (key) => myStore.delete(key),
+ *   },
+ * });
+ * ```
+ */
+export type WalletStorage = {
+    getItem(key: string): Promise<string | null> | string | null;
+    removeItem(key: string): Promise<void> | void;
+    setItem(key: string, value: string): Promise<void> | void;
+};
+
+/**
+ * Configuration for the wallet plugins.
+ *
+ * @see {@link walletSigner}
+ * @see {@link walletIdentity}
+ * @see {@link walletPayer}
+ * @see {@link walletWithoutSigner}
+ */
+export type WalletPluginConfig = {
+    /**
+     * Whether to attempt silent reconnection on startup using the persisted
+     * wallet account from `storage`.
+     *
+     * Has no effect if `storage` is `null`.
+     *
+     * @default true
+     */
+    autoConnect?: boolean;
+
+    /**
+     * The chain this client targets (e.g. `'solana:mainnet'`).
+     *
+     * Accepts any {@link SolanaChain} (with literal autocomplete) and, as an
+     * escape hatch, any wallet-standard {@link IdentifierString} shape
+     * (`${string}:${string}`) for custom chains or non-Solana L2s. The plugin's
+     * runtime behavior is chain-agnostic — it passes the identifier to
+     * wallet-standard discovery (`uiWallet.chains.includes(chain)`) and to
+     * `createSignerFromWalletAccount`. Wallets that don't advertise the chain
+     * are filtered out, and accounts that can't produce a signer for the chain
+     * resolve to `signer: null` (matching the read-only-wallet contract).
+     *
+     * One client = one chain. To switch networks, create a separate client
+     * with a different chain and RPC endpoint.
+     */
+    chain: SolanaChain | (IdentifierString & {});
+
+    /**
+     * Optional filter function for wallet discovery. Called for each wallet
+     * that supports the configured chain and `standard:connect`. Return `true`
+     * to include the wallet, `false` to exclude it.
+     *
+     * @example
+     * ```ts
+     * // Require signAndSendTransaction
+     * filter: (w) => w.features.includes('solana:signAndSendTransaction')
+     *
+     * // Whitelist specific wallets
+     * filter: (w) => ['SomeWallet', 'SomeOtherWallet'].includes(w.name)
+     * ```
+     */
+    filter?: (wallet: UiWallet) => boolean;
+
+    /**
+     * Storage adapter for persisting the selected wallet account across page
+     * loads. Pass `null` to disable persistence entirely.
+     *
+     * When omitted in a browser environment, `localStorage` is used by default.
+     * On the server, storage is always skipped regardless of this option.
+     *
+     * @default localStorage (in browser)
+     * @see {@link WalletStorage}
+     */
+    storage?: WalletStorage | null;
+
+    /**
+     * Storage key used for persistence.
+     *
+     * @default 'kit-wallet'
+     */
+    storageKey?: string;
+};
+
+/**
+ * The `wallet` namespace exposed on the client as `client.wallet`.
+ *
+ * All wallet state is accessed via {@link getState}. Use {@link subscribe}
+ * to be notified of changes and integrate with framework primitives such as
+ * React's `useSyncExternalStore`.
+ *
+ * @see {@link ClientWithWallet}
+ */
+export type WalletNamespace = {
+    // -- Actions --
+
+    /**
+     * Connect to a wallet. Calls `standard:connect`, then selects the first
+     * newly authorized account (or the first account if reconnecting). Creates
+     * and caches a signer for the active account.
+     *
+     * Resolving means the wallet is connected; any failure rejects. If a wallet
+     * is already connected, it stays connected until the new one is established:
+     * a failed attempt — a rejected prompt, no authorized accounts, or the
+     * wallet becoming unavailable — leaves the previous connection in place
+     * rather than disconnecting it.
+     *
+     * @returns All accounts from the wallet after connection.
+     * @throws The wallet's rejection error if the user declines the prompt.
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if the wallet
+     *   authorizes no accounts, or unregisters (or drops a required
+     *   feature/chain) while its connect prompt is open. Any previously
+     *   connected wallet is left in place.
+     * @throws `DOMException` with `name: 'AbortError'` if a newer `connect` or
+     *   `signIn` is started before this call resolves. The newer request wins
+     *   and owns the resulting connection; this superseded call rejects so it
+     *   can be ignored like any other aborted operation (e.g. an accidental
+     *   double-click still connects — only the orphaned first promise rejects).
+     * @throws `options.abortSignal.reason` if the signal is already aborted
+     *   when the action is called. Aborts after the wallet call has been
+     *   dispatched do not take effect.
+     */
+    connect: (wallet: UiWallet, options?: WalletActionOptions) => Promise<readonly UiWalletAccount[]>;
+
+    /**
+     * Disconnect the active wallet. Calls `standard:disconnect` if supported.
+     *
+     * @throws `options.abortSignal.reason` if the signal is already aborted
+     *   when the action is called. Aborts after the wallet call has been
+     *   dispatched do not take effect.
+     */
+    disconnect: (options?: WalletActionOptions) => Promise<void>;
+
+    // -- State --
+    /**
+     * Get the current wallet state. Referentially stable — a new object is
+     * only created when a field actually changes, so React's
+     * `useSyncExternalStore` skips re-renders when nothing meaningful changed.
+     *
+     * @see {@link WalletState}
+     */
+    getState: () => WalletState;
+
+    /**
+     * Switch to a different account within the connected wallet. Creates and
+     * caches a new signer for the selected account.
+     *
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if no wallet is
+     *   connected, or the connected wallet is currently disconnecting.
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE)` if the
+     *   specified account is not among the connected wallet's accounts.
+     */
+    selectAccount: (account: UiWalletAccount) => void;
+
+    /**
+     * Sign In With Solana (SIWS-as-connect).
+     *
+     * Connects the wallet, calls `solana:signIn`, sets the returned account as
+     * active, and creates a signer. Resolving means the client is in the same
+     * state as if {@link connect} had been called; any failure to connect
+     * rejects rather than resolving while disconnected.
+     *
+     * All fields on `SolanaSignInInput` are optional — pass `{}` if no sign-in
+     * customization is needed.
+     *
+     * To sign in with the already-connected wallet, pass
+     * `getState().connected.wallet`.
+     *
+     * Like {@link connect}, a failed sign-in to a different wallet rejects and
+     * leaves any existing connection in place rather than disconnecting it.
+     *
+     * @returns The wallet's sign-in output, once the connection is established.
+     * @throws `WalletStandardError(WALLET_STANDARD_ERROR__FEATURES__WALLET_ACCOUNT_FEATURE_UNIMPLEMENTED)`
+     *   if the wallet does not support `solana:signIn`.
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if the wallet
+     *   unregisters (or drops a required feature/chain) while its sign-in prompt
+     *   is open, or signs in with an account it does not expose. Any previously
+     *   connected wallet is left in place.
+     * @throws `DOMException` with `name: 'AbortError'` if a newer `connect` or
+     *   `signIn` is started before this call resolves. The newer request wins
+     *   and owns the resulting connection; this superseded call rejects so it
+     *   can be ignored like any other aborted operation.
+     * @throws `options.abortSignal.reason` if the signal is already aborted
+     *   when the action is called. Aborts after the wallet call has been
+     *   dispatched do not take effect.
+     */
+    signIn: (wallet: UiWallet, input: SolanaSignInInput, options?: WalletActionOptions) => Promise<SolanaSignInOutput>;
+
+    /**
+     * Sign an arbitrary message with the connected account.
+     *
+     * Calls the wallet's `solana:signMessage` feature directly (does not go
+     * through the cached signer), so message signing works even for wallets
+     * that don't support transaction signing.
+     *
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if no wallet is connected.
+     * @throws `WalletStandardError(WALLET_STANDARD_ERROR__FEATURES__WALLET_ACCOUNT_FEATURE_UNIMPLEMENTED)`
+     *   if the wallet does not support `solana:signMessage`.
+     * @throws `options.abortSignal.reason` if the signal is already aborted
+     *   when the action is called. Aborts after the wallet call has been
+     *   dispatched do not take effect.
+     */
+    signMessage: (message: Uint8Array, options?: WalletActionOptions) => Promise<SignatureBytes>;
+
+    /**
+     * Subscribe to any wallet state change. Compatible with React's
+     * `useSyncExternalStore` and similar framework primitives.
+     *
+     * @returns An unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const state = useSyncExternalStore(client.wallet.subscribe, client.wallet.getState);
+     * ```
+     */
+    subscribe: (listener: () => void) => () => void;
+};
+
+/**
+ * Properties added to the client by the wallet plugins.
+ *
+ * All wallet state and actions are namespaced under `client.wallet`.
+ * Depending on which plugin variant is used, `client.payer` and/or
+ * `client.identity` may also be set to the connected wallet's signer.
+ * This is not part of Kit plugin-interfaces, as it depends on wallet-standard types
+ *
+ * @see {@link walletSigner}
+ * @see {@link walletPayer}
+ * @see {@link walletIdentity}
+ * @see {@link walletWithoutSigner}
+ * @see {@link WalletNamespace}
+ *
+ */
+export type ClientWithWallet = {
+    /** The wallet namespace — state, actions, and framework integration. */
+    readonly wallet: WalletNamespace;
+};

package/src/wallet.ts

@@ -0,0 +1,216 @@
+import {
+    type ClientWithIdentity,
+    type ClientWithPayer,
+    type ClientWithSubscribeToIdentity,
+    type ClientWithSubscribeToPayer,
+    extendClient,
+    SOLANA_ERROR__WALLET__NO_SIGNER_CONNECTED,
+    SOLANA_ERROR__WALLET__SIGNER_NOT_AVAILABLE,
+    SolanaError,
+    withCleanup,
+} from '@solana/kit';
+
+import { createWalletStore } from './store';
+import type { ClientWithWallet, WalletPluginConfig } from './types';
+
+// -- Internal helpers ---------------------------------------------------------
+
+function defineSignerGetter(
+    additions: Record<string, unknown>,
+    property: string,
+    store: ReturnType<typeof createWalletStore>,
+): void {
+    Object.defineProperty(additions, property, {
+        configurable: true,
+        enumerable: true,
+        get() {
+            const state = store.getState();
+            if (!state.connected) {
+                throw new SolanaError(SOLANA_ERROR__WALLET__NO_SIGNER_CONNECTED, { status: state.status });
+            }
+            if (!state.connected.signer) {
+                throw new SolanaError(SOLANA_ERROR__WALLET__SIGNER_NOT_AVAILABLE);
+            }
+            return state.connected.signer;
+        },
+    });
+}
+
+type SignerProperties = 'payer' | 'identity';
+
+// Maps each signer capability to the Kit-convention reactive hook installed
+// alongside it (`@solana/plugin-interfaces`). A plugin whose `client.payer` /
+// `client.identity` is dynamic installs the matching `subscribeTo*` function
+// so reactive consumers can observe changes without naming this plugin.
+const SUBSCRIBE_PROPERTY: Record<SignerProperties, 'subscribeToIdentity' | 'subscribeToPayer'> = {
+    identity: 'subscribeToIdentity',
+    payer: 'subscribeToPayer',
+};
+
+function createPlugin<TAdditions extends ClientWithWallet>(
+    config: WalletPluginConfig,
+    signerProperties: SignerProperties[],
+) {
+    return <T extends object & { wallet?: never }>(client: T): Disposable & Omit<T, keyof TAdditions> & TAdditions => {
+        if ('wallet' in client) {
+            throw new Error(
+                'Only one wallet plugin can be used per client. ' +
+                    'Use walletSigner, walletPayer, walletIdentity, or walletWithoutSigner — not multiple.',
+            );
+        }
+
+        const store = createWalletStore(config);
+
+        const additions: Record<string, unknown> = { wallet: store };
+        for (const prop of signerProperties) {
+            defineSignerGetter(additions, prop, store);
+            additions[SUBSCRIBE_PROPERTY[prop]] = store.subscribeSigner;
+        }
+
+        return withCleanup(extendClient(client, additions), () => store[Symbol.dispose]()) as unknown as Disposable &
+            Omit<T, keyof TAdditions> &
+            TAdditions;
+    };
+}
+
+// -- Public API ---------------------------------------------------------------
+
+/**
+ * A framework-agnostic Kit plugin that manages wallet discovery, connection
+ * lifecycle, and signer creation using wallet-standard — and syncs the
+ * connected wallet's signer to both `client.payer` and `client.identity`.
+ *
+ * This is the most common entrypoint for dApps. When a signing-capable
+ * wallet is connected, `client.payer` and `client.identity` both return the
+ * wallet signer. When disconnected or read-only, accessing either throws.
+ *
+ * Because the signer is dynamic, both `client.subscribeToPayer` and
+ * `client.subscribeToIdentity` are installed so reactive consumers can observe
+ * changes (the Kit reactive-capability convention).
+ *
+ * **SSR-safe.** Can be included in a shared client chain that runs on both
+ * server and browser.
+ *
+ * ```ts
+ * const client = createClient()
+ *   .use(walletSigner({ chain: 'solana:mainnet' }))
+ *   .use(solanaRpc({ rpcUrl: 'https://api.mainnet-beta.solana.com' }))
+ *   .use(planAndSendTransactions());
+ * ```
+ *
+ * @param config - Plugin configuration.
+ *
+ * @see {@link walletPayer}
+ * @see {@link walletIdentity}
+ * @see {@link walletWithoutSigner}
+ * @see {@link WalletPluginConfig}
+ */
+export function walletSigner(config: WalletPluginConfig) {
+    return createPlugin<
+        ClientWithIdentity &
+            ClientWithPayer &
+            ClientWithSubscribeToIdentity &
+            ClientWithSubscribeToPayer &
+            ClientWithWallet
+    >(config, ['payer', 'identity']);
+}
+
+/**
+ * A framework-agnostic Kit plugin that manages wallet discovery, connection
+ * lifecycle, and signer creation using wallet-standard — and syncs the
+ * connected wallet's signer to `client.identity`.
+ *
+ * Use this when `client.payer` is controlled by a separate `payer()` plugin
+ * (e.g. a backend relayer pays fees, but the user's wallet is the identity).
+ *
+ * Because the signer is dynamic, `client.subscribeToIdentity` is installed so
+ * reactive consumers can observe changes (the Kit reactive-capability convention).
+ *
+ * **SSR-safe.** Can be included in a shared client chain that runs on both
+ * server and browser.
+ *
+ * ```ts
+ * const client = createClient()
+ *   .use(payer(relayerKeypair))
+ *   .use(walletIdentity({ chain: 'solana:mainnet' }))
+ *   .use(solanaRpc({ rpcUrl: 'https://api.mainnet-beta.solana.com' }))
+ *   .use(planAndSendTransactions());
+ * ```
+ *
+ * @param config - Plugin configuration.
+ *
+ * @see {@link walletSigner}
+ * @see {@link walletPayer}
+ * @see {@link walletWithoutSigner}
+ * @see {@link WalletPluginConfig}
+ */
+export function walletIdentity(config: WalletPluginConfig) {
+    return createPlugin<ClientWithIdentity & ClientWithSubscribeToIdentity & ClientWithWallet>(config, ['identity']);
+}
+
+/**
+ * A framework-agnostic Kit plugin that manages wallet discovery, connection
+ * lifecycle, and signer creation using wallet-standard — and syncs the
+ * connected wallet's signer to `client.payer`.
+ *
+ * Use this when you need the wallet as the fee payer but don't need
+ * `client.identity`. For most dApps, prefer {@link walletSigner} which
+ * sets both.
+ *
+ * Because the signer is dynamic, `client.subscribeToPayer` is installed so
+ * reactive consumers can observe changes (the Kit reactive-capability convention).
+ *
+ * **SSR-safe.** Can be included in a shared client chain that runs on both
+ * server and browser.
+ *
+ * ```ts
+ * const client = createClient()
+ *   .use(walletPayer({ chain: 'solana:mainnet' }))
+ *   .use(solanaRpc({ rpcUrl: 'https://api.mainnet-beta.solana.com' }))
+ *   .use(planAndSendTransactions());
+ * ```
+ *
+ * @param config - Plugin configuration.
+ *
+ * @see {@link walletSigner}
+ * @see {@link walletIdentity}
+ * @see {@link walletWithoutSigner}
+ * @see {@link WalletPluginConfig}
+ */
+export function walletPayer(config: WalletPluginConfig) {
+    return createPlugin<ClientWithPayer & ClientWithSubscribeToPayer & ClientWithWallet>(config, ['payer']);
+}
+
+/**
+ * A framework-agnostic Kit plugin that manages wallet discovery, connection
+ * lifecycle, and signer creation using wallet-standard.
+ *
+ * Adds the `wallet` namespace to the client without setting `client.payer`
+ * or `client.identity`. Use this alongside separate `payer()` and/or
+ * `identity()` plugins, or when the wallet's signer is used explicitly in
+ * instructions. For most dApps, prefer {@link walletSigner} instead.
+ *
+ * **SSR-safe.** Can be included in a shared client chain that runs on both
+ * server and browser.
+ *
+ * ```ts
+ * const client = createClient()
+ *   .use(payer(backendKeypair))
+ *   .use(walletWithoutSigner({ chain: 'solana:mainnet' }))
+ *   .use(solanaRpc({ rpcUrl: 'https://api.mainnet-beta.solana.com' }))
+ *   .use(planAndSendTransactions());
+ *
+ * // client.payer is always backendKeypair
+ * // client.wallet.getState().connected?.signer for manual use
+ * ```
+ *
+ * @param config - Plugin configuration.
+ *
+ * @see {@link walletSigner}
+ * @see {@link walletPayer}
+ * @see {@link walletIdentity}
+ * @see {@link WalletPluginConfig}
+ */
+export function walletWithoutSigner(config: WalletPluginConfig) {
+    return createPlugin<ClientWithWallet>(config, []);
+}