@sundaeswap/sprinkles 0.6.1 → 0.8.0

package/src/Sprinkle/actions/builtin/addressbook-actions.ts

@@ -0,0 +1,168 @@
+/**
+ * Built-in addressbook actions for managing named native scripts.
+ *
+ * The addressbook stores MultisigScript entries by name in the profile,
+ * allowing them to be reused across actions and automatically resolved
+ * by script hash during transaction building.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { MultisigScript } from "../../schemas.js";
+import type { TMultisigScript } from "../../schemas.js";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+import { toNativeScript } from "./native-script.js";
+
+/**
+ * `list-addressbook` -- List all entries in the addressbook.
+ */
+export const listAddressbook: IAction<
+  Record<string, never>,
+  { entries: Array<{ name: string; scriptHash: string; script: TMultisigScript }> },
+  TSchema
+> = {
+  name: "list-addressbook",
+  description: "List all named native scripts in the addressbook.",
+  category: "addressbook",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({
+    entries: Type.Array(
+      Type.Object({
+        name: Type.String(),
+        scriptHash: Type.String(),
+        script: MultisigScript,
+      }),
+    ),
+  }),
+  execute: async (_input, context) => {
+    const addressbook = context.sprinkle.addressbook ?? {};
+    const entries = [];
+    for (const [name, ms] of Object.entries(addressbook)) {
+      try {
+        const script = toNativeScript(ms);
+        entries.push({ name, scriptHash: script.hash(), script: ms });
+      } catch {
+        // Include entries even if hash computation fails
+        entries.push({ name, scriptHash: "unknown", script: ms });
+      }
+    }
+    return { entries };
+  },
+};
+
+/**
+ * `set-addressbook-entry` -- Add or update a named native script in the addressbook.
+ */
+export const setAddressbookEntry: IAction<
+  { name: string; script: TMultisigScript },
+  { name: string; scriptHash: string },
+  TSchema
+> = {
+  name: "set-addressbook-entry",
+  description:
+    "Add or update a named native script in the addressbook. Accepts a MultisigScript JSON structure.",
+  category: "addressbook",
+  inputSchema: Type.Object({
+    name: Type.String({
+      minLength: 1,
+      description: "Name for this addressbook entry",
+    }),
+    script: MultisigScript,
+  }),
+  outputSchema: Type.Object({
+    name: Type.String(),
+    scriptHash: Type.String({ description: "Computed script hash" }),
+  }),
+  execute: async (input, context) => {
+    // Validate the script can be converted
+    const blazeScript = toNativeScript(input.script);
+    const scriptHash = blazeScript.hash();
+
+    context.sprinkle.addressbook[input.name] = input.script;
+    context.sprinkle.saveSettings();
+
+    return { name: input.name, scriptHash };
+  },
+};
+
+/**
+ * `delete-addressbook-entry` -- Remove a named native script from the addressbook.
+ */
+export const deleteAddressbookEntry: IAction<
+  { name: string },
+  { deleted: boolean; name: string },
+  TSchema
+> = {
+  name: "delete-addressbook-entry",
+  description: "Remove a named native script from the addressbook.",
+  category: "addressbook",
+  inputSchema: Type.Object({
+    name: Type.String({
+      minLength: 1,
+      description: "Name of the addressbook entry to delete",
+    }),
+  }),
+  outputSchema: Type.Object({
+    deleted: Type.Boolean(),
+    name: Type.String(),
+  }),
+  execute: async (input, context) => {
+    if (!(input.name in context.sprinkle.addressbook)) {
+      throw new ActionError(
+        `Addressbook entry "${input.name}" not found.`,
+        "NOT_FOUND",
+        { name: input.name },
+      );
+    }
+
+    delete context.sprinkle.addressbook[input.name];
+    context.sprinkle.saveSettings();
+
+    return { deleted: true, name: input.name };
+  },
+};
+
+/**
+ * `get-addressbook-entry` -- Get a specific named native script from the addressbook.
+ */
+export const getAddressbookEntry: IAction<
+  { name: string },
+  { name: string; scriptHash: string; script: TMultisigScript },
+  TSchema
+> = {
+  name: "get-addressbook-entry",
+  description: "Get a specific named native script from the addressbook.",
+  category: "addressbook",
+  inputSchema: Type.Object({
+    name: Type.String({
+      minLength: 1,
+      description: "Name of the addressbook entry to retrieve",
+    }),
+  }),
+  outputSchema: Type.Object({
+    name: Type.String(),
+    scriptHash: Type.String(),
+    script: MultisigScript,
+  }),
+  execute: async (input, context) => {
+    const ms = context.sprinkle.addressbook[input.name];
+    if (!ms) {
+      throw new ActionError(
+        `Addressbook entry "${input.name}" not found.`,
+        "NOT_FOUND",
+        { name: input.name },
+      );
+    }
+
+    let scriptHash = "unknown";
+    try {
+      const blazeScript = toNativeScript(ms);
+      scriptHash = blazeScript.hash();
+    } catch {
+      // Return entry even if hash computation fails
+    }
+
+    return { name: input.name, scriptHash, script: ms };
+  },
+};

