feat!: add a new function to generate and track unused addresses in ObservableWallets

AngelCastilloB · AngelCastilloB · commit d1418f4ad415 · 2024-08-02T19:55:00.000+08:00
BREAKING CHANGE: CIP30 getUnusedAddresses now returns the next used address instead of an empty array
- add a new getNextUnusedAddress method to the ObservableWallet interface.
diff --git a/packages/wallet/src/Wallets/BaseWallet.ts b/packages/wallet/src/Wallets/BaseWallet.ts
@@ -41,6 +41,7 @@ import {
   distinctBlock,
   distinctEraSummaries
 } from '../services';
+import { AddressType, Bip32Account, GroupedAddress, WitnessedTx, Witnesser, util } from '@cardano-sdk/key-management';
 import {
   AssetProvider,
   Cardano,
@@ -64,6 +65,7 @@ import {
   SignDataProps,
   SyncStatus,
   UpdateWitnessProps,
+  WalletAddress,
   WalletNetworkInfoProvider
 } from '../types';
 import { BehaviorObservable, TrackerSubject, coldObservableProvider } from '@cardano-sdk/util-rxjs';
@@ -86,7 +88,6 @@ import {
   tap,
   throwError
 } from 'rxjs';
-import { Bip32Account, GroupedAddress, WitnessedTx, Witnesser, util } from '@cardano-sdk/key-management';
 import { ChangeAddressResolver, InputSelector, roundRobinRandomImprove } from '@cardano-sdk/input-selection';
 import { Cip30DataSignature } from '@cardano-sdk/dapp-connector';
 import { Ed25519PublicKey, Ed25519PublicKeyHex } from '@cardano-sdk/crypto';
@@ -142,6 +143,27 @@ export const isBip32PublicCredentialsManager = (
   credManager: PublicCredentialsManager
 ): credManager is Bip32PublicCredentialsManager => !isScriptPublicCredentialsManager(credManager);
 
+/**
+ * Gets whether the given address has a transaction history.
+ *
+ * @param address The address to query.
+ * @param chainHistoryProvider The chain history provider where to fetch the history from.
+ */
+const addressHasTx = async (
+  address: Cardano.PaymentAddress,
+  chainHistoryProvider: ChainHistoryProvider
+): Promise<boolean> => {
+  const txs = await chainHistoryProvider.transactionsByAddresses({
+    addresses: [address],
+    pagination: {
+      limit: 1,
+      startAt: 0
+    }
+  });
+
+  return txs.totalResultCount > 0;
+};
+
 export interface BaseWalletDependencies {
   readonly witnesser: Witnesser;
   readonly txSubmitProvider: TxSubmitProvider;
@@ -821,6 +843,41 @@ export class BaseWallet implements ObservableWallet {
     return firstValueFrom(this.addresses$);
   }
 
+  async getNextUnusedAddress(): Promise<WalletAddress[]> {
+    const knownAddresses = await firstValueFrom(this.addresses$);
+
+    if (knownAddresses.length === 0) {
+      throw new Error('No known address found for this wallet');
+    }
+
+    if (isBip32PublicCredentialsManager(this.#publicCredentialsManager)) {
+      knownAddresses.sort((a, b) => b.index - a.index);
+      const latestAddress = knownAddresses[0];
+
+      let isEmpty = !(await addressHasTx(latestAddress.address, this.chainHistoryProvider));
+
+      if (isEmpty) return [latestAddress];
+
+      const newAddress = await this.#publicCredentialsManager.bip32Account.deriveAddress(
+        { index: latestAddress.index + 1, type: AddressType.External },
+        0
+      );
+
+      await firstValueFrom(this.#addressTracker.addAddresses([newAddress]));
+
+      // Sanity check, make sure the newly generated address is also empty.
+      isEmpty = !(await addressHasTx(newAddress.address, this.chainHistoryProvider));
+
+      if (isEmpty) return [newAddress];
+
+      return await this.getNextUnusedAddress();
+    }
+
+    // Script wallet.
+    const isEmpty = !(await addressHasTx(knownAddresses[0].address, this.chainHistoryProvider));
+    return isEmpty ? [knownAddresses[0]] : [];
+  }
+
   /** Update the witness of a transaction with witness provided by this wallet */
   async updateWitness({ tx, sender }: UpdateWitnessProps): Promise<Cardano.Tx> {
     return this.finalizeTx({
diff --git a/packages/wallet/src/cip30.ts b/packages/wallet/src/cip30.ts
@@ -388,7 +388,10 @@ const baseCip30WalletApi = (
   },
   getUnusedAddresses: async (): Promise<Cbor[]> => {
     logger.debug('getting unused addresses');
-    return Promise.resolve([]);
+    const wallet = await firstValueFrom(wallet$);
+    const addresses = await wallet.getNextUnusedAddress();
+
+    return addresses.map((groupAddresses) => cardanoAddressToCbor(groupAddresses.address));
   },
   getUsedAddresses: async (): Promise<Cbor[]> => {
     logger.debug('getting used addresses');
diff --git a/packages/wallet/src/types.ts b/packages/wallet/src/types.ts
@@ -130,6 +130,14 @@ export interface ObservableWallet {
    */
   discoverAddresses(): Promise<WalletAddress[]>;
 
+  /**
+   * Get the next unused address for the wallet.
+   *
+   * @returns Promise that resolves with the next unused addresses. Return an empty array if there
+   * are no available unused addresses (I.E Single address wallets such as script wallets which already used up their only address).
+   */
+  getNextUnusedAddress(): Promise<WalletAddress[]>;
+
   shutdown(): void;
 }
 
diff --git a/packages/wallet/test/PersonalWallet/methods.test.ts b/packages/wallet/test/PersonalWallet/methods.test.ts
@@ -1,6 +1,6 @@
 /* eslint-disable unicorn/consistent-destructuring, sonarjs/no-duplicate-string, @typescript-eslint/no-floating-promises, promise/no-nesting */
 import * as Crypto from '@cardano-sdk/crypto';
-import { AddressDiscovery, BaseWallet, TxInFlight, createPersonalWallet } from '../../src';
+import { AddressDiscovery, BaseWallet, TxInFlight, createPersonalWallet, createSharedWallet } from '../../src';
 import { AddressType, Bip32Account, GroupedAddress, Witnesser, util } from '@cardano-sdk/key-management';
 import { AssetId, createStubStakePoolProvider, mockProviders as mocks } from '@cardano-sdk/util-dev';
 import { BehaviorSubject, Subscription, firstValueFrom, skip } from 'rxjs';
@@ -76,6 +76,9 @@ describe('BaseWallet methods', () => {
     stakeKeyDerivationPath,
     type: AddressType.External
   };
+
+  const groupedAddress2: GroupedAddress = { ...groupedAddress, address: '1' as Cardano.PaymentAddress, index: 1 };
+  const groupedAddress3: GroupedAddress = { ...groupedAddress, address: '2' as Cardano.PaymentAddress, index: 2 };
   let txSubmitProvider: mocks.TxSubmitProviderStub;
   let networkInfoProvider: mocks.NetworkInfoProviderStub;
   let assetProvider: mocks.MockAssetProvider;
@@ -531,4 +534,260 @@ describe('BaseWallet methods', () => {
       await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual(newAddresses);
     });
   });
+
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  describe('getNextUnusedAddress', () => {
+    const script: Cardano.NativeScript = {
+      __type: Cardano.ScriptType.Native,
+      kind: Cardano.NativeScriptKind.RequireAllOf,
+      scripts: [
+        {
+          __type: Cardano.ScriptType.Native,
+          keyHash: Crypto.Ed25519KeyHashHex('b275b08c999097247f7c17e77007c7010cd19f20cc086ad99d398538'),
+          kind: Cardano.NativeScriptKind.RequireSignature
+        }
+      ]
+    };
+
+    // Computed from script above
+    const scriptAddress = {
+      accountIndex: 0,
+      address:
+        'addr_test1xrrujjsfy60k96pm8ymadcxhx82p54z3aswlwxa8r9pggy78e99qjf5lvt5rkwfh6msdwvw5rf29rmqa7ud6wx2zssfs0l4tsq' as Cardano.PaymentAddress,
+      index: 0,
+      networkId: Cardano.NetworkId.Testnet,
+      rewardAccount: 'stake_test17rrujjsfy60k96pm8ymadcxhx82p54z3aswlwxa8r9pggycfg4jxy' as Cardano.RewardAccount,
+      type: AddressType.External
+    };
+
+    beforeEach(() => {
+      wallet.shutdown();
+
+      bip32Account.deriveAddress = jest.fn((args) => {
+        if (args.index === 0) {
+          return Promise.resolve(groupedAddress);
+        }
+
+        if (args.index === 1) {
+          return Promise.resolve(groupedAddress2);
+        }
+
+        return Promise.resolve(groupedAddress3);
+      });
+    });
+
+    it('returns the latest known empty address if any', async () => {
+      chainHistoryProvider = {
+        blocksByHashes: jest.fn().mockResolvedValue([{ epoch: Cardano.EpochNo(3) }]),
+        healthCheck: jest.fn().mockResolvedValue({ ok: true }),
+        transactionsByAddresses: jest.fn().mockResolvedValue({
+          pageResults: [],
+          totalResultCount: 0
+        }),
+        transactionsByHashes: jest.fn().mockResolvedValue([])
+      };
+
+      wallet = createPersonalWallet(
+        { name: 'Test Wallet' },
+        {
+          addressDiscovery,
+          assetProvider,
+          bip32Account,
+          chainHistoryProvider,
+          handleProvider,
+          logger,
+          networkInfoProvider,
+          rewardsProvider,
+          stakePoolProvider,
+          txSubmitProvider,
+          utxoProvider,
+          witnesser
+        }
+      );
+
+      await waitForWalletStateSettle(wallet);
+
+      // Only one address being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([groupedAddress]);
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([groupedAddress]);
+    });
+
+    it('returns a fresh empty address if all known addresses are used', async () => {
+      chainHistoryProvider = {
+        blocksByHashes: jest.fn().mockResolvedValue([{ epoch: Cardano.EpochNo(3) }]),
+        healthCheck: jest.fn().mockResolvedValue({ ok: true }),
+        transactionsByAddresses: jest.fn((args) => {
+          if (args.addresses[0] === '1') {
+            return Promise.resolve({
+              pageResults: [],
+              totalResultCount: 0
+            });
+          }
+
+          return Promise.resolve({
+            pageResults: mocks.queryTransactionsResult.pageResults,
+            totalResultCount: mocks.queryTransactionsResult.totalResultCount
+          });
+        }),
+        transactionsByHashes: jest.fn().mockResolvedValue([])
+      };
+
+      wallet = createPersonalWallet(
+        { name: 'Test Wallet' },
+        {
+          addressDiscovery,
+          assetProvider,
+          bip32Account,
+          chainHistoryProvider,
+          handleProvider,
+          logger,
+          networkInfoProvider,
+          rewardsProvider,
+          stakePoolProvider,
+          txSubmitProvider,
+          utxoProvider,
+          witnesser
+        }
+      );
+
+      await waitForWalletStateSettle(wallet);
+
+      // Only one address being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([groupedAddress]);
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([groupedAddress2]);
+
+      // New empty address is now being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([groupedAddress, groupedAddress2]);
+
+      // No new addresses are generated until the new empty address is used up.
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([groupedAddress2]);
+    });
+
+    it('returns a fresh empty address if all known addresses are used, and the new created address was also used', async () => {
+      chainHistoryProvider = {
+        blocksByHashes: jest.fn().mockResolvedValue([{ epoch: Cardano.EpochNo(3) }]),
+        healthCheck: jest.fn().mockResolvedValue({ ok: true }),
+        transactionsByAddresses: jest.fn((args) => {
+          if (args.addresses[0] === '2') {
+            return Promise.resolve({
+              pageResults: [],
+              totalResultCount: 0
+            });
+          }
+
+          return Promise.resolve({
+            pageResults: mocks.queryTransactionsResult.pageResults,
+            totalResultCount: mocks.queryTransactionsResult.totalResultCount
+          });
+        }),
+        transactionsByHashes: jest.fn().mockResolvedValue([])
+      };
+
+      wallet = createPersonalWallet(
+        { name: 'Test Wallet' },
+        {
+          addressDiscovery,
+          assetProvider,
+          bip32Account,
+          chainHistoryProvider,
+          handleProvider,
+          logger,
+          networkInfoProvider,
+          rewardsProvider,
+          stakePoolProvider,
+          txSubmitProvider,
+          utxoProvider,
+          witnesser
+        }
+      );
+
+      await waitForWalletStateSettle(wallet);
+
+      // Only one address being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([groupedAddress]);
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([groupedAddress3]);
+
+      // Discovered used address, plus new empty address is now being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([
+        groupedAddress,
+        groupedAddress2,
+        groupedAddress3
+      ]);
+
+      // No new addresses are generated until the new empty address is used up.
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([groupedAddress3]);
+    });
+
+    it('returns script address if unused', async () => {
+      chainHistoryProvider = {
+        blocksByHashes: jest.fn().mockResolvedValue([{ epoch: Cardano.EpochNo(3) }]),
+        healthCheck: jest.fn().mockResolvedValue({ ok: true }),
+        transactionsByAddresses: jest.fn().mockResolvedValue({
+          pageResults: [],
+          totalResultCount: 0
+        }),
+        transactionsByHashes: jest.fn().mockResolvedValue([])
+      };
+
+      wallet = createSharedWallet(
+        { name: 'Test Wallet' },
+        {
+          assetProvider,
+          chainHistoryProvider,
+          handleProvider,
+          logger,
+          networkInfoProvider,
+          paymentScript: script,
+          rewardsProvider,
+          stakePoolProvider,
+          stakingScript: script,
+          txSubmitProvider,
+          utxoProvider,
+          witnesser
+        }
+      );
+
+      await waitForWalletStateSettle(wallet);
+
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([scriptAddress]);
+      // Only one address being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([scriptAddress]);
+    });
+
+    it('returns an empty array if script address is already used', async () => {
+      chainHistoryProvider = {
+        blocksByHashes: jest.fn().mockResolvedValue([{ epoch: Cardano.EpochNo(3) }]),
+        healthCheck: jest.fn().mockResolvedValue({ ok: true }),
+        transactionsByAddresses: jest.fn().mockResolvedValue({
+          pageResults: [],
+          totalResultCount: 1
+        }),
+        transactionsByHashes: jest.fn().mockResolvedValue([])
+      };
+
+      wallet = createSharedWallet(
+        { name: 'Test Wallet' },
+        {
+          assetProvider,
+          chainHistoryProvider,
+          handleProvider,
+          logger,
+          networkInfoProvider,
+          paymentScript: script,
+          rewardsProvider,
+          stakePoolProvider,
+          stakingScript: script,
+          txSubmitProvider,
+          utxoProvider,
+          witnesser
+        }
+      );
+
+      await waitForWalletStateSettle(wallet);
+
+      await expect(wallet.getNextUnusedAddress()).resolves.toEqual([]);
+      // Only one address being tracked.
+      await expect(firstValueFrom(wallet.addresses$)).resolves.toEqual([scriptAddress]);
+    });
+  });
 });
diff --git a/packages/wallet/test/integration/cip30mapping.test.ts b/packages/wallet/test/integration/cip30mapping.test.ts
diff --git a/packages/web-extension/src/observableWallet/util.ts b/packages/web-extension/src/observableWallet/util.ts
