Refactor signTransaction endpoint

Andre-Diamond · Andre-Diamond · commit b215bd0dafb6 · 2025-11-07T09:07:55.000+02:00
- Removed outdated details from README.md regarding the signTransaction endpoint and streamlined the description.
- Updated the signTransaction handler to improve request validation and error handling, replacing the signedTx parameter with txCbor.
- Enhanced the logic for broadcasting transactions and managing state transitions.
- Removed Swagger documentation for the signTransaction endpoint to reflect the changes in request parameters and responses.
diff --git a/src/pages/api/v1/README.md b/src/pages/api/v1/README.md
@@ -43,22 +43,6 @@ A comprehensive REST API implementation for the multisig wallet application, pro
 - **Response**: Transaction object with ID, state, and metadata
 - **Error Handling**: 400 (validation), 401 (auth), 403 (authorization), 500 (server)
 
-#### `signTransaction.ts` - POST `/api/v1/signTransaction`
-
-- **Purpose**: Record a signature for a pending multisig transaction
-- **Authentication**: Required (JWT Bearer token)
-- **Features**:
-  - Signature tracking with duplicate and rejection safeguards
-  - Wallet membership validation and JWT address enforcement
-  - Threshold detection with automatic submission when the final signature is collected
-- **Request Body**:
-  - `walletId`: Wallet identifier
-  - `transactionId`: Pending transaction identifier
-  - `address`: Signer address
-  - `signedTx`: CBOR transaction payload after applying the signature
-- **Response**: Updated transaction record with threshold status metadata; includes `txHash` when submission succeeds
-- **Error Handling**: 400 (validation), 401 (auth), 403 (authorization), 404 (not found), 409 (duplicate/rejected), 502 (submission failure), 500 (server)
-
 #### `pendingTransactions.ts` - GET `/api/v1/pendingTransactions`
 
 - **Purpose**: Retrieve all pending multisig transactions for a wallet
diff --git a/src/pages/api/v1/signTransaction.ts b/src/pages/api/v1/signTransaction.ts
@@ -5,18 +5,17 @@ import { verifyJwt } from "@/lib/verifyJwt";
 import { createCaller } from "@/server/api/root";
 import { db } from "@/server/db";
 import { getProvider } from "@/utils/get-provider";