package/src/Sprinkle/actions/builtin/blaze-helper.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared helper utilities for wallet and transaction actions.
+ * Provides Blaze instance creation from action context settings.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { Blaze, HotWallet } from "@blaze-cardano/sdk";
+import type { Provider } from "@blaze-cardano/query";
+import type { Wallet } from "@blaze-cardano/sdk";
+import { GetBlaze } from "../../wallet.js";
+import { ActionError } from "../types.js";
+import type { IActionContext } from "../types.js";
+import type {
+  NetworkSchema,
+  ProviderSettingsSchema,
+  WalletSettingsSchema,
+} from "../../schemas.js";
+import type { TExact } from "../../types.js";
+
+/** Settings shape expected on context.settings for wallet access */
+export interface IWalletSettings {
+  network?: TExact<typeof NetworkSchema>;
+  provider?: TExact<typeof ProviderSettingsSchema>;
+  wallet?: TExact<typeof WalletSettingsSchema>;
+}
+
+/** Optional overrides for Blaze initialization, in case field names differ */
+export interface IBlazeOverrides {
+  network?: TExact<typeof NetworkSchema>;
+  provider?: TExact<typeof ProviderSettingsSchema>;
+  wallet?: TExact<typeof WalletSettingsSchema>;
+}
+
+/**
+ * Creates a Blaze instance from action context settings.
+ *
+ * Falls back to `context.settings.network`, `context.settings.provider`,
+ * and `context.settings.wallet` when overrides are not provided.
+ *
+ * @throws `ActionError("WALLET_NOT_CONFIGURED")` if required settings are missing
+ * @throws `ActionError("BLAZE_INIT_ERROR")` if Blaze fails to initialize
+ */
+export async function getBlazeFromContext<S extends TSchema>(
+  context: IActionContext<S>,
+  overrides?: IBlazeOverrides,
+): Promise<Blaze<Provider, Wallet>> {
+  const settings = context.settings as unknown as IWalletSettings;
+
+  const network = overrides?.network ?? settings.network;
+  const provider = overrides?.provider ?? settings.provider;
+  const wallet = overrides?.wallet ?? settings.wallet;
+
+  // Validate required fields and collect missing ones for a helpful error message
+  const missing: string[] = [];
+  if (!network) missing.push("network");
+  if (!provider) missing.push("provider");
+  if (!wallet) missing.push("wallet");
+
+  if (missing.length > 0) {
+    throw new ActionError(
+      `Wallet is not configured. Missing settings: ${missing.join(", ")}. ` +
+        `Set these fields in your profile settings before using wallet actions.`,
+      "WALLET_NOT_CONFIGURED",
+      { missingFields: missing },
+    );
+  }
+
+  try {
+    return await GetBlaze(
+      network as TExact<typeof NetworkSchema>,
+      provider as TExact<typeof ProviderSettingsSchema>,
+      wallet as TExact<typeof WalletSettingsSchema>,
+    );
+  } catch (err) {
+    throw new ActionError(
+      `Failed to initialize Blaze wallet: ${err instanceof Error ? err.message : String(err)}`,
+      "BLAZE_INIT_ERROR",
+      { error: err instanceof Error ? err.message : String(err) },
+    );
+  }
+}
+
+/**
+ * Checks whether the wallet in a Blaze instance is a hot wallet.
+ * Cold wallets cannot sign transactions.
+ */
+export function isHotWallet(blaze: Blaze<Provider, Wallet>): boolean {
+  return blaze.wallet instanceof HotWallet;
+}

package/src/Sprinkle/actions/builtin/index.ts

