feat: single address policy

__tests__/integration/adapters/fullnode.adapter.ts

@@ -8,7 +8,7 @@
 
 import HathorWallet from '../../../src/new/wallet';
 import { WalletTracker } from '../utils/wallet-tracker.util';
-import { WalletState } from '../../../src/types';
+import { AddressScanPolicyData, SCANNING_POLICY, WalletState } from '../../../src/types';
 import type Transaction from '../../../src/models/transaction';
 import {
   generateConnection,
@@ -30,6 +30,7 @@ import type {
   CreateWalletResult,
 } from './types';
 import type { PrecalculatedWalletData } from '../helpers/wallet-precalculation.helper';
+import { getGapLimitConfig } from '../utils/core.util';
 
 /** Stop options shared between {@link stopWallet} and the {@link WalletTracker}. */
 const STOP_OPTIONS: WalletStopOptions = { cleanStorage: true, cleanAddresses: true };
@@ -215,6 +216,12 @@ export class FullnodeWalletTestAdapter implements IWalletTestAdapter {
     // When both are provided (e.g. shared readonly tests pass seed for service
     // pre-registration), prefer xpub/xpriv and omit the seed.
     const useSeed = !options?.xpub && !options?.xpriv;
+    let scanPolicy: AddressScanPolicyData | null = null;
+    if (options?.singleAddressMode === true) {
+      scanPolicy = { policy: SCANNING_POLICY.SINGLE_ADDRESS };
+    } else if (!options?.singleAddressMode) {
+      scanPolicy = getGapLimitConfig();
+    }
     return {
       ...(useSeed && walletData.words ? { seed: walletData.words } : {}),
       connection: generateConnection(),
@@ -229,6 +236,7 @@ export class FullnodeWalletTestAdapter implements IWalletTestAdapter {
       ...(options?.passphrase && { passphrase: options.passphrase }),
       ...(options?.multisig && { multisig: options.multisig }),
       ...(options?.tokenUid && { tokenUid: options.tokenUid }),
+      scanPolicy,
     };
   }
 }

__tests__/integration/adapters/service.adapter.ts

@@ -132,6 +132,7 @@ export class ServiceWalletTestAdapter implements IWalletTestAdapter {
       words: options?.xpub ? '' : options?.seed || '',
       xpub: options?.xpub || '',
       enableWs: false,
+      singleAddressMode: options?.singleAddressMode,
     });
 
     this.tracker.track(result.wallet);

__tests__/integration/adapters/types.ts

@@ -43,6 +43,7 @@ export interface CreateWalletOptions {
     numSignatures: number;
   };
   tokenUid?: string;
