feat(wallets): add keyVersion field to Wallet model

Adds a keyVersion integer field (default 1) to the Wallet model to track
the key algorithm/derivation scheme version independently of the existing
encryptionVersion (envelope format) and secretVersion (rotation counter).

Changes:
- prisma/schema.prisma: add keyVersion Int @default(1) to Wallet
- prisma/migrations/20260602_add_wallet_key_version/migration.sql: safe
  ALTER TABLE adding the column with DEFAULT 1 (no data migration needed)
- src/wallets/domain/wallet.model.ts: add keyVersion to Wallet interface
- src/wallets/wallets.service.ts: write keyVersion:1 on create, increment
  on rotateWalletKey, coerce null/undefined to 1 in mapper (stale rows)
- src/wallets/wallet-creation-orchestrator.service.ts: same creation write
  and mapper fallback
- src/key-management/domain/key-types.ts: add keyVersion to EncryptedKeyMaterial
- src/key-management/key-management.service.ts: return keyVersion:1 from
  generateKey; preserve keyVersion in reEncryptKey (algo unchanged)
- src/key-management/key-management.controller.ts: expose keyVersion in
  generate response
- src/wallets/wallets.service.spec.ts: update mocks, add keyVersion describe
  block (init, increment on rotation, stale-row fallback)
- src/key-management/key-management.service.spec.ts: assert keyVersion:1
  in generateKey result

Author: Mux Protocol

prisma/migrations/20260602_add_wallet_key_version/migration.sql

@@ -0,0 +1,10 @@
+-- Migration: add keyVersion field to Wallet
+--
+-- keyVersion tracks the key algorithm/derivation scheme version on a wallet.
+-- It is distinct from:
+--   encryptionVersion  – the envelope/KMS format used to encrypt the secret material
+--   secretVersion      – a monotonic counter incremented on every key rotation
+--
+-- Default value of 1 is applied to all existing rows so no data migration is needed.
+
+ALTER TABLE "Wallet" ADD COLUMN "keyVersion" INTEGER NOT NULL DEFAULT 1;

prisma/schema.prisma

