@xian-tech/wallet-core 0.1.0 → 0.1.4

package/dist/controller.js

@@ -1,8 +1,9 @@
 import { Ed25519Signer, XianClient } from "@xian-tech/client";
 import { ProviderChainMismatchError, ProviderUnauthorizedError, ProviderUnsupportedMethodError } from "@xian-tech/provider";
-import { approvalKindFromMethod, buildApprovalView } from "./approvals";
-import { DEFAULT_NETWORK_PRESETS, DEFAULT_DASHBOARD_URL, DEFAULT_RPC_URL, LOCAL_NETWORK_PRESET_NAME, DEFAULT_WALLET_CAPABILITIES, LOCAL_NETWORK_PRESET_ID } from "./constants";
-import { createWalletSecret, decryptMnemonic, decryptPrivateKey, encryptMnemonic, encryptPrivateKey, isUnsafeMessageToSign } from "./crypto";
+import { approvalKindFromMethod, buildApprovalView } from "./approvals.js";
+import { DEFAULT_NETWORK_PRESETS, DEFAULT_DASHBOARD_URL, DEFAULT_RPC_URL, LOCAL_NETWORK_PRESET_NAME, DEFAULT_WALLET_CAPABILITIES, LOCAL_NETWORK_PRESET_ID, UNLOCKED_SESSION_TIMEOUT_MS } from "./constants.js";
+import { createWalletSecret, decryptMnemonic, decryptPrivateKey, derivePrivateKeyFromMnemonic, encryptMnemonic, encryptPrivateKey, isUnsafeMessageToSign } from "./crypto.js";
+const SAFE_CHAIN_ID_LOOKUP_TIMEOUT_MS = 2_000;
 function firstParamObject(params) {
     if (Array.isArray(params)) {
         return (params[0] ?? {});
@@ -35,6 +36,15 @@ function trimOptionalString(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+function normalizeTrackedAsset(asset) {
+    return {
+        contract: asset.contract.trim(),
+        name: trimOptionalString(asset.name),
+        symbol: trimOptionalString(asset.symbol),
+        icon: trimOptionalString(asset.icon),
+        decimals: asset.decimals
+    };
+}
 function createLocalNetworkPreset() {
     const preset = DEFAULT_NETWORK_PRESETS[0];
     if (preset) {
@@ -168,13 +178,55 @@ export class WalletController {
             message: String(error)
         };
     }
-    getUnlockedSigner() {
+    async restoreUnlockedSession() {
+        if (this.unlockedPrivateKey) {
+            return true;
+        }
+        const session = await this.store.loadUnlockedSession();
+        if (!session) {
+            return false;
+        }
+        if (session.expiresAt <= this.now()) {
+            await this.store.clearUnlockedSession();
+            return false;
+        }
+        this.unlockedPrivateKey = session.privateKey;
+        this.unlockedSigner = new Ed25519Signer(session.privateKey);
+        if (session.mnemonic) {
+            this.unlockedMnemonic = session.mnemonic;
+        }
+        if (session.password) {
+            this.unlockedPassword = session.password;
+        }
+        return true;
+    }
+    unlockedMnemonic = null;
+    unlockedPassword = null;
+    async persistUnlockedSession(privateKey, expiresAt = this.now() + UNLOCKED_SESSION_TIMEOUT_MS) {
+        const session = {
+            privateKey,
+            mnemonic: this.unlockedMnemonic ?? undefined,
+            password: this.unlockedPassword ?? undefined,
+            expiresAt
+        };
+        await this.store.saveUnlockedSession(session);
+    }
+    async clearUnlockedSession() {
+        this.unlockedPrivateKey = null;
+        this.unlockedSigner = null;
+        this.unlockedMnemonic = null;
+        this.unlockedPassword = null;
+        await this.store.clearUnlockedSession();
+    }
+    async getUnlockedSigner() {
+        await this.restoreUnlockedSession();
         if (!this.unlockedPrivateKey) {
             throw new ProviderUnauthorizedError("wallet is locked");
         }
         if (!this.unlockedSigner) {
             this.unlockedSigner = new Ed25519Signer(this.unlockedPrivateKey);
         }
+        await this.persistUnlockedSession(this.unlockedPrivateKey);
         return this.unlockedSigner;
     }
     currentClient(state) {
@@ -255,12 +307,30 @@ export class WalletController {
             return undefined;
         }
         try {
-            return await this.currentClient(state).getChainId();
+            return await this.withTimeout(this.currentClient(state).getChainId(), SAFE_CHAIN_ID_LOOKUP_TIMEOUT_MS);
         }
         catch {
             return undefined;
         }
     }
+    async withTimeout(promise, timeoutMs) {
+        let timeoutId;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    timeoutId = globalThis.setTimeout(() => {
+                        reject(new Error("operation timed out"));
+                    }, timeoutMs);
+                })
+            ]);
+        }
+        finally {
+            if (timeoutId !== undefined) {
+                globalThis.clearTimeout(timeoutId);
+            }
+        }
+    }
     async buildWalletInfo(state, origin) {
         if (!state) {
             return {
@@ -272,7 +342,7 @@ export class WalletController {
             };
         }
         const connected = state.connectedOrigins.includes(origin);
-        const unlocked = this.unlockedPrivateKey != null;
+        const unlocked = await this.restoreUnlockedSession();
         const preset = this.activeNetworkPreset(state);
         const resolvedChainId = await this.safeGetChainId(state);
         return {
@@ -312,6 +382,50 @@ export class WalletController {
             watchedAssets: updater(state.watchedAssets)
         });
     }
+    async fetchDetectedAssets(state) {
+        if (!state) {
+            return [];
+        }
+        const client = this.currentClient(state);
+        const trackedContracts = new Set(state.watchedAssets.map((asset) => asset.contract));
+        const detectedAssets = [];
+        const seenContracts = new Set();
+        const pageSize = 200;
+        let offset = 0;
+        while (true) {
+            const page = await client.getTokenBalances(state.publicKey, {
+                limit: pageSize,
+                offset
+            });
+            for (const item of page.items) {
+                const contract = item.contract.trim();
+                if (!contract || seenContracts.has(contract)) {
+                    continue;
+                }
+                seenContracts.add(contract);
+                detectedAssets.push({
+                    contract,
+                    name: trimOptionalString(item.name ?? undefined),
+                    symbol: trimOptionalString(item.symbol ?? undefined),
+                    icon: trimOptionalString(item.logoUrl ?? undefined),
+                    balance: item.balance,
+                    tracked: trackedContracts.has(contract)
+                });
+            }
+            const fetched = page.items.length;
+            if (fetched === 0 || offset + fetched >= page.total) {
+                break;
+            }
+            offset += fetched;
+        }
+        detectedAssets.sort((left, right) => {
+            if (left.tracked !== right.tracked) {
+                return left.tracked ? 1 : -1;
+            }
+            return left.contract.localeCompare(right.contract);
+        });
+        return detectedAssets;
+    }
     sanitizeNetworkPresetInput(input) {
         const name = input.name.trim();
         const rpcUrl = input.rpcUrl.trim();
@@ -375,8 +489,45 @@ export class WalletController {
         await this.broadcastProviderEvent("accountsChanged", [[]], origin);
         await this.broadcastProviderEvent("disconnect", [{ code: 4100, message: "wallet disconnected" }], origin);
     }
+    async notifyUnlockedOrigins(state) {
+        if (state.connectedOrigins.length === 0) {
+            return;
+        }
+        const chainId = this.displayChainId(this.activeNetworkPreset(state), await this.safeGetChainId(state)) ?? "unknown";
+        await Promise.allSettled(state.connectedOrigins.map((origin) => this.emitConnectionLifecycle(origin, chainId, state.publicKey)));
+    }
+    async emitSelectedAccountChangedForConnectedOrigins(state) {
+        if (state.connectedOrigins.length === 0) {
+            return;
+        }
+        if (await this.restoreUnlockedSession()) {
+            await Promise.allSettled(state.connectedOrigins.map((origin) => this.broadcastProviderEvent("accountsChanged", [[state.publicKey]], origin)));
+            return;
+        }
+        await Promise.allSettled(state.connectedOrigins.map((origin) => this.emitDisconnectLifecycle(origin)));
+    }
+    async invalidatePendingRequests(reason) {
+        const requestStates = await this.store.listRequestStates();
+        const settledPendingRequestIds = new Set();
+        for (const requestState of requestStates) {
+            if (requestState.status !== "pending") {
+                continue;
+            }
+            settledPendingRequestIds.add(requestState.requestId);
+            await this.rejectRequest(requestState, reason);
+        }
+        for (const [requestId, waiter] of this.requestWaiters.entries()) {
+            if (!settledPendingRequestIds.has(requestId)) {
+                waiter.reject(reason);
+            }
+        }
+        this.requestWaiters.clear();
+        for (const approval of await this.store.listApprovalStates()) {
+            await this.store.deleteApprovalState(approval.id);
+        }
+    }
     async prepareTransaction(state, intent) {
-        const signer = this.getUnlockedSigner();
+        const signer = await this.getUnlockedSigner();
         const client = this.currentClient(state);
         const activeChainId = await client.getChainId();
         if (intent.chainId && intent.chainId !== activeChainId) {
@@ -393,7 +544,7 @@ export class WalletController {
         });
     }
     async signPreparedTransaction(state, tx) {
-        const signer = this.getUnlockedSigner();
+        const signer = await this.getUnlockedSigner();
         const activeChainId = await this.currentClient(state).getChainId();
         if (tx.payload.sender !== signer.address) {
             throw new ProviderUnauthorizedError("transaction sender does not match the active wallet");
@@ -411,7 +562,7 @@ export class WalletController {
         const state = this.requireStoredWallet(await this.loadWalletState());
         switch (request.method) {
             case "xian_requestAccounts": {
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const chainId = this.displayChainId(this.activeNetworkPreset(state), await this.safeGetChainId(state));
                 const nextState = await this.updateConnectedOrigin(origin, true);
                 await this.emitConnectionLifecycle(origin, chainId ?? "unknown", nextState.publicKey);
@@ -419,9 +570,9 @@ export class WalletController {
             }
             case "xian_watchAsset": {
                 this.requireConnectedOrigin(state, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const assetRequest = firstParamObject(request.params);
-                const asset = assetRequest.options;
+                const asset = normalizeTrackedAsset(assetRequest.options);
                 await this.updateWatchedAssets((assets) => {
                     const next = assets.filter((entry) => entry.contract !== asset.contract);
                     next.push(asset);
@@ -431,7 +582,7 @@ export class WalletController {
             }
             case "xian_signMessage": {
                 this.requireConnectedOrigin(state, origin);
-                const signer = this.getUnlockedSigner();
+                const signer = await this.getUnlockedSigner();
                 const { message } = firstParamObject(request.params);
                 if (typeof message !== "string") {
                     throw new TypeError("xian_signMessage requires a message string");
@@ -443,13 +594,13 @@ export class WalletController {
             }
             case "xian_signTransaction": {
                 this.requireConnectedOrigin(state, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const { tx } = firstParamObject(request.params);
                 return this.signPreparedTransaction(state, tx);
             }
             case "xian_sendTransaction": {
                 this.requireConnectedOrigin(state, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const { tx, mode, waitForTx, timeoutMs, pollIntervalMs } = firstParamObject(request.params);
                 return this.sendPreparedTransaction(state, tx, {
                     mode: mode,
@@ -460,7 +611,7 @@ export class WalletController {
             }
             case "xian_sendCall": {
                 this.requireConnectedOrigin(state, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const { intent, mode, waitForTx, timeoutMs, pollIntervalMs } = firstParamObject(request.params);
                 const tx = await this.prepareTransaction(state, intent);
                 return this.sendPreparedTransaction(state, tx, {
@@ -563,7 +714,7 @@ export class WalletController {
                 };
             case "xian_requestAccounts": {
                 const walletState = this.requireStoredWallet(state);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const approvalChainId = this.displayChainId(this.activeNetworkPreset(walletState), await this.safeGetChainId(walletState));
                 if (walletState.connectedOrigins.includes(origin)) {
                     return {
@@ -592,9 +743,7 @@ export class WalletController {
                 };
             }
             case "xian_accounts":
-                if (!state ||
-                    this.unlockedPrivateKey == null ||
-                    !state.connectedOrigins.includes(origin)) {
+                if (!state || !(await this.restoreUnlockedSession()) || !state.connectedOrigins.includes(origin)) {
                     return {
                         kind: "result",
                         value: []
@@ -640,7 +789,7 @@ export class WalletController {
             case "xian_watchAsset": {
                 const walletState = this.requireStoredWallet(state);
                 this.requireConnectedOrigin(walletState, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 return {
                     kind: "approval",
                     account: walletState.publicKey,
@@ -650,7 +799,7 @@ export class WalletController {
             case "xian_signMessage": {
                 const walletState = this.requireStoredWallet(state);
                 this.requireConnectedOrigin(walletState, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 return {
                     kind: "approval",
                     account: walletState.publicKey,
@@ -660,7 +809,7 @@ export class WalletController {
             case "xian_prepareTransaction": {
                 const walletState = this.requireStoredWallet(state);
                 this.requireConnectedOrigin(walletState, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 const { intent } = firstParamObject(request.params);
                 return {
                     kind: "result",
@@ -672,7 +821,7 @@ export class WalletController {
             case "xian_sendCall": {
                 const walletState = this.requireStoredWallet(state);
                 this.requireConnectedOrigin(walletState, origin);
-                this.getUnlockedSigner();
+                await this.getUnlockedSigner();
                 return {
                     kind: "approval",
                     account: walletState.publicKey,
@@ -683,6 +832,13 @@ export class WalletController {
                 throw new ProviderUnsupportedMethodError(request.method);
         }
     }
+    getAccountsList(state) {
+        if (state.accounts && state.accounts.length > 0) {
+            return state.accounts.map((a) => ({ index: a.index, publicKey: a.publicKey, name: a.name }));
+        }
+        // Backward compat: create virtual account from legacy fields
+        return [{ index: 0, publicKey: state.publicKey, name: "Account 1" }];
+    }
     async getPopupState() {
         const state = await this.loadWalletState();
         const approvals = await this.store.listApprovalStates();
@@ -691,9 +847,11 @@ export class WalletController {
             .sort((left, right) => right.createdAt - left.createdAt);
         const activePreset = state ? this.activeNetworkPreset(state) : undefined;
         const resolvedChainId = await this.safeGetChainId(state);
+        const unlocked = await this.restoreUnlockedSession();
+        const watchedAssets = state?.watchedAssets ?? [];
         return {
             hasWallet: state != null,
-            unlocked: this.unlockedPrivateKey != null,
+            unlocked,
             publicKey: state?.publicKey,
             rpcUrl: state?.rpcUrl ?? DEFAULT_RPC_URL,
             dashboardUrl: state?.dashboardUrl ?? DEFAULT_DASHBOARD_URL,
@@ -708,16 +866,133 @@ export class WalletController {
             activeNetworkId: activePreset?.id,
             activeNetworkName: activePreset?.name,
             networkPresets: state?.networkPresets ?? DEFAULT_NETWORK_PRESETS,
-            watchedAssets: state?.watchedAssets ?? [],
+            watchedAssets,
+            detectedAssets: [],
+            assetBalances: {},
+            assetFiatValues: {},
             connectedOrigins: state?.connectedOrigins ?? [],
             pendingApprovalCount: pendingApprovals.length,
             pendingApprovals,
             hasRecoveryPhrase: Boolean(state?.encryptedMnemonic),
             seedSource: state?.seedSource,
             mnemonicWordCount: state?.mnemonicWordCount,
+            accounts: state ? this.getAccountsList(state) : [],
+            activeAccountIndex: state?.activeAccountIndex ?? 0,
             version: this.options.version
         };
     }
+    async getAssetBalances() {
+        const state = await this.loadWalletState();
+        if (!state) {
+            return {};
+        }
+        return this.fetchAssetBalances(state, state.watchedAssets);
+    }
+    async getTokenMetadata(contract) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        return this.currentClient(state).getTokenMetadata(contract);
+    }
+    async getDetectedAssets() {
+        const state = await this.loadWalletState();
+        if (!state) {
+            return [];
+        }
+        try {
+            return await this.fetchDetectedAssets(state);
+        }
+        catch {
+            return [];
+        }
+    }
+    async trackAsset(asset) {
+        const normalized = normalizeTrackedAsset(asset);
+        if (!normalized.contract) {
+            throw new TypeError("asset contract is required");
+        }
+        await this.updateWatchedAssets((assets) => {
+            const next = assets.filter((entry) => entry.contract !== normalized.contract);
+            next.push(normalized);
+            return next;
+        });
+        return this.getPopupState();
+    }
+    async updateAssetSettings(assets) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        for (const update of assets) {
+            const asset = state.watchedAssets.find((a) => a.contract === update.contract);
+            if (asset) {
+                if (update.hidden !== undefined) {
+                    asset.hidden = update.hidden;
+                }
+                if (update.order !== undefined) {
+                    asset.order = update.order;
+                }
+            }
+        }
+        await this.store.saveState(state);
+        return this.getPopupState();
+    }
+    async updateWatchedAssetDecimals(contract, decimals) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const idx = state.watchedAssets.findIndex((asset) => asset.contract === contract);
+        if (idx === -1) {
+            throw new Error(`asset ${contract} is not watched`);
+        }
+        const existing = state.watchedAssets[idx];
+        state.watchedAssets[idx] = { ...existing, decimals };
+        await this.store.saveState(state);
+        return this.getPopupState();
+    }
+    async estimateTransactionStamps(request) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const client = this.currentClient(state);
+        return client.estimateStamps({
+            sender: state.publicKey,
+            contract: request.contract,
+            function: request.function,
+            kwargs: request.kwargs
+        });
+    }
+    async sendDirectTransaction(intent) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        await this.getUnlockedSigner();
+        const tx = await this.prepareTransaction(state, {
+            contract: intent.contract,
+            function: intent.function,
+            kwargs: intent.kwargs,
+            stamps: intent.stamps
+        });
+        return this.sendPreparedTransaction(state, tx, { mode: "commit" });
+    }
+    async getContractMethods(contract) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        return this.currentClient(state).getContractMethods(contract);
+    }
+    async fetchAssetBalances(state, assets) {
+        const balances = {};
+        if (!state || assets.length === 0) {
+            return balances;
+        }
+        const client = this.currentClient(state);
+        const results = await Promise.allSettled(assets.map(async (asset) => {
+            const raw = await client.getBalance(state.publicKey, {
+                contract: asset.contract
+            });
+            return { contract: asset.contract, raw };
+        }));
+        for (const result of results) {
+            if (result.status === "fulfilled") {
+                const { contract, raw } = result.value;
+                balances[contract] =
+                    raw != null ? String(raw) : null;
+            }
+            else {
+                // If a single balance fetch fails, mark it null rather than
+                // failing the entire popup state.
+            }
+        }
+        return balances;
+    }
     async createOrImportWallet(input) {
         const secret = await createWalletSecret({
             privateKey: input.privateKey,
@@ -731,17 +1006,10 @@ export class WalletController {
             : undefined;
         this.unlockedPrivateKey = secret.privateKey;
         this.unlockedSigner = signer;
-        const waiters = [...this.requestWaiters.values()];
-        this.requestWaiters.clear();
-        for (const waiter of waiters) {
-            waiter.reject(new ProviderUnauthorizedError("wallet was replaced"));
-        }
-        for (const requestState of await this.store.listRequestStates()) {
-            await this.store.deleteRequestState(requestState.requestId);
-        }
-        for (const approval of await this.store.listApprovalStates()) {
-            await this.store.deleteApprovalState(approval.id);
-        }
+        this.unlockedMnemonic = secret.mnemonic ?? null;
+        this.unlockedPassword = input.password;
+        await this.persistUnlockedSession(secret.privateKey);
+        await this.invalidatePendingRequests(new ProviderUnauthorizedError("wallet was replaced"));
         const setupRpcUrl = trimOptionalString(input.rpcUrl) ?? DEFAULT_RPC_URL;
         const setupDashboardUrl = trimOptionalString(input.dashboardUrl) ?? DEFAULT_DASHBOARD_URL;
         const localPreset = createLocalNetworkPreset();
@@ -767,12 +1035,20 @@ export class WalletController {
         const networkPresets = useLocalPreset
             ? [localPreset]
             : [localPreset, activePreset];
+        const initialAccount = {
+            index: 0,
+            publicKey: signer.address,
+            encryptedPrivateKey,
+            name: "Account 1"
+        };
         const popupState = await this.persistWalletState({
             publicKey: signer.address,
             encryptedPrivateKey,
             encryptedMnemonic,
             seedSource: secret.seedSource,
             mnemonicWordCount: secret.mnemonicWordCount,
+            accounts: [initialAccount],
+            activeAccountIndex: 0,
             rpcUrl: activePreset.rpcUrl,
             dashboardUrl: activePreset.dashboardUrl,
             activeNetworkId: activePreset.id,
@@ -802,8 +1078,18 @@ export class WalletController {
         }
         this.unlockedPrivateKey = privateKey;
         this.unlockedSigner = signer;
-        const chainId = this.displayChainId(this.activeNetworkPreset(state), await this.safeGetChainId(state));
-        await Promise.all(state.connectedOrigins.map((origin) => this.emitConnectionLifecycle(origin, chainId ?? "unknown", state.publicKey)));
+        this.unlockedPassword = password;
+        // Decrypt mnemonic into session for account switching
+        if (state.encryptedMnemonic) {
+            try {
+                this.unlockedMnemonic = await decryptMnemonic(state.encryptedMnemonic, password);
+            }
+            catch {
+                this.unlockedMnemonic = null;
+            }
+        }
+        await this.persistUnlockedSession(privateKey);
+        void this.notifyUnlockedOrigins(state);
         return this.getPopupState();
     }
     async revealMnemonic(password) {
@@ -813,13 +1099,233 @@ export class WalletController {
         }
         return decryptMnemonic(state.encryptedMnemonic, password);
     }
+    async revealPrivateKey(password) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        return decryptPrivateKey(state.encryptedPrivateKey, password);
+    }
+    async exportWallet(password) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const accounts = state.accounts ?? [
+            { index: 0, publicKey: state.publicKey, encryptedPrivateKey: state.encryptedPrivateKey, name: "Account 1" }
+        ];
+        const backup = {
+            version: 1,
+            type: state.seedSource,
+            accounts: accounts.map((a) => ({ index: a.index, name: a.name })),
+            activeAccountIndex: state.activeAccountIndex ?? accounts[0]?.index ?? 0,
+            activeNetworkId: state.activeNetworkId,
+            networkPresets: state.networkPresets.filter((p) => !p.builtin),
+            watchedAssets: state.watchedAssets
+        };
+        if (state.encryptedMnemonic) {
+            backup.mnemonic = await decryptMnemonic(state.encryptedMnemonic, password);
+        }
+        else {
+            backup.privateKey = await decryptPrivateKey(state.encryptedPrivateKey, password);
+        }
+        return backup;
+    }
+    async importWalletBackup(backup, password) {
+        // Derive or use the provided private key
+        let primaryKey;
+        let mnemonic;
+        if (backup.type === "mnemonic" && backup.mnemonic) {
+            mnemonic = backup.mnemonic;
+            primaryKey = await derivePrivateKeyFromMnemonic(mnemonic, 0);
+        }
+        else if (backup.privateKey) {
+            primaryKey = backup.privateKey;
+        }
+        else {
+            throw new Error("backup must contain a mnemonic or private key");
+        }
+        const encryptedMnemonic = mnemonic
+            ? await encryptMnemonic(mnemonic, password)
+            : undefined;
+        // Build accounts list
+        const accountEntries = backup.accounts ?? [{ index: 0, name: "Account 1" }];
+        const accounts = [];
+        const privateKeysByIndex = new Map();
+        for (const entry of accountEntries) {
+            const key = mnemonic
+                ? await derivePrivateKeyFromMnemonic(mnemonic, entry.index)
+                : primaryKey;
+            privateKeysByIndex.set(entry.index, key);
+            const acctSigner = new Ed25519Signer(key);
+            accounts.push({
+                index: entry.index,
+                publicKey: acctSigner.address,
+                encryptedPrivateKey: await encryptPrivateKey(key, password),
+                name: entry.name
+            });
+        }
+        const activeAccount = accounts.find((account) => account.index === backup.activeAccountIndex) ??
+            accounts[0];
+        if (!activeAccount) {
+            throw new Error("backup must contain at least one account");
+        }
+        const activePrivateKey = privateKeysByIndex.get(activeAccount.index) ?? primaryKey;
+        const signer = new Ed25519Signer(activePrivateKey);
+        this.unlockedPrivateKey = activePrivateKey;
+        this.unlockedSigner = signer;
+        this.unlockedMnemonic = mnemonic ?? null;
+        this.unlockedPassword = password;
+        await this.persistUnlockedSession(activePrivateKey);
+        await this.invalidatePendingRequests(new ProviderUnauthorizedError("wallet was replaced"));
+        // Merge network presets
+        const presets = [...DEFAULT_NETWORK_PRESETS];
+        for (const p of backup.networkPresets ?? []) {
+            if (!presets.some((existing) => existing.id === p.id)) {
+                presets.push(p);
+            }
+        }
+        const activePreset = presets.find((preset) => preset.id === backup.activeNetworkId) ??
+            presets[0];
+        if (!activePreset) {
+            throw new Error("backup must contain at least one network preset");
+        }
+        const watchedAssets = backup.watchedAssets?.length
+            ? backup.watchedAssets
+            : [{ contract: "currency", name: "Xian", symbol: "XIAN" }];
+        await this.persistWalletState({
+            publicKey: activeAccount.publicKey,
+            encryptedPrivateKey: activeAccount.encryptedPrivateKey,
+            encryptedMnemonic,
+            seedSource: backup.type,
+            mnemonicWordCount: mnemonic ? mnemonic.split(" ").length : undefined,
+            accounts,
+            activeAccountIndex: activeAccount.index,
+            rpcUrl: activePreset.rpcUrl,
+            dashboardUrl: activePreset.dashboardUrl,
+            activeNetworkId: activePreset.id,
+            networkPresets: presets,
+            watchedAssets,
+            connectedOrigins: [],
+            createdAt: new Date().toISOString()
+        });
+        return this.getPopupState();
+    }
+    async addAccount() {
+        await this.restoreUnlockedSession();
+        if (!this.unlockedMnemonic || !this.unlockedPassword) {
+            throw new Error("wallet must be unlocked to add an account");
+        }
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const accounts = state.accounts ?? [
+            { index: 0, publicKey: state.publicKey, encryptedPrivateKey: state.encryptedPrivateKey, name: "Account 1" }
+        ];
+        const nextIndex = Math.max(...accounts.map((a) => a.index)) + 1;
+        const privateKey = await derivePrivateKeyFromMnemonic(this.unlockedMnemonic, nextIndex);
+        const signer = new Ed25519Signer(privateKey);
+        const encrypted = await encryptPrivateKey(privateKey, this.unlockedPassword);
+        accounts.push({
+            index: nextIndex,
+            publicKey: signer.address,
+            encryptedPrivateKey: encrypted,
+            name: `Account ${accounts.length + 1}`
+        });
+        state.publicKey = signer.address;
+        state.encryptedPrivateKey = encrypted;
+        state.activeAccountIndex = nextIndex;
+        state.accounts = accounts;
+        await this.store.saveState(state);
+        this.unlockedPrivateKey = privateKey;
+        this.unlockedSigner = signer;
+        await this.persistUnlockedSession(privateKey);
+        await this.emitSelectedAccountChangedForConnectedOrigins(state);
+        return this.getPopupState();
+    }
+    async switchAccount(index) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const accounts = state.accounts ?? [
+            { index: 0, publicKey: state.publicKey, encryptedPrivateKey: state.encryptedPrivateKey, name: "Account 1" }
+        ];
+        const target = accounts.find((a) => a.index === index);
+        if (!target) {
+            throw new Error("account not found");
+        }
+        // Update active account in state
+        state.publicKey = target.publicKey;
+        state.encryptedPrivateKey = target.encryptedPrivateKey;
+        state.activeAccountIndex = index;
+        await this.store.saveState(state);
+        // If unlocked, switch the in-memory signer
+        if (this.unlockedMnemonic) {
+            const privateKey = await derivePrivateKeyFromMnemonic(this.unlockedMnemonic, index);
+            this.unlockedPrivateKey = privateKey;
+            this.unlockedSigner = new Ed25519Signer(privateKey);
+            await this.persistUnlockedSession(privateKey);
+        }
+        else if (this.unlockedPrivateKey) {
+            // No mnemonic in session — clear unlock (requires re-auth)
+            await this.clearUnlockedSession();
+        }
+        await this.emitSelectedAccountChangedForConnectedOrigins(state);
+        return this.getPopupState();
+    }
+    async renameAccount(index, name) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        const accounts = state.accounts ?? [
+            { index: 0, publicKey: state.publicKey, encryptedPrivateKey: state.encryptedPrivateKey, name: "Account 1" }
+        ];
+        const target = accounts.find((a) => a.index === index);
+        if (!target) {
+            throw new Error("account not found");
+        }
+        target.name = name;
+        state.accounts = accounts;
+        await this.store.saveState(state);
+        return this.getPopupState();
+    }
+    async removeAccount(index) {
+        const state = this.requireStoredWallet(await this.loadWalletState());
+        if (index === 0) {
+            throw new Error("cannot remove the primary account");
+        }
+        const accounts = state.accounts ?? [];
+        const nextAccounts = accounts.filter((account) => account.index !== index);
+        if (nextAccounts.length === 0) {
+            throw new Error("cannot remove the last remaining account");
+        }
+        const removedActiveAccount = state.activeAccountIndex === index;
+        state.accounts = nextAccounts;
+        if (removedActiveAccount) {
+            const nextActiveAccount = nextAccounts[0];
+            state.publicKey = nextActiveAccount.publicKey;
+            state.encryptedPrivateKey = nextActiveAccount.encryptedPrivateKey;
+            state.activeAccountIndex = nextActiveAccount.index;
+            if (this.unlockedMnemonic) {
+                const privateKey = await derivePrivateKeyFromMnemonic(this.unlockedMnemonic, nextActiveAccount.index);
+                this.unlockedPrivateKey = privateKey;
+                this.unlockedSigner = new Ed25519Signer(privateKey);
+                await this.persistUnlockedSession(privateKey);
+            }
+            else if (this.unlockedPrivateKey) {
+                await this.clearUnlockedSession();
+            }
+        }
+        await this.store.saveState(state);
+        if (removedActiveAccount) {
+            await this.emitSelectedAccountChangedForConnectedOrigins(state);
+        }
+        return this.getPopupState();
+    }
     async lockWallet() {
         const state = await this.loadWalletState();
-        this.unlockedPrivateKey = null;
-        this.unlockedSigner = null;
+        await this.clearUnlockedSession();
+        if (state) {
+            await Promise.all(state.connectedOrigins.map((origin) => this.emitDisconnectLifecycle(origin)));
+        }
+        return this.getPopupState();
+    }
+    async removeWallet() {
+        const state = await this.loadWalletState();
+        await this.clearUnlockedSession();
         if (state) {
             await Promise.all(state.connectedOrigins.map((origin) => this.emitDisconnectLifecycle(origin)));
         }
+        await this.invalidatePendingRequests(new ProviderUnauthorizedError("wallet was removed"));
+        await this.store.clearState();
         return this.getPopupState();
     }
     async updateSettings(input) {