feat: add hot wallet low liquidity alert

AndresQuijano · AndresQuijano · commit 370e0941a153 · 2026-03-02T20:54:32.000Z
diff --git a/internal/adapters/entrypoints/watcher/liquidity_check.go b/internal/adapters/entrypoints/watcher/liquidity_check.go
@@ -2,30 +2,34 @@ package watcher
 
 import (
 	"context"
+	"time"
+
 	"github.com/rsksmart/liquidity-provider-server/internal/entities/utils"
 	"github.com/rsksmart/liquidity-provider-server/internal/usecases/liquidity_provider"
 	log "github.com/sirupsen/logrus"
-	"time"
 )
 
 type LiquidityCheckWatcher struct {
-	checkLiquidityUseCase *liquidity_provider.CheckLiquidityUseCase
-	watcherStopChannel    chan bool
-	ticker                utils.Ticker
-	validationTimeout     time.Duration
+	checkLiquidityUseCase    *liquidity_provider.CheckLiquidityUseCase
+	lowLiquidityAlertUseCase *liquidity_provider.LowLiquidityAlertUseCase
+	watcherStopChannel       chan bool
+	ticker                   utils.Ticker
+	validationTimeout        time.Duration
 }
 
 func NewLiquidityCheckWatcher(
 	checkLiquidityUseCase *liquidity_provider.CheckLiquidityUseCase,
+	lowLiquidityAlertUseCase *liquidity_provider.LowLiquidityAlertUseCase,
 	ticker utils.Ticker,
 	validationTimeout time.Duration,
 ) *LiquidityCheckWatcher {
 	watcherStopChannel := make(chan bool, 1)
 	return &LiquidityCheckWatcher{
-		checkLiquidityUseCase: checkLiquidityUseCase,
-		watcherStopChannel:    watcherStopChannel,
-		ticker:                ticker,
-		validationTimeout:     validationTimeout,
+		checkLiquidityUseCase:    checkLiquidityUseCase,
+		lowLiquidityAlertUseCase: lowLiquidityAlertUseCase,
+		watcherStopChannel:       watcherStopChannel,
+		ticker:                   ticker,
+		validationTimeout:        validationTimeout,
 	}
 }
 
@@ -46,6 +50,9 @@ watcherLoop:
 			if err := watcher.checkLiquidityUseCase.Run(ctx); err != nil {
 				log.Error("Error checking liquidity inside watcher: ", err)
 			}
+			if err := watcher.lowLiquidityAlertUseCase.Run(ctx); err != nil {
+				log.Error("Error checking low liquidity inside watcher: ", err)
+			}
 			cancel()
 		case <-watcher.watcherStopChannel:
 			watcher.ticker.Stop()
diff --git a/internal/adapters/entrypoints/watcher/liquidity_check_test.go b/internal/adapters/entrypoints/watcher/liquidity_check_test.go
@@ -2,6 +2,10 @@ package watcher_test
 
 import (
 	"context"
+	"sync"
+	"testing"
+	"time"
+
 	"github.com/rsksmart/liquidity-provider-server/internal/adapters/entrypoints/watcher"
 	"github.com/rsksmart/liquidity-provider-server/internal/entities"
 	"github.com/rsksmart/liquidity-provider-server/internal/entities/blockchain"
@@ -12,22 +16,20 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
-	"sync"
-	"testing"
-	"time"
 )
 
 func TestLiquidityCheckWatcher_Shutdown(t *testing.T) {
 	createWatcherShutdownTest(t, func(ticker utils.Ticker) watcher.Watcher {
-		return watcher.NewLiquidityCheckWatcher(nil, ticker, time.Duration(1))
+		return watcher.NewLiquidityCheckWatcher(nil, nil, ticker, time.Duration(1))
 	})
 }
 
 func TestNewLiquidityCheckWatcher(t *testing.T) {
 	ticker := &mocks.TickerMock{}
 	providerMock := &mocks.ProviderMock{}
-	useCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{}, &mocks.AlertSenderMock{}, test.AnyString)
-	test.AssertNonZeroValues(t, watcher.NewLiquidityCheckWatcher(useCase, ticker, time.Duration(1)))
+	checkLiquidityUseCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{}, &mocks.AlertSenderMock{}, test.AnyString)
+	lowLiquidityUseCase := liquidity_provider.NewLowLiquidityAlertUseCase(providerMock, providerMock, &mocks.AlertSenderMock{}, test.AnyString, 3, 1)
+	test.AssertNonZeroValues(t, watcher.NewLiquidityCheckWatcher(checkLiquidityUseCase, lowLiquidityUseCase, ticker, time.Duration(1)))
 }
 
 func TestLiquidityCheckWatcher_Start(t *testing.T) {
@@ -38,10 +40,15 @@ func TestLiquidityCheckWatcher_Start(t *testing.T) {
 	providerMock := &mocks.ProviderMock{}
 	providerMock.On("HasPeginLiquidity", mock.Anything, mock.Anything).Return(nil)
 	providerMock.On("HasPegoutLiquidity", mock.Anything, mock.Anything).Return(nil)
+	providerMock.On("AvailablePeginLiquidity", mock.Anything).Return(entities.NewWei(0), nil)
+	providerMock.On("AvailablePegoutLiquidity", mock.Anything).Return(entities.NewWei(0), nil)
 	bridgeMock := &mocks.BridgeMock{}
 	bridgeMock.On("GetMinimumLockTxValue").Return(entities.NewWei(5), nil)
-	useCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{Bridge: bridgeMock}, &mocks.AlertSenderMock{}, test.AnyString)
-	w := watcher.NewLiquidityCheckWatcher(useCase, ticker, time.Duration(1))
+	alertSenderMock := &mocks.AlertSenderMock{}
+	alertSenderMock.On("SendAlert", mock.Anything, mock.Anything, mock.Anything, mock.Anything).Return(nil)
+	checkLiquidityUseCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{Bridge: bridgeMock}, alertSenderMock, test.AnyString)
+	lowLiquidityUseCase := liquidity_provider.NewLowLiquidityAlertUseCase(providerMock, providerMock, alertSenderMock, test.AnyString, 3, 1)
+	w := watcher.NewLiquidityCheckWatcher(checkLiquidityUseCase, lowLiquidityUseCase, ticker, time.Duration(1))
 	wg := sync.WaitGroup{}
 	wg.Add(2)
 	closeChannel := make(chan bool)
@@ -68,10 +75,15 @@ func TestLiquidityCheckWatcher_Start_ErrorHandling(t *testing.T) {
 	ticker.EXPECT().C().Return(tickerChannel)
 	ticker.EXPECT().Stop().Return()
 	providerMock := &mocks.ProviderMock{}
+	providerMock.On("AvailablePeginLiquidity", mock.Anything).Return(entities.NewWei(0), nil)
+	providerMock.On("AvailablePegoutLiquidity", mock.Anything).Return(entities.NewWei(0), nil)
 	bridgeMock := &mocks.BridgeMock{}
 	bridgeMock.On("GetMinimumLockTxValue").Return(nil, assert.AnError)
-	useCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{Bridge: bridgeMock}, &mocks.AlertSenderMock{}, test.AnyString)
-	w := watcher.NewLiquidityCheckWatcher(useCase, ticker, time.Duration(1))
+	alertSenderMock := &mocks.AlertSenderMock{}
+	alertSenderMock.On("SendAlert", mock.Anything, mock.Anything, mock.Anything, mock.Anything).Return(nil)
+	checkLiquidityUseCase := liquidity_provider.NewCheckLiquidityUseCase(providerMock, providerMock, blockchain.RskContracts{Bridge: bridgeMock}, alertSenderMock, test.AnyString)
+	lowLiquidityUseCase := liquidity_provider.NewLowLiquidityAlertUseCase(providerMock, providerMock, alertSenderMock, test.AnyString, 3, 1)
+	w := watcher.NewLiquidityCheckWatcher(checkLiquidityUseCase, lowLiquidityUseCase, ticker, time.Duration(1))
 	wg := sync.WaitGroup{}
 	wg.Add(2)
 	defer test.AssertLogContains(t, assert.AnError.Error())
@@ -90,6 +102,6 @@ func TestLiquidityCheckWatcher_Start_ErrorHandling(t *testing.T) {
 }
 
 func TestLiquidityCheckWatcher_Prepare(t *testing.T) {
-	w := watcher.NewLiquidityCheckWatcher(nil, &mocks.TickerMock{}, time.Duration(1))
+	w := watcher.NewLiquidityCheckWatcher(nil, nil, &mocks.TickerMock{}, time.Duration(1))
 	require.NoError(t, w.Prepare(context.Background()))
 }
diff --git a/internal/configuration/environment/environment.go b/internal/configuration/environment/environment.go
@@ -190,20 +190,29 @@ type ManagementEnv struct {
 }
 
 type ColdWalletEnv struct {
-	BtcMinTransferFeeMultiplier  uint64 `env:"BTC_MIN_TRANSFER_FEE_MULTIPLIER"`
-	RbtcMinTransferFeeMultiplier uint64 `env:"RBTC_MIN_TRANSFER_FEE_MULTIPLIER"`
-	ForceTransferAfterSeconds    uint64 `env:"COLD_WALLET_FORCE_TRANSFER_AFTER_SECONDS"`
+	BtcMinTransferFeeMultiplier   uint64 `env:"BTC_MIN_TRANSFER_FEE_MULTIPLIER"`
+	RbtcMinTransferFeeMultiplier  uint64 `env:"RBTC_MIN_TRANSFER_FEE_MULTIPLIER"`
+	ForceTransferAfterSeconds     uint64 `env:"COLD_WALLET_FORCE_TRANSFER_AFTER_SECONDS"`
+	HotWalletLowLiquidityWarning  uint64 `env:"HOT_WALLET_LOW_LIQUIDITY_WARNING"`
+	HotWalletLowLiquidityCritical uint64 `env:"HOT_WALLET_LOW_LIQUIDITY_CRITICAL"`
 }
 
 func (env *ColdWalletEnv) FillWithDefaults() *ColdWalletEnv {
 	defaults := ColdWalletEnv{
-		BtcMinTransferFeeMultiplier:  5,
-		RbtcMinTransferFeeMultiplier: 100,
-		ForceTransferAfterSeconds:    1209600, // 2 weeks (14 days * 24 hours * 60 minutes * 60 seconds)
+		BtcMinTransferFeeMultiplier:   5,
+		RbtcMinTransferFeeMultiplier:  100,
+		ForceTransferAfterSeconds:     1209600, // 2 weeks (14 days * 24 hours * 60 minutes * 60 seconds)
+		HotWalletLowLiquidityWarning:  3,
+		HotWalletLowLiquidityCritical: 1,
 	}
 	env.BtcMinTransferFeeMultiplier = utils.FirstNonZero(env.BtcMinTransferFeeMultiplier, defaults.BtcMinTransferFeeMultiplier)
 	env.RbtcMinTransferFeeMultiplier = utils.FirstNonZero(env.RbtcMinTransferFeeMultiplier, defaults.RbtcMinTransferFeeMultiplier)
 	env.ForceTransferAfterSeconds = utils.FirstNonZero(env.ForceTransferAfterSeconds, defaults.ForceTransferAfterSeconds)
+	env.HotWalletLowLiquidityWarning = utils.FirstNonZero(env.HotWalletLowLiquidityWarning, defaults.HotWalletLowLiquidityWarning)
+	env.HotWalletLowLiquidityCritical = utils.FirstNonZero(env.HotWalletLowLiquidityCritical, defaults.HotWalletLowLiquidityCritical)
+	if env.HotWalletLowLiquidityCritical >= env.HotWalletLowLiquidityWarning {
+		log.Fatal("HOT_WALLET_LOW_LIQUIDITY_CRITICAL must be less than HOT_WALLET_LOW_LIQUIDITY_WARNING")
+	}
 	return env
 }
 
diff --git a/internal/configuration/registry/usecase.go b/internal/configuration/registry/usecase.go
@@ -82,6 +82,7 @@ type UseCaseRegistry struct {
 	recommendedPeginUseCase             *pegin.RecommendedPeginUseCase
 	transferExcessToColdWalletUseCase   *liquidity_provider.TransferExcessToColdWalletUseCase
 	checkColdWalletAddressChangeUseCase *liquidity_provider.CheckColdWalletAddressChangeUseCase
+	lowLiquidityAlertUseCase            *liquidity_provider.LowLiquidityAlertUseCase
 }
 
 // NewUseCaseRegistry
@@ -391,6 +392,17 @@ func NewUseCaseRegistry(
 			messaging.AlertSender,
 			env.Provider.AlertRecipientEmail,
 		),
+		lowLiquidityAlertUseCase: func() *liquidity_provider.LowLiquidityAlertUseCase {
+			coldWallet := env.ColdWallet.FillWithDefaults()
+			return liquidity_provider.NewLowLiquidityAlertUseCase(
+				lpRegistry.LiquidityProvider,
+				lpRegistry.LiquidityProvider,
+				messaging.AlertSender,
+				env.Provider.AlertRecipientEmail,
+				coldWallet.HotWalletLowLiquidityWarning,
+				coldWallet.HotWalletLowLiquidityCritical,
+			)
+		}(),
 		checkColdWalletAddressChangeUseCase: liquidity_provider.NewCheckColdWalletAddressChangeUseCase(
 			databaseRegistry.LiquidityProviderRepository,
 			lpRegistry.LiquidityProvider,
@@ -578,3 +590,7 @@ func (registry *UseCaseRegistry) TransferExcessToColdWalletUseCase() *liquidity_
 func (registry *UseCaseRegistry) CheckColdWalletAddressChangeUseCase() *liquidity_provider.CheckColdWalletAddressChangeUseCase {
 	return registry.checkColdWalletAddressChangeUseCase
 }
+
+func (registry *UseCaseRegistry) LowLiquidityAlertUseCase() *liquidity_provider.LowLiquidityAlertUseCase {
+	return registry.lowLiquidityAlertUseCase
+}
diff --git a/internal/configuration/registry/watcher.go b/internal/configuration/registry/watcher.go
@@ -89,6 +89,7 @@ func NewWatcherRegistry(
 		),
 		LiquidityCheckWatcher: watcher.NewLiquidityCheckWatcher(
 			useCaseRegistry.liquidityCheckUseCase,
+			useCaseRegistry.lowLiquidityAlertUseCase,
 			tickers.LiquidityCheckTicker,
 			timeouts.WatcherValidation.Seconds(),
 		),
diff --git a/internal/entities/alerts/alerts.go b/internal/entities/alerts/alerts.go
@@ -6,12 +6,14 @@ import "context"
 // Changing one of these constants impacts the external alerting system and there is not an automatic way
 // to identify that error.
 const (
-	AlertSubjectPenalization         = "LPS has been penalized"
-	AlertSubjectPeginOutOfLiquidity  = "PegIn: Out of liquidity"
-	AlertSubjectPegoutOutOfLiquidity = "PegOut: Out of liquidity"
-	AlertSubjectEclipseAttack        = "Node Eclipse Detected"
-	AlertSubjectColdWalletChange     = "Cold wallet address changed"
-	AlertSubjectHotToColdTransfer   = "Hot to cold wallet transfer executed"
+	AlertSubjectPenalization                  = "LPS has been penalized"
+	AlertSubjectPeginOutOfLiquidity           = "PegIn: Out of liquidity"
+	AlertSubjectPegoutOutOfLiquidity          = "PegOut: Out of liquidity"
+	AlertSubjectEclipseAttack                 = "Node Eclipse Detected"
+	AlertSubjectColdWalletChange              = "Cold wallet address changed"
+	AlertSubjectHotToColdTransfer             = "Hot to cold wallet transfer executed"
+	AlertSubjectHotWalletLowLiquidityWarning  = "Hot wallet: Low liquidity, refill recommended"
+	AlertSubjectHotWalletLowLiquidityCritical = "Hot wallet: Critical low liquidity, refill required"
 )
 
 type AlertSender interface {
diff --git a/internal/entities/wei.go b/internal/entities/wei.go
@@ -56,6 +56,13 @@ func SatoshiToWei(x uint64) *Wei {
 	return w
 }
 
+func CoinToWei(x uint64) *Wei {
+	coin := new(big.Int).SetUint64(x)
+	w := new(Wei)
+	w.AsBigInt().Mul(coin, bTenPowEighteen)
+	return w
+}
+
 func (w *Wei) Copy() *Wei {
 	return NewBigWei(w.AsBigInt())
 }
diff --git a/internal/usecases/common.go b/internal/usecases/common.go
@@ -82,6 +82,7 @@ const (
 	RecommendedPeginId             UseCaseId = "RecommendedPegin"
 	TransferExcessToColdWalletId   UseCaseId = "TransferExcessToColdWallet"
 	CheckColdWalletAddressChangeId UseCaseId = "CheckColdWalletAddressChange"
+	LowLiquidityAlertId            UseCaseId = "LowLiquidityAlert"
 )
 
 var (
diff --git a/internal/usecases/liquidity_provider/low_liquidity_alert.go b/internal/usecases/liquidity_provider/low_liquidity_alert.go
@@ -0,0 +1,89 @@
+package liquidity_provider
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/rsksmart/liquidity-provider-server/internal/entities"
+	"github.com/rsksmart/liquidity-provider-server/internal/entities/alerts"
+	"github.com/rsksmart/liquidity-provider-server/internal/entities/liquidity_provider"
+	"github.com/rsksmart/liquidity-provider-server/internal/usecases"
+	log "github.com/sirupsen/logrus"
+)
+
+type LowLiquidityAlertUseCase struct {
+	peginProvider     liquidity_provider.PeginLiquidityProvider
+	pegoutProvider    liquidity_provider.PegoutLiquidityProvider
+	alertSender       alerts.AlertSender
+	recipient         string
+	warningThreshold  uint64
+	criticalThreshold uint64
+}
+
+func NewLowLiquidityAlertUseCase(
+	peginProvider liquidity_provider.PeginLiquidityProvider,
+	pegoutProvider liquidity_provider.PegoutLiquidityProvider,
+	alertSender alerts.AlertSender,
+	recipient string,
+	warningThreshold uint64,
+	criticalThreshold uint64,
+) *LowLiquidityAlertUseCase {
+	return &LowLiquidityAlertUseCase{
+		peginProvider:     peginProvider,
+		pegoutProvider:    pegoutProvider,
+		alertSender:       alertSender,
+		recipient:         recipient,
+		warningThreshold:  warningThreshold,
+		criticalThreshold: criticalThreshold,
+	}
+}
+
+func (useCase *LowLiquidityAlertUseCase) Run(ctx context.Context) error {
+	btcLiquidity, err := useCase.pegoutProvider.AvailablePegoutLiquidity(ctx)
+	if err != nil {
+		return usecases.WrapUseCaseError(usecases.LowLiquidityAlertId, err)
+	}
+	rbtcLiquidity, err := useCase.peginProvider.AvailablePeginLiquidity(ctx)
+	if err != nil {
+		return usecases.WrapUseCaseError(usecases.LowLiquidityAlertId, err)
+	}
+
+	warningWei := entities.CoinToWei(useCase.warningThreshold)
+	criticalWei := entities.CoinToWei(useCase.criticalThreshold)
+
+	useCase.checkAndAlert(ctx, "BTC", btcLiquidity, warningWei, criticalWei)
+	useCase.checkAndAlert(ctx, "RBTC", rbtcLiquidity, warningWei, criticalWei)
+
+	return nil
+}
+
+func (useCase *LowLiquidityAlertUseCase) checkAndAlert(
+	ctx context.Context,
+	network string,
+	current *entities.Wei,
+	warningThreshold, criticalThreshold *entities.Wei,
+) {
+	if current.Cmp(criticalThreshold) < 0 {
+		useCase.sendAlert(ctx, network, current, criticalThreshold, alerts.AlertSubjectHotWalletLowLiquidityCritical)
+		return
+	}
+	if current.Cmp(warningThreshold) < 0 {
+		useCase.sendAlert(ctx, network, current, warningThreshold, alerts.AlertSubjectHotWalletLowLiquidityWarning)
+	}
+}
+
+func (useCase *LowLiquidityAlertUseCase) sendAlert(
+	ctx context.Context,
+	network string,
+	current, threshold *entities.Wei,
+	subject string,
+) {
+	body := fmt.Sprintf("Network: %s | Current: %s | Threshold: %s",
+		network,
+		current.ToRbtc().Text('f', 18),
+		threshold.ToRbtc().Text('f', 18),
+	)
+	if err := useCase.alertSender.SendAlert(ctx, subject, body, []string{useCase.recipient}); err != nil {
+		log.Error("Error sending low liquidity alert: ", err)
+	}
+}
diff --git a/internal/usecases/liquidity_provider/low_liquidity_alert_test.go b/internal/usecases/liquidity_provider/low_liquidity_alert_test.go

Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,13 @@ func SatoshiToWei(x uint64) *Wei {`
`56`	`56`	`return w`
`57`	`57`	`}`
`58`	`58`
	`59`	`+func CoinToWei(x uint64) *Wei {`
	`60`	`+ coin := new(big.Int).SetUint64(x)`
	`61`	`+ w := new(Wei)`
	`62`	`+ w.AsBigInt().Mul(coin, bTenPowEighteen)`
	`63`	`+ return w`
	`64`	`+}`
	`65`	`+`
`59`	`66`	`func (w Wei) Copy() Wei {`
`60`	`67`	`return NewBigWei(w.AsBigInt())`
`61`	`68`	`}`
Original file line number	Diff line number	Diff line change
`@@ -82,6 +82,7 @@ const (`
`82`	`82`	`RecommendedPeginId UseCaseId = "RecommendedPegin"`
`83`	`83`	`TransferExcessToColdWalletId UseCaseId = "TransferExcessToColdWallet"`
`84`	`84`	`CheckColdWalletAddressChangeId UseCaseId = "CheckColdWalletAddressChange"`
	`85`	`+ LowLiquidityAlertId UseCaseId = "LowLiquidityAlert"`
`85`	`86`	`)`
`86`	`87`
`87`	`88`	`var (`