@sundaeswap/sprinkles 0.7.0 → 0.8.0

package/src/Sprinkle/__tests__/utility-actions.test.ts

@@ -0,0 +1,348 @@
+import { describe, expect, test, mock, beforeEach } from "bun:test";
+import { ActionError } from "../actions/types.js";
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+// Controllable mock state
+let mockBlaze: any = {};
+let mockIsHot = true;
+let mockBlazeError: Error | null = null;
+
+mock.module("../actions/builtin/blaze-helper.js", () => ({
+  getBlazeFromContext: async () => {
+    if (mockBlazeError) throw mockBlazeError;
+    return mockBlaze;
+  },
+  isHotWallet: () => mockIsHot,
+}));
+
+// Track calls to blaze transaction builder
+let mintCalls: Array<{ policyId: string; mints: Map<string, bigint> }> = [];
+let provideScriptCalls: any[] = [];
+let payAssetsCalls: Array<{ address: any; value: any }> = [];
+let registerStakeCalls: any[] = [];
+
+// Mock transaction returned by complete()
+const mockCompletedTx = {
+  toCbor: () => "mock-tx-cbor-hex",
+};
+
+// Mock transaction builder chain
+function makeTxBuilder() {
+  return {
+    addMint: (policyId: string, mints: Map<string, bigint>) => {
+      mintCalls.push({ policyId, mints });
+      return makeTxBuilder();
+    },
+    provideScript: (script: any) => {
+      provideScriptCalls.push(script);
+      return makeTxBuilder();
+    },
+    payAssets: (address: any, value: any) => {
+      payAssetsCalls.push({ address, value });
+      return makeTxBuilder();
+    },
+    addRegisterStake: (credential: any) => {
+      registerStakeCalls.push(credential);
+      return makeTxBuilder();
+    },
+    complete: async () => mockCompletedTx,
+  };
+}
+
+// Mock address with payment credential
+function makeMockAddress(hash = "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234") {
+  return {
+    toBech32: () => "addr_test1qzmock",
+    asBase: () => ({
+      getPaymentCredential: () => ({
+        hash: { toString: () => hash },
+      }),
+    }),
+  };
+}
+
+mock.module("@blaze-cardano/sdk", () => ({
+  Core: {
+    Ed25519KeyHashHex: (h: string) => h,
+    ScriptPubkey: class {
+      hash: string;
+      constructor(h: string) { this.hash = h; }
+    },
+    Script: {
+      newNativeScript: (ns: any) => ({
+        hash: () => "mock-policy-id-hash",
+      }),
+    },
+    NativeScript: {
+      newScriptPubkey: (sp: any) => sp,
+    },
+    PolicyId: (s: string) => s,
+    AssetName: (s: string) => s,
+    toHex: (buf: Buffer) => buf.toString("hex"),
+    Address: {
+      fromBech32: (addr: string) => {
+        if (addr === "invalid-address") throw new Error("Invalid bech32");
+        return { toBech32: () => addr };
+      },
+    },
+    TxCBOR: (s: string) => s,
+    Hash28ByteBase16: (s: string) => s,
+    Credential: {
+      fromCore: (c: any) => c,
+    },
+    CredentialType: {
+      ScriptHash: 1,
+    },
+  },
+  makeValue: (...args: any[]) => ({ __makeValueArgs: args }),
+  Blaze: class {},
+  HotWallet: class {},
+}));
+
+// Import actions after mocks are set up
+const { mintToken, simpleSend, registerStakeScript } = await import(
+  "../actions/builtin/utility-actions.js"
+);
+
+// Minimal context factory
+function makeContext(settingsOverrides: Record<string, unknown> = {}) {
+  return {
+    sprinkle: {} as any,
+    settings: {
+      network: "preview",
+      provider: { type: "blockfrost", apiKey: "test" },
+      wallet: { type: "hot", mnemonic: "test words" },
+      ...settingsOverrides,
+    } as any,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// mint-token
+// ---------------------------------------------------------------------------
+
+describe("mint-token", () => {
+  beforeEach(() => {
+    mockBlazeError = null;
+    mockIsHot = true;
+    mintCalls = [];
+    provideScriptCalls = [];
+    mockBlaze = {
+      wallet: {
+        getChangeAddress: async () => makeMockAddress(),
+      },
+      newTransaction: () => makeTxBuilder(),
+    };
+  });
+
+  test("has correct metadata", () => {
+    expect(mintToken.name).toBe("mint-token");
+    expect(mintToken.category).toBe("utility");
+  });
+
+  test("builds a mint transaction and returns policy info", async () => {
+    const ctx = makeContext();
+    const result = await mintToken.execute(
+      { tokenName: "MyToken", amount: "1000" },
+      ctx,
+    );
+    expect(result.policyId).toBe("mock-policy-id-hash");
+    expect(result.tokenName).toBe("MyToken");
+    expect(result.amount).toBe("1000");
+    expect(result.txCbor).toBe("mock-tx-cbor-hex");
+    expect(mintCalls).toHaveLength(1);
+    expect(provideScriptCalls).toHaveLength(1);
+  });
+
+  test("throws COLD_WALLET when wallet is not hot", async () => {
+    mockIsHot = false;
+    const ctx = makeContext();
+    await expect(
+      mintToken.execute({ tokenName: "T", amount: "1" }, ctx),
+    ).rejects.toMatchObject({ code: "COLD_WALLET" });
+  });
+
+  test("throws WALLET_NOT_CONFIGURED when blaze init fails", async () => {
+    mockBlazeError = new ActionError(
+      "Missing settings",
+      "WALLET_NOT_CONFIGURED",
+      { missingFields: ["wallet"] },
+    );
+    const ctx = makeContext();
+    await expect(
+      mintToken.execute({ tokenName: "T", amount: "1" }, ctx),
+    ).rejects.toMatchObject({ code: "WALLET_NOT_CONFIGURED" });
+  });
+
+  test("throws NO_ADDRESS when getChangeAddress fails", async () => {
+    mockBlaze = {
+      wallet: {
+        getChangeAddress: async () => {
+          throw new Error("no address");
+        },
+      },
+      newTransaction: () => makeTxBuilder(),
+    };
+    const ctx = makeContext();
+    await expect(
+      mintToken.execute({ tokenName: "T", amount: "1" }, ctx),
+    ).rejects.toMatchObject({ code: "NO_ADDRESS" });
+  });
+
+  test("throws INVALID_ADDRESS when base address is null", async () => {
+    mockBlaze = {
+      wallet: {
+        getChangeAddress: async () => ({
+          toBech32: () => "addr_test1...",
+          asBase: () => null,
+        }),
+      },
+      newTransaction: () => makeTxBuilder(),
+    };
+    const ctx = makeContext();
+    await expect(
+      mintToken.execute({ tokenName: "T", amount: "1" }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_ADDRESS" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// simple-send
+// ---------------------------------------------------------------------------
+
+describe("simple-send", () => {
+  beforeEach(() => {
+    mockBlazeError = null;
+    mockIsHot = true;
+    payAssetsCalls = [];
+    mockBlaze = {
+      newTransaction: () => makeTxBuilder(),
+    };
+  });
+
+  test("has correct metadata", () => {
+    expect(simpleSend.name).toBe("simple-send");
+    expect(simpleSend.category).toBe("wallet");
+  });
+
+  test("builds a lovelace-only send transaction", async () => {
+    const ctx = makeContext();
+    const result = await simpleSend.execute(
+      { recipientAddress: "addr_test1qzrecipient", lovelace: "5000000" },
+      ctx,
+    );
+    expect(result.txCbor).toBe("mock-tx-cbor-hex");
+    expect(payAssetsCalls).toHaveLength(1);
+  });
+
+  test("builds a token send transaction", async () => {
+    const ctx = makeContext();
+    const result = await simpleSend.execute(
+      {
+        recipientAddress: "addr_test1qzrecipient",
+        policyId: "a".repeat(56),
+        assetName: "4d79546f6b656e",
+        tokenAmount: "100",
+      },
+      ctx,
+    );
+    expect(result.txCbor).toBe("mock-tx-cbor-hex");
+    expect(payAssetsCalls).toHaveLength(1);
+  });
+
+  test("throws INVALID_INPUT when neither lovelace nor token provided", async () => {
+    const ctx = makeContext();
+    await expect(
+      simpleSend.execute({ recipientAddress: "addr_test1qzrecipient" }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  test("throws INVALID_ADDRESS for bad recipient", async () => {
+    const ctx = makeContext();
+    await expect(
+      simpleSend.execute(
+        { recipientAddress: "invalid-address", lovelace: "1000000" },
+        ctx,
+      ),
+    ).rejects.toMatchObject({ code: "INVALID_ADDRESS" });
+  });
+
+  test("throws WALLET_NOT_CONFIGURED when blaze init fails", async () => {
+    mockBlazeError = new ActionError(
+      "Missing settings",
+      "WALLET_NOT_CONFIGURED",
+      { missingFields: ["wallet"] },
+    );
+    const ctx = makeContext();
+    await expect(
+      simpleSend.execute(
+        { recipientAddress: "addr_test1qz", lovelace: "1000000" },
+        ctx,
+      ),
+    ).rejects.toMatchObject({ code: "WALLET_NOT_CONFIGURED" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// register-stake-script
+// ---------------------------------------------------------------------------
+
+describe("register-stake-script", () => {
+  beforeEach(() => {
+    mockBlazeError = null;
+    mockIsHot = true;
+    registerStakeCalls = [];
+    mockBlaze = {
+      newTransaction: () => makeTxBuilder(),
+    };
+  });
+
+  test("has correct metadata", () => {
+    expect(registerStakeScript.name).toBe("register-stake-script");
+    expect(registerStakeScript.category).toBe("utility");
+  });
+
+  test("builds a stake registration transaction", async () => {
+    const validHash = "a".repeat(56);
+    const ctx = makeContext();
+    const result = await registerStakeScript.execute(
+      { scriptHash: validHash },
+      ctx,
+    );
+    expect(result.txCbor).toBe("mock-tx-cbor-hex");
+    expect(registerStakeCalls).toHaveLength(1);
+    expect(registerStakeCalls[0]).toMatchObject({
+      hash: validHash,
+      type: 1, // ScriptHash
+    });
+  });
+
+  test("throws INVALID_SCRIPT_HASH for wrong length", async () => {
+    const ctx = makeContext();
+    await expect(
+      registerStakeScript.execute({ scriptHash: "tooshort" }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_SCRIPT_HASH" });
+  });
+
+  test("throws INVALID_SCRIPT_HASH for non-hex characters", async () => {
+    const ctx = makeContext();
+    await expect(
+      registerStakeScript.execute({ scriptHash: "g".repeat(56) }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_SCRIPT_HASH" });
+  });
+
+  test("throws WALLET_NOT_CONFIGURED when blaze init fails", async () => {
+    mockBlazeError = new ActionError(
+      "Missing settings",
+      "WALLET_NOT_CONFIGURED",
+      { missingFields: ["provider"] },
+    );
+    const ctx = makeContext();
+    await expect(
+      registerStakeScript.execute({ scriptHash: "a".repeat(56) }, ctx),
+    ).rejects.toMatchObject({ code: "WALLET_NOT_CONFIGURED" });
+  });
+});

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/index.ts

@@ -1,7 +1,7 @@
 /**
  * Barrel export for built-in Sprinkle actions.
  *
- * Provides a `getBuiltinActions()` factory that returns all 14 built-in actions
+ * Provides a `getBuiltinActions()` factory that returns all 17 built-in actions
  * ready for registration on an ActionRegistry.
  */
 
@@ -31,6 +31,25 @@ export {
   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,
@@ -54,8 +73,21 @@ import {
   decodeTransaction,
 } from "./transaction-actions.js";
 
+import {
+  mintToken,
+  simpleSend,
+  registerStakeScript,
+} from "./utility-actions.js";
+
+import {
+  listAddressbook,
+  getAddressbookEntry,
+  setAddressbookEntry,
+  deleteAddressbookEntry,
+} from "./addressbook-actions.js";
+
 /**
- * Returns an array of all 14 built-in Sprinkle actions.
+ * Returns all built-in Sprinkle actions.
  * Register them on your ActionRegistry or pass them to `Sprinkle.run()`.
  *
  * @example
@@ -82,5 +114,12 @@ export function getBuiltinActions<S extends TSchema>(): AnyAction<S>[] {
     submitTransaction,
     signAndSubmit,
     decodeTransaction,
+    mintToken,
+    simpleSend,
+    registerStakeScript,
+    listAddressbook,
+    getAddressbookEntry,
+    setAddressbookEntry,
+    deleteAddressbookEntry,
   ] as unknown as AnyAction<S>[];
 }