@@ -140,6 +140,11 @@ model Wallet {
   /// Supports rotation by incrementing secret material while preserving history.
   secretVersion Int @default(1)
 
+  /// Key algorithm/derivation scheme version (e.g. 1 = Stellar Ed25519 via stellar-sdk).
+  /// Increment when the key algorithm or derivation path changes so consumers can detect
+  /// stale material and trigger re-encryption or re-issuance.
+  keyVersion Int @default(1)
+
   network WalletNetwork
   status  WalletStatus  @default(PROVISIONING)
 

src/key-management/domain/key-types.ts

@@ -30,6 +30,8 @@ export interface GeneratedKeyPair {
 export interface EncryptedKeyMaterial {
   encryptedData: string;
   encryptionVersion: number;
+  /** Key algorithm/derivation scheme version. Matches Wallet.keyVersion. */
+  keyVersion: number;
   keyType: KeyType;
   publicKey: string;
 }

src/key-management/key-management.controller.ts

@@ -35,6 +35,7 @@ export class KeyManagementController {
       publicKey: result.publicKey,
       encryptedData: result.encryptedData,
       encryptionVersion: result.encryptionVersion,
+      keyVersion: result.keyVersion,
       keyType: result.keyType,
       // Note: No private key is ever returned
     };

src/key-management/key-management.service.spec.ts

@@ -42,6 +42,7 @@ describe('KeyManagementService', () => {
       expect(result).toHaveProperty('publicKey');
       expect(result).toHaveProperty('keyType', KeyType.STELLAR_ED25519);
       expect(result).toHaveProperty('encryptionVersion');
+      expect(result).toHaveProperty('keyVersion', 1);
 
       // Critical: Should NOT contain plaintext private key
       expect(result).not.toHaveProperty('privateKey');

src/key-management/key-management.service.ts

@@ -101,6 +101,7 @@ export class KeyManagementService {
       return {
         encryptedData,
         encryptionVersion: 1,
+        keyVersion: 1,
         keyType: request.keyType,
         publicKey: keyPair.publicKey,
       };
@@ -199,6 +200,7 @@ export class KeyManagementService {
   async reEncryptKey(
     encryptedKeyMaterial: string,
     keyType: KeyType,
+    currentKeyVersion: number = 1,
   ): Promise<EncryptedKeyMaterial> {
     try {
       // Decrypt with old encryption
@@ -209,15 +211,12 @@ export class KeyManagementService {
       const newEncryptedData =
         this.encryptionService.encryptAndSerialize(privateKeyMaterial);
 
-      // Derive public key for result
-      const provider = this.getProvider(keyType);
-      const keyPair = await provider.generateKeyPair(keyType); // Temp for structure
-
       this.logger.log('Successfully re-encrypted key material');
 
       return {
         encryptedData: newEncryptedData,
-        encryptionVersion: 2, // Increment version
+        encryptionVersion: 2, // Increment encryption envelope version
+        keyVersion: currentKeyVersion, // Key algorithm version is unchanged on re-encryption
         keyType,
         publicKey: '', // Would derive from private key in production
       };

src/wallets/domain/wallet.model.ts

@@ -37,6 +37,13 @@ export interface Wallet {
   /** Supports rotation by incrementing secret material while preserving history. */
   secretVersion: number;
 
+  /**
+   * Key algorithm/derivation scheme version (e.g. 1 = Stellar Ed25519 via stellar-sdk).
+   * Increment when the key algorithm or derivation path changes so consumers can detect
+   * stale material and trigger re-encryption or re-issuance.
+   */
+  keyVersion: number;
+
   /** Mainnet/testnet separation. */
   network: WalletNetwork;
 

src/wallets/wallet-creation-orchestrator.service.ts

@@ -242,6 +242,7 @@ export class WalletCreationOrchestrator {
           status: 'ACTIVE',
           encryptionVersion: 1,
           secretVersion: 1,
+          keyVersion: 1,
         },
       });
 
@@ -308,6 +309,7 @@ export class WalletCreationOrchestrator {
       encryptedSecret: prismaWallet.encryptedSecret,
       encryptionVersion: prismaWallet.encryptionVersion,
       secretVersion: prismaWallet.secretVersion,
+      keyVersion: prismaWallet.keyVersion ?? 1,
       network: prismaWallet.network as WalletNetwork,
       status: prismaWallet.status as WalletStatus,
       statusReason: prismaWallet.statusReason,

src/wallets/wallets.service.spec.ts

@@ -95,6 +95,7 @@ describe('WalletsService', () => {
         status: 'ACTIVE',
         encryptionVersion: 1,
         secretVersion: 1,
+        keyVersion: 1,
         statusReason: null,
         statusChangedAt: new Date(),
         rotatedFromId: null,
@@ -114,6 +115,7 @@ describe('WalletsService', () => {
       expect(result.wallet.userId).toBe('user-123');
       expect(result.wallet.publicKey).toBe('public-key-123');
       expect(result.privateKey).toBeDefined();
+      expect(result.wallet.keyVersion).toBe(1);
       expect(encryptionService.encryptAndSerialize).toHaveBeenCalled();
     });
 
@@ -251,6 +253,7 @@ describe('WalletsService', () => {
         publicKey: 'old-public-key',
         encryptedSecret: 'old-encrypted-secret',
         secretVersion: 1,
+        keyVersion: 1,
       };
 
       const updatedWallet = {
@@ -259,6 +262,7 @@ describe('WalletsService', () => {
         publicKey: 'new-public-key',
         encryptedSecret: 'new-encrypted-secret',
         secretVersion: 2,
+        keyVersion: 2,
         network: WalletNetwork.TESTNET,
         status: 'ACTIVE',
         encryptionVersion: 1,
@@ -279,8 +283,19 @@ describe('WalletsService', () => {
 
       expect(result.wallet.id).toBe('wallet-123');
       expect(result.wallet.secretVersion).toBe(2);
+      expect(result.wallet.keyVersion).toBe(2);
       expect(result.privateKey).toBeDefined();
       expect(encryptionService.encryptAndSerialize).toHaveBeenCalled();
+
+      // Verify both secretVersion and keyVersion are incremented in the update call
+      expect(mockPrisma.wallet.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            secretVersion: existingWallet.secretVersion + 1,
+            keyVersion: existingWallet.keyVersion + 1,
+          }),
+        }),
+      );
     });
 
     it('should throw NotFoundException if wallet not found', async () => {
@@ -291,4 +306,105 @@ describe('WalletsService', () => {
       );
     });
   });
+
+  describe('keyVersion field', () => {
+    it('should initialise keyVersion to 1 on wallet creation', async () => {
+      const mockWallet = {
+        id: 'wallet-kv-1',
+        userId: 'user-kv',
+        publicKey: 'pk',
+        encryptedSecret: 'enc',
+        network: WalletNetwork.TESTNET,
+        status: 'ACTIVE',
+        encryptionVersion: 1,
+        secretVersion: 1,
+        keyVersion: 1,
+        statusReason: null,
+        statusChangedAt: new Date(),
+        rotatedFromId: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrisma.wallet.findFirst.mockResolvedValue(null);
+      mockPrisma.wallet.create.mockResolvedValue(mockWallet);
+      jest.spyOn(encryptionService, 'encryptAndSerialize').mockReturnValue('enc');
+
+      const result = await service.createWallet({ userId: 'user-kv', network: WalletNetwork.TESTNET });
+
+      expect(result.wallet.keyVersion).toBe(1);
+      // Verify keyVersion: 1 is passed to Prisma on creation
+      expect(mockPrisma.wallet.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ keyVersion: 1 }),
+        }),
+      );
+    });
+
+    it('should increment keyVersion on key rotation', async () => {
+      const existingWallet = {
+        id: 'wallet-kv-2',
+        userId: 'user-kv',
+        publicKey: 'old-pk',
+        encryptedSecret: 'old-enc',
+        secretVersion: 3,
+        keyVersion: 3,
+      };
+      const updatedWallet = {
+        ...existingWallet,
+        publicKey: 'new-pk',
+        encryptedSecret: 'new-enc',
+        secretVersion: 4,
+        keyVersion: 4,
+        network: WalletNetwork.TESTNET,
+        status: 'ACTIVE',
+        encryptionVersion: 1,
+        statusReason: null,
+        statusChangedAt: new Date(),
+        rotatedFromId: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrisma.wallet.findUnique.mockResolvedValue(existingWallet);
+      mockPrisma.wallet.update.mockResolvedValue(updatedWallet);
+      jest.spyOn(encryptionService, 'encryptAndSerialize').mockReturnValue('new-enc');
+
+      const result = await service.rotateWalletKey('wallet-kv-2');
+
+      expect(result.wallet.keyVersion).toBe(4);
+      expect(mockPrisma.wallet.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ keyVersion: 4 }),
+        }),
+      );
+    });
+
+    it('should fall back to keyVersion 1 when field is absent (stale row)', async () => {
+      // Simulates a wallet row that pre-dates the migration (no keyVersion column yet)
+      const staleWallet = {
+        id: 'wallet-stale',
+        userId: 'user-stale',
+        publicKey: 'pk',
+        encryptedSecret: 'enc',
+        network: WalletNetwork.TESTNET,
+        status: 'ACTIVE',
+        encryptionVersion: 1,
+        secretVersion: 1,
+        // keyVersion intentionally omitted (simulates NULL / missing column on old row)
+        statusReason: null,
+        statusChangedAt: new Date(),
+        rotatedFromId: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrisma.wallet.findUnique.mockResolvedValue(staleWallet);
+
+      const result = await service.findWalletById('wallet-stale');
+
+      // mapPrismaWalletToDomain should coerce undefined/null to 1
+      expect(result.keyVersion).toBe(1);
+    });
+  });
 });

src/wallets/wallets.service.ts

@@ -85,6 +85,7 @@ export class WalletsService {
           status: 'ACTIVE',
           encryptionVersion: 1,
           secretVersion: 1,
+          keyVersion: 1,
         },
       });
 
@@ -239,6 +240,7 @@ export class WalletsService {
           publicKey: newKeyPair.publicKey,
           encryptedSecret: newEncryptedSecret,
           secretVersion: existingWallet.secretVersion + 1,
+          keyVersion: existingWallet.keyVersion + 1,
           updatedAt: new Date(),
         },
       });
@@ -334,6 +336,7 @@ export class WalletsService {
       encryptedSecret: prismaWallet.encryptedSecret,
       encryptionVersion: prismaWallet.encryptionVersion,
       secretVersion: prismaWallet.secretVersion,
+      keyVersion: prismaWallet.keyVersion ?? 1,
       network: prismaWallet.network as WalletNetwork,
       status: prismaWallet.status as WalletStatus,
       statusReason: prismaWallet.statusReason,