@@ -0,0 +1,125 @@
+/**
+ * Barrel export for built-in Sprinkle actions.
+ *
+ * Provides a `getBuiltinActions()` factory that returns all 17 built-in actions
+ * ready for registration on an ActionRegistry.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { AnyAction } from "../types.js";
+
+export {
+  listProfiles,
+  getProfile,
+  setProfile,
+  createProfile,
+  deleteProfile,
+} from "./profile-actions.js";
+
+export { getSettings, updateSettings } from "./settings-actions.js";
+
+export {
+  getWalletAddress,
+  getWalletBalance,
+  getWalletUtxos,
+} from "./wallet-actions.js";
+
+export {
+  signTransaction,
+  submitTransaction,
+  signAndSubmit,
+  decodeTransaction,
+} from "./transaction-actions.js";
+
+export {
+  mintToken,
+  simpleSend,
+  registerStakeScript,
+} from "./utility-actions.js";
+
+export {
+  toNativeScript,
+  completeWithScripts,
+} from "./native-script.js";
+export type { NativeScriptInput } from "./native-script.js";
+
+export {
+  listAddressbook,
+  getAddressbookEntry,
+  setAddressbookEntry,
+  deleteAddressbookEntry,
+} from "./addressbook-actions.js";
+
+import {
+  listProfiles,
+  getProfile,
+  setProfile,
+  createProfile,
+  deleteProfile,
+} from "./profile-actions.js";
+
+import { getSettings, updateSettings } from "./settings-actions.js";
+
+import {
+  getWalletAddress,
+  getWalletBalance,
+  getWalletUtxos,
+} from "./wallet-actions.js";
+
+import {
+  signTransaction,
+  submitTransaction,
+  signAndSubmit,
+  decodeTransaction,
+} from "./transaction-actions.js";
+
+import {
+  mintToken,
+  simpleSend,
+  registerStakeScript,
+} from "./utility-actions.js";
+
+import {
+  listAddressbook,
+  getAddressbookEntry,
+  setAddressbookEntry,
+  deleteAddressbookEntry,
+} from "./addressbook-actions.js";
+
+/**
+ * Returns all built-in Sprinkle actions.
+ * Register them on your ActionRegistry or pass them to `Sprinkle.run()`.
+ *
+ * @example
+ * ```ts
+ * const sprinkle = new Sprinkle(MySchema, storagePath);
+ * for (const action of getBuiltinActions()) {
+ *   sprinkle.registerAction(action);
+ * }
+ * ```
+ */
+export function getBuiltinActions<S extends TSchema>(): AnyAction<S>[] {
+  return [
+    listProfiles,
+    getProfile,
+    setProfile,
+    createProfile,
+    deleteProfile,
+    getSettings,
+    updateSettings,
+    getWalletAddress,
+    getWalletBalance,
+    getWalletUtxos,
+    signTransaction,
+    submitTransaction,
+    signAndSubmit,
+    decodeTransaction,
+    mintToken,
+    simpleSend,
+    registerStakeScript,
+    listAddressbook,
+    getAddressbookEntry,
+    setAddressbookEntry,
+    deleteAddressbookEntry,
+  ] as unknown as AnyAction<S>[];
+}

package/src/Sprinkle/actions/builtin/native-script.ts

