@sundaeswap/sprinkles 0.6.1 → 0.7.0

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

@@ -0,0 +1,381 @@
+/**
+ * Built-in transaction actions for the Sprinkle action system.
+ * These actions expose transaction signing, submission, and decoding
+ * as non-interactive actions available in CLI and MCP modes.
+ *
+ * Sign/submit actions use category "wallet".
+ * The decode action uses category "transaction" (no wallet required).
+ */
+
+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, isHotWallet } from "./blaze-helper.js";
+import { countSignatures, getRequiredSigners } from "../../tx-dialog.js";
+
+/** Shared token entry schema (also used in wallet-actions) */
+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)" }),
+});
+
+/**
+ * Parses a hex CBOR string into a `Core.Transaction`.
+ * Throws `ActionError("INVALID_CBOR")` if the string is not valid transaction CBOR.
+ */
+function parseTxCbor(txCbor: string): Core.Transaction {
+  try {
+    return Core.Transaction.fromCbor(Core.TxCBOR(txCbor));
+  } catch (err) {
+    throw new ActionError(
+      `Invalid transaction CBOR: ${err instanceof Error ? err.message : String(err)}`,
+      "INVALID_CBOR",
+      { error: err instanceof Error ? err.message : String(err) },
+    );
+  }
+}
+
+/**
+ * `sign-transaction` -- Signs a transaction with the configured hot wallet.
+ * Cold wallets cannot sign; use an external signing tool and submit the result.
+ */
+export const signTransaction: IAction<
+  { txCbor: string },
+  { signedTxCbor: string; txHash: string; signatureCount: number },
+  TSchema
+> = {
+  name: "sign-transaction",
+  description:
+    "Sign a transaction with the configured hot wallet. Requires a hot wallet; cold wallets cannot sign.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to sign" }),
+  }),
+  outputSchema: Type.Object({
+    signedTxCbor: Type.String({ description: "Signed transaction CBOR hex" }),
+    txHash: Type.String({ description: "Transaction hash" }),
+    signatureCount: Type.Number({ description: "Number of VKey witnesses after signing" }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    if (!isHotWallet(blaze)) {
+      throw new ActionError(
+        "Cold wallets cannot sign transactions. Export the CBOR and sign externally, then use submit-transaction.",
+        "COLD_WALLET",
+      );
+    }
+
+    const tx = parseTxCbor(input.txCbor);
+
+    let signedTx: Core.Transaction;
+    try {
+      signedTx = await blaze.signTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Failed to sign transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "SIGN_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      signedTxCbor: signedTx.toCbor(),
+      txHash: signedTx.body().hash().toString(),
+      signatureCount: countSignatures(signedTx),
+    };
+  },
+};
+
+/**
+ * `submit-transaction` -- Submits a signed transaction to the blockchain.
+ */
+export const submitTransaction: IAction<
+  { txCbor: string },
+  { txHash: string; submitted: boolean },
+  TSchema
+> = {
+  name: "submit-transaction",
+  description: "Submit a signed transaction to the blockchain.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Signed transaction CBOR hex string to submit" }),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Submitted transaction hash" }),
+    submitted: Type.Boolean(),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+    const tx = parseTxCbor(input.txCbor);
+
+    let txHash: Core.TransactionId;
+    try {
+      txHash = await blaze.submitTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Transaction submission failed: ${err instanceof Error ? err.message : String(err)}`,
+        "SUBMISSION_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      txHash: txHash.toString(),
+      submitted: true,
+    };
+  },
+};
+
+/**
+ * `sign-and-submit` -- Signs a transaction and immediately submits it.
+ * Optionally waits for on-chain confirmation with a configurable timeout.
+ */
+export const signAndSubmit: IAction<
+  {
+    txCbor: string;
+    waitForConfirmation?: boolean;
+    confirmationTimeout?: number;
+  },
+  {
+    txHash: string;
+    submitted: boolean;
+    confirmed?: boolean;
+    signedTxCbor: string;
+  },
+  TSchema
+> = {
+  name: "sign-and-submit",
+  description:
+    "Sign and submit a transaction. Optionally wait for on-chain confirmation.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to sign and submit" }),
+    waitForConfirmation: Type.Optional(
+      Type.Boolean({
+        default: false,
+        description: "Whether to wait for on-chain confirmation before returning",
+      }),
+    ),
+    confirmationTimeout: Type.Optional(
+      Type.Number({
+        default: 60,
+        description: "Timeout in seconds to wait for confirmation",
+      }),
+    ),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Transaction hash" }),
+    submitted: Type.Boolean(),
+    confirmed: Type.Optional(Type.Boolean({ description: "Whether tx was confirmed on-chain" })),
+    signedTxCbor: Type.String({ description: "Signed transaction CBOR hex" }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    if (!isHotWallet(blaze)) {
+      throw new ActionError(
+        "Cold wallets cannot sign transactions. Export the CBOR and sign externally, then use submit-transaction.",
+        "COLD_WALLET",
+      );
+    }
+
+    const tx = parseTxCbor(input.txCbor);
+
+    // Sign
+    let signedTx: Core.Transaction;
+    try {
+      signedTx = await blaze.signTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Failed to sign transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "SIGN_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    const signedTxCbor = signedTx.toCbor();
+
+    // Submit
+    let txHash: Core.TransactionId;
+    try {
+      txHash = await blaze.submitTransaction(signedTx);
+    } catch (err) {
+      throw new ActionError(
+        `Transaction submission failed: ${err instanceof Error ? err.message : String(err)}`,
+        "SUBMISSION_ERROR",
+        { error: err instanceof Error ? err.message : String(err), signedTxCbor },
+      );
+    }
+
+    const txHashStr = txHash.toString();
+
+    // If confirmation not requested, return immediately
+    if (!input.waitForConfirmation) {
+      return {
+        txHash: txHashStr,
+        submitted: true,
+        signedTxCbor,
+      };
+    }
+
+    // Poll for confirmation
+    const timeoutSeconds = input.confirmationTimeout ?? 60;
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const pollIntervalMs = 5000; // 5 seconds between polls
+
+    let confirmed = false;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      try {
+        // Query UTxOs and check if any reference this tx hash
+        // This is a lightweight confirmation check using the provider
+        const utxos = await blaze.provider.getUnspentOutputs(
+          await blaze.wallet.getChangeAddress(),
+        );
+        // If provider returns without error and tx hash appears in a UTxO input or
+        // the query succeeds after submission, assume confirmed.
+        // A more precise check would be to look up the tx directly.
+        // Use resolveUnspentOutputs if available, otherwise accept the provider response.
+        const anyMatch = utxos.some(
+          (u) => u.input().transactionId().toString() === txHashStr,
+        );
+        // If we get a fresh UTxO referencing our tx, confirmed
+        if (anyMatch) {
+          confirmed = true;
+          break;
+        }
+        // Check if we got back any UTxOs at all - for a send transaction the
+        // change output should be visible once confirmed
+        // Fall through and keep polling
+      } catch {
+        // Provider error during poll -- keep trying until timeout
+      }
+    }
+
+    if (!confirmed && input.waitForConfirmation) {
+      // Return partial success rather than throwing -- tx was submitted successfully
+      // but we couldn't confirm within the timeout
+      return {
+        txHash: txHashStr,
+        submitted: true,
+        confirmed: false,
+        signedTxCbor,
+      };
+    }
+
+    return {
+      txHash: txHashStr,
+      submitted: true,
+      confirmed,
+      signedTxCbor,
+    };
+  },
+};
+
+/**
+ * `decode-transaction` -- Decodes a transaction CBOR hex without requiring a wallet.
+ * Extracts inputs, outputs, fee, witness count, and required signers from the tx body.
+ */
+export const decodeTransaction: IAction<
+  { txCbor: string },
+  {
+    txHash: string;
+    inputs: Array<{ txHash: string; outputIndex: number }>;
+    outputs: Array<{
+      address: string;
+      lovelace: string;
+      tokens: Array<{ policyId: string; assetName: string; quantity: string }>;
+    }>;
+    fee: string;
+    signatureCount: number;
+    requiredSigners: string[];
+  },
+  TSchema
+> = {
+  name: "decode-transaction",
+  description:
+    "Decode a transaction CBOR hex and return its inputs, outputs, fee, and signers. Does not require a wallet.",
+  category: "transaction",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to decode" }),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Transaction body hash" }),
+    inputs: Type.Array(
+      Type.Object({
+        txHash: Type.String({ description: "Input transaction hash" }),
+        outputIndex: Type.Number({ description: "Input output index" }),
+      }),
+    ),
+    outputs: Type.Array(
+      Type.Object({
+        address: Type.String({ description: "Output address (bech32 or hex)" }),
+        lovelace: Type.String({ description: "Output lovelace amount as string" }),
+        tokens: Type.Array(TokenEntrySchema),
+      }),
+    ),
+    fee: Type.String({ description: "Transaction fee in lovelace as string" }),
+    signatureCount: Type.Number({ description: "Number of VKey witnesses" }),
+    requiredSigners: Type.Array(
+      Type.String({ description: "Required signer key hashes" }),
+    ),
+  }),
+  execute: async (input, _context) => {
+    // No Blaze instance needed -- pure CBOR parsing
+    const tx = parseTxCbor(input.txCbor);
+
+    const body = tx.body();
+    const txHash = body.hash().toString();
+
+    // Extract inputs
+    const inputSet = body.inputs();
+    const inputs = Array.from(inputSet.values()).map((txInput) => ({
+      txHash: txInput.transactionId().toString(),
+      outputIndex: Number(txInput.index()),
+    }));
+
+    // Extract outputs
+    const outputs = body.outputs().map((txOutput) => {
+      const value = txOutput.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(),
+          });
+        }
+      }
+
+      // Attempt bech32 address, fall back to hex if conversion fails
+      let address: string;
+      try {
+        address = txOutput.address().toBech32();
+      } catch {
+        address = txOutput.address().toBytes();
+      }
+
+      return {
+        address,
+        lovelace: value.coin().toString(),
+        tokens,
+      };
+    });
+
+    return {
+      txHash,
+      inputs,
+      outputs,
+      fee: body.fee().toString(),
+      signatureCount: countSignatures(tx),
+      requiredSigners: getRequiredSigners(tx),
+    };
+  },
+};

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 };
+  },
+};