@mysten-incubation/dev-wallet 0.0.0

package/src/client/dev-wallet-client.ts

@@ -0,0 +1,280 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromBase64, toBase64 } from '@mysten/sui/utils';
+import { mitt, type Emitter } from '@mysten/utils';
+import type {
+	StandardConnectFeature,
+	StandardConnectMethod,
+	StandardDisconnectFeature,
+	StandardDisconnectMethod,
+	StandardEventsFeature,
+	StandardEventsOnMethod,
+	SuiFeatures,
+	SuiSignAndExecuteTransactionMethod,
+	SuiSignPersonalMessageMethod,
+	SuiSignTransactionMethod,
+	Wallet,
+	WalletIcon,
+} from '@mysten/wallet-standard';
+import { getWallets, ReadonlyWalletAccount, SUI_CHAINS } from '@mysten/wallet-standard';
+import { DappPostMessageChannel, decodeJwtSession } from '@mysten/window-wallet-core';
+
+import { DEFAULT_WALLET_ICON, type WalletEventsMap } from '../wallet/constants.js';
+
+const DEFAULT_WALLET_NAME = 'Dev Wallet (Web)';
+const DEFAULT_ORIGIN = 'http://localhost:5174';
+
+/**
+ * Creates a wallet initializer that can be passed to `createDAppKit({ walletInitializers: [...] })`.
+ *
+ * This registers a {@link DevWalletClient} that communicates with a standalone
+ * dev wallet server via PostMessage popups.
+ *
+ * @example
+ * ```ts
+ * import { createDAppKit } from '@mysten/dapp-kit-react';
+ * import { devWalletClientInitializer } from '@mysten-incubation/dev-wallet/client';
+ *
+ * const dAppKit = createDAppKit({
+ *   networks: ['devnet'],
+ *   walletInitializers: [
+ *     devWalletClientInitializer({ origin: 'http://localhost:5174' }),
+ *   ],
+ * });
+ * ```
+ */
+export function devWalletClientInitializer(options?: DevWalletClientOptions): {
+	id: string;
+	initialize(): { unregister: () => void };
+} {
+	return {
+		id: 'dev-wallet-client-initializer',
+		initialize() {
+			const unregister = DevWalletClient.register(options);
+			return { unregister };
+		},
+	};
+}
+
+const WALLET_FEATURES = [
+	'sui:signTransaction',
+	'sui:signAndExecuteTransaction',
+	'sui:signPersonalMessage',
+] as const;
+
+/**
+ * Options for creating a DevWalletClient.
+ */
+export interface DevWalletClientOptions {
+	/** Display name for the wallet. Defaults to 'Dev Wallet (Web)'. */
+	name?: string;
+	/** Data URI icon for the wallet. */
+	icon?: WalletIcon;
+	/** Origin of the dev wallet web app. Defaults to 'http://localhost:5174'. */
+	origin?: string;
+}
+
+/**
+ * Wallet-standard wallet that communicates with a standalone DevWallet
+ * web app via PostMessage popups (started via `npx @mysten-incubation/dev-wallet serve`).
+ */
+export class DevWalletClient implements Wallet {
+	readonly #name: string;
+	readonly #icon: WalletIcon;
+	readonly #origin: string;
+	readonly #sessionKey: string;
+	#accounts: ReadonlyWalletAccount[] = [];
+	#events: Emitter<WalletEventsMap>;
+
+	constructor(options?: DevWalletClientOptions) {
+		this.#name = options?.name ?? DEFAULT_WALLET_NAME;
+		this.#icon = options?.icon ?? DEFAULT_WALLET_ICON;
+		this.#origin = options?.origin ?? DEFAULT_ORIGIN;
+		this.#sessionKey = `dev-wallet:session:${this.#origin}`;
+		this.#events = mitt();
+		this.#tryRestoreSession();
+	}
+
+	static register(options?: DevWalletClientOptions): () => void {
+		const wallet = new DevWalletClient(options);
+		const wallets = getWallets();
+		return wallets.register(wallet);
+	}
+
+	get version() {
+		return '1.0.0' as const;
+	}
+
+	get name() {
+		return this.#name;
+	}
+
+	get icon() {
+		return this.#icon;
+	}
+
+	get chains() {
+		return SUI_CHAINS;
+	}
+
+	get accounts(): readonly ReadonlyWalletAccount[] {
+		return this.#accounts;
+	}
+
+	get features(): StandardConnectFeature &
+		StandardEventsFeature &
+		StandardDisconnectFeature &
+		SuiFeatures {
+		return {
+			'standard:connect': {
+				version: '1.0.0',
+				connect: this.#connect,
+			},
+			'standard:events': {
+				version: '1.0.0',
+				on: this.#on,
+			},
+			'standard:disconnect': {
+				version: '1.0.0',
+				disconnect: this.#disconnect,
+			},
+			'sui:signPersonalMessage': {
+				version: '1.1.0',
+				signPersonalMessage: this.#signPersonalMessage,
+			},
+			'sui:signTransaction': {
+				version: '2.0.0',
+				signTransaction: this.#signTransaction,
+			},
+			'sui:signAndExecuteTransaction': {
+				version: '2.0.0',
+				signAndExecuteTransaction: this.#signAndExecuteTransaction,
+			},
+		};
+	}
+
+	#on: StandardEventsOnMethod = (event, listener) => {
+		this.#events.on(event, listener);
+		return () => this.#events.off(event, listener);
+	};
+
+	#connect: StandardConnectMethod = async () => {
+		const channel = this.#createChannel();
+		const response = await channel.send({ type: 'connect' });
+
+		this.#setSession(response.session);
+		this.#setAccountsFromSession(response.session);
+
+		return { accounts: this.accounts };
+	};
+
+	#disconnect: StandardDisconnectMethod = async () => {
+		this.#clearSession();
+		this.#accounts = [];
+		this.#events.emit('change', { accounts: this.#accounts });
+	};
+
+	#signPersonalMessage: SuiSignPersonalMessageMethod = async (input) => {
+		const channel = this.#createChannel();
+		const response = await channel.send({
+			type: 'sign-personal-message',
+			message: toBase64(input.message),
+			address: input.account.address,
+			chain: input.chain ?? input.account.chains[0] ?? 'sui:unknown',
+			session: this.#getSession(),
+		});
+
+		return { bytes: response.bytes, signature: response.signature };
+	};
+
+	#signTransaction: SuiSignTransactionMethod = async (input) => {
+		const txJson = await input.transaction.toJSON();
+		const channel = this.#createChannel();
+		const response = await channel.send({
+			type: 'sign-transaction',
+			transaction: txJson,
+			address: input.account.address,
+			chain: input.chain,
+			session: this.#getSession(),
+		});
+
+		return { bytes: response.bytes, signature: response.signature };
+	};
+
+	#signAndExecuteTransaction: SuiSignAndExecuteTransactionMethod = async (input) => {
+		const txJson = await input.transaction.toJSON();
+		const channel = this.#createChannel();
+		const response = await channel.send({
+			type: 'sign-and-execute-transaction',
+			transaction: txJson,
+			address: input.account.address,
+			chain: input.chain,
+			session: this.#getSession(),
+		});
+
+		return {
+			bytes: response.bytes,
+			signature: response.signature,
+			digest: response.digest,
+			effects: response.effects,
+		};
+	};
+
+	#createChannel(): DappPostMessageChannel {
+		return new DappPostMessageChannel({
+			appName: this.#name,
+			hostOrigin: this.#origin,
+		});
+	}
+
+	#getSession(): string {
+		if (typeof localStorage === 'undefined') {
+			throw new Error('No active session. Call connect() first.');
+		}
+		const session = localStorage.getItem(this.#sessionKey);
+		if (!session) {
+			throw new Error('No active session. Call connect() first.');
+		}
+		return session;
+	}
+
+	#setSession(session: string): void {
+		if (typeof localStorage !== 'undefined') {
+			localStorage.setItem(this.#sessionKey, session);
+		}
+	}
+
+	#clearSession(): void {
+		if (typeof localStorage !== 'undefined') {
+			localStorage.removeItem(this.#sessionKey);
+		}
+	}
+
+	#setAccountsFromSession(session: string): void {
+		const decoded = decodeJwtSession(session);
+		this.#accounts = decoded.payload.accounts.map(
+			(account: { address: string; publicKey: string; label?: string }) =>
+				new ReadonlyWalletAccount({
+					address: account.address,
+					publicKey: account.publicKey ? fromBase64(account.publicKey) : new Uint8Array(0),
+					chains: [...SUI_CHAINS],
+					features: [...WALLET_FEATURES],
+					label: account.label,
+				}),
+		);
+		this.#events.emit('change', { accounts: this.#accounts });
+	}
+
+	#tryRestoreSession(): void {
+		if (typeof localStorage === 'undefined') return;
+		const session = localStorage.getItem(this.#sessionKey);
+		if (!session) return;
+
+		try {
+			this.#setAccountsFromSession(session);
+		} catch {
+			this.#clearSession();
+		}
+	}
+}