@@ -0,0 +1,165 @@
+/**
+ * Native script utilities for Sprinkle actions.
+ *
+ * Provides conversion from user-friendly input formats (CBOR hex or structured JSON)
+ * to Blaze NativeScript objects, and a helper to attach scripts during tx completion.
+ */
+
+import { Core } from "@blaze-cardano/sdk";
+import type { TxBuilder } from "@blaze-cardano/tx";
+import type { TSchema } from "@sinclair/typebox";
+import type { TMultisigScript } from "../../schemas.js";
+import { ActionError } from "../types.js";
+import type { IActionContext } from "../types.js";
+
+/** Input type: either a CBOR hex string or a MultisigScript JSON structure */
+export type NativeScriptInput = string | TMultisigScript;
+
+/**
+ * Converts a MultisigScript JSON structure to a Blaze NativeScript.
+ * Handles the recursive structure (AllOf, AnyOf, AtLeast contain nested scripts).
+ */
+function multisigToNativeScript(ms: TMultisigScript): Core.NativeScript {
+  if ("Signature" in ms) {
+    const hash = Core.Ed25519KeyHashHex(ms.Signature.key_hash);
+    return Core.NativeScript.newScriptPubkey(new Core.ScriptPubkey(hash));
+  }
+  if ("AllOf" in ms) {
+    const scripts = ms.AllOf.scripts.map(multisigToNativeScript);
+    return Core.NativeScript.newScriptAll(new Core.ScriptAll(scripts));
+  }
+  if ("AnyOf" in ms) {
+    const scripts = ms.AnyOf.scripts.map(multisigToNativeScript);
+    return Core.NativeScript.newScriptAny(new Core.ScriptAny(scripts));
+  }
+  if ("AtLeast" in ms) {
+    const scripts = ms.AtLeast.scripts.map(multisigToNativeScript);
+    return Core.NativeScript.newScriptNOfK(
+      new Core.ScriptNOfK(scripts, Number(ms.AtLeast.required)),
+    );
+  }
+  if ("Before" in ms) {
+    return Core.NativeScript.newTimelockExpiry(
+      new Core.TimelockExpiry(Core.Slot(Number(ms.Before.time))),
+    );
+  }
+  if ("After" in ms) {
+    return Core.NativeScript.newTimelockStart(
+      new Core.TimelockStart(Core.Slot(Number(ms.After.time))),
+    );
+  }
+  if ("Script" in ms) {
+    // Script variant references a script by hash — this is a ScriptPubkey
+    // but using the script hash directly as a key hash reference
+    const hash = Core.Ed25519KeyHashHex(ms.Script.script_hash);
+    return Core.NativeScript.newScriptPubkey(new Core.ScriptPubkey(hash));
+  }
+
+  throw new ActionError(
+    "Unrecognized MultisigScript variant",
+    "INVALID_NATIVE_SCRIPT",
+    { input: ms },
+  );
+}
+
+/**
+ * Converts a native script input (CBOR hex string or MultisigScript JSON)
+ * to a Blaze Script object suitable for `provideScript()`.
+ */
+export function toNativeScript(input: NativeScriptInput): Core.Script {
+  if (typeof input === "string") {
+    try {
+      const nativeScript = Core.NativeScript.fromCbor(
+        Core.HexBlob(input),
+      );
+      return Core.Script.newNativeScript(nativeScript);
+    } catch (err) {
+      throw new ActionError(
+        `Invalid native script CBOR: ${err instanceof Error ? err.message : String(err)}`,
+        "INVALID_NATIVE_SCRIPT",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+  }
+
+  try {
+    const nativeScript = multisigToNativeScript(input);
+    return Core.Script.newNativeScript(nativeScript);
+  } catch (err) {
+    if (err instanceof ActionError) throw err;
+    throw new ActionError(
+      `Failed to convert MultisigScript to native script: ${err instanceof Error ? err.message : String(err)}`,
+      "INVALID_NATIVE_SCRIPT",
+      { error: err instanceof Error ? err.message : String(err) },
+    );
+  }
+}
+
+/** Regex to extract a script hash from Blaze's "Could not resolve script hash" error */
+const MISSING_SCRIPT_HASH_RE =
+  /complete: Could not resolve script hash[: ]*([0-9a-fA-F]+)/;
+
+/**
+ * Builds a hash → Script lookup from the addressbook in the sprinkle context.
+ * Returns an empty map if there's no addressbook.
+ */
+function buildAddressbookIndex(
+  addressbook: Record<string, TMultisigScript> | undefined,
+): Map<string, Core.Script> {
+  const index = new Map<string, Core.Script>();
+  if (!addressbook) return index;
+  for (const [, ms] of Object.entries(addressbook)) {
+    try {
+      const script = toNativeScript(ms);
+      index.set(script.hash(), script);
+    } catch {
+      // Skip invalid addressbook entries
+    }
+  }
+  return index;
+}
+
+/**
+ * Attaches optional native scripts to a transaction builder and completes it.
+ *
+ * If completion fails because Blaze cannot resolve a required native script hash,
+ * and a context with an addressbook is provided, it will look up the missing script
+ * by hash in the addressbook and retry once.
+ */
+export async function completeWithScripts<S extends TSchema>(
+  txBuilder: TxBuilder,
+  nativeScripts?: NativeScriptInput[],
+  context?: IActionContext<S>,
+): Promise<Core.Transaction> {
+  if (nativeScripts?.length) {
+    for (const input of nativeScripts) {
+      txBuilder.provideScript(toNativeScript(input));
+    }
+  }
+
+  try {
+    return await txBuilder.complete();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const match = message.match(MISSING_SCRIPT_HASH_RE);
+
+    if (!match || !context?.sprinkle?.addressbook) {
+      throw err;
+    }
+
+    // Build hash index from addressbook and try to resolve the missing script
+    const addressbookIndex = buildAddressbookIndex(
+      context.sprinkle.addressbook,
+    );
+    const missingHash = match[1];
+    const script = addressbookIndex.get(missingHash);
+
+    if (!script) {
+      throw err;
+    }
+
+    // Attach the found script and retry
+    txBuilder.provideScript(script);
+    return txBuilder.complete();
+  }
+}