+  singleAddressMode?: boolean;
 }
 
 /**

__tests__/integration/fullnode-specific/start.test.ts

@@ -23,7 +23,7 @@ import { AuthorityType, TokenVersion } from '../../../src/types';
 import Network from '../../../src/models/network';
 import { MemoryStore, Storage } from '../../../src/storage';
 import { WalletTracker } from '../utils/wallet-tracker.util';
-import { deriveXpubFromSeed } from '../utils/core.util';
+import { deriveXpubFromSeed, getGapLimitConfig } from '../utils/core.util';
 import { WALLET_CONSTANTS } from '../configuration/test-constants';
 import {
   createTokenHelper,
@@ -168,6 +168,7 @@ describe('[Fullnode-specific] start', () => {
       password: DEFAULT_PASSWORD,
       pinCode: DEFAULT_PIN_CODE,
       preCalculatedAddresses: walletData.addresses,
+      scanPolicy: getGapLimitConfig(),
     });
     tracker.track(hWallet);
     await hWallet.start();
@@ -188,6 +189,7 @@ describe('[Fullnode-specific] start', () => {
       password: DEFAULT_PASSWORD,
       pinCode: DEFAULT_PIN_CODE,
       // No preCalculatedAddresses — all calculated at runtime
+      scanPolicy: getGapLimitConfig(),
     };
     const hWallet = new HathorWallet(walletConfig);
     tracker.track(hWallet);
@@ -211,6 +213,7 @@ describe('[Fullnode-specific] start', () => {
         pubkeys: multisigWalletsData.pubkeys,
         numSignatures: 3,
       },
+      scanPolicy: getGapLimitConfig(),
     };
 
     const hWallet = new HathorWallet(walletConfig);

__tests__/integration/helpers/genesis-wallet.helper.ts

@@ -10,7 +10,7 @@ import Connection from '../../../src/new/connection';
 import HathorWallet from '../../../src/new/wallet';
 import { waitForTxReceived, waitForWalletReady, waitUntilNextTimestamp } from './wallet.helper';
 import { loggers } from '../utils/logger.util';
-import { delay } from '../utils/core.util';
+import { delay, getGapLimitConfig } from '../utils/core.util';
 import { OutputValueType } from '../../../src/types';
 import Transaction from '../../../src/models/transaction';
 import { HathorWalletServiceWallet } from '../../../src';
@@ -53,6 +53,7 @@ export class GenesisWalletHelper {
         pinCode: pin,
         multisig: null,
         preCalculatedAddresses: WALLET_CONSTANTS.genesis.addresses,
+        scanPolicy: getGapLimitConfig(),
       });
       await this.hWallet.start();
 

__tests__/integration/helpers/service-facade.helper.ts

@@ -55,6 +55,7 @@ export function buildWalletInstance({
   words = '',
   xpub = '',
   passwordForRequests = 'test-password',
+  singleAddressMode = false,
 } = {}) {
   let addresses: string[] = [];
 
@@ -82,6 +83,7 @@ export function buildWalletInstance({
     network,
     storage,
     enableWs,
+    singleAddressMode,
   });
 
   return { wallet: newWallet, store, storage, words, addresses };

__tests__/integration/helpers/wallet.helper.ts

@@ -17,7 +17,7 @@ import {
 import HathorWallet from '../../../src/new/wallet';
 import walletUtils from '../../../src/utils/wallet';
 import { multisigWalletsData, precalculationHelpers } from './wallet-precalculation.helper';
-import { delay } from '../utils/core.util';
+import { delay, getGapLimitConfig } from '../utils/core.util';
 import { loggers } from '../utils/logger.util';
 import { MemoryStore, Storage } from '../../../src/storage';
 import { TxHistoryProcessingStatus, IHistoryTx } from '../../../src/types';
@@ -101,6 +101,7 @@ export async function generateWalletHelper(param) {
     password: DEFAULT_PASSWORD,
     pinCode: DEFAULT_PIN_CODE,
     preCalculatedAddresses: walletData.addresses,
+    scanPolicy: getGapLimitConfig(),
   };
   if (param) {
     Object.assign(walletConfig, param);
@@ -158,6 +159,7 @@ export async function generateWalletHelperRO(options) {
     password: DEFAULT_PASSWORD,
     pinCode: DEFAULT_PIN_CODE,
     preCalculatedAddresses: walletData.addresses,
+    scanPolicy: getGapLimitConfig(),
   };
   const hWallet = new HathorWallet(walletConfig);
   await hWallet.start();
@@ -196,6 +198,7 @@ export async function generateMultisigWalletHelper(parameters) {
       pubkeys: parameters.pubkeys || multisigWalletsData.pubkeys,
       numSignatures: parameters.numSignatures || 3,
     },
+    scanPolicy: getGapLimitConfig(),
   };
   const mhWallet = new HathorWallet(walletConfig);
   await mhWallet.start();

__tests__/integration/shared/start.test.ts

@@ -10,10 +10,12 @@ import type { EventEmitter } from 'events';
 import type { AddressInfoObject } from '../../../src/wallet/types';
 import type { ConcreteWalletType, FuzzyWalletType, IWalletTestAdapter } from '../adapters/types';
 import { NATIVE_TOKEN_UID } from '../../../src/constants';
-import { deriveXpubFromSeed, getRandomInt } from '../utils/core.util';
+import { delay, deriveXpubFromSeed, getRandomInt } from '../utils/core.util';
 import { loggers } from '../utils/logger.util';
 import { FullnodeWalletTestAdapter } from '../adapters/fullnode.adapter';
 import { ServiceWalletTestAdapter } from '../adapters/service.adapter';
+import { WalletAddressMode } from '../../../src';
+import { HasTxOutsideFirstAddressError } from '../../../src/errors';
 
 const adapters: IWalletTestAdapter[] = [
   new FullnodeWalletTestAdapter(),
@@ -266,6 +268,30 @@ describe.each(adapters)('[Shared] start — $name', adapter => {
         await adapter.stopWallet(wallet);
       }
     });
+
+    it('should be able to start in single address mode', async () => {
+      const walletData = adapter.getPrecalculatedWallet();
+      const xpub = deriveXpubFromSeed(walletData.words);
+
+      const { wallet } = await adapter.createWallet({
+        seed: walletData.words,
+        xpub,
+        preCalculatedAddresses: walletData.addresses,
+        singleAddressMode: true,
+      });
+
+      try {
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+        const currentAddress = await wallet.getCurrentAddress();
+        expect(currentAddress.index).toBe(0);
+        expect(currentAddress.address).toBe(walletData.addresses[0]);
+        const nextAddress = await wallet.getNextAddress();
+        expect(nextAddress.index).toBe(0);
+        expect(nextAddress.address).toBe(walletData.addresses[0]);
+      } finally {
+        await adapter.stopWallet(wallet);
+      }
+    });
   });
 
   // --- Stop lifecycle tests ---
@@ -290,4 +316,138 @@ describe.each(adapters)('[Shared] start — $name', adapter => {
       await expect(adapter.stopWallet(wallet)).resolves.not.toThrow();
     });
   });
+
+  // --- Single Address mode ---
+
+  describe('single address mode', () => {
+    it('should be able to receive txs on index 0 and keep in single address mode', async () => {
+      const walletData = adapter.getPrecalculatedWallet();
+
+      const { wallet } = await adapter.createWallet({
+        seed: walletData.words,
+        preCalculatedAddresses: walletData.addresses,
+        singleAddressMode: true,
+      });
+
+      try {
+        // Start in SINGLE mode
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+        const currentAddress = await wallet.getCurrentAddress();
+        expect(currentAddress.index).toBe(0);
+        expect(currentAddress.address).toBe(walletData.addresses[0]);
+        const nextAddress = await wallet.getNextAddress();
+        expect(nextAddress.index).toBe(0);
+        expect(nextAddress.address).toBe(walletData.addresses[0]);
+
+        // Tx in index 0
+        const addr = await wallet.getAddressAtIndex(0);
+        expect(addr).toBeDefined();
+        await adapter.injectFunds(wallet, addr!, 1n);
+
+        // Current and next address is still 0 and in SINGLE mode
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+        const currentAddressAfterTx = await wallet.getCurrentAddress();
+        expect(currentAddressAfterTx.index).toBe(0);
+        expect(currentAddressAfterTx.address).toBe(walletData.addresses[0]);
+        const nextAddressAfterTx = await wallet.getNextAddress();
+        expect(nextAddressAfterTx.index).toBe(0);
+        expect(nextAddressAfterTx.address).toBe(walletData.addresses[0]);
+      } finally {
+        await adapter.stopAllWallets();
+      }
+    });
+
+    it('should be able to switch between modes', async () => {
+      const walletData = adapter.getPrecalculatedWallet();
+
+      const { wallet } = await adapter.createWallet({
+        seed: walletData.words,
+        preCalculatedAddresses: walletData.addresses,
+        singleAddressMode: true,
+      });
+
+      try {
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+
+        await wallet.enableMultiAddressMode();
+
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+
+        await wallet.enableSingleAddressMode();
+
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+      } finally {
+        await adapter.stopAllWallets();
+      }
+    });
+
+    it('should not be able to switch with tx outside index 0', async () => {
+      const walletData = adapter.getPrecalculatedWallet();
+
+      try {
+        const { wallet: walletMulti } = await adapter.createWallet({
+          seed: walletData.words,
+          preCalculatedAddresses: walletData.addresses,
+          singleAddressMode: false,
+        });
+        await expect(walletMulti.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+
+        // Tx in index 1
+        const addr1 = await walletMulti.getAddressAtIndex(1);
+        expect(addr1).toBeDefined();
+        await adapter.injectFunds(walletMulti, addr1!, 1n);
+        await adapter.stopWallet(walletMulti);
+
+        // Re-create the wallet with single address mode
+        const { wallet } = await adapter.createWallet({
+          seed: walletData.words,
+          preCalculatedAddresses: walletData.addresses,
+          singleAddressMode: true, // This will be ignored by the wallet
+        });
+
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+        await expect(wallet.enableSingleAddressMode()).rejects.toThrow(
+          HasTxOutsideFirstAddressError
+        );
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+      } finally {
+        await adapter.stopAllWallets();
+      }
+    });
+
+    it('should not respond to tx on not-loaded index', async () => {
+      const walletData = adapter.getPrecalculatedWallet();
+
+      try {
+        const { wallet: walletMulti } = await adapter.createWallet({
+          seed: walletData.words,
+          preCalculatedAddresses: walletData.addresses,
+          singleAddressMode: false,
+        });
+        await expect(walletMulti.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+        // Re-create the wallet with single address mode
+        const { wallet } = await adapter.createWallet({
+          seed: walletData.words,
+          preCalculatedAddresses: walletData.addresses,
+          singleAddressMode: true,
+        });
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+
+        // Same address on index 1 since its the same wallet
+        const addr1Multi = await walletMulti.getAddressAtIndex(1);
+        const addr1 = await wallet.getAddressAtIndex(1);
+        expect(addr1).toEqual(addr1Multi);
+        // Tx in index 1
+        expect(addr1).toBeDefined();
+        await adapter.injectFunds(walletMulti, addr1!, 1n);
+
+        await delay(100);
+
+        await expect(wallet.getAddressMode()).resolves.toEqual(WalletAddressMode.SINGLE);
+        await expect(walletMulti.getAddressMode()).resolves.toEqual(WalletAddressMode.MULTI);
+      } finally {
+        await adapter.stopAllWallets();
+      }
+    });
+  });
 });

__tests__/integration/storage/storage.test.ts

@@ -17,6 +17,7 @@ import { MemoryStore, Storage } from '../../../src/storage';
 import transactionUtils from '../../../src/utils/transaction';
 import { NATIVE_TOKEN_UID } from '../../../src/constants';
 import { IHathorWallet } from '../../../src/wallet/types';
+import { getGapLimitConfig } from '../utils/core.util';
 
 const startedWallets = [];
 
@@ -45,6 +46,7 @@ async function startWallet(storage, walletData) {
     pinCode: DEFAULT_PIN_CODE,
     preCalculatedAddresses: walletData.addresses,
     storage,
+    scanPolicy: getGapLimitConfig(),
   };
   const hWallet = new HathorWallet(walletConfig);
   await hWallet.start();

__tests__/integration/utils/core.util.ts

@@ -8,6 +8,7 @@
 import Mnemonic from 'bitcore-mnemonic/lib/mnemonic';
 import { P2PKH_ACCT_PATH } from '../../../src/constants';
 import Network from '../../../src/models/network';
+import { AddressScanPolicyData, SCANNING_POLICY } from '../../../src/types';
 
 /**
  * Simple way to wait asynchronously before continuing the funcion. Does not block the JS thread.
@@ -35,3 +36,10 @@ export function deriveXpubFromSeed(words: string): string {
   const rootXpriv = code.toHDPrivateKey('', new Network('testnet'));
   return rootXpriv.deriveNonCompliantChild(P2PKH_ACCT_PATH).xpubkey;
 }
+
+/**
+ * Generates a gap limit scanning policy configuration.
+ */
+export function getGapLimitConfig(gapLimit: number = 20): AddressScanPolicyData {
+  return { policy: SCANNING_POLICY.GAP_LIMIT, gapLimit };
+}