feat: add blockfrost input resolver and address discovery (#1633)

Author: AngelCastilloB

apps/browser-extension-wallet/src/lib/scripts/background/config.ts

@@ -43,6 +43,7 @@ export const getProviders = async (chainName: Wallet.ChainName): Promise<Wallet.
   const baseCardanoServicesUrl = getBaseUrlForChain(chainName);
   const magic = getMagicForChain(chainName);
   const { customSubmitTxUrl, featureFlags } = await getBackgroundStorage();
+
   const isExperimentEnabled = (experimentName: ExperimentName) => !!(featureFlags?.[magic]?.[experimentName] ?? false);
 
   return Wallet.createProviders({
@@ -65,7 +66,8 @@ export const getProviders = async (chainName: Wallet.ChainName): Promise<Wallet.
       useBlockfrostNetworkInfoProvider: isExperimentEnabled(ExperimentName.BLOCKFROST_NETWORK_INFO_PROVIDER),
       useBlockfrostRewardsProvider: isExperimentEnabled(ExperimentName.BLOCKFROST_REWARDS_PROVIDER),
       useBlockfrostTxSubmitProvider: isExperimentEnabled(ExperimentName.BLOCKFROST_TX_SUBMIT_PROVIDER),
-      useBlockfrostUtxoProvider: isExperimentEnabled(ExperimentName.BLOCKFROST_UTXO_PROVIDER)
+      useBlockfrostUtxoProvider: isExperimentEnabled(ExperimentName.BLOCKFROST_UTXO_PROVIDER),
+      useBlockfrostAddressDiscovery: isExperimentEnabled(ExperimentName.BLOCKFROST_ADDRESS_DISCOVERY)
     }
   });
 };

apps/browser-extension-wallet/src/lib/scripts/background/wallet.ts

@@ -2,14 +2,7 @@
 import { runtime, storage as webStorage } from 'webextension-polyfill';
 import { of, combineLatest, map, EMPTY, BehaviorSubject, Observable, from, firstValueFrom, defaultIfEmpty } from 'rxjs';
 import { getProviders } from './config';
-import {
-  DEFAULT_LOOK_AHEAD_SEARCH,
-  DEFAULT_POLLING_CONFIG,
-  HDSequentialDiscovery,
-  createPersonalWallet,
-  storage,
-  createSharedWallet
-} from '@cardano-sdk/wallet';
+import { DEFAULT_POLLING_CONFIG, createPersonalWallet, storage, createSharedWallet } from '@cardano-sdk/wallet';
 import { handleHttpProvider } from '@cardano-sdk/cardano-services-client';
 import {
   AnyWallet,
@@ -177,6 +170,7 @@ const walletFactory: WalletFactory<Wallet.WalletMetadata, Wallet.AccountMetadata
       ? // eslint-disable-next-line no-magic-numbers
         Number(process.env.WALLET_POLLING_INTERVAL_IN_SEC) * 1000
       : DEFAULT_POLLING_CONFIG.pollInterval;
+
     return createPersonalWallet(
       {
         name: walletAccount.metadata.name,
@@ -196,7 +190,6 @@ const walletFactory: WalletFactory<Wallet.WalletMetadata, Wallet.AccountMetadata
               logger
             })
           : noopHandleResolver,
-        addressDiscovery: new HDSequentialDiscovery(providers.chainHistoryProvider, DEFAULT_LOOK_AHEAD_SEARCH),
         witnesser,
         bip32Account
       }

apps/browser-extension-wallet/src/providers/ExperimentsProvider/config.ts

@@ -12,6 +12,7 @@ export const getDefaultFeatureFlags = (): FallbackConfiguration => ({
   [ExperimentName.BLOCKFROST_REWARDS_PROVIDER]: false,
   [ExperimentName.BLOCKFROST_TX_SUBMIT_PROVIDER]: false,
   [ExperimentName.BLOCKFROST_UTXO_PROVIDER]: false,
+  [ExperimentName.BLOCKFROST_ADDRESS_DISCOVERY]: false,
   [ExperimentName.EXTENSION_STORAGE]: false,
   [ExperimentName.USE_DREP_PROVIDER_OVERRIDE]: false
 });