-import { paymentKeyHash } from "@/utils/multisigSDK";
-import { csl } from "@meshsdk/core-csl";
-
-const HEX_REGEX = /^[0-9a-fA-F]+$/;
-
-const isHexString = (value: unknown): value is string =>
-  typeof value === "string" && value.length > 0 && HEX_REGEX.test(value);
-
-const resolveNetworkFromAddress = (bech32Address: string): 0 | 1 =>
-  bech32Address.startsWith("addr_test") || bech32Address.startsWith("stake_test")
-    ? 0
-    : 1;
+import { addressToNetwork } from "@/utils/multisigSDK";
+
+function coerceBoolean(value: unknown, fallback = false): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") return true;
+    if (normalized === "false") return false;
+  }
+  return fallback;
+}
 
 export default async function handler(
   req: NextApiRequest,
@@ -34,7 +33,9 @@ export default async function handler(
   }
 
   const authHeader = req.headers.authorization;
-  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+  const token = authHeader?.startsWith("Bearer ")
+    ? authHeader.slice(7)
+    : null;
 
   if (!token) {
     return res.status(401).json({ error: "Unauthorized - Missing token" });
@@ -50,42 +51,49 @@ export default async function handler(
     expires: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
   } as const;
 
-  const caller = createCaller({ db, session });
-
-  const body =
-    typeof req.body === "object" && req.body !== null
-      ? (req.body as Record<string, unknown>)
-      : {};
-
-  const { walletId, transactionId, address, signedTx } = body;
-
-  if (typeof walletId !== "string" || walletId.trim().length === 0) {
+  type SignTransactionRequestBody = {
+    walletId?: unknown;
+    transactionId?: unknown;
+    address?: unknown;
+    txCbor?: unknown;
+    broadcast?: unknown;
+    txHash?: unknown;
+  };
+
+  const {
+    walletId,
+    transactionId,
+    address,
+    txCbor,
+    broadcast: rawBroadcast,
+    txHash: rawTxHash,
+  } = (req.body ?? {}) as SignTransactionRequestBody;
+
+  if (typeof walletId !== "string" || walletId.trim() === "") {
     return res.status(400).json({ error: "Missing or invalid walletId" });
   }
 
-  if (typeof transactionId !== "string" || transactionId.trim().length === 0) {
+  if (typeof transactionId !== "string" || transactionId.trim() === "") {
     return res
       .status(400)
       .json({ error: "Missing or invalid transactionId" });
   }
 
-  if (typeof address !== "string" || address.trim().length === 0) {
+  if (typeof address !== "string" || address.trim() === "") {
     return res.status(400).json({ error: "Missing or invalid address" });
   }
 
-  if (!isHexString(signedTx)) {
-    return res.status(400).json({ error: "Missing or invalid signedTx" });
-  }
-
-  if (signedTx.length % 2 !== 0) {
-    return res.status(400).json({ error: "Missing or invalid signedTx" });
+  if (typeof txCbor !== "string" || txCbor.trim() === "") {
+    return res.status(400).json({ error: "Missing or invalid txCbor" });
   }
 
   if (payload.address !== address) {
     return res.status(403).json({ error: "Address mismatch" });
   }
 
   try {
+    const caller = createCaller({ db, session });
+
     const wallet = await caller.wallet.getWallet({ walletId, address });
     if (!wallet) {
       return res.status(404).json({ error: "Wallet not found" });
@@ -114,111 +122,91 @@ export default async function handler(
     if (transaction.signedAddresses.includes(address)) {
       return res
         .status(409)
-        .json({ error: "Address already signed this transaction" });
+        .json({ error: "Address has already signed this transaction" });
     }
 
     if (transaction.rejectedAddresses.includes(address)) {
       return res
         .status(409)
-        .json({ error: "Address has rejected this transaction" });
-    }
-
-    let signerKeyHash: string;
-    try {
-      signerKeyHash = paymentKeyHash(address).toLowerCase();
-    } catch (deriveError) {
-      console.error("Failed to derive payment key hash", {
-        message: (deriveError as Error)?.message,
-      });
-      return res.status(400).json({ error: "Unable to derive signer key" });
+        .json({ error: "Address has already rejected this transaction" });
     }
 
-    let signerWitnessFound = false;
-    try {
-      const tx = csl.Transaction.from_hex(signedTx);
-      const vkeys = tx.witness_set()?.vkeys();
-
-      if (vkeys) {
-        for (let i = 0; i < vkeys.len(); i += 1) {
-          const witness = vkeys.get(i);
-          const witnessKeyHash = Buffer.from(
-            witness.vkey().public_key().hash().to_bytes(),
-          )
-            .toString("hex")
-            .toLowerCase();
-
-          if (witnessKeyHash === signerKeyHash) {
-            signerWitnessFound = true;
-            break;
-          }
-        }
+    const updatedSignedAddresses = [
+      ...transaction.signedAddresses,
+      address,
+    ];
+
+    const shouldAttemptBroadcast = coerceBoolean(rawBroadcast, true);
+
+    const threshold = (() => {
+      switch (wallet.type) {
+        case "atLeast":
+          return wallet.numRequiredSigners ?? wallet.signersAddresses.length;
+        case "all":
+          return wallet.signersAddresses.length;
+        case "any":
+          return 1;
+        default:
+          return wallet.numRequiredSigners ?? 1;
       }
-    } catch (decodeError) {
-      console.error("Failed to inspect transaction witnesses", {
-        message: (decodeError as Error)?.message,
-        stack: (decodeError as Error)?.stack,
-      });
-      return res.status(400).json({ error: "Invalid signedTx payload" });
-    }
-
-    if (!signerWitnessFound) {
-      return res.status(400).json({
-        error: "Signed transaction does not include caller signature",
-      });
-    }
-
-    const updatedSignedAddresses = [...transaction.signedAddresses, address];
-    const updatedRejectedAddresses = [...transaction.rejectedAddresses];
-
-    const totalSigners = wallet.signersAddresses.length;
-    const requiredSigners = wallet.numRequiredSigners ?? undefined;
-
-    let thresholdReached = false;
-    switch (wallet.type) {
-      case "any":
-        thresholdReached = true;
-        break;
-      case "all":
-        thresholdReached = updatedSignedAddresses.length >= totalSigners;
-        break;
-      case "atLeast":
-        thresholdReached =
-          typeof requiredSigners === "number" &&
-          updatedSignedAddresses.length >= requiredSigners;
-        break;
-      default:
-        thresholdReached = false;
-    }
-
-    let finalTxHash: string | undefined;
-    if (thresholdReached && !finalTxHash) {
+    })();
+
+    const providedTxHash =
+      typeof rawTxHash === "string" && rawTxHash.trim() !== ""
+        ? rawTxHash.trim()
+        : undefined;
+
+    let nextState = transaction.state;
+    let finalTxHash = providedTxHash ?? transaction.txHash ?? undefined;
+    let submissionError: string | undefined;
+
+    if (
+      shouldAttemptBroadcast &&
+      threshold > 0 &&
+      updatedSignedAddresses.length >= threshold &&
+      !providedTxHash
+    ) {
       try {
-        const network = resolveNetworkFromAddress(address);
-        const blockchainProvider = getProvider(network);
-        finalTxHash = await blockchainProvider.submitTx(signedTx);
-      } catch (submitError) {
-        console.error("Failed to submit transaction", {
-          message: (submitError as Error)?.message,
-          stack: (submitError as Error)?.stack,
+        const networkSource = wallet.signersAddresses[0] ?? address;
+        const network = addressToNetwork(networkSource);
+        const provider = getProvider(network);
+        const submittedHash = await provider.submitTx(txCbor);
+        finalTxHash = submittedHash;
+        nextState = 1;
+      } catch (error) {
+        console.error("Error submitting signed transaction", {
+          transactionId,
+          error,
         });
-        return res.status(502).json({ error: "Failed to submit transaction" });
+        submissionError = (error as Error)?.message ?? "Failed to submit transaction";
       }
     }
 
-    const nextState = finalTxHash ? 1 : 0;
+    if (providedTxHash) {
+      nextState = 1;
+    }
+
+    // Ensure we do not downgrade a completed transaction back to pending
+    if (transaction.state === 1) {
+      nextState = 1;
+    } else if (nextState !== 1) {
+      nextState = 0;
+    }
 
     const updatedTransaction = await caller.transaction.updateTransaction({
       transactionId,
-      txCbor: signedTx,
+      txCbor,
       signedAddresses: updatedSignedAddresses,
-      rejectedAddresses: updatedRejectedAddresses,
+      rejectedAddresses: transaction.rejectedAddresses,
       state: nextState,
-      txHash: finalTxHash,
+      ...(finalTxHash ? { txHash: finalTxHash } : {}),
     });
 
     return res.status(200).json({
       transaction: updatedTransaction,
-      thresholdReached,
+      submitted: nextState === 1,
+      txHash: finalTxHash,
+      ...(submissionError ? { submissionError } : {}),
     });
   } catch (error) {
     console.error("Error in signTransaction handler", {
@@ -228,4 +216,3 @@ export default async function handler(
     return res.status(500).json({ error: "Internal Server Error" });
   }
 }
-
diff --git a/src/utils/swagger.ts b/src/utils/swagger.ts
@@ -196,81 +196,6 @@ export const swaggerSpec = swaggerJSDoc({
           },
         },
       },
-      "/api/v1/signTransaction": {
-        post: {
-          tags: ["V1"],
-          summary: "Sign a pending multisig transaction",
-          description:
-            "Adds a signature to an existing multisig transaction and automatically submits it once the required signatures are met.",
-          requestBody: {
-            required: true,
-            content: {
-              "application/json": {
-                schema: {
-                  type: "object",
-                  properties: {
-                    walletId: { type: "string" },
-                    transactionId: { type: "string" },
-                    address: { type: "string" },
-                    signedTx: { type: "string" },
-                  },
-                  required: [
-                    "walletId",
-                    "transactionId",
-                    "address",
-                    "signedTx",
-                  ],
-                },
-              },
-            },
-          },
-          responses: {
-            200: {
-              description: "Transaction successfully updated",
-              content: {
-                "application/json": {
-                  schema: {
-                    type: "object",
-                    properties: {
-                      transaction: {
-                        type: "object",
-                        properties: {
-                          id: { type: "string" },
-                          walletId: { type: "string" },
-                          txJson: { type: "string" },
-                          txCbor: { type: "string" },
-                          signedAddresses: {
-                            type: "array",
-                            items: { type: "string" },
-                          },
-                          rejectedAddresses: {
-                            type: "array",
-                            items: { type: "string" },
-                          },
-                          description: { type: "string" },
-                          state: { type: "number" },
-                          txHash: { type: "string" },
-                          createdAt: { type: "string" },
-                          updatedAt: { type: "string" },
-                        },
-                      },
-                      thresholdReached: { type: "boolean" },
-                    },
-                  },
-                },
-              },
-            },
-            400: { description: "Validation error" },
-            401: { description: "Unauthorized" },
-            403: { description: "Authorization error" },
-            404: { description: "Wallet or transaction not found" },
-            409: { description: "Signer already processed this transaction" },
-            502: { description: "Blockchain submission failed" },
-            405: { description: "Method not allowed" },
-            500: { description: "Internal server error" },
-          },
-        },
-      },
       "/api/v1/pendingTransactions": {
         get: {
           tags: ["V1"],
