backend/frontend: add option to configure bitcoin gap limit

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Allow up to 6 unused BTC/LTC accounts (previously 5)
 - Add support for New Zealand Dollar (NZD)
 - Fix empty suggested name for BTC account when only BTC is supported by the BitBox.
+- Add expert setting to configure gap limit for bitcoin transaction discovery
 
 ## v4.48.4
 - macOS: fix potential USB communication issue with BitBox02 bootloaders <v1.1.2 and firmwares <v9.23.1

backend/accounts.go

@@ -29,6 +29,7 @@ import (
 	"github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/btc"
 	"github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/btc/addresses"
 	"github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/btc/blockchain"
+	btctypes "github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/btc/types"
 	coinpkg "github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/coin"
 	"github.com/BitBoxSwiss/bitbox-wallet-app/backend/coins/eth"
 	"github.com/BitBoxSwiss/bitbox-wallet-app/backend/config"
@@ -1072,10 +1073,23 @@ func (backend *Backend) createAndAddAccount(coin coinpkg.Coin, persistedConfig *
 
 	switch specificCoin := coin.(type) {
 	case *btc.Coin:
+		// Arguments have priority over config settings
+		gapLimits := backend.arguments.GapLimits()
+
+		if gapLimits == nil {
+			configReceive := uint16(backend.config.AppConfig().Backend.GapLimitReceive)
+			configChange := uint16(backend.config.AppConfig().Backend.GapLimitChange)
+			if configReceive > 0 && configChange > 0 {
+				gapLimits = &btctypes.GapLimits{
+					Receive: configReceive,
+					Change:  configChange,
+				}
+			}
+		}
 		account = backend.makeBtcAccount(
 			accountConfig,
 			specificCoin,
-			backend.arguments.GapLimits(),
+			gapLimits,
 			getAddressCallback,
 			backend.log,
 		)

backend/config/config.go

@@ -106,6 +106,10 @@ type Backend struct {
 	// StartInTestnet represents whether the app should launch in testnet on the next start.
 	// It resets to `false` after the app starts.
 	StartInTestnet bool `json:"startInTestnet"`
+
+	// Gap limits optionally forces gap limits for receive/change addresses used in bitcoin accounts
+	GapLimitReceive int `json:"gapLimitReceive"`
+	GapLimitChange  int `json:"gapLimitChange"`
 }
 
 // DeprecatedCoinActive returns the Active setting for a coin by code.  This call is should not be

frontends/web/src/locales/en/app.json

@@ -388,6 +388,7 @@
   "button": {
     "abort": "Abort",
     "back": "Back",
+    "cancel": "Cancel",
     "changepin": "Change device password",
     "check": "Check backup",
     "continue": "Continue",
@@ -402,6 +403,7 @@
     "proceedOnBitBox": "Proceed on your BitBox",
     "receive": "Receive",
     "restore": "Restore",
+    "save": "Save",
     "select": "Select",
     "send": "Send",
     "unlock": "Unlock",
@@ -822,6 +824,14 @@
   "footer": {
     "appVersion": "App version:"
   },
+  "gapLimit": {
+    "change": "Gap limit for change addresses",
+    "description": "Configure custom gap limits for bitcoin receive and change addresses.",
+    "minValue": "The gap limit must be at least {{min}}.",
+    "receive": "Gap limit for receive addresses",
+    "resetToDefault": "Reset to default",
+    "title": "Custom gap limit settings"
+  },
   "generic": {
     "buy": "Buy {{coinCode}}",
     "buySell": "Buy & sell",

frontends/web/src/routes/settings/advanced-settings.tsx

@@ -28,6 +28,7 @@ import { EnableTorProxySetting } from './components/advanced-settings/enable-tor
 import { UnlockSoftwareKeystore } from './components/advanced-settings/unlock-software-keystore';
 import { RestartInTestnetSetting } from './components/advanced-settings/restart-in-testnet-setting';
 import { ExportLogSetting } from './components/advanced-settings/export-log-setting';
+import { CustomGapLimitSettings } from './components/advanced-settings/custom-gap-limit-setting';
 import { getConfig } from '@/utils/config';
 import { MobileHeader } from './components/mobile-header';
 import { Guide } from '@/components/guide/guide';
@@ -50,6 +51,8 @@ export type TBackendConfig = {
   proxy?: TProxyConfig
   authentication?: boolean;
   startInTestnet?: boolean;
+  gapLimitReceive?: number;
+  gapLimitChange?: number;
 }
 
 export type TConfig = {
@@ -99,6 +102,7 @@ export const AdvancedSettings = ({ devices, hasAccounts }: TPagePropsWithSetting
                 <EnableAuthSetting backendConfig={backendConfig} onChangeConfig={setConfig} />
                 <EnableTorProxySetting proxyConfig={proxyConfig} onChangeConfig={setConfig} />
                 <RestartInTestnetSetting onChangeConfig={setConfig} />
+                <CustomGapLimitSettings backendConfig={backendConfig} onChangeConfig={setConfig} />
                 <UnlockSoftwareKeystore deviceIDs={deviceIDs}/>
                 <ConnectFullNodeSetting />
                 <ExportLogSetting />

frontends/web/src/routes/settings/components/advanced-settings/custom-gap-limit-setting.tsx

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2025 Shift Crypto AG
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { SettingsItem } from '@/routes/settings/components/settingsItem/settingsItem';
+import { Dialog, DialogButtons } from '@/components/dialog/dialog';
+import { Button } from '@/components/forms';
+import { NumberInput } from '@/components/forms/input-number';
+import { setConfig } from '@/utils/config';
+import type { TBackendConfig, TConfig } from '@/routes/settings/advanced-settings';
+
+type TProps = {
+  backendConfig?: TBackendConfig;
+  onChangeConfig: (config: TConfig) => void;
+}
+
+export const CustomGapLimitSettings = ({ backendConfig, onChangeConfig }: TProps) => {
+  const { t } = useTranslation();
+  const [showDialog, setShowDialog] = useState(false);
+
+  const DEFAULT_GAP_LIMIT_RECEIVE = 20;
+  const DEFAULT_GAP_LIMIT_CHANGE = 6;
+
+  const [gapLimitReceive, setGapLimitReceive] = useState(backendConfig?.gapLimitReceive || DEFAULT_GAP_LIMIT_RECEIVE);
+  const [gapLimitChange, setGapLimitChange] = useState(backendConfig?.gapLimitChange || DEFAULT_GAP_LIMIT_CHANGE);
+
+  useEffect(() => {
+    if (backendConfig) {
+      setGapLimitReceive(backendConfig.gapLimitReceive || DEFAULT_GAP_LIMIT_RECEIVE);
+      setGapLimitChange(backendConfig.gapLimitChange || DEFAULT_GAP_LIMIT_CHANGE);
+    }
+  }, [backendConfig]);
+
+  const handleSave = async () => {
+    const config = await setConfig({
+      backend: {
+        ...backendConfig,
+        gapLimitReceive,
+        gapLimitChange,
+      },
+    }) as TConfig;
+    onChangeConfig(config);
+    setShowDialog(false);
+  };
+
+  return (
+    <>
+      <SettingsItem
+        settingName={t('gapLimit.title')}
+        secondaryText={t('gapLimit.description')}
+        onClick={() => setShowDialog(true)}
+      />
+      <Dialog
+        open={showDialog}
+        onClose={() => setShowDialog(false)}
+        title={t('gapLimit.title')}
+        small>
+        <div className="columnsContainer half">
+          <div className="columns half">
+            <div className="column">
+              <NumberInput
+                label={t('gapLimit.receive')}
+                value={gapLimitReceive}
+                onChange={(e) => setGapLimitReceive(Number((e.target as HTMLInputElement).value) || DEFAULT_GAP_LIMIT_RECEIVE)}
+                error={gapLimitReceive < DEFAULT_GAP_LIMIT_RECEIVE ? t('gapLimit.minValue', { min: DEFAULT_GAP_LIMIT_RECEIVE }) : undefined}
+              />
+            </div>
+            <div className="column">
+              <NumberInput
+                label={t('gapLimit.change')}
+                value={gapLimitChange}
+                onChange={(e) => setGapLimitChange(parseInt((e.target as HTMLInputElement).value, 10) || DEFAULT_GAP_LIMIT_CHANGE)}
+                error={gapLimitChange < DEFAULT_GAP_LIMIT_CHANGE ? t('gapLimit.minValue', { min: DEFAULT_GAP_LIMIT_CHANGE }) : undefined}
+              />
+            </div>
+            <div>
+              <Button
+                onClick={() => {
+                  setGapLimitReceive(DEFAULT_GAP_LIMIT_RECEIVE);
+                  setGapLimitChange(DEFAULT_GAP_LIMIT_CHANGE);
+                }}
+                transparent
+                style={{ paddingLeft: '0' }}>
+                {t('gapLimit.resetToDefault')}
+              </Button>
+            </div>
+          </div>
+        </div>
+        <DialogButtons>
+          <Button
+            primary
+            disabled={gapLimitReceive < DEFAULT_GAP_LIMIT_RECEIVE || gapLimitChange < DEFAULT_GAP_LIMIT_CHANGE}
+            onClick={handleSave}>
+            {t('button.save')}
+          </Button>
+          <Button
+            secondary
+            onClick={() => setShowDialog(false)}>
+            {t('button.cancel')}
+          </Button>
+        </DialogButtons>
+      </Dialog>
+    </>
+  );
+};