Enhance signTransaction endpoint with additional mocks and Swagger documentation

- Added mock implementations for database transaction updates and console error/warn handling in tests.
- Updated the signTransaction API documentation in Swagger to include detailed request and response structures.
- Improved test coverage for transaction updates and error handling scenarios.

Author: Andre-Diamond

src/__tests__/signTransaction.test.ts

@@ -37,10 +37,17 @@ jest.mock(
 );
 
 const dbTransactionFindUniqueMock = jest.fn<(args: unknown) => Promise<unknown>>();
+const dbTransactionUpdateManyMock = jest.fn<
+  (args: {
+    where: unknown;
+    data: unknown;
+  }) => Promise<{ count: number }>
+>();
 
 const dbMock = {
   transaction: {
     findUnique: dbTransactionFindUniqueMock,
+    updateMany: dbTransactionUpdateManyMock,
   },
 };
 
@@ -94,6 +101,10 @@ class MockEd25519Signature {
   static from_hex(hex: string) {
     return new MockEd25519Signature(hex);
   }
+
+  to_bytes() {
+    return Buffer.from(this.hex, 'hex');
+  }
 }
 
 class MockPublicKey {
@@ -112,6 +123,10 @@ class MockPublicKey {
   verify() {
     return true;
   }
+
+  to_bech32() {
+    return `mock_bech32_${this.hex.slice(0, 8)}`;
+  }
 }
 
 class MockVkey {
@@ -139,6 +154,10 @@ class MockVkeywitness {
   vkey() {
     return this.vkeyInstance;
   }
+
+  signature() {
+    return this.signatureInstance;
+  }
 }
 
 class MockVkeywitnesses {
@@ -284,6 +303,13 @@ jest.mock(
   { virtual: true },
 );
 
+const consoleErrorSpy = jest
+  .spyOn(console, 'error')
+  .mockImplementation(() => undefined);
+const consoleWarnSpy = jest
+  .spyOn(console, 'warn')
+  .mockImplementation(() => undefined);
+
 type ResponseMock = NextApiResponse & { statusCode?: number };
 
 function createMockResponse(): ResponseMock {
@@ -306,7 +332,6 @@ function createMockResponse(): ResponseMock {
 }
 
 const walletGetWalletMock = jest.fn<(args: unknown) => Promise<unknown>>();
-const transactionUpdateMock = jest.fn<(args: unknown) => Promise<unknown>>();
 
 let handler: (req: NextApiRequest, res: NextApiResponse) => Promise<void | NextApiResponse>;
 
@@ -319,8 +344,8 @@ beforeEach(() => {
   MockVkeywitnesses.reset();
 
   walletGetWalletMock.mockReset();
-  transactionUpdateMock.mockReset();
   dbTransactionFindUniqueMock.mockReset();
+  dbTransactionUpdateManyMock.mockReset();
   getProviderMock.mockReset();
   addressToNetworkMock.mockReset();
   resolvePaymentKeyHashMock.mockReset();
@@ -340,10 +365,19 @@ beforeEach(() => {
 
   createCallerMock.mockReturnValue({
     wallet: { getWallet: walletGetWalletMock },
-    transaction: { updateTransaction: transactionUpdateMock },
   });
 });
 
+afterEach(() => {
+  consoleErrorSpy.mockClear();
+  consoleWarnSpy.mockClear();
+});
+
+afterAll(() => {
+  consoleErrorSpy.mockRestore();
+  consoleWarnSpy.mockRestore();
+});
+
 describe('signTransaction API route', () => {
   it('updates transaction when payload is valid', async () => {
     const address = 'addr_test1qpl3w9v4l5qhxk778exampleaddress';
@@ -369,19 +403,27 @@ describe('signTransaction API route', () => {
       rejectedAddresses: [] as string[],
       txCbor: 'stored-tx-hex',
       txHash: null as string | null,
+      txJson: '{}',
     };
 
-    dbTransactionFindUniqueMock.mockResolvedValue(transactionRecord);
-
     const updatedTransaction = {
       ...transactionRecord,
       signedAddresses: [address],
       txCbor: 'updated-tx-hex',
       state: 1,
       txHash: 'provided-hash',
+      txJson: '{"multisig":{"state":1}}',
     };
 
-    transactionUpdateMock.mockResolvedValue(updatedTransaction);
+    dbTransactionFindUniqueMock
+      .mockResolvedValueOnce(transactionRecord)
+      .mockResolvedValueOnce(updatedTransaction);
+
+    dbTransactionUpdateManyMock.mockResolvedValue({ count: 1 });
+
+    const submitTxMock = jest.fn<(txHex: string) => Promise<string>>();
+    submitTxMock.mockResolvedValue('provided-hash');
+    getProviderMock.mockReturnValue({ submitTx: submitTxMock });
 
     const req = {
       method: 'POST',
@@ -411,17 +453,33 @@ describe('signTransaction API route', () => {
       }),
     });
     expect(walletGetWalletMock).toHaveBeenCalledWith({ walletId, address });
-    expect(dbTransactionFindUniqueMock).toHaveBeenCalledWith({ where: { id: transactionId } });
-    expect(res.status).toHaveBeenCalledWith(200);
-    expect(getProviderMock).not.toHaveBeenCalled();
-    expect(transactionUpdateMock).toHaveBeenCalledWith({
-      transactionId,
-      txCbor: 'updated-tx-hex',
-      signedAddresses: [address],
-      rejectedAddresses: [],
-      state: 1,
-      txHash: 'provided-hash',
+    expect(dbTransactionFindUniqueMock).toHaveBeenNthCalledWith(1, {
+      where: { id: transactionId },
     });
+    expect(getProviderMock).toHaveBeenCalledWith(0);
+    expect(submitTxMock).toHaveBeenCalledWith('updated-tx-hex');
+    expect(dbTransactionUpdateManyMock).toHaveBeenCalledWith({
+      where: {
+        id: transactionId,
+        signedAddresses: { equals: [] },
+        rejectedAddresses: { equals: [] },
+        txCbor: 'stored-tx-hex',
+        txJson: '{}',
+      },
+      data: expect.objectContaining({
+        signedAddresses: { set: [address] },
+        rejectedAddresses: { set: [] },
+        txCbor: 'updated-tx-hex',
+        state: 1,
+        txHash: 'provided-hash',
+        txJson: expect.any(String),
+      }),
+    });
+    expect(dbTransactionFindUniqueMock).toHaveBeenNthCalledWith(2, {
+      where: { id: transactionId },
+    });
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(200);
     expect(res.json).toHaveBeenCalledWith({
       transaction: updatedTransaction,
       submitted: true,
@@ -587,7 +645,7 @@ describe('signTransaction API route', () => {
     expect(res.json).toHaveBeenCalledWith({
       error: 'Address has already signed this transaction',
     });
-    expect(transactionUpdateMock).not.toHaveBeenCalled();
+    expect(dbTransactionUpdateManyMock).not.toHaveBeenCalled();
     expect(getProviderMock).not.toHaveBeenCalled();
   });
 
@@ -633,7 +691,7 @@ describe('signTransaction API route', () => {
     expect(res.json).toHaveBeenCalledWith({
       error: 'Stored transaction is missing txCbor',
     });
-    expect(transactionUpdateMock).not.toHaveBeenCalled();
+    expect(dbTransactionUpdateManyMock).not.toHaveBeenCalled();
   });
 
 });

src/utils/swagger.ts

@@ -259,6 +259,126 @@ export const swaggerSpec = swaggerJSDoc({
           },
         },
       },
+      "/api/v1/signTransaction": {
+        post: {
+          tags: ["V1"],
+          summary: "Sign an existing transaction",
+          description:
+            "Records a witness for an existing multisig transaction and optionally submits it if the signing threshold is met.",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    walletId: { type: "string" },
+                    transactionId: { type: "string" },
+                    address: { type: "string" },
+                    signature: { type: "string" },
+                    key: { type: "string" },
+                    broadcast: { type: "boolean" },
+                  },
+                  required: [
+                    "walletId",
+                    "transactionId",
+                    "address",
+                    "signature",
+                    "key",
+                  ],
+                },
+              },
+            },
+          },
+          responses: {
+            200: {
+              description:
+                "Witness stored. Includes updated transaction and submission status.",
+              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" },
+                        },
+                      },
+                      submitted: { type: "boolean" },
+                      txHash: { type: "string", nullable: true },
+                    },
+                  },
+                },
+              },
+            },
+            401: { description: "Unauthorized or invalid signature" },
+            403: { description: "Forbidden due to address mismatch or access" },
+            404: { description: "Wallet or transaction not found" },
+            409: {
+              description:
+                "Transaction already finalized or conflicting update detected",
+            },
+            502: {
+              description:
+                "Witness stored but submission to the network failed",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      error: { type: "string" },
+                      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" },
+                        },
+                      },
+                      submitted: { type: "boolean" },
+                      txHash: { type: "string", nullable: true },
+                      submissionError: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            405: { description: "Method not allowed" },
+            500: { description: "Internal server error" },
+          },
+        },
+      },
       "/api/v1/submitDatum": {
         post: {
           tags: ["V1"],