package/src/client/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export { DevWalletClient, devWalletClientInitializer } from './dev-wallet-client.js';
+export type { DevWalletClientOptions } from './dev-wallet-client.js';
+export { parseWalletRequest } from './request-handler.js';
+export type { PendingWalletRequest, HandleRequestOptions } from './request-handler.js';

package/src/client/request-handler.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ClientWithCoreApi } from '@mysten/sui/client';
+import { fromBase64, toBase64 } from '@mysten/sui/utils';
+import { createJwtSession, WalletPostMessageChannel } from '@mysten/window-wallet-core';
+
+import type { SignerAdapter } from '../types.js';
+import { getNetworkFromChain } from '../wallet/constants.js';
+import { executeSigning } from '../wallet/signing.js';
+
+/**
+ * A parsed wallet request with methods to approve or reject it.
+ *
+ * This is different from `PendingSigningRequest` (in dev-wallet.ts) — this interface
+ * includes `approve()`/`reject()` methods and is specific to the standalone popup flow.
+ */
+export interface PendingWalletRequest {
+	type: 'connect' | 'sign-transaction' | 'sign-and-execute-transaction' | 'sign-personal-message';
+	appName: string;
+	appUrl: string;
+	address?: string;
+	chain?: string;
+	data?: string | Uint8Array;
+	/**
+	 * Approve the request.
+	 * For connect: creates a session with the selected accounts (or all if none specified).
+	 * For signing: signs with the adapter.
+	 */
+	approve(options?: { selectedAddresses?: string[] }): Promise<void>;
+	/** Reject the request with an optional reason. */
+	reject(reason?: string): void;
+}
+
+export interface HandleRequestOptions {
+	/** The signer adapters providing accounts and signing capability. */
+	adapters: SignerAdapter[];
+	/** JWT secret key for session creation. */
+	jwtSecretKey: CryptoKey | Uint8Array;
+	/** Resolve a client for a given network name (needed for signAndExecute). */
+	getClient?: (network: string) => ClientWithCoreApi | undefined;
+	/** URL hash containing the encoded request. Defaults to window.location.hash. */
+	hash?: string;
+}
+
+export function parseWalletRequest(options: HandleRequestOptions): PendingWalletRequest {
+	if (!options.hash && typeof window === 'undefined') {
+		throw new Error(
+			'parseWalletRequest requires either options.hash or a browser environment with window.location',
+		);
+	}
+	const hash = options.hash ?? window.location.hash.slice(1);
+	const channel = WalletPostMessageChannel.fromUrlHash(hash);
+	const requestData = channel.getRequestData();
+	const payload = requestData.payload;
+
+	if (payload.type === 'connect') {
+		return {
+			type: 'connect',
+			appName: requestData.appName,
+			appUrl: requestData.appUrl,
+			async approve(approveOptions?: { selectedAddresses?: string[] }) {
+				const allAccounts = options.adapters.flatMap((adapter) =>
+					adapter.getAccounts().map((a) => ({
+						address: a.address,
+						publicKey: toBase64(a.signer.getPublicKey().toSuiBytes()),
+						label: a.label,
+					})),
+				);
+				const selected = approveOptions?.selectedAddresses;
+				const accounts = selected
+					? allAccounts.filter((a) => selected.includes(a.address))
+					: allAccounts;
+
+				const session = await createJwtSession(
+					{ accounts },
+					{
+						secretKey: options.jwtSecretKey,
+						expirationTime: '7d',
+						issuer: 'dev-wallet',
+						audience: new URL(requestData.appUrl).origin,
+					},
+				);
+
+				channel.sendMessage({
+					type: 'resolve',
+					data: { type: 'connect', session },
+				});
+			},
+			reject(reason?: string) {
+				channel.sendMessage({ type: 'reject', reason });
+			},
+		};
+	}
+
+	const messageData =
+		payload.type === 'sign-personal-message' ? fromBase64(payload.message) : payload.transaction;
+
+	return {
+		type: payload.type,
+		appName: requestData.appName,
+		appUrl: requestData.appUrl,
+		address: payload.address,
+		chain: payload.chain,
+		data: messageData,
+		async approve() {
+			// Verify JWT session before signing — ensures the dApp was previously
+			// authorized for this account via a connect flow
+			try {
+				await channel.verifyJwtSession(options.jwtSecretKey);
+			} catch (error) {
+				channel.sendMessage({
+					type: 'reject',
+					reason: `Session verification failed: ${error instanceof Error ? error.message : String(error)}`,
+				});
+				return;
+			}
+
+			let account;
+			for (const adapter of options.adapters) {
+				account = adapter.getAccount(payload.address);
+				if (account) break;
+			}
+			if (!account) {
+				channel.sendMessage({
+					type: 'reject',
+					reason: `Account ${payload.address} not found`,
+				});
+				return;
+			}
+
+			try {
+				const network = payload.chain ? getNetworkFromChain(payload.chain) : undefined;
+				const client = network ? options.getClient?.(network) : undefined;
+				const result = await executeSigning({
+					type: payload.type,
+					signer: account.signer,
+					data: messageData,
+					client,
+				});
+				// effects must be a string in the PostMessage protocol
+				const data =
+					result.type === 'sign-and-execute-transaction'
+						? { ...result, effects: result.effects ?? '' }
+						: result;
+				channel.sendMessage({
+					type: 'resolve',
+					data,
+				});
+			} catch (error) {
+				channel.sendMessage({
+					type: 'reject',
+					reason: error instanceof Error ? error.message : String(error),
+				});
+			}
+		},
+		reject(reason?: string) {
+			channel.sendMessage({ type: 'reject', reason });
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export { DevWallet, DEFAULT_NETWORK_URLS } from './wallet/dev-wallet.js';
+export { devWalletInitializer } from './wallet/initializer.js';
+export type { DevWalletInitializerConfig } from './wallet/initializer.js';
+export type { SigningResult } from './wallet/signing.js';
+export type {
+	AutoApprovePolicy,
+	DevWalletConfig,
+	PendingConnectRequest,
+	PendingSigningRequest,
+} from './wallet/dev-wallet.js';
+export type {
+	SignerAdapter,
+	ManagedAccount,
+	CreateAccountOptions,
+	ImportAccountOptions,
+} from './types.js';

package/src/react/components.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+if (typeof customElements === 'undefined') {
+	throw new Error(
+		'@mysten-incubation/dev-wallet/react components require a browser environment. ' +
+			'Use dynamic imports with ssr:false in Next.js.',
+	);
+}
+
+import { createComponent, type EventName } from '@lit/react';
+import * as React from 'react';
+
+import { DevWalletAccounts as DevWalletAccountsElement } from '../ui/dev-wallet-accounts.js';
+import { DevWalletBalances as DevWalletBalancesElement } from '../ui/dev-wallet-balances.js';
+import { DevWalletNewAccount as DevWalletNewAccountElement } from '../ui/dev-wallet-new-account.js';
+import { DevWalletPanel as DevWalletPanelElement } from '../ui/dev-wallet-panel.js';
+import { DevWalletSigning as DevWalletSigningElement } from '../ui/dev-wallet-signing.js';
+
+export const DevWalletPanel = createComponent({
+	react: React,
+	tagName: 'dev-wallet-panel',
+	elementClass: DevWalletPanelElement,
+});
+
+export const DevWalletAccounts = createComponent({
+	react: React,
+	tagName: 'dev-wallet-accounts',
+	elementClass: DevWalletAccountsElement,
+	events: {
+		onAccountSelected: 'account-selected' as EventName<
+			CustomEvent<{ account: import('@mysten/wallet-standard').ReadonlyWalletAccount }>
+		>,
+		onAccountRenamed: 'account-renamed' as EventName<
+			CustomEvent<{ address: string; label: string }>
+		>,
+	},
+});
+
+export const DevWalletBalances = createComponent({
+	react: React,
+	tagName: 'dev-wallet-balances',
+	elementClass: DevWalletBalancesElement,
+});
+
+export const DevWalletNewAccount = createComponent({
+	react: React,
+	tagName: 'dev-wallet-new-account',
+	elementClass: DevWalletNewAccountElement,
+	events: {
+		onClose: 'close' as EventName<CustomEvent>,
+		onAccountCreated: 'account-created' as EventName<CustomEvent>,
+	},
+});
+
+export const DevWalletSigning = createComponent({
+	react: React,
+	tagName: 'dev-wallet-signing',
+	elementClass: DevWalletSigningElement,
+	events: {
+		onApprove: 'approve' as EventName<CustomEvent>,
+		onReject: 'reject' as EventName<CustomEvent>,
+	},
+});

package/src/react/context.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { createContext, createElement, useContext } from 'react';
+import type { ReactNode } from 'react';
+
+import type { DevWallet } from '../wallet/dev-wallet.js';
+
+export const DevWalletContext = createContext<DevWallet | null>(null);
+
+export interface DevWalletProviderProps {
+	wallet: DevWallet;
+	children?: ReactNode;
+}
+
+export function DevWalletProvider({ wallet, children }: DevWalletProviderProps) {
+	return createElement(DevWalletContext.Provider, { value: wallet }, children);
+}
+
+/**
+ * @param wallet - If provided, context is bypassed.
+ * @throws If no wallet is provided and no DevWalletProvider is in the tree.
+ */
+export function useDevWalletInstance(wallet?: DevWallet): DevWallet {
+	const contextValue = useContext(DevWalletContext);
+
+	if (wallet) {
+		return wallet;
+	}
+
+	if (!contextValue) {
+		throw new Error(
+			'Could not find DevWalletContext. Ensure that you have set up the DevWalletProvider.',
+		);
+	}
+
+	return contextValue;
+}

package/src/react/index.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export { useDevWallet } from './useDevWallet.js';
+export type { UseDevWalletOptions, UseDevWalletResult } from './useDevWallet.js';
+
+export { DevWalletContext, DevWalletProvider, useDevWalletInstance } from './context.js';
+export type { DevWalletProviderProps } from './context.js';
+
+export {
+	DevWalletAccounts,
+	DevWalletBalances,
+	DevWalletNewAccount,
+	DevWalletPanel,
+	DevWalletSigning,
+} from './components.js';

package/src/react/useDevWallet.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { mountDevWallet } from '../ui/mount.js';
+import { DevWallet, type DevWalletConfig } from '../wallet/dev-wallet.js';
+
+export interface UseDevWalletOptions extends DevWalletConfig {
+	/** Whether to call adapter.initialize() automatically. Defaults to true. */
+	autoInitialize?: boolean;
+	/** Whether to create an initial account after initialization (if adapter supports it). Defaults to true. */
+	createInitialAccount?: boolean;
+	/** Whether to mount the floating wallet drawer UI. Defaults to true. */
+	mountUI?: boolean;
+	/** Container element for the UI drawer. Defaults to document.body. */
+	container?: HTMLElement;
+}
+
+export interface UseDevWalletResult {
+	wallet: DevWallet | null;
+	/** Initialization error, if any (e.g. IndexedDB quota exceeded, adapter failure). */
+	error: Error | null;
+	/** True while the wallet is being initialized. */
+	loading: boolean;
+}
+
+/**
+ * React hook that initializes a DevWallet, registers it with the wallet-standard
+ * registry, and optionally mounts the wallet drawer UI.
+ *
+ * The adapters are captured on first render and used for the wallet's
+ * lifetime. Pass stable references (created outside the component or via useMemo).
+ *
+ * @example
+ * ```tsx
+ * const adapters = useMemo(() => [new InMemorySignerAdapter()], []);
+ *
+ * const wallet = useDevWallet({ adapters, networks: { devnet: 'https://fullnode.devnet.sui.io:443' } });
+ * ```
+ */
+export function useDevWallet(options: UseDevWalletOptions): UseDevWalletResult {
+	const [wallet, setWallet] = useState<DevWallet | null>(null);
+	const [error, setError] = useState<Error | null>(null);
+	const [loading, setLoading] = useState(true);
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+
+	useEffect(() => {
+		const {
+			autoInitialize = true,
+			createInitialAccount = true,
+			mountUI = true,
+			container,
+			...walletConfig
+		} = optionsRef.current;
+
+		let cancelled = false;
+		let unregister: (() => void) | undefined;
+		let unmountUI: (() => void) | undefined;
+
+		let devWallet: DevWallet;
+		try {
+			devWallet = new DevWallet(walletConfig);
+		} catch (err) {
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoading(false);
+			return;
+		}
+
+		async function setup() {
+			if (autoInitialize) {
+				await Promise.all(walletConfig.adapters.map((a) => a.initialize()));
+			}
+			if (cancelled) return;
+
+			if (createInitialAccount) {
+				const hasAccounts = walletConfig.adapters.some((a) => a.getAccounts().length > 0);
+				if (!hasAccounts) {
+					const creatableAdapter = walletConfig.adapters.find(
+						(a) => a.createAccount && a.getAccounts().length === 0,
+					);
+					if (creatableAdapter?.createAccount) {
+						await creatableAdapter.createAccount({ label: 'Dev Account' });
+					}
+				}
+			}
+			if (cancelled) return;
+
+			unregister = devWallet.register();
+
+			if (mountUI && typeof document !== 'undefined') {
+				unmountUI = mountDevWallet(devWallet, { container });
+			}
+
+			if (!cancelled) {
+				setWallet(devWallet);
+				setLoading(false);
+			}
+		}
+
+		setup().catch((err) => {
+			if (!cancelled) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setLoading(false);
+			}
+		});
+
+		return () => {
+			cancelled = true;
+			unmountUI?.();
+			unregister?.();
+			devWallet.destroy();
+		};
+	}, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+	return useMemo(() => ({ wallet, error, loading }), [wallet, error, loading]);
+}