@sundaeswap/sprinkles 0.6.1 → 0.8.0

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

@@ -0,0 +1,285 @@
+/**
+ * Built-in utility actions for the Sprinkle action system.
+ * These actions provide common Cardano operations: minting tokens,
+ * sending ADA/tokens, and registering stake scripts.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { Core, makeValue } from "@blaze-cardano/sdk";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+import { getBlazeFromContext, isHotWallet } from "./blaze-helper.js";
+import { NativeScriptsParam } from "../../schemas.js";
+import type { NativeScriptInput } from "./native-script.js";
+import { completeWithScripts } from "./native-script.js";
+
+/**
+ * `mint-token` -- Mint native tokens using a native script derived from the wallet's payment key.
+ * The policy is a simple ScriptPubkey requiring the wallet's payment credential to sign.
+ * Requires a hot wallet.
+ */
+export const mintToken: IAction<
+  { tokenName: string; amount: string; nativeScripts?: NativeScriptInput[] },
+  { policyId: string; tokenName: string; amount: string; txCbor: string },
+  TSchema
+> = {
+  name: "mint-token",
+  description:
+    "Mint native tokens using a native script policy derived from the wallet's payment key.",
+  category: "utility",
+  inputSchema: Type.Object({
+    tokenName: Type.String({ description: "Name of the token to mint" }),
+    amount: Type.String({
+      description: "Amount of tokens to mint (as string for BigInt safety)",
+    }),
+    nativeScripts: NativeScriptsParam,
+  }),
+  outputSchema: Type.Object({
+    policyId: Type.String({ description: "Policy ID of the minted token" }),
+    tokenName: Type.String({ description: "Token name" }),
+    amount: Type.String({ description: "Amount minted" }),
+    txCbor: Type.String({
+      description: "Unsigned transaction CBOR hex ready for signing",
+    }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    if (!isHotWallet(blaze)) {
+      throw new ActionError(
+        "Mint token requires a hot wallet to derive the native script policy.",
+        "COLD_WALLET",
+      );
+    }
+
+    // Get the wallet's payment credential hash for the native script
+    let address: Core.Address;
+    try {
+      address = await blaze.wallet.getChangeAddress();
+    } catch (err) {
+      throw new ActionError(
+        `Failed to get wallet address: ${err instanceof Error ? err.message : String(err)}`,
+        "NO_ADDRESS",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    const baseAddress = address.asBase();
+    if (!baseAddress) {
+      throw new ActionError(
+        "Could not derive base address from wallet. Ensure the wallet has a payment credential.",
+        "INVALID_ADDRESS",
+      );
+    }
+
+    const paymentCredential = baseAddress.getPaymentCredential();
+    if (!paymentCredential?.hash) {
+      throw new ActionError(
+        "Could not extract payment credential hash from wallet address.",
+        "NO_PAYMENT_CREDENTIAL",
+      );
+    }
+
+    const hash = Core.Ed25519KeyHashHex(paymentCredential.hash.toString());
+    const tokenPolicy = new Core.ScriptPubkey(hash);
+    const policy = Core.Script.newNativeScript(
+      Core.NativeScript.newScriptPubkey(tokenPolicy),
+    );
+
+    const policyId = policy.hash();
+    const assetName = Core.AssetName(
+      Core.toHex(Buffer.from(input.tokenName)),
+    );
+    const mintAmount = BigInt(input.amount);
+
+    const mints = new Map<Core.AssetName, bigint>();
+    mints.set(assetName, mintAmount);
+
+    let tx: Core.Transaction;
+    try {
+      const txBuilder = blaze
+        .newTransaction()
+        .addMint(Core.PolicyId(policyId), mints)
+        .provideScript(policy);
+      tx = await completeWithScripts(txBuilder, input.nativeScripts, context);
+    } catch (err) {
+      if (err instanceof ActionError) throw err;
+      throw new ActionError(
+        `Failed to build mint transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "BUILD_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      policyId: policyId.toString(),
+      tokenName: input.tokenName,
+      amount: input.amount,
+      txCbor: tx.toCbor(),
+    };
+  },
+};
+
+/**
+ * `simple-send` -- Send ADA or a native token to a recipient address.
+ * Builds an unsigned transaction that can be signed via TxDialog or sign-transaction.
+ */
+export const simpleSend: IAction<
+  {
+    recipientAddress: string;
+    lovelace?: string;
+    policyId?: string;
+    assetName?: string;
+    tokenAmount?: string;
+    nativeScripts?: NativeScriptInput[];
+  },
+  { txCbor: string },
+  TSchema
+> = {
+  name: "simple-send",
+  description: "Send ADA or a native token to a recipient address.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    recipientAddress: Type.String({
+      description: "Bech32 recipient address",
+    }),
+    lovelace: Type.Optional(
+      Type.String({
+        description:
+          "Amount of lovelace to send (as string for BigInt safety). Required if not sending a token.",
+      }),
+    ),
+    policyId: Type.Optional(
+      Type.String({ description: "Policy ID of the token to send" }),
+    ),
+    assetName: Type.Optional(
+      Type.String({
+        description: "Asset name of the token to send (hex-encoded)",
+      }),
+    ),
+    tokenAmount: Type.Optional(
+      Type.String({
+        description: "Amount of tokens to send (as string for BigInt safety)",
+      }),
+    ),
+    nativeScripts: NativeScriptsParam,
+  }),
+  outputSchema: Type.Object({
+    txCbor: Type.String({
+      description: "Unsigned transaction CBOR hex ready for signing",
+    }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    // Validate: must provide lovelace or token details
+    const hasToken = input.policyId && input.assetName && input.tokenAmount;
+    if (!input.lovelace && !hasToken) {
+      throw new ActionError(
+        "Must provide either lovelace amount or token details (policyId, assetName, tokenAmount).",
+        "INVALID_INPUT",
+      );
+    }
+
+    let recipient: Core.Address;
+    try {
+      recipient = Core.Address.fromBech32(input.recipientAddress);
+    } catch (err) {
+      throw new ActionError(
+        `Invalid recipient address: ${err instanceof Error ? err.message : String(err)}`,
+        "INVALID_ADDRESS",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    let value: Core.Value;
+    if (hasToken) {
+      const assetId =
+        `${input.policyId}${input.assetName}` as Core.AssetId;
+      value = makeValue(
+        BigInt(input.lovelace ?? "0"),
+        [assetId, BigInt(input.tokenAmount!)],
+      );
+    } else {
+      value = makeValue(BigInt(input.lovelace!));
+    }
+
+    let tx: Core.Transaction;
+    try {
+      const txBuilder = blaze.newTransaction().payAssets(recipient, value);
+      tx = await completeWithScripts(txBuilder, input.nativeScripts, context);
+    } catch (err) {
+      if (err instanceof ActionError) throw err;
+      throw new ActionError(
+        `Failed to build send transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "BUILD_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      txCbor: tx.toCbor(),
+    };
+  },
+};
+
+/**
+ * `register-stake-script` -- Register a stake script credential on-chain.
+ * Takes a script hash and builds a stake registration transaction.
+ */
+export const registerStakeScript: IAction<
+  { scriptHash: string; nativeScripts?: NativeScriptInput[] },
+  { txCbor: string },
+  TSchema
+> = {
+  name: "register-stake-script",
+  description:
+    "Register a stake script credential on-chain. Takes a script hash (hex) and builds the registration transaction.",
+  category: "utility",
+  inputSchema: Type.Object({
+    scriptHash: Type.String({
+      description: "Stake script hash in hex (28 bytes / 56 hex characters)",
+    }),
+    nativeScripts: NativeScriptsParam,
+  }),
+  outputSchema: Type.Object({
+    txCbor: Type.String({
+      description: "Unsigned transaction CBOR hex ready for signing",
+    }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    // Validate hex format
+    if (!/^[0-9a-fA-F]{56}$/.test(input.scriptHash)) {
+      throw new ActionError(
+        "Script hash must be exactly 56 hex characters (28 bytes).",
+        "INVALID_SCRIPT_HASH",
+        { provided: input.scriptHash },
+      );
+    }
+
+    const credential = Core.Credential.fromCore({
+      hash: Core.Hash28ByteBase16(input.scriptHash),
+      type: Core.CredentialType.ScriptHash,
+    });
+
+    let tx: Core.Transaction;
+    try {
+      const txBuilder = blaze.newTransaction().addRegisterStake(credential);
+      tx = await completeWithScripts(txBuilder, input.nativeScripts, context);
+    } catch (err) {
+      if (err instanceof ActionError) throw err;
+      throw new ActionError(
+        `Failed to build stake registration transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "BUILD_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      txCbor: tx.toCbor(),
+    };
+  },
+};

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

@@ -0,0 +1,233 @@
+/**
+ * Built-in wallet query actions for the Sprinkle action system.
+ * These actions expose wallet address, balance, and UTxO queries as
+ * non-interactive actions available in CLI and MCP modes.
+ *
+ * All actions use category "wallet".
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { Core } from "@blaze-cardano/sdk";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+import { getBlazeFromContext } from "./blaze-helper.js";
+
+/** Shared token entry shape for balance and UTxO output */
+const TokenEntrySchema = Type.Object({
+  policyId: Type.String({ description: "Policy ID of the token" }),
+  assetName: Type.String({ description: "Asset name of the token (hex)" }),
+  quantity: Type.String({ description: "Token quantity as string (BigInt-safe)" }),
+});
+
+/**
+ * `get-wallet-address` -- Returns the primary change address of the configured wallet.
+ */
+export const getWalletAddress: IAction<
+  Record<string, never>,
+  { address: string; network: string },
+  TSchema
+> = {
+  name: "get-wallet-address",
+  description: "Get the primary address of the configured wallet.",
+  category: "wallet",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({
+    address: Type.String({ description: "Bech32-encoded payment/change address" }),
+    network: Type.String({ description: "Network name (mainnet, preview, preprod)" }),
+  }),
+  execute: async (_input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    let address: Core.Address;
+    try {
+      address = await blaze.wallet.getChangeAddress();
+    } catch (err) {
+      throw new ActionError(
+        `Failed to get wallet address: ${err instanceof Error ? err.message : String(err)}`,
+        "NO_ADDRESS",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    if (!address) {
+      throw new ActionError(
+        "The wallet returned no address. Ensure the wallet is properly configured.",
+        "NO_ADDRESS",
+      );
+    }
+
+    const settings = context.settings as unknown as { network?: string };
+    const network = settings.network ?? "unknown";
+
+    return {
+      address: address.toBech32(),
+      network,
+    };
+  },
+};
+
+/**
+ * `get-wallet-balance` -- Returns the ADA and token balance of the configured wallet.
+ * Aggregates lovelace and multi-asset amounts from all UTxOs.
+ * All quantities are returned as strings for BigInt-safe JSON serialization.
+ */
+export const getWalletBalance: IAction<
+  Record<string, never>,
+  {
+    lovelace: string;
+    ada: string;
+    tokens: Array<{ policyId: string; assetName: string; quantity: string }>;
+  },
+  TSchema
+> = {
+  name: "get-wallet-balance",
+  description:
+    "Get the ADA and token balance of the configured wallet. Quantities returned as strings.",
+  category: "wallet",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({
+    lovelace: Type.String({
+      description: "Total ADA balance in lovelace (as string for BigInt safety)",
+    }),
+    ada: Type.String({ description: "Total ADA balance as decimal string" }),
+    tokens: Type.Array(TokenEntrySchema),
+  }),
+  execute: async (_input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    let utxos: Awaited<ReturnType<typeof blaze.wallet.getUnspentOutputs>>;
+    try {
+      utxos = await blaze.wallet.getUnspentOutputs();
+    } catch (err) {
+      throw new ActionError(
+        `Provider error while fetching UTxOs: ${err instanceof Error ? err.message : String(err)}`,
+        "PROVIDER_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    // Aggregate lovelace and token amounts
+    let totalLovelace = 0n;
+    const tokenMap = new Map<string, bigint>(); // key: `${policyId}.${assetName}`
+
+    for (const utxo of utxos) {
+      const value = utxo.output().amount();
+      totalLovelace += value.coin();
+
+      const multiasset = value.multiasset();
+      if (multiasset) {
+        for (const [assetId, quantity] of multiasset.entries()) {
+          const policyId = Core.AssetId.getPolicyId(assetId);
+          const assetName = Core.AssetId.getAssetName(assetId);
+          const key = `${policyId}.${assetName}`;
+          tokenMap.set(key, (tokenMap.get(key) ?? 0n) + quantity);
+        }
+      }
+    }
+
+    // Convert tokens map to array, serializing BigInt quantities as strings
+    const tokens = Array.from(tokenMap.entries()).map(([key, quantity]) => {
+      const [policyId, assetName] = key.split(".");
+      return {
+        policyId: policyId ?? "",
+        assetName: assetName ?? "",
+        quantity: quantity.toString(),
+      };
+    });
+
+    // ADA = lovelace / 1_000_000, with 6 decimal places
+    const adaWhole = totalLovelace / 1_000_000n;
+    const adaFraction = totalLovelace % 1_000_000n;
+    const ada = `${adaWhole}.${adaFraction.toString().padStart(6, "0")}`;
+
+    return {
+      lovelace: totalLovelace.toString(),
+      ada,
+      tokens,
+    };
+  },
+};
+
+/**
+ * `get-wallet-utxos` -- Returns raw UTxO set for the configured wallet.
+ * Accepts an optional limit (default 100). Returns UTxOs and the total count.
+ */
+export const getWalletUtxos: IAction<
+  { limit?: number },
+  {
+    utxos: Array<{
+      txHash: string;
+      outputIndex: number;
+      lovelace: string;
+      tokens: Array<{ policyId: string; assetName: string; quantity: string }>;
+    }>;
+    total: number;
+  },
+  TSchema
+> = {
+  name: "get-wallet-utxos",
+  description: "Get the UTxO set for the configured wallet.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    limit: Type.Optional(
+      Type.Number({ default: 100, description: "Maximum number of UTxOs to return" }),
+    ),
+  }),
+  outputSchema: Type.Object({
+    utxos: Type.Array(
+      Type.Object({
+        txHash: Type.String({ description: "Transaction hash of the UTxO" }),
+        outputIndex: Type.Number({ description: "Output index within the transaction" }),
+        lovelace: Type.String({ description: "Lovelace amount as string (BigInt-safe)" }),
+        tokens: Type.Array(TokenEntrySchema),
+      }),
+    ),
+    total: Type.Number({ description: "Total number of UTxOs (before limit)" }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+    const limit = input.limit ?? 100;
+
+    let allUtxos: Awaited<ReturnType<typeof blaze.wallet.getUnspentOutputs>>;
+    try {
+      allUtxos = await blaze.wallet.getUnspentOutputs();
+    } catch (err) {
+      throw new ActionError(
+        `Provider error while fetching UTxOs: ${err instanceof Error ? err.message : String(err)}`,
+        "PROVIDER_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    const total = allUtxos.length;
+    const limited = allUtxos.slice(0, limit);
+
+    const utxos = limited.map((utxo) => {
+      const input = utxo.input();
+      const output = utxo.output();
+      const value = output.amount();
+
+      const tokens: Array<{ policyId: string; assetName: string; quantity: string }> = [];
+      const multiasset = value.multiasset();
+      if (multiasset) {
+        for (const [assetId, quantity] of multiasset.entries()) {
+          tokens.push({
+            policyId: Core.AssetId.getPolicyId(assetId),
+            assetName: Core.AssetId.getAssetName(assetId),
+            quantity: quantity.toString(),
+          });
+        }
+      }
+
+      return {
+        txHash: input.transactionId().toString(),
+        outputIndex: Number(input.index()),
+        lovelace: value.coin().toString(),
+        tokens,
+      };
+    });
+
+    return { utxos, total };
+  },
+};