@sundaeswap/sprinkles 0.8.1 → 0.9.0

package/src/Sprinkle/index.ts

@@ -5,7 +5,7 @@ import {
   HotWallet,
   type Wallet,
 } from "@blaze-cardano/sdk";
-import { CborSet, VkeyWitness, TxCBOR } from "@blaze-cardano/core";
+import { CborSet, VkeyWitness, TxCBOR, wordlist } from "@blaze-cardano/core";
 import {
   selectCancellable,
   selectWithClear,
@@ -217,6 +217,14 @@ export interface IMenu<S extends TSchema> {
   beforeShow?: (sprinkle: Sprinkle<S>) => Promise<void>;
 }
 
+interface ILeaf<S extends TSchema> {
+  breadcrumb: string;
+  leafTitle: string;
+  action: (sprinkle: Sprinkle<S>) => Promise<Sprinkle<S> | void>;
+  beforeShowChain: Array<(sprinkle: Sprinkle<S>) => Promise<void>>;
+  isExit?: boolean;
+}
+
 export class Sprinkle<S extends TSchema> {
   storagePath: string;
   settings: TExact<S> = {} as TExact<S>;
@@ -440,10 +448,157 @@ export class Sprinkle<S extends TSchema> {
     }
   }
 
+  // --- Importing profiles from external files ---
+
+  private static globToRegex(pattern: string): RegExp {
+    const escaped = pattern
+      .split("*")
+      .map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+      .join(".*");
+    return new RegExp(`^${escaped}$`);
+  }
+
+  /**
+   * Scan the current working directory for files matching `importPattern`.
+   * Returns absolute paths. Designed to surface state files committed to a
+   * project repo (e.g. `state.preview.json`) that the consumer might want
+   * to restore from.
+   */
+  findImportableProfiles(cwd: string = process.cwd()): string[] {
+    if (this.options.importPattern === null) return [];
+    const pattern = this.options.importPattern ?? "state.*.json";
+    const regex = Sprinkle.globToRegex(pattern);
+    try {
+      return fs
+        .readdirSync(cwd)
+        .filter((f) => regex.test(f))
+        .map((f) => path.join(cwd, f));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Read a profile or raw-settings JSON file and save it as a new local
+   * profile. Prompts for missing sensitive fields before writing.
+   */
+  async importProfileFromFile(filePath: string): Promise<void> {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content, Sprinkle.bigIntReviver) as
+      | {
+          meta?: IProfileMeta;
+          settings?: unknown;
+          defaults?: Record<string, unknown>;
+        }
+      | unknown;
+
+    let importedSettings: TExact<S>;
+    let importedMeta: IProfileMeta | undefined;
+    let importedDefaults: Record<string, unknown> = {};
+
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "settings" in (parsed as object) &&
+      "meta" in (parsed as object)
+    ) {
+      const obj = parsed as {
+        meta: IProfileMeta;
+        settings: TExact<S>;
+        defaults?: Record<string, unknown>;
+      };
+      importedMeta = obj.meta;
+      importedSettings = obj.settings;
+      importedDefaults = obj.defaults ?? {};
+    } else {
+      importedSettings = parsed as TExact<S>;
+    }
+
+    // If the file came from this same Sprinkle install (same encryption),
+    // decrypt sensitive fields. Otherwise we'll re-prompt for missing ones below.
+    try {
+      importedSettings = await this.decryptSettings(importedSettings);
+    } catch {
+      // ignore - encrypted with a different key, will re-prompt
+    }
+
+    const baseName = path.basename(filePath).replace(/\.json$/, "");
+    const meta = await this.promptProfileMeta(
+      importedMeta?.name ?? baseName,
+      importedMeta?.description,
+    );
+    if (meta === null) return; // user cancelled
+    const { name, description } = meta;
+
+    // Re-prompt any sensitive fields that are missing or look encrypted
+    const sensitivePaths = collectSensitivePaths(this.type);
+    for (const p of sensitivePaths) {
+      const value = getNestedValue(importedSettings, p);
+      if (typeof value !== "string" || value.length === 0) {
+        const entered = await passwordCancellable({
+          message: `Enter value for sensitive field "${p}":`,
+        });
+        if (entered === null) return; // user cancelled
+        setNestedValue(importedSettings, p, entered);
+      }
+    }
+
+    const profilesDir = Sprinkle.profilesDir(this.storagePath);
+    if (!fs.existsSync(profilesDir)) {
+      fs.mkdirSync(profilesDir, { recursive: true });
+    }
+    const id = Sprinkle.findAvailableId(
+      profilesDir,
+      Sprinkle.sanitizeProfileId(name),
+    );
+    const now = new Date().toISOString();
+    this.profileId = id;
+    this.profileMeta = { name, description, createdAt: now, updatedAt: now };
+    this.settings = importedSettings;
+    this.defaults = importedDefaults;
+    this.saveProfile();
+    fs.writeFileSync(Sprinkle.activeProfilePath(this.storagePath), id, "utf-8");
+  }
+
+  private async promptImportFromCwd(): Promise<boolean> {
+    const importable = this.findImportableProfiles();
+    if (importable.length === 0) return false;
+
+    const cancelToken = "__cancel__";
+    const choices: { name: string; value: string }[] = [
+      ...importable.map((f) => ({
+        name: `Import ${path.basename(f)}`,
+        value: f,
+      })),
+      { name: "Enter a different path...", value: "__custom__" },
+      { name: "Skip import", value: cancelToken },
+    ];
+    const choice = await select({
+      message:
+        "Found importable state file(s) in this directory. Restore from one?",
+      choices,
+    });
+    if (choice === null || choice === cancelToken) return false;
+    let filePath: string = choice;
+    if (choice === "__custom__") {
+      const entered = await inputCancellable({
+        message: "Path to state file:",
+        validate: (v: string) =>
+          v.trim().length > 0 ? true : "Path cannot be empty",
+      });
+      if (entered === null) return false;
+      filePath = entered;
+    }
+    await this.importProfileFromFile(filePath);
+    return true;
+  }
+
   private async selectOrCreateProfile(): Promise<void> {
     const profiles = this.scanProfiles();
 
     if (profiles.length === 0) {
+      const imported = await this.promptImportFromCwd();
+      if (imported) return;
       await this.createProfile();
       return;
     }
@@ -514,6 +669,7 @@ export class Sprinkle<S extends TSchema> {
       jsonContent,
       "utf-8",
     );
+    await this.loadProfile(id);
     console.log(`Profile "${name}" created as a copy.`);
   }
 
@@ -593,8 +749,355 @@ export class Sprinkle<S extends TSchema> {
 
   // --- Menu ---
 
+  private async importProfileInteractive(): Promise<void> {
+    const importable = this.findImportableProfiles();
+    const customToken = "__custom__";
+    let filePath: string;
+    if (importable.length > 0) {
+      const choice = await select({
+        message: "Select a file to import:",
+        choices: [
+          ...importable.map((f) => ({ name: path.basename(f), value: f })),
+          { name: "Enter a different path...", value: customToken },
+        ],
+      });
+      if (choice === null) return; // user cancelled
+      if (choice === customToken) {
+        const entered = await inputCancellable({
+          message: "Path to state file:",
+          validate: (v: string) =>
+            v.trim().length > 0 ? true : "Path cannot be empty",
+        });
+        if (entered === null) return;
+        filePath = entered;
+      } else {
+        filePath = choice;
+      }
+    } else {
+      const entered = await inputCancellable({
+        message: "Path to state file:",
+        validate: (v: string) =>
+          v.trim().length > 0 ? true : "Path cannot be empty",
+      });
+      if (entered === null) return;
+      filePath = entered;
+    }
+    try {
+      await this.importProfileFromFile(filePath);
+      console.log(`Imported profile "${this.profileMeta.name}".`);
+    } catch (error) {
+      console.error(`Import failed: ${(error as Error).message}`);
+    }
+  }
+
+  private buildSettingsMenu(): IMenu<S> {
+    return {
+      title: "Settings & Profiles",
+      items: [
+        {
+          title: "View settings",
+          action: async () => {
+            const jsonStr = JSON.stringify(this.getDisplaySettings(), bigIntReplacer, 2);
+            const jsonLines = jsonStr.split("\n").length;
+            console.log(jsonStr);
+
+            // Wait for user to press Enter
+            await selectWithClear({
+              message: "Press Enter to continue...",
+              choices: [{ name: "Continue", value: "continue" }],
+            });
+
+            // Clear the JSON output
+            process.stdout.write("\x1b[1A\x1b[2K".repeat(jsonLines) + "\x1b[G");
+          },
+        },
+        {
+          title: "Edit settings",
+          action: async () => {
+            try {
+              this.settings = await this.EditStruct(this.type, this.settings);
+              this.saveSettings();
+            } catch (e) {
+              if (e instanceof UserCancelledError) {
+                return; // User cancelled, return to menu
+              }
+              throw e;
+            }
+          },
+        },
+        {
+          title: "Switch profile",
+          action: async () => {
+            this.saveSettings();
+            const profiles = this.scanProfiles();
+            if (profiles.length <= 1) {
+              console.log(
+                "No other profiles to switch to. Create a new one first.",
+              );
+            } else {
+              await this.selectProfile(profiles);
+            }
+          },
+        },
+        {
+          title: "Create new profile",
+          action: async () => {
+            await this.createProfile();
+          },
+        },
+        {
+          title: "Duplicate current profile",
+          action: async () => {
+            await this.duplicateProfile();
+          },
+        },
+        {
+          title: "Rename current profile",
+          action: async () => {
+            await this.renameProfile();
+          },
+        },
+        {
+          title: "Delete a profile",
+          action: async () => {
+            await this.deleteProfile();
+          },
+        },
+        {
+          title: "Import profile from file",
+          action: async () => {
+            await this.importProfileInteractive();
+          },
+        },
+        {
+          title: "Addressbook",
+          items: [
+            {
+              title: "View entries",
+              action: async () => {
+                const entries = Object.entries(this.addressbook);
+                if (entries.length === 0) {
+                  console.log("Addressbook is empty.");
+                } else {
+                  for (const [name, ms] of entries) {
+                    const json = JSON.stringify(ms, bigIntReplacer, 2);
+                    let hashStr = "unknown";
+                    try {
+                      hashStr = toNativeScript(ms).hash();
+                    } catch { /* skip */ }
+                    console.log(colors.bold(name) + "  " + colors.dim(hashStr));
+                    console.log(json);
+                    console.log();
+                  }
+                }
+                await selectWithClear({
+                  message: "Press Enter to continue...",
+                  choices: [{ name: "Continue", value: "continue" }],
+                });
+              },
+            },
+            {
+              title: "Add entry",
+              action: async () => {
+                const name = await inputCancellable({
+                  message: "Entry name:",
+                  validate: (v) =>
+                    v.trim().length > 0 ? true : "Name cannot be empty",
+                });
+                if (name === null) return;
+                if (this.addressbook[name]) {
+                  const overwrite = await confirmCancellable({
+                    message: `Entry "${name}" already exists. Overwrite?`,
+                    default: false,
+                  });
+                  if (!overwrite) return;
+                }
+                try {
+                  const script = await this.FillInStruct(MultisigScriptSchema);
+                  this.addressbook[name] = script as TMultisigScript;
+                  this.saveSettings();
+                  console.log(`Added "${name}" to addressbook.`);
+                } catch (e) {
+                  if (e instanceof UserCancelledError) return;
+                  throw e;
+                }
+              },
+            },
+            {
+              title: "Edit entry",
+              action: async () => {
+                const entries = Object.keys(this.addressbook);
+                if (entries.length === 0) {
+                  console.log("Addressbook is empty.");
+                  return;
+                }
+                const selected = await selectCancellable({
+                  message: "Select entry to edit:",
+                  choices: entries.map((n) => ({ name: n, value: n })),
+                });
+                if (selected === null) return;
+                const editName = selected as string;
+                try {
+                  const updated = await this.EditStruct(
+                    MultisigScriptSchema,
+                    this.addressbook[editName] as any,
+                  );
+                  this.addressbook[editName] = updated as TMultisigScript;
+                  this.saveSettings();
+                  console.log(`Updated "${editName}".`);
+                } catch (e) {
+                  if (e instanceof UserCancelledError) return;
+                  throw e;
+                }
+              },
+            },
+            {
+              title: "Delete entry",
+              action: async () => {
+                const entries = Object.keys(this.addressbook);
+                if (entries.length === 0) {
+                  console.log("Addressbook is empty.");
+                  return;
+                }
+                const delSelected = await selectCancellable({
+                  message: "Select entry to delete:",
+                  choices: entries.map((n) => ({ name: n, value: n })),
+                });
+                if (delSelected === null) return;
+                const delName = delSelected as string;
+                const confirmed = await confirmCancellable({
+                  message: `Delete "${delName}"?`,
+                  default: false,
+                });
+                if (!confirmed) return;
+                delete this.addressbook[delName];
+                this.saveSettings();
+                console.log(`Deleted "${delName}".`);
+              },
+            },
+          ],
+        } as IMenu<S>,
+      ],
+    };
+  }
+
   async showMenu(menu: IMenu<S>): Promise<void> {
-    return this._showMenu(menu, true, [menu.title]);
+    return this._searchMenu(menu);
+  }
+
+  // --- Flat search-based top-level menu ---
+
+  private _flattenLeaves(
+    menu: IMenu<S>,
+    prefix: string[],
+    beforeShowChain: Array<(s: Sprinkle<S>) => Promise<void>>,
+    isRoot: boolean,
+  ): ILeaf<S>[] {
+    // Root's title is omitted from breadcrumbs (no "Main Menu › " prefix on
+    // every leaf). Root's beforeShow is fired by the search loop, not as part
+    // of the leaf chain (otherwise it would fire twice).
+    const chain =
+      !isRoot && menu.beforeShow
+        ? [...beforeShowChain, menu.beforeShow]
+        : beforeShowChain;
+    const breadcrumbPrefix = isRoot ? prefix : [...prefix, menu.title];
+
+    const leaves: ILeaf<S>[] = [];
+    for (const item of menu.items) {
+      if ("action" in item) {
+        leaves.push({
+          breadcrumb: [...breadcrumbPrefix, item.title].join(" › "),
+          leafTitle: item.title,
+          action: item.action,
+          beforeShowChain: chain,
+        });
+      } else {
+        leaves.push(
+          ...this._flattenLeaves(item, breadcrumbPrefix, chain, false),
+        );
+      }
+    }
+    return leaves;
+  }
+
+  private static _scoreLeaf(
+    leaf: { breadcrumb: string; leafTitle: string },
+    tokens: string[],
+  ): number {
+    if (tokens.length === 0) return 1;
+    const crumbLower = leaf.breadcrumb.toLowerCase();
+    const titleLower = leaf.leafTitle.toLowerCase();
+    let score = 0;
+    for (const t of tokens) {
+      if (!crumbLower.includes(t)) return 0; // require every token
+      if (titleLower.includes(t)) {
+        score += 3; // matches in the leaf title outrank ancestor matches
+      } else {
+        score += 1;
+      }
+    }
+    return score;
+  }
+
+  private _filterLeaves(leaves: ILeaf<S>[], term: string): ILeaf<S>[] {
+    const trimmed = term.trim();
+    if (!trimmed) return leaves;
+    const tokens = trimmed.toLowerCase().split(/\s+/);
+    return leaves
+      .map((leaf) => ({ leaf, score: Sprinkle._scoreLeaf(leaf, tokens) }))
+      .filter((x) => x.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .map((x) => x.leaf);
+  }
+
+  private async _searchMenu(menu: IMenu<S>): Promise<void> {
+    const EXIT_TITLE = "Exit";
+    while (true) {
+      // Root beforeShow fires once per iteration so consumers can refresh any
+      // dynamic state before the search prompt is built.
+      if (menu.beforeShow) {
+        await menu.beforeShow(this);
+      }
+
+      const userLeaves = this._flattenLeaves(menu, [], [], true);
+      const settingsLeaves = this._flattenLeaves(
+        this.buildSettingsMenu(),
+        [],
+        [],
+        false,
+      );
+      const exitLeaf: ILeaf<S> = {
+        breadcrumb: EXIT_TITLE,
+        leafTitle: EXIT_TITLE,
+        action: async () => {},
+        beforeShowChain: [],
+        isExit: true,
+      };
+      const allLeaves = [...userLeaves, ...settingsLeaves, exitLeaf];
+
+      const selected = (await searchCancellable({
+        message: "What would you like to do?",
+        source: async (term: string | undefined) => {
+          return this._filterLeaves(allLeaves, term ?? "").map((leaf) => ({
+            name: leaf.breadcrumb,
+            value: leaf,
+          }));
+        },
+      })) as ILeaf<S> | null;
+
+      if (selected === null || selected.isExit) return;
+
+      // Fire submenu beforeShow hooks along the path to the selected leaf
+      for (const beforeShow of selected.beforeShowChain) {
+        await beforeShow(this);
+      }
+
+      const result = await selected.action(this);
+      if (result instanceof Sprinkle) {
+        this.settings = result.settings;
+        this.saveSettings();
+      }
+    }
   }
 
   private async _showMenu(menu: IMenu<S>, main: boolean, path: string[], clearPrevious = false): Promise<void> {
@@ -704,189 +1207,7 @@ export class Sprinkle<S extends TSchema> {
       return;
     }
     if (selection === -5) {
-      const settingsMenu: IMenu<S> = {
-        title: "Settings & Profiles",
-        items: [
-          {
-            title: "View settings",
-            action: async () => {
-              const jsonStr = JSON.stringify(this.getDisplaySettings(), bigIntReplacer, 2);
-              const jsonLines = jsonStr.split("\n").length;
-              console.log(jsonStr);
-
-              // Wait for user to press Enter
-              await selectWithClear({
-                message: "Press Enter to continue...",
-                choices: [{ name: "Continue", value: "continue" }],
-              });
-
-              // Clear the JSON output
-              process.stdout.write("\x1b[1A\x1b[2K".repeat(jsonLines) + "\x1b[G");
-            },
-          },
-          {
-            title: "Edit settings",
-            action: async () => {
-              try {
-                this.settings = await this.EditStruct(this.type, this.settings);
-                this.saveSettings();
-              } catch (e) {
-                if (e instanceof UserCancelledError) {
-                  return; // User cancelled, return to menu
-                }
-                throw e;
-              }
-            },
-          },
-          {
-            title: "Switch profile",
-            action: async () => {
-              this.saveSettings();
-              const profiles = this.scanProfiles();
-              if (profiles.length <= 1) {
-                console.log(
-                  "No other profiles to switch to. Create a new one first.",
-                );
-              } else {
-                await this.selectProfile(profiles);
-              }
-            },
-          },
-          {
-            title: "Create new profile",
-            action: async () => {
-              await this.createProfile();
-            },
-          },
-          {
-            title: "Duplicate current profile",
-            action: async () => {
-              await this.duplicateProfile();
-            },
-          },
-          {
-            title: "Rename current profile",
-            action: async () => {
-              await this.renameProfile();
-            },
-          },
-          {
-            title: "Delete a profile",
-            action: async () => {
-              await this.deleteProfile();
-            },
-          },
-          {
-            title: "Addressbook",
-            items: [
-              {
-                title: "View entries",
-                action: async () => {
-                  const entries = Object.entries(this.addressbook);
-                  if (entries.length === 0) {
-                    console.log("Addressbook is empty.");
-                  } else {
-                    for (const [name, ms] of entries) {
-                      const json = JSON.stringify(ms, bigIntReplacer, 2);
-                      let hashStr = "unknown";
-                      try {
-                        hashStr = toNativeScript(ms).hash();
-                      } catch { /* skip */ }
-                      console.log(colors.bold(name) + "  " + colors.dim(hashStr));
-                      console.log(json);
-                      console.log();
-                    }
-                  }
-                  await selectWithClear({
-                    message: "Press Enter to continue...",
-                    choices: [{ name: "Continue", value: "continue" }],
-                  });
-                },
-              },
-              {
-                title: "Add entry",
-                action: async () => {
-                  const name = await inputCancellable({
-                    message: "Entry name:",
-                    validate: (v) =>
-                      v.trim().length > 0 ? true : "Name cannot be empty",
-                  });
-                  if (name === null) return;
-                  if (this.addressbook[name]) {
-                    const overwrite = await confirmCancellable({
-                      message: `Entry "${name}" already exists. Overwrite?`,
-                      default: false,
-                    });
-                    if (!overwrite) return;
-                  }
-                  try {
-                    const script = await this.FillInStruct(MultisigScriptSchema);
-                    this.addressbook[name] = script as TMultisigScript;
-                    this.saveSettings();
-                    console.log(`Added "${name}" to addressbook.`);
-                  } catch (e) {
-                    if (e instanceof UserCancelledError) return;
-                    throw e;
-                  }
-                },
-              },
-              {
-                title: "Edit entry",
-                action: async () => {
-                  const entries = Object.keys(this.addressbook);
-                  if (entries.length === 0) {
-                    console.log("Addressbook is empty.");
-                    return;
-                  }
-                  const selected = await selectCancellable({
-                    message: "Select entry to edit:",
-                    choices: entries.map((n) => ({ name: n, value: n })),
-                  });
-                  if (selected === null) return;
-                  const editName = selected as string;
-                  try {
-                    const updated = await this.EditStruct(
-                      MultisigScriptSchema,
-                      this.addressbook[editName] as any,
-                    );
-                    this.addressbook[editName] = updated as TMultisigScript;
-                    this.saveSettings();
-                    console.log(`Updated "${editName}".`);
-                  } catch (e) {
-                    if (e instanceof UserCancelledError) return;
-                    throw e;
-                  }
-                },
-              },
-              {
-                title: "Delete entry",
-                action: async () => {
-                  const entries = Object.keys(this.addressbook);
-                  if (entries.length === 0) {
-                    console.log("Addressbook is empty.");
-                    return;
-                  }
-                  const delSelected = await selectCancellable({
-                    message: "Select entry to delete:",
-                    choices: entries.map((n) => ({ name: n, value: n })),
-                  });
-                  if (delSelected === null) return;
-                  const delName = delSelected as string;
-                  const confirmed = await confirmCancellable({
-                    message: `Delete "${delName}"?`,
-                    default: false,
-                  });
-                  if (!confirmed) return;
-                  delete this.addressbook[delName];
-                  this.saveSettings();
-                  console.log(`Deleted "${delName}".`);
-                },
-              },
-            ],
-          } as IMenu<S>,
-        ],
-      };
-      await this._showMenu(settingsMenu, false, [...path, "Settings & Profiles"], true);
+      await this._showMenu(this.buildSettingsMenu(), false, [...path, "Settings & Profiles"], true);
       await this._showMenu(menu, main, path, true);
       return;
     }
@@ -947,6 +1268,42 @@ export class Sprinkle<S extends TSchema> {
     return GetBlazeFn(network, providerSettings, walletSettings);
   }
 
+  /**
+   * Derive a Bip32 private key hex from a BIP39 mnemonic phrase.
+   * Accepts 12, 15, or 24 word phrases.
+   */
+  private static privateKeyFromMnemonic(phrase: string): string {
+    const normalized = phrase.trim().toLowerCase().split(/\s+/).join(" ");
+    const words = normalized.split(" ");
+    if (![12, 15, 24].includes(words.length)) {
+      throw new Error(
+        `Expected 12, 15, or 24 words but got ${words.length}.`,
+      );
+    }
+    const entropy = Core.mnemonicToEntropy(normalized, wordlist);
+    const masterKey = Core.Bip32PrivateKey.fromBip39Entropy(
+      Buffer.from(entropy),
+      "",
+    );
+    return masterKey.hex();
+  }
+
+  /**
+   * Prompt the user for a recovery phrase and derive the Bip32 private key hex.
+   */
+  private static async importWalletFromMnemonic(): Promise<string> {
+    const phrase = await passwordCancellable({
+      message: "Enter your recovery phrase (12, 15, or 24 words):",
+    });
+    if (phrase === null) {
+      throw new UserCancelledError();
+    }
+    if (phrase.trim().length === 0) {
+      throw new Error("Recovery phrase cannot be empty");
+    }
+    return Sprinkle.privateKeyFromMnemonic(phrase);
+  }
+
   /**
    * Generates a new wallet from a BIP39 mnemonic phrase.
    * Displays the 24-word recovery phrase and requires user confirmation.
@@ -1542,6 +1899,9 @@ export class Sprinkle<S extends TSchema> {
       // if the literal field values in the selected variant match those in `def`.
       // For non-discriminated unions, fall back to structural matching with Value.Check.
       let matchedDef: unknown = undefined;
+      // Build references array for Value.Check — schemas with $id from defs
+      // so TypeBox can resolve $ref inside variant schemas (e.g. MultisigScript).
+      const references = Object.values(defs).filter((s) => s.$id) as TSchema[];
       if (def !== undefined) {
         if (isObject(selection)) {
           // Check if all literal fields in the selected variant match def
@@ -1559,13 +1919,13 @@ export class Sprinkle<S extends TSchema> {
             }
           } else {
             // No literal discriminators - use structural check
-            if (Value.Check(selection, def)) {
+            if (Value.Check(selection, references, def)) {
               matchedDef = def;
             }
           }
         } else {
           // Non-object variant - use structural check
-          if (Value.Check(selection, def)) {
+          if (Value.Check(selection, references, def)) {
             matchedDef = def;
           }
         }
@@ -1574,12 +1934,13 @@ export class Sprinkle<S extends TSchema> {
     }
 
     if (isString(type)) {
-      // Special handling for hot wallet private key - offer generation option
+      // Special handling for hot wallet private key - offer multiple sources
       if (type.title === "Hot Wallet Private Key") {
         const choice = await selectWithClear({
           message: "Hot wallet setup:",
           choices: [
             { name: "Enter existing private key", value: "existing" },
+            { name: "Import from recovery phrase", value: "mnemonic" },
             { name: "Generate new wallet", value: "generate" },
           ],
         });
@@ -1590,6 +1951,9 @@ export class Sprinkle<S extends TSchema> {
         if (choice === "generate") {
           return Sprinkle.generateWalletFromMnemonic() as Promise<TExact<U>>;
         }
+        if (choice === "mnemonic") {
+          return Sprinkle.importWalletFromMnemonic() as Promise<TExact<U>>;
+        }
         // Fall through to password prompt for "existing" choice
         const answer = await passwordWithClear({
           message: "Enter your private key:",