feat(wallet): implement external stake credential support and enhance wallet management features

- Added support for external stake credentials in wallet creation and management.
- Updated wallet models to include `stakeCredentialHash` and `scriptType`.
- Enhanced UI components to reflect changes in stake key handling based on external credentials.
- Introduced new methods for managing stake keys and validating addresses.
- Updated API endpoints to handle new wallet properties.
- Improved user experience with informative messages regarding stake key imports.

Author: QSchlegel

jest.config.mjs

@@ -0,0 +1,29 @@
+/** @type {import('jest').Config} */
+export default {
+  preset: 'ts-jest/presets/default-esm',
+  extensionsToTreatAsEsm: ['.ts', '.tsx'],
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: [
+    '**/__tests__/**/*.(test|spec).+(ts|tsx|js)',
+    '**/*.(test|spec).+(ts|tsx|js)'
+  ],
+  transform: {
+    '^.+\\.(ts|tsx)$': ['ts-jest', {
+      useESM: true
+    }],
+  },
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/pages/**',
+    '!src/components/**/*.tsx',
+    '!src/**/*.stories.{ts,tsx}',
+    '!src/__tests__/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  testTimeout: 10000,
+  verbose: true,
+};

package-lock.json

@@ -14,7 +14,11 @@
     "dev": "next dev",
     "postinstall": "prisma format && prisma generate && prisma migrate deploy",
     "lint": "next lint",
-    "start": "next start"
+    "start": "next start",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false"
   },
   "dependencies": {
     "@auth/prisma-adapter": "^1.6.0",
@@ -85,10 +89,12 @@
     "zustand": "^4.5.5"
   },
   "devDependencies": {
+    "@jest/globals": "^30.1.2",
     "@types/busboy": "^1.5.4",
     "@types/cors": "^2.8.18",
     "@types/eslint": "^8.56.10",
     "@types/formidable": "^3.4.5",
+    "@types/jest": "^30.0.0",
     "@types/jsonld": "^1.5.15",
     "@types/jsonwebtoken": "^9.0.9",
     "@types/node": "^20.14.10",
@@ -101,11 +107,13 @@
     "@typescript-eslint/parser": "^8.1.0",
     "eslint": "^8.57.0",
     "eslint-config-next": "^14.2.4",
+    "jest": "^30.1.3",
     "postcss": "^8.4.39",
     "prettier": "^3.3.2",
     "prettier-plugin-tailwindcss": "^0.6.5",
     "prisma": "^6.4.1",
     "tailwindcss": "^3.4.3",
+    "ts-jest": "^29.4.4",
     "typescript": "^5.5.3"
   },
   "ct3aMetadata": {

package.json

@@ -0,0 +1,3 @@
+-- AlterTable
+ALTER TABLE "NewWallet" ADD COLUMN     "scriptType" TEXT,
+ADD COLUMN     "stakeCredentialHash" TEXT;

prisma/migrations/20250925091447_add_stake_credential_and_script_type_to_new_wallet/migration.sql

@@ -73,6 +73,8 @@ model NewWallet {
   signersDescriptions String[]
   numRequiredSigners  Int?
   ownerAddress        String
+  stakeCredentialHash String?
+  scriptType          String?
 }
 
 model Nonce {

prisma/schema.prisma

@@ -0,0 +1,80 @@
+# MultisigSDK Testing Framework
+
+This directory contains comprehensive tests for the MultisigSDK functionality.
+
+## Test Structure
+
+- `setup.ts` - Jest configuration and global test setup
+- `testUtils.ts` - Mock data and helper functions for testing
+- `multisigSDK.test.ts` - Tests for the MultisigWallet class
+- `helpers.test.ts` - Tests for utility functions
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode during development
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests for CI/CD (no watch mode)
+npm run test:ci
+```
+
+## Test Coverage
+
+The tests cover:
+
+### MultisigWallet Class
+- Constructor validation and key filtering/sorting
+- Role-based key management (`getKeysByRole`)
+- Script building for different roles (`buildScript`)
+- Staking functionality detection (`stakingEnabled`)
+- Stake credential hash computation
+- JSON metadata generation (CIP-0146)
+- Error handling for invalid inputs
+
+### Helper Functions
+- `paymentKeyHash` - Extract payment key hash from addresses
+- `stakeKeyHash` - Extract stake key hash from stake addresses
+- `addressToNetwork` - Determine network from address format
+- `checkValidAddress` - Validate Cardano addresses
+- `checkValidStakeKey` - Validate stake addresses
+
+## Mock Data
+
+The `testUtils.ts` file provides:
+- Mock key hashes for different roles (payment, stake, drep)
+- Mock addresses for mainnet and testnet
+- Mock MultisigKey arrays for testing
+- Helper functions to create test wallets
+
+## Important Notes
+
+1. **Real Addresses**: Some tests use mock addresses. For production testing, use real Cardano addresses.
+
+2. **Network Dependencies**: Tests that interact with @meshsdk/core functions may require actual Cardano address formats.
+
+3. **Error Handling**: Tests verify both success paths and error conditions.
+
+4. **Lexicographic Sorting**: Tests verify that keys are properly sorted per CIP-1854.
+
+## Adding New Tests
+
+When adding new functionality to the MultisigSDK:
+
+1. Add corresponding test cases in the appropriate test file
+2. Update mock data in `testUtils.ts` if needed
+3. Ensure both success and error cases are covered
+4. Run `npm run test:coverage` to verify coverage levels
+
+## CI/CD Integration
+
+The `test:ci` script is designed for continuous integration:
+- Runs without watch mode
+- Generates coverage reports
+- Exits with appropriate status codes for build systems

src/__tests__/README.md

@@ -0,0 +1,148 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  paymentKeyHash,
+  stakeKeyHash,
+  addressToNetwork,
+  checkValidAddress,
+  checkValidStakeKey,
+} from '../utils/multisigSDK';
+import { mockAddresses, mockStakeAddresses, realTestAddresses, externalStakeCredential } from './testUtils';
+
+describe('Helper Functions', () => {
+  describe('paymentKeyHash', () => {
+    it('should be a function', () => {
+      expect(typeof paymentKeyHash).toBe('function');
+    });
+
+    it('should extract key hash from real testnet addresses', () => {
+      const keyHash1 = paymentKeyHash(realTestAddresses.address1);
+      const keyHash2 = paymentKeyHash(realTestAddresses.address2);
+      
+      expect(keyHash1).toBeDefined();
+      expect(keyHash2).toBeDefined();
+      expect(keyHash1).not.toBe(keyHash2);
+      expect(typeof keyHash1).toBe('string');
+      expect(typeof keyHash2).toBe('string');
+    });
+
+    it('should handle invalid addresses', () => {
+      expect(() => paymentKeyHash(mockAddresses.invalid)).toThrow();
+    });
+
+    it('should handle empty string', () => {
+      expect(() => paymentKeyHash('')).toThrow();
+    });
+  });
+
+  describe('stakeKeyHash', () => {
+    it('should be a function', () => {
+      expect(typeof stakeKeyHash).toBe('function');
+    });
+
+    it('should extract stake key hash from real stake address', () => {
+      const extractedHash = stakeKeyHash(externalStakeCredential);
+      expect(extractedHash).toBeDefined();
+      expect(typeof extractedHash).toBe('string');
+    });
+
+    it('should handle invalid stake addresses', () => {
+      expect(() => stakeKeyHash(mockStakeAddresses.invalid)).toThrow();
+    });
+
+    it('should handle empty string', () => {
+      expect(() => stakeKeyHash('')).toThrow();
+    });
+  });
+
+  describe('addressToNetwork', () => {
+    it('should return 0 for real testnet addresses', () => {
+      expect(addressToNetwork(realTestAddresses.address1)).toBe(0);
+      expect(addressToNetwork(realTestAddresses.address2)).toBe(0);
+    });
+
+    it('should return 1 for mainnet addresses', () => {
+      const mainnetAddress = 'addr1qx3w7rh2p447qkx34x0p0vlr6z34r3n8e8r9qxrl6n';
+      expect(addressToNetwork(mainnetAddress)).toBe(1);
+    });
+
+    it('should handle addresses without test prefix', () => {
+      const addressWithoutTest = 'addr1qx3w7rh2p447qkx34x0p0vlr6z34r3n8e8r9qxrl6n';
+      expect(addressToNetwork(addressWithoutTest)).toBe(1);
+    });
+
+    it('should handle empty string', () => {
+      expect(addressToNetwork('')).toBe(1);
+    });
+  });
+
+  describe('checkValidAddress', () => {
+    it('should return true for real testnet addresses', () => {
+      expect(checkValidAddress(realTestAddresses.address1)).toBe(true);
+      expect(checkValidAddress(realTestAddresses.address2)).toBe(true);
+    });
+
+    it('should return false for invalid addresses', () => {
+      expect(checkValidAddress(mockAddresses.invalid)).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      expect(checkValidAddress('')).toBe(false);
+    });
+
+    it('should return false for null or undefined', () => {
+      expect(checkValidAddress(null as any)).toBe(false);
+      expect(checkValidAddress(undefined as any)).toBe(false);
+    });
+  });
+
+  describe('checkValidStakeKey', () => {
+    it('should return true for real stake address', () => {
+      expect(checkValidStakeKey(externalStakeCredential)).toBe(true);
+    });
+
+    it('should return false for invalid stake addresses', () => {
+      expect(checkValidStakeKey(mockStakeAddresses.invalid)).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      expect(checkValidStakeKey('')).toBe(false);
+    });
+
+    it('should return false for null or undefined', () => {
+      expect(checkValidStakeKey(null as any)).toBe(false);
+      expect(checkValidStakeKey(undefined as any)).toBe(false);
+    });
+  });
+});
+
+describe('Integration Tests', () => {
+  describe('Address and Network utilities', () => {
+    it('should correctly identify network from real addresses and validate', () => {
+      expect(addressToNetwork(realTestAddresses.address1)).toBe(0);
+      expect(addressToNetwork(realTestAddresses.address2)).toBe(0);
+      
+      const mainnetAddr = 'addr1qx3w7rh2p447qkx34x0p0vlr6z34r3n8e8r9qxrl6n';
+      expect(addressToNetwork(mainnetAddr)).toBe(1);
+    });
+
+    it('should handle validation edge cases', () => {
+      const invalidInputs = ['', null, undefined, 'random_string', 123];
+      
+      invalidInputs.forEach(input => {
+        expect(checkValidAddress(input as any)).toBe(false);
+        expect(checkValidStakeKey(input as any)).toBe(false);
+      });
+    });
+
+    it('should work with real address extraction and validation', () => {
+      // Test that we can extract key hashes and validate addresses
+      const keyHash1 = paymentKeyHash(realTestAddresses.address1);
+      const keyHash2 = paymentKeyHash(realTestAddresses.address2);
+      
+      expect(keyHash1).toBeDefined();
+      expect(keyHash2).toBeDefined();
+      expect(checkValidAddress(realTestAddresses.address1)).toBe(true);
+      expect(checkValidAddress(realTestAddresses.address2)).toBe(true);
+    });
+  });
+});