Dial primary plus fallback arkd-wallets

Add ARKD_WALLET_FALLBACK_ADDRS so arkd can connect to a primary
arkd-wallet plus additional LP wallets. Fallbacks are dialed and
validated (reachable, same network, initialized and unlocked) at
startup; the primary is unchanged and remains the sole source of the
forfeit pubkey, addresses and signing. Fallbacks are not used by sweep
yet.

The regtest compose stack now runs a second arkd-wallet so the existing
e2e suite exercises arkd with a fallback plugged in.

Author: bitcoin-coder-bob

README.md

@@ -81,6 +81,7 @@ The `arkd` server can be configured using environment variables and the admin se
 | `ARKD_REDIS_NUM_OF_RETRIES`         | Maximum number of retries for Redis write operations in case of conflicts       | -                              |
 | `ARKD_ESPLORA_URL`                  | Esplora API URL                                                                 | `https://blockstream.info/api` |
 | `ARKD_WALLET_ADDR`                  | The arkd wallet address to connect to in the form `host:port`                   | -                              |
+| `ARKD_WALLET_FALLBACK_ADDRS`        | Additional arkd-wallet addresses (other LPs), comma-separated `host:port` list   | -                              |
 | `ARKD_SIGNER_ADDR`                  | The signer address to connect to in the form `host:port`                        | value of `ARKD_WALLET_ADDR`    |
 | `ARKD_NO_MACAROONS`                 | Disable macaroon authentication                                                 | `false`                        |
 | `ARKD_NO_TLS`                       | Disable TLS                                                                     | `true`                         |
@@ -180,6 +181,16 @@ To connect `arkd` to `arkd-wallet` use this environment variable:
 export ARKD_WALLET_ADDR=localhost:6060
 ```
 
+### Configuring multiple LP wallets
+
+`arkd` can be backed by a primary `arkd-wallet` plus additional wallets belonging to other liquidity providers. List the additional wallets with `ARKD_WALLET_FALLBACK_ADDRS`, a comma-separated list of `host:port` addresses:
+
+```sh
+export ARKD_WALLET_FALLBACK_ADDRS=localhost:6061,localhost:6062
+```
+
+Every wallet, primary and fallback, must be initialized and unlocked out of band (see [Setup arkd](#setup-arkd)) and must be on the same network as the primary; `arkd` validates this at startup and refuses to start otherwise. The primary wallet remains the sole source of the forfeit address, connector address, scanning and signing. The additional wallets are used only as sweep fallbacks; that wiring lands in a later change.
+
 ### Connect to signer
 
 By default, `arkd` makes use of the provided `arkd-wallet` also as signer, but you can customize its url either via environment variable or via API.

docker-compose.regtest.yml

@@ -60,6 +60,26 @@ services:
       - ARKD_WALLET_SIGNER_KEY=afcd3fa10f82a05fddc9574fdb13b3991b568e89cc39a72ba4401df8abef35f0
     volumes:
       - arkd-wallet-volume:/app/data
+  # A second arkd-wallet acting as an additional LP wallet, wired into arkd as a
+  # sweep fallback via ARKD_WALLET_FALLBACK_ADDRS.
+  arkd-wallet-2:
+    restart: unless-stopped
+    build:
+      context: .
+      dockerfile: arkdwallet.Dockerfile
+    container_name: arkd-wallet-2
+    depends_on:
+      - nbxplorer
+    ports:
+      - "6061:6060"
+    environment:
+      - ARKD_WALLET_LOG_LEVEL=5
+      - ARKD_WALLET_NBXPLORER_URL=http://nbxplorer:32838
+      - ARKD_WALLET_DATADIR=./data/regtest-2
+      - ARKD_WALLET_NETWORK=regtest
+      - ARKD_WALLET_SIGNER_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
+    volumes:
+      - arkd-wallet-2-volume:/app/data
   redis:
     restart: unless-stopped
     image: redis:7-alpine
@@ -82,6 +102,7 @@ services:
     restart: unless-stopped
     depends_on:
       - arkd-wallet
+      - arkd-wallet-2
       - pg
       - redis
     ports:
@@ -106,6 +127,7 @@ services:
       - ARKD_BAN_THRESHOLD=1
       - ARKD_DATADIR=./data/regtest
       - ARKD_WALLET_ADDR=arkd-wallet:6060
+      - ARKD_WALLET_FALLBACK_ADDRS=arkd-wallet-2:6060
       - ARKD_ESPLORA_URL=http://chopsticks:3000
       - ARKD_DB_TYPE=${ARKD_DB_TYPE:-sqlite}
       - ARKD_PG_DB_URL=${ARKD_PG_DB_URL:-}
@@ -122,6 +144,8 @@ services:
 volumes:
   arkd-wallet-volume:
     name: arkd-wallet-volume
+  arkd-wallet-2-volume:
+    name: arkd-wallet-2-volume
   arkd-volume:
     name: arkd-volume
 

internal/config/config.go

@@ -95,6 +95,7 @@ type Config struct {
 	RedisUrl                   string
 	RedisTxNumOfRetries        int
 	WalletAddr                 string
+	WalletFallbackAddrs        []string
 	SignerAddr                 string
 	VtxoTreeExpiry             arklib.RelativeLocktime
 	UnilateralExitDelay        arklib.RelativeLocktime
@@ -145,21 +146,22 @@ type Config struct {
 	MaxConcurrentStreams uint32
 	StreamConnPoolSize   uint32
 
-	fee            ports.FeeManager
-	repo           ports.RepoManager
-	svc            application.Service
-	adminSvc       application.AdminService
-	wallet         ports.WalletService
-	signer         ports.SignerService
-	txBuilder      ports.TxBuilder
-	scanner        ports.BlockchainScanner
-	scheduler      ports.SchedulerService
-	unlocker       ports.Unlocker
-	liveStore      ports.LiveStore
-	network        *arklib.Network
-	roundReportSvc application.RoundReportService
-	alerts         ports.Alerts
-	settings       *domain.Settings
+	fee             ports.FeeManager
+	repo            ports.RepoManager
+	svc             application.Service
+	adminSvc        application.AdminService
+	wallet          ports.WalletService
+	walletFallbacks []ports.WalletService
+	signer          ports.SignerService
+	txBuilder       ports.TxBuilder
+	scanner         ports.BlockchainScanner
+	scheduler       ports.SchedulerService
+	unlocker        ports.Unlocker
+	liveStore       ports.LiveStore
+	network         *arklib.Network
+	roundReportSvc  application.RoundReportService
+	alerts          ports.Alerts
+	settings        *domain.Settings
 }
 
 func (c *Config) String() string {
@@ -180,6 +182,7 @@ func (c *Config) String() string {
 var (
 	Datadir                   = "DATADIR"
 	WalletAddr                = "WALLET_ADDR"
+	WalletFallbackAddrs       = "WALLET_FALLBACK_ADDRS"
 	SignerAddr                = "SIGNER_ADDR"
 	SessionDuration           = "SESSION_DURATION"
 	BanDuration               = "BAN_DURATION"
@@ -442,6 +445,7 @@ func LoadConfig() (*Config, error) {
 	return &Config{
 		Datadir:                   viper.GetString(Datadir),
 		WalletAddr:                viper.GetString(WalletAddr),
+		WalletFallbackAddrs:       parseWalletFallbackAddrs(viper.GetString(WalletFallbackAddrs)),
 		SignerAddr:                signerAddr,
 		SessionDuration:           viper.GetInt64(SessionDuration),
 		BanDuration:               viper.GetInt64(BanDuration),
@@ -664,6 +668,10 @@ func (c *Config) WalletService() ports.WalletService {
 	return c.wallet
 }
 
+func (c *Config) FallbackWalletServices() []ports.WalletService {
+	return c.walletFallbacks
+}
+
 func (c *Config) UnlockerService() ports.Unlocker {
 	return c.unlocker
 }
@@ -793,22 +801,86 @@ func (c *Config) repoManager() error {
 	return nil
 }
 
+// newWalletClient is the wallet client constructor, indirected so tests can
+// stub out the gRPC dial.
+var newWalletClient = walletclient.New
+
 func (c *Config) walletService() error {
 	arkWallet := c.WalletAddr
 	if arkWallet == "" {
 		return fmt.Errorf("missing ark wallet address")
 	}
 
-	walletSvc, network, err := walletclient.New(arkWallet, c.OtelCollectorEndpoint)
+	walletSvc, network, err := newWalletClient(arkWallet, c.OtelCollectorEndpoint)
 	if err != nil {
 		return err
 	}
 
 	c.wallet = walletSvc
 	c.network = network
+
+	fallbacks, err := c.dialFallbackWallets()
+	if err != nil {
+		return err
+	}
+	c.walletFallbacks = fallbacks
+
 	return nil
 }
 
+// dialFallbackWallets dials the configured fallback arkd-wallets and validates
+// that each one is reachable and on the same network as the primary. Fallback
+// wallets belong to additional liquidity providers and are used only as sweep
+// fallbacks; the primary remains the sole source of the forfeit pubkey,
+// addresses and signing. Any failure is fatal so a misconfigured wallet is
+// surfaced at startup rather than at sweep time.
+func (c *Config) dialFallbackWallets() ([]ports.WalletService, error) {
+	fallbacks := make([]ports.WalletService, 0, len(c.WalletFallbackAddrs))
+	for _, addr := range c.WalletFallbackAddrs {
+		if addr == "" {
+			continue
+		}
+		fbSvc, fbNetwork, err := newWalletClient(addr, c.OtelCollectorEndpoint)
+		if err != nil {
+			closeWallets(fallbacks)
+			return nil, fmt.Errorf("failed to dial fallback wallet %q: %w", addr, err)
+		}
+		if fbNetwork.Name != c.network.Name {
+			fbSvc.Close()
+			closeWallets(fallbacks)
+			return nil, fmt.Errorf(
+				"fallback wallet %q is on network %q, expected %q (same as primary)",
+				addr, fbNetwork.Name, c.network.Name,
+			)
+		}
+		log.Infof("dialed fallback wallet %q on network %s", addr, fbNetwork.Name)
+		fallbacks = append(fallbacks, fbSvc)
+	}
+	return fallbacks, nil
+}
+
+func closeWallets(wallets []ports.WalletService) {
+	for _, w := range wallets {
+		w.Close()
+	}
+}
+
+// parseWalletFallbackAddrs splits a comma-separated list of wallet addresses,
+// trimming whitespace and dropping empty entries.
+func parseWalletFallbackAddrs(raw string) []string {
+	parts := strings.Split(raw, ",")
+	addrs := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			addrs = append(addrs, p)
+		}
+	}
+	if len(addrs) == 0 {
+		return nil
+	}
+	return addrs
+}
+
 func (c *Config) signerService() error {
 	signer := c.SignerAddr
 	if signer == "" {

internal/config/config_test.go

@@ -1,9 +1,11 @@
 package config
 
 import (
+	"fmt"
 	"testing"
 	"time"
 
+	"github.com/arkade-os/arkd/internal/core/ports"
 	arklib "github.com/arkade-os/arkd/pkg/ark-lib"
 	"github.com/stretchr/testify/require"
 )
@@ -270,3 +272,98 @@ func TestConfigStringRedactsSecrets(t *testing.T) {
 		})
 	}
 }
+
+func TestParseWalletFallbackAddrs(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  string
+		want []string
+	}{
+		{"empty", "", nil},
+		{"single", "localhost:6061", []string{"localhost:6061"}},
+		{"multiple", "a:6060,b:6060,c:6060", []string{"a:6060", "b:6060", "c:6060"}},
+		{"trims whitespace", "a:6060, b:6060 ,c:6060", []string{"a:6060", "b:6060", "c:6060"}},
+		{"drops empty entries", "a:6060,,b:6060,", []string{"a:6060", "b:6060"}},
+		{"only separators", " , , ", nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			require.Equal(t, tt.want, parseWalletFallbackAddrs(tt.raw))
+		})
+	}
+}
+
+// fakeFallbackWallet is a ports.WalletService that only implements Close; via
+// the embedded nil interface every other method is unused by these tests.
+type fakeFallbackWallet struct {
+	ports.WalletService
+	closed *int
+}
+
+func (f *fakeFallbackWallet) Close() { *f.closed++ }
+
+func TestDialFallbackWallets(t *testing.T) {
+	orig := newWalletClient
+	t.Cleanup(func() { newWalletClient = orig })
+
+	regtest := &arklib.Network{Name: "regtest"}
+	testnet := &arklib.Network{Name: "testnet"}
+
+	t.Run("all on the same network", func(t *testing.T) {
+		var closes int
+		newWalletClient = func(_, _ string) (ports.WalletService, *arklib.Network, error) {
+			return &fakeFallbackWallet{closed: &closes}, regtest, nil
+		}
+
+		c := &Config{network: regtest, WalletFallbackAddrs: []string{"a:6060", "b:6060"}}
+		fbs, err := c.dialFallbackWallets()
+
+		require.NoError(t, err)
+		require.Len(t, fbs, 2)
+		require.Zero(t, closes)
+	})
+
+	t.Run("network mismatch hard-fails and closes dialed", func(t *testing.T) {
+		var closes, calls int
+		newWalletClient = func(_, _ string) (ports.WalletService, *arklib.Network, error) {
+			calls++
+			net := regtest
+			if calls == 2 {
+				net = testnet
+			}
+			return &fakeFallbackWallet{closed: &closes}, net, nil
+		}
+
+		c := &Config{network: regtest, WalletFallbackAddrs: []string{"a:6060", "b:6060"}}
+		fbs, err := c.dialFallbackWallets()
+
+		require.Error(t, err)
+		require.Nil(t, fbs)
+		require.Contains(t, err.Error(), "b:6060")
+		require.Contains(t, err.Error(), "testnet")
+		require.Contains(t, err.Error(), "regtest")
+		// The mismatched wallet and the previously dialed one are both closed.
+		require.Equal(t, 2, closes)
+	})
+
+	t.Run("dial error hard-fails and closes dialed", func(t *testing.T) {
+		var closes, calls int
+		newWalletClient = func(_, _ string) (ports.WalletService, *arklib.Network, error) {
+			calls++
+			if calls == 2 {
+				return nil, nil, fmt.Errorf("connection refused")
+			}
+			return &fakeFallbackWallet{closed: &closes}, regtest, nil
+		}
+
+		c := &Config{network: regtest, WalletFallbackAddrs: []string{"a:6060", "b:6060"}}
+		fbs, err := c.dialFallbackWallets()
+
+		require.Error(t, err)
+		require.Nil(t, fbs)
+		require.Contains(t, err.Error(), "b:6060")
+		// The first, successfully dialed fallback is closed.
+		require.Equal(t, 1, closes)
+	})
+}

internal/interface/grpc/service.go

@@ -230,6 +230,12 @@ func (s *service) stop() {
 			log.Warn("failed to close admin transport connection")
 		}
 	}
+
+	// Close the fallback wallet connections (the primary is closed by the app
+	// service). arkd owns these dialed connections, nothing else does.
+	for _, fb := range s.appConfig.FallbackWalletServices() {
+		fb.Close()
+	}
 }
 
 func (s *service) startAppServices() error {
@@ -673,6 +679,30 @@ func (s *service) ensureWalletReady() error {
 		)
 	}
 
+	// Fallback wallets must also be initialized and unlocked out of band: they
+	// are needed to sign sweeps when the primary cannot. Balance is not checked
+	// (they are not liquidity sources).
+	for i, fb := range s.appConfig.FallbackWalletServices() {
+		fbStatus, err := fb.Status(ctx)
+		if err != nil {
+			return fmt.Errorf("failed to get fallback wallet %d status: %s", i, err)
+		}
+		if !fbStatus.IsInitialized() {
+			return fmt.Errorf(
+				"fallback wallet %d is not initialized: "+
+					"initialize the arkd-wallet out of band before starting arkd",
+				i,
+			)
+		}
+		if !fbStatus.IsUnlocked() {
+			return fmt.Errorf(
+				"fallback wallet %d is locked: "+
+					"unlock the arkd-wallet out of band before starting arkd",
+				i,
+			)
+		}
+	}
+
 	return nil
 }