@@ -61,6 +62,10 @@ export const experiments: ExperimentsConfig = {
     value: false,
     default: false
   },
+  [ExperimentName.BLOCKFROST_ADDRESS_DISCOVERY]: {
+    value: false,
+    default: false
+  },
   [ExperimentName.EXTENSION_STORAGE]: {
     value: false,
     default: false

apps/browser-extension-wallet/src/providers/ExperimentsProvider/types.ts

@@ -17,6 +17,7 @@ export enum ExperimentName {
   BLOCKFROST_REWARDS_PROVIDER = 'blockfrost-rewards-provider',
   BLOCKFROST_TX_SUBMIT_PROVIDER = 'blockfrost-tx-submit-provider',
   BLOCKFROST_UTXO_PROVIDER = 'blockfrost-utxo-provider',
+  BLOCKFROST_ADDRESS_DISCOVERY = 'blockfrost-address-discovery',
   EXTENSION_STORAGE = 'extension-storage',
   USE_DREP_PROVIDER_OVERRIDE = 'use-drep-provider-override'
 }

packages/cardano/src/wallet/index.ts

@@ -85,6 +85,8 @@ export * from '@wallet/lib/get-auxiliary-data';
 export * as util from '@wallet/util';
 export * from '@wallet/lib/providers';
 export * from '@wallet/lib/config';
+export * from '@wallet/lib/blockfrost-input-resolver';
+export * from '@wallet/lib/blockfrost-address-discovery';
 
 export * as mockUtils from '@wallet/test/mocks';
 export * from '@wallet/types';

packages/cardano/src/wallet/lib/__tests__/blockfrost-address-discovery.test.ts

@@ -0,0 +1,155 @@
+/* eslint-disable no-magic-numbers */
+import { BlockfrostAddressDiscovery } from '../blockfrost-address-discovery';
+import { Cardano } from '@cardano-sdk/core';
+import { BlockfrostClient, BlockfrostError } from '@cardano-sdk/cardano-services-client';
+import { Logger } from 'ts-log';
+import { AddressType, Bip32Account, KeyRole } from '@cardano-sdk/key-management';
+
+jest.mock('@cardano-sdk/cardano-services-client');
+
+describe('BlockfrostAddressDiscovery', () => {
+  let clientMock: jest.Mocked<BlockfrostClient>;
+  let loggerMock: jest.Mocked<Logger>;
+  let accountMock: jest.Mocked<Bip32Account>;
+  let addressDiscovery: BlockfrostAddressDiscovery;
+
+  beforeEach(() => {
+    clientMock = {
+      request: jest.fn()
+    } as unknown as jest.Mocked<BlockfrostClient>;
+
+    loggerMock = {
+      debug: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn()
+    } as unknown as jest.Mocked<Logger>;
+
+    accountMock = {
+      deriveAddress: jest.fn()
+    } as unknown as jest.Mocked<Bip32Account>;
+
+    addressDiscovery = new BlockfrostAddressDiscovery(clientMock, loggerMock);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should discover addresses correctly', async () => {
+    const rewardAccount = 'stake1u9p...' as Cardano.RewardAccount;
+    const paymentAddress1 = 'addr1...' as Cardano.PaymentAddress;
+    const paymentAddress2 = 'addr2...' as Cardano.PaymentAddress;
+
+    accountMock.deriveAddress
+      .mockResolvedValueOnce({
+        address: paymentAddress1,
+        rewardAccount,
+        type: AddressType.External,
+        index: 0,
+        networkId: Cardano.NetworkId.Mainnet,
+        accountIndex: 0,
+        stakeKeyDerivationPath: {
+          index: 0,
+          role: KeyRole.Stake
+        }
+      })
+      .mockResolvedValue({
+        address: paymentAddress2,
+        rewardAccount,
+        type: AddressType.External,
+        index: 1,
+        networkId: Cardano.NetworkId.Mainnet,
+        accountIndex: 0,
+        stakeKeyDerivationPath: {
+          index: 0,
+          role: KeyRole.Stake
+        }
+      });
+
+    clientMock.request.mockResolvedValueOnce([
+      {
+        address: paymentAddress1,
+        rewardAccount,
+        type: AddressType.External,
+        index: 0,
+        networkId: Cardano.NetworkId.Mainnet,
+        accountIndex: 0,
+        stakeKeyDerivationPath: {
+          index: 0,
+          role: KeyRole.Stake
+        }
+      },
+      {
+        address: paymentAddress2,
+        rewardAccount,
+        type: AddressType.External,
+        index: 1,
+        networkId: Cardano.NetworkId.Mainnet,
+        accountIndex: 0,
+        stakeKeyDerivationPath: {
+          index: 0,
+          role: KeyRole.Stake
+        }
+      }
+    ]);
+
+    const result = await addressDiscovery.discover(accountMock);
+
+    expect(result).toHaveLength(2);
+    expect(clientMock.request).toHaveBeenCalledWith(`accounts/${rewardAccount}/addresses?count=100&page=1`);
+  });
+
+  it('should not throw if Blockfrost returns 404 not found', async () => {
+    const rewardAccount = 'stake1u9p...' as Cardano.RewardAccount;
+    const paymentAddress1 = 'addr1...' as Cardano.PaymentAddress;
+
+    accountMock.deriveAddress.mockResolvedValue({
+      address: paymentAddress1,
+      rewardAccount,
+      type: AddressType.External,
+      index: 0,
+      networkId: Cardano.NetworkId.Mainnet,
+      accountIndex: 0,
+      stakeKeyDerivationPath: {
+        index: 0,
+        role: KeyRole.Stake
+      }
+    });
+
+    const error = new BlockfrostError(404, 'Not Found');
+    error.status = 404;
+
+    clientMock.request.mockRejectedValueOnce(error);
+    const result = await addressDiscovery.discover(accountMock);
+    expect(result).toHaveLength(1); // There is always at least one address
+  });
+
+  it('should handle unknown/franken addresses gracefully', async () => {
+    const rewardAccount = 'stake1u9p...' as Cardano.RewardAccount;
+    const paymentAddress1 = 'addr1...' as Cardano.PaymentAddress;
+    const frankenAddress = 'addrUnknown...' as Cardano.PaymentAddress;
+
+    accountMock.deriveAddress.mockResolvedValue({
+      address: paymentAddress1,
+      rewardAccount,
+      type: AddressType.External,
+      index: 0,
+      networkId: Cardano.NetworkId.Mainnet,
+      accountIndex: 0,
+      stakeKeyDerivationPath: {
+        index: 0,
+        role: KeyRole.Stake
+      }
+    });
+
+    clientMock.request.mockResolvedValueOnce([{ address: paymentAddress1 }, { address: frankenAddress }]);
+
+    const result = await addressDiscovery.discover(accountMock);
+
+    expect(result).toHaveLength(1);
+    expect(loggerMock.warn).toHaveBeenCalledWith('The following addresses under stakeIndex 0 were not matched:', [
+      frankenAddress
+    ]);
+  });
+});

packages/cardano/src/wallet/lib/__tests__/blockfrost-input-resolver.test.ts

@@ -0,0 +1,108 @@
+/* eslint-disable no-magic-numbers, camelcase */
+import { BlockfrostInputResolver } from '../blockfrost-input-resolver';
+import { Cardano } from '@cardano-sdk/core';
+import { BlockfrostClient, BlockfrostError, BlockfrostToCore } from '@cardano-sdk/cardano-services-client';
+import { Logger } from 'ts-log';
+
+jest.mock('@cardano-sdk/cardano-services-client');
+
+describe('BlockfrostInputResolver', () => {
+  let clientMock: jest.Mocked<BlockfrostClient>;
+  let loggerMock: jest.Mocked<Logger>;
+  let resolver: BlockfrostInputResolver;
+
+  beforeEach(() => {
+    clientMock = {
+      request: jest.fn()
+    } as unknown as jest.Mocked<BlockfrostClient>;
+
+    loggerMock = {
+      debug: jest.fn(),
+      error: jest.fn(),
+      warn: jest.fn()
+    } as unknown as jest.Mocked<Logger>;
+
+    resolver = new BlockfrostInputResolver(clientMock, loggerMock);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should resolve input using hints if available', async () => {
+    const txIn: Cardano.TxIn = { txId: 'txId1' as Cardano.TransactionId, index: 0 };
+    const hint = {
+      id: 'txId1' as Cardano.TransactionId,
+      body: {
+        outputs: [{ address: 'addr1' as Cardano.PaymentAddress, value: { coins: BigInt(1000) } }]
+      }
+    } as Cardano.Tx;
+
+    const result = await resolver.resolveInput(txIn, { hints: [hint] });
+
+    expect(result).toEqual(hint.body.outputs[0]);
+  });
+
+  it('should fetch transaction output on first resolve and use cache on second resolve', async () => {
+    const txIn: Cardano.TxIn = { txId: 'txId2' as Cardano.TransactionId, index: 1 };
+    const responseMock = {
+      outputs: [{ output_index: 1, address: 'addr2', amount: [{ unit: 'lovelace', quantity: '2000' }] }]
+    };
+
+    clientMock.request.mockResolvedValue(responseMock);
+
+    jest.spyOn(BlockfrostToCore, 'txOut').mockReturnValue({
+      address: 'addr2' as Cardano.PaymentAddress,
+      value: { coins: BigInt(2000) }
+    } as Cardano.TxOut);
+
+    const result1 = await resolver.resolveInput(txIn);
+
+    expect(result1).toEqual({ address: 'addr2', value: { coins: BigInt(2000) } });
+    expect(clientMock.request).toHaveBeenCalledWith('txs/txId2/utxos');
+    expect(clientMock.request).toHaveBeenCalledTimes(1);
+
+    const result2 = await resolver.resolveInput(txIn);
+
+    expect(result2).toEqual(result1);
+    expect(clientMock.request).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return null if transaction output is not found', async () => {
+    const txIn: Cardano.TxIn = { txId: 'txId3' as Cardano.TransactionId, index: 2 };
+    const responseMock = { outputs: [] };
+    clientMock.request.mockResolvedValue(responseMock);
+
+    const result = await resolver.resolveInput(txIn);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return null for 404 errors from Blockfrost', async () => {
+    const txIn: Cardano.TxIn = { txId: 'txId4' as Cardano.TransactionId, index: 0 };
+
+    const error = new BlockfrostError(404, 'Not Found');
+    error.status = 404;
+
+    clientMock.request.mockRejectedValue(error);
+
+    const result = await resolver.resolveInput(txIn);
+
+    expect(result).toBeNull();
+  });
+
+  it('should throw errors for non-404 Blockfrost errors', async () => {
+    const txIn: Cardano.TxIn = { txId: 'txId5' as Cardano.TransactionId, index: 0 };
+    const error = new BlockfrostError(500, 'Invalid Request');
+    error.status = 500;
+
+    clientMock.request.mockRejectedValue(error);
+
+    try {
+      await resolver.resolveInput(txIn);
+    } catch (error_) {
+      expect(error_).toBeInstanceOf(BlockfrostError);
+      expect(error_.status).toEqual(500);
+    }
+  });
+});