@mysten-incubation/dev-wallet 0.0.1 → 0.3.0

package/src/adapters/fork-relay.ts

@@ -0,0 +1,321 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Browser-side relay for sui-fork admin RPCs. A compatible devstack
+// wallet endpoint can proxy a curated subset of the fork-control surface
+// (status read, advance-clock, advance-checkpoint, impersonation slot
+// list) over HTTP so the fork panel does not have to ship a gRPC
+// client into the browser bundle.
+
+export const FORK_RELAY_HTTP_PATH = {
+	STATUS: '/api/v1/devstack/fork/status',
+	ADVANCE_CLOCK: '/api/v1/devstack/fork/advance-clock',
+	ADVANCE_CHECKPOINT: '/api/v1/devstack/fork/advance-checkpoint',
+	IMPERSONATIONS: '/api/v1/devstack/fork/impersonations',
+} as const;
+
+/** Snapshot of the fork's current head state.
+ *
+ * Mirrors the body of `ForkControl.getStatus()` minus the unused
+ * heartbeat fields. `clockMs` is a Unix-ms timestamp (the value
+ * `clock::timestamp_ms()` returns on chain); `checkpoint` is the
+ * latest sealed sequence number.
+ */
+export interface ForkStatus {
+	readonly checkpoint: bigint;
+	readonly clockMs: bigint;
+	readonly autoTickMs?: number;
+	/** Best-effort label of the upstream the fork is pointed at, e.g.
+	 *  `'mainnet'` or `'testnet'`. Sourced from the devstack manifest. */
+	readonly upstream?: string;
+}
+
+/** A single impersonation slot resolved by devstack — typically every
+ *  address that was passed to `Sui({fork:{impersonate:[…]}})`. */
+export interface ForkImpersonationSlot {
+	readonly address: string;
+	readonly label?: string;
+	/** Whether the wallet currently routes user-driven tx signing through
+	 *  the `executeImpersonated` path for this address. The dev-wallet
+	 *  server stores the toggle so it persists across page reloads. */
+	readonly active: boolean;
+}
+
+export interface ForkRelayOptions {
+	/** Wallet-app origin (e.g. `http://localhost:9420`). Same value
+	 *  `DevstackSignerAdapter` consumes — read from the manifest entry's
+	 *  `app.wallet.url`. */
+	readonly serverOrigin: string;
+	/** Bearer token. Same parsing rules as `DevstackSignerAdapter`. */
+	readonly token?: string | null;
+}
+
+class ForkRelayHttpError extends Error {
+	constructor(
+		public readonly status: number,
+		message: string,
+	) {
+		super(message);
+		this.name = 'ForkRelayHttpError';
+	}
+}
+
+/** Tagged result so callers can render an inline error without throwing. */
+export type ForkRelayResult<T> =
+	| { readonly ok: true; readonly value: T }
+	| { readonly ok: false; readonly error: string; readonly status?: number };
+
+function isForkStatusBody(
+	value: unknown,
+): value is { checkpoint: string; clockMs: string; autoTickMs?: number; upstream?: string } {
+	if (value === null || typeof value !== 'object') return false;
+	const v = value as Record<string, unknown>;
+	return typeof v.checkpoint === 'string' && typeof v.clockMs === 'string';
+}
+
+function isImpersonationsBody(
+	value: unknown,
+): value is { slots: { address: string; label?: string; active: boolean }[] } {
+	if (value === null || typeof value !== 'object') return false;
+	const slots = (value as { slots?: unknown }).slots;
+	return Array.isArray(slots);
+}
+
+/**
+ * Thin HTTP client for the fork admin relay. Stateless — each call
+ * issues a fresh `fetch`. The UI layer (`dev-wallet-fork-panel`)
+ * polls `getStatus` on a low cadence and only refreshes after action
+ * verbs land, so the lack of caching here is intentional.
+ *
+ * @example
+ * const relay = new ForkRelay({ serverOrigin, token });
+ * const status = await relay.getStatus();
+ * if (status.ok) console.log(`clock=${status.value.clockMs}ms`);
+ */
+export class ForkRelay {
+	#serverOrigin: string;
+	#authToken: string | null;
+
+	constructor(options: ForkRelayOptions) {
+		try {
+			new URL(options.serverOrigin);
+		} catch {
+			throw new Error(`ForkRelay: invalid serverOrigin "${options.serverOrigin}"`);
+		}
+		this.#serverOrigin = options.serverOrigin;
+		this.#authToken = options.token ?? null;
+	}
+
+	get serverOrigin(): string {
+		return this.#serverOrigin;
+	}
+
+	async getStatus(): Promise<ForkRelayResult<ForkStatus>> {
+		return this.#request('GET', FORK_RELAY_HTTP_PATH.STATUS, undefined, (body) => {
+			if (!isForkStatusBody(body)) {
+				throw new Error('Malformed fork status response');
+			}
+			return {
+				checkpoint: BigInt(body.checkpoint),
+				clockMs: BigInt(body.clockMs),
+				autoTickMs: body.autoTickMs,
+				upstream: body.upstream,
+			};
+		});
+	}
+
+	async advanceClock(durationMs: number): Promise<ForkRelayResult<ForkStatus>> {
+		if (!Number.isFinite(durationMs) || durationMs <= 0 || !Number.isInteger(durationMs)) {
+			return {
+				ok: false,
+				error: `advanceClock: durationMs must be a positive integer (got ${durationMs})`,
+			};
+		}
+		return this.#request('POST', FORK_RELAY_HTTP_PATH.ADVANCE_CLOCK, { durationMs }, (body) => {
+			if (!isForkStatusBody(body)) {
+				throw new Error('Malformed advance-clock response');
+			}
+			return {
+				checkpoint: BigInt(body.checkpoint),
+				clockMs: BigInt(body.clockMs),
+				autoTickMs: body.autoTickMs,
+				upstream: body.upstream,
+			};
+		});
+	}
+
+	async advanceCheckpoint(count: number): Promise<ForkRelayResult<ForkStatus>> {
+		if (!Number.isFinite(count) || count <= 0 || !Number.isInteger(count)) {
+			return {
+				ok: false,
+				error: `advanceCheckpoint: count must be a positive integer (got ${count})`,
+			};
+		}
+		return this.#request('POST', FORK_RELAY_HTTP_PATH.ADVANCE_CHECKPOINT, { count }, (body) => {
+			if (!isForkStatusBody(body)) {
+				throw new Error('Malformed advance-checkpoint response');
+			}
+			return {
+				checkpoint: BigInt(body.checkpoint),
+				clockMs: BigInt(body.clockMs),
+				autoTickMs: body.autoTickMs,
+				upstream: body.upstream,
+			};
+		});
+	}
+
+	async listImpersonations(): Promise<ForkRelayResult<ForkImpersonationSlot[]>> {
+		return this.#request('GET', FORK_RELAY_HTTP_PATH.IMPERSONATIONS, undefined, (body) => {
+			if (!isImpersonationsBody(body)) {
+				throw new Error('Malformed impersonations response');
+			}
+			return body.slots.map((s) => ({
+				address: s.address,
+				label: s.label,
+				active: s.active,
+			}));
+		});
+	}
+
+	/** Toggle the impersonation slot identified by `address`. The server
+	 *  is the source of truth — the response carries the resulting slot
+	 *  list so the panel re-renders consistently. */
+	async setImpersonation(
+		address: string,
+		active: boolean,
+	): Promise<ForkRelayResult<ForkImpersonationSlot[]>> {
+		return this.#request(
+			'POST',
+			FORK_RELAY_HTTP_PATH.IMPERSONATIONS,
+			{ address, active },
+			(body) => {
+				if (!isImpersonationsBody(body)) {
+					throw new Error('Malformed impersonations response');
+				}
+				return body.slots.map((s) => ({
+					address: s.address,
+					label: s.label,
+					active: s.active,
+				}));
+			},
+		);
+	}
+
+	async #request<T>(
+		method: 'GET' | 'POST',
+		path: string,
+		body: unknown,
+		parse: (raw: unknown) => T,
+	): Promise<ForkRelayResult<T>> {
+		const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+		if (this.#authToken !== null) {
+			headers['Authorization'] = `Bearer ${this.#authToken}`;
+		}
+		const init: RequestInit = { method, headers };
+		if (method === 'POST' && body !== undefined) {
+			init.body = JSON.stringify(body);
+		}
+		let res: Response;
+		try {
+			res = await fetch(`${this.#serverOrigin}${path}`, init);
+		} catch (cause) {
+			return {
+				ok: false,
+				error: `Network error: ${cause instanceof Error ? cause.message : String(cause)}`,
+			};
+		}
+		if (!res.ok) {
+			const text = await res.text().catch(() => res.statusText);
+			return { ok: false, error: text || res.statusText, status: res.status };
+		}
+		let parsedBody: unknown;
+		try {
+			parsedBody = await res.json();
+		} catch (cause) {
+			return {
+				ok: false,
+				error: `Invalid JSON response: ${cause instanceof Error ? cause.message : String(cause)}`,
+				status: res.status,
+			};
+		}
+		try {
+			return { ok: true, value: parse(parsedBody) };
+		} catch (cause) {
+			return {
+				ok: false,
+				error: cause instanceof Error ? cause.message : String(cause),
+				status: res.status,
+			};
+		}
+	}
+}
+
+export { ForkRelayHttpError };
+
+/** Narrow input mirroring `DevstackAdapterManifest` — enough to
+ *  discover the wallet endpoint + fork-mode flag without pulling in
+ *  the full devstack `Manifest` type (no reverse dependency edge,
+ *  same reasoning as `devstack-adapter.ts`). */
+export interface ForkRelayManifest {
+	readonly app?: {
+		readonly wallet?: {
+			readonly url: string;
+			readonly pairUrl?: string;
+		};
+	};
+	readonly meta?: {
+		/** Devstack's `meta.runtime` is `'bundled' | 'forked'`. Only
+		 *  `'forked'` triggers fork-controls construction. */
+		readonly runtime?: string;
+		/** Optional upstream label (`'mainnet'`, `'testnet'`, …) used
+		 *  by the panel banner. */
+		readonly upstream?: string;
+	};
+}
+
+/** Parse the bearer token off the manifest's `pairUrl`. Duplicates the
+ *  logic in `devstack-adapter.ts` rather than importing it because the
+ *  fork-relay module must remain dependency-free from the adapter
+ *  layer (it's also consumed by codegen-emitted glue that doesn't pull
+ *  in the signer adapter bundle). */
+function tokenFromPairUrl(pairedUrl: string | undefined): string | null {
+	if (pairedUrl === undefined) return null;
+	try {
+		const url = new URL(pairedUrl);
+		if (url.hash.length > 1) {
+			const params = new URLSearchParams(url.hash.slice(1));
+			const fromHash = params.get('token');
+			if (fromHash !== null && fromHash !== '<redacted>') return fromHash;
+		}
+		const fromQuery = url.searchParams.get('token');
+		if (fromQuery !== null && fromQuery !== '<redacted>') return fromQuery;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Build a configured {@link ForkRelay} from a devstack manifest, or
+ * `null` when fork-mode isn't active (bundled stack, no wallet entry,
+ * or the manifest hasn't loaded yet).
+ *
+ * Codegen-emitted browser glue calls this and forwards the result to
+ * `<dev-wallet-panel forkRelay={…}>`.
+ */
+export function createForkRelayFromManifest(manifest: ForkRelayManifest): ForkRelay | null {
+	if (manifest.meta?.runtime !== 'forked') return null;
+	const wallet = manifest.app?.wallet;
+	if (wallet === undefined) return null;
+	try {
+		return new ForkRelay({
+			serverOrigin: wallet.url,
+			token: tokenFromPairUrl(wallet.pairUrl),
+		});
+	} catch {
+		// `new URL(…)` failure surfaces as a thrown Error — swallow it
+		// here rather than propagating, the calling app shouldn't
+		// blow up just because the manifest's wallet URL is malformed.
+		return null;
+	}
+}

package/src/app/index.html

@@ -4,6 +4,12 @@
 		<meta charset="UTF-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<title>Dev Wallet</title>
+		<link rel="preconnect" href="https://fonts.googleapis.com" />
+		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+		<link
+			href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap"
+			rel="stylesheet"
+		/>
 		<style>
 			* {
 				margin: 0;
@@ -12,29 +18,22 @@
 			}
 			body {
 				font-family:
+					'Geist',
 					ui-sans-serif,
 					system-ui,
 					-apple-system,
 					BlinkMacSystemFont,
 					'Segoe UI',
-					Roboto,
-					'Helvetica Neue',
-					Arial,
 					sans-serif;
-				background: oklch(0.175 0.028 283);
-				color: oklch(0.91 0 0);
+				background: #05080f;
+				color: #e6eefb;
 				min-height: 100vh;
 			}
 			#app {
-				display: flex;
-				flex-direction: column;
-				align-items: center;
-				justify-content: center;
 				min-height: 100vh;
-				padding: 20px;
 			}
 			.loading {
-				color: oklch(0.62 0.04 280);
+				color: #94a6c2;
 				font-size: 14px;
 			}
 		</style>

package/src/react/useDevWallet.ts

@@ -4,6 +4,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 
 import { mountDevWallet } from '../ui/mount.js';
+import type { DevWalletDockStyle } from '../ui/dev-wallet-panel.js';
 import { DevWallet, type DevWalletConfig } from '../wallet/dev-wallet.js';
 
 export interface UseDevWalletOptions extends DevWalletConfig {
@@ -13,6 +14,8 @@ export interface UseDevWalletOptions extends DevWalletConfig {
 	createInitialAccount?: boolean;
 	/** Whether to mount the floating wallet drawer UI. Defaults to true. */
 	mountUI?: boolean;
+	/** Floating dock presentation when `mountUI` is true. Defaults to `corner-pill`. */
+	dockStyle?: DevWalletDockStyle;
 	/** Container element for the UI drawer. Defaults to document.body. */
 	container?: HTMLElement;
 }
@@ -51,6 +54,7 @@ export function useDevWallet(options: UseDevWalletOptions): UseDevWalletResult {
 			autoInitialize = true,
 			createInitialAccount = true,
 			mountUI = true,
+			dockStyle,
 			container,
 			...walletConfig
 		} = optionsRef.current;
@@ -90,7 +94,7 @@ export function useDevWallet(options: UseDevWalletOptions): UseDevWalletResult {
 			unregister = devWallet.register();
 
 			if (mountUI && typeof document !== 'undefined') {
-				unmountUI = mountDevWallet(devWallet, { container });
+				unmountUI = mountDevWallet(devWallet, { container, dockStyle });
 			}
 
 			if (!cancelled) {

package/src/ui/dev-wallet-account-selector.ts

@@ -32,17 +32,22 @@ export class DevWalletAccountSelector extends LitElement {
 			.active-account {
 				display: flex;
 				align-items: center;
-				gap: 8px;
+				gap: 10px;
 				width: 100%;
-				padding: 8px 10px;
-				border-radius: var(--dev-wallet-radius-md);
-				background: var(--dev-wallet-secondary);
+				min-height: 54px;
+				padding: 10px 12px;
+				border-radius: var(--dev-wallet-radius-lg);
+				border: 1px solid var(--dev-wallet-border);
+				background: var(--dev-wallet-surface);
 				cursor: pointer;
-				transition: background 0.15s;
+				transition:
+					background 120ms,
+					border-color 120ms;
 			}
 
 			.active-account:hover {
-				background: var(--dev-wallet-border);
+				background: var(--dev-wallet-bg-hover);
+				border-color: var(--dev-wallet-border-strong);
 			}
 
 			.avatar {
@@ -73,26 +78,36 @@ export class DevWalletAccountSelector extends LitElement {
 				text-overflow: ellipsis;
 			}
 
+			.account-label-row {
+				display: flex;
+				align-items: center;
+				gap: 6px;
+				min-width: 0;
+			}
+
 			.account-address {
 				font-size: 11px;
 				font-family: var(--dev-wallet-font-mono);
-				color: var(--dev-wallet-muted-foreground);
+				color: var(--dev-wallet-text-3);
 			}
 
 			.copy-btn {
-				width: 22px;
-				height: 22px;
+				width: 36px;
+				height: 54px;
 				display: flex;
 				align-items: center;
 				justify-content: center;
-				border-radius: var(--dev-wallet-radius-xs);
+				border-radius: var(--dev-wallet-radius);
+				border: 1px solid var(--dev-wallet-border);
+				background: transparent;
 				color: var(--dev-wallet-muted-foreground);
 				flex-shrink: 0;
 				font-size: 12px;
 			}
 
 			.copy-btn:hover {
-				background: var(--dev-wallet-border);
+				background: var(--dev-wallet-bg-hover);
+				border-color: var(--dev-wallet-border-strong);
 				color: var(--dev-wallet-foreground);
 			}
 
@@ -108,7 +123,8 @@ export class DevWalletAccountSelector extends LitElement {
 			}
 
 			.dropdown-item[aria-selected='true'] {
-				background: color-mix(in oklab, var(--dev-wallet-primary) 10%, transparent);
+				background: var(--dev-wallet-accent-fade);
+				border-color: var(--dev-wallet-border-strong);
 			}
 
 			.dropdown-item .avatar {
@@ -136,11 +152,16 @@ export class DevWalletAccountSelector extends LitElement {
 			}
 
 			.adapter-badge {
+				height: 16px;
+				display: inline-flex;
+				align-items: center;
+				padding: 0 5px;
+				border-radius: 999px;
+				border: 1px solid var(--dev-wallet-border);
+				background: var(--dev-wallet-bg-3);
+				color: var(--dev-wallet-text-3);
+				font-family: var(--dev-wallet-font-mono);
 				font-size: 9px;
-				padding: 1px 4px;
-				border-radius: var(--dev-wallet-radius-2xs);
-				background: var(--dev-wallet-secondary);
-				color: var(--dev-wallet-muted-foreground);
 				white-space: nowrap;
 			}
 
@@ -188,6 +209,7 @@ export class DevWalletAccountSelector extends LitElement {
 
 		const label = this.#getLabel(active);
 		const initial = (label[0] ?? '?').toUpperCase();
+		const activeAdapterName = this.#getAdapterName(active.address);
 
 		return html`
 			<div class="selector-row">
@@ -207,7 +229,12 @@ export class DevWalletAccountSelector extends LitElement {
 					>
 						<span class="avatar">${initial}</span>
 						<div class="account-info">
-							<div class="account-label">${label}</div>
+							<div class="account-label-row">
+								<div class="account-label">${label}</div>
+								${activeAdapterName
+									? html`<span class="adapter-badge">${activeAdapterName}</span>`
+									: nothing}
+							</div>
 							<div class="account-address">${formatAddress(active.address)}</div>
 						</div>
 						<svg