configurable fee rate

Author: lnliz

README.md

@@ -36,6 +36,17 @@ Only enable a client-IP header when the reverse proxy overwrites it and the
 origin cannot be reached directly. Otherwise a client can spoof the address
 used by the payout limits and admin IP allowlist.
 
+### payout fee rate
+
+Automatic faucet payouts use `0.11 sat/vB` by default. Set a different rate
+with `-payout-fee-rate-sats-per-vb`, or with the
+`FAUCET_PAYOUT_FEE_RATE_SATS_PER_VB` environment variable. The command-line
+flag takes precedence over the environment variable. Set the value to `0` to
+omit `fee_rate` and let the Bitcoin Core wallet select its default rate.
+
+```sh
+-payout-fee-rate-sats-per-vb=0.25
+```
 
 ### quick run with docker
 
@@ -65,6 +76,7 @@ docker run  \
     -turnstile-secret="0x4AAAAAA..." \
     -data-dir /data \
     -batch-interval=10s \
+    -payout-fee-rate-sats-per-vb=0.25 \
     -consolidation-amount-threshold=2.1 \
     -consolidation-min-utxos=10 \
     -consolidation-max-utxos=35 \

main.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"flag"
 	"log"
+	"math"
 	"net"
 	"net/http"
 	"os"
@@ -45,6 +46,14 @@ func main() {
 	var batchIntervalStr string
 	var autoConsolidationIntervalStr string
 	clientIPHeaderDefault := os.Getenv("FAUCET_CLIENT_IP_HEADER")
+	payoutFeeRateDefault := service.DefaultPayoutFeeRateSatsPerVB
+	if value := strings.TrimSpace(os.Getenv("FAUCET_PAYOUT_FEE_RATE_SATS_PER_VB")); value != "" {
+		parsed, err := strconv.ParseFloat(value, 64)
+		if err != nil {
+			log.Fatalf("Error: invalid FAUCET_PAYOUT_FEE_RATE_SATS_PER_VB value %q: %v", value, err)
+		}
+		payoutFeeRateDefault = parsed
+	}
 
 	flag.StringVar(&cfg.ListenAddr, "listen", ":8080", "HTTP server listen address")
 	flag.StringVar(&cfg.MetricsAddr, "metrics-addr", "0.0.0.0:9222", "Metrics server listen address")
@@ -56,6 +65,7 @@ func main() {
 	flag.StringVar(&cfg.BitcoinCoreWalletName, "bitcoin-wallet-name", "faucet", "Bitcoin wallet name, will be loaded at start")
 
 	flag.StringVar(&batchIntervalStr, "batch-interval", "1m", "Batch processing interval (e.g., 1m, 5m, 30s)")
+	flag.Float64Var(&cfg.PayoutFeeRateSatsPerVB, "payout-fee-rate-sats-per-vb", payoutFeeRateDefault, "Fee rate for automatic faucet payouts in sat/vB (0 uses the Bitcoin Core wallet default)")
 	flag.StringVar(&enabledAmountRangesStr, "enabled-amount-ranges", "1,2,3", "Comma-separated amount ranges to enable (1=0.001-0.009, 2=0.01-0.09, 3=0.1-0.9, 4=1.0-2.0)")
 	flag.IntVar(&cfg.DefaultAmountRange, "default-amount-range", 2, "Default selected amount range (1-4)")
 	flag.Float64Var(&cfg.MinBalance, "min-balance", 0.1, "Minimum wallet balance threshold (BTC)")
@@ -98,6 +108,9 @@ func main() {
 	if cfg.MinConsolidationUTXOs > cfg.MaxConsolidationUTXOs {
 		log.Fatalf("invalid consolidation cfg, min: %d > max: %d", cfg.MinConsolidationUTXOs, cfg.MaxConsolidationUTXOs)
 	}
+	if cfg.PayoutFeeRateSatsPerVB < 0 || math.IsNaN(cfg.PayoutFeeRateSatsPerVB) || math.IsInf(cfg.PayoutFeeRateSatsPerVB, 0) {
+		log.Fatal("Error: payout fee rate must be a finite number greater than or equal to 0")
+	}
 
 	if len(adminAllowlistIP) == 0 && len(adminAllowlistCIDR) == 0 {
 		adminAllowlistIP = []string{"127.0.0.1"}
@@ -173,6 +186,11 @@ func main() {
 	log.Printf("Metrics address: %s", cfg.MetricsAddr)
 	log.Printf("Data directory: %s", cfg.DataDir)
 	log.Printf("Batch interval: %s", cfg.BatchInterval)
+	if cfg.PayoutFeeRateSatsPerVB == 0 {
+		log.Printf("Payout fee rate: Bitcoin Core wallet default")
+	} else {
+		log.Printf("Payout fee rate: %.8f sat/vB", cfg.PayoutFeeRateSatsPerVB)
+	}
 	log.Printf("Enabled amount ranges: %v (default: %d)", cfg.EnabledAmountRanges, cfg.DefaultAmountRange)
 	if cfg.ClientIPHeader == "" {
 		log.Printf("Client IP source: direct peer address")

service/admin.go

@@ -174,6 +174,7 @@ func (svc *Service) adminDashboardHandler(w http.ResponseWriter, r *http.Request
 		"ClientIPHeader":                  svc.cfg.ClientIPHeader,
 		"AdminAllowlist":                  formatCIDRs(svc.cfg.AdminAllowlist),
 		"BatchInterval":                   svc.cfg.BatchInterval,
+		"PayoutFeeRateSatsPerVB":          svc.cfg.PayoutFeeRateSatsPerVB,
 	}
 
 	if err := svc.renderTemplate(w, "admin_dashboard.html", data); err != nil {

service/processor.go

@@ -69,11 +69,10 @@ func (svc *Service) processBatch() {
 			continue
 		}
 
-		fees := btc.FeeSatsPerVBLowerLimit * 1.15
 		txid, err := svc.rpcClient.SendToAddressWithOpReturn(
 			tx.Address,
 			tx.AmountBTC,
-			fees,
+			svc.cfg.PayoutFeeRateSatsPerVB,
 			defaultOpReturn,
 		)
 

service/service.go

@@ -36,13 +36,16 @@ var AllAmountRanges = []AmountRange{
 	{ID: 4, MinBTC: 1.0, MaxBTC: 2.0, Label: "1.0 - 2.0"},
 }
 
+const DefaultPayoutFeeRateSatsPerVB = 0.11
+
 type Config struct {
 	ListenAddr                      string
 	MetricsAddr                     string
 	DataDir                         string
 	BitcoinRPC                      btc.BitcoinRPCConfig
 	BitcoinCoreWalletName           string
 	BatchInterval                   time.Duration
+	PayoutFeeRateSatsPerVB          float64
 	MinBalance                      float64
 	TurnstileSecret                 string
 	TurnstileSiteKey                string

service/service_test.go

@@ -136,6 +136,7 @@ func testConfig() *Config {
 		DataDir:                         "/tmp/test",
 		BitcoinCoreWalletName:           "faucet",
 		BatchInterval:                   time.Minute,
+		PayoutFeeRateSatsPerVB:          DefaultPayoutFeeRateSatsPerVB,
 		MinBalance:                      0.1,
 		SubmitTokenSecret:               "submit-token-secret-for-tests-32-chars",
 		AdminPassword:                   "testpass123",
@@ -1773,6 +1774,45 @@ func TestProcessBatch_SendsTransactions(t *testing.T) {
 	}
 }
 
+func TestProcessBatch_UsesConfiguredPayoutFeeRate(t *testing.T) {
+	mock := newMockRPC()
+	var feeRate string
+	mock.handlers["fundrawtransaction"] = func(params json.RawMessage) (any, *rpcErr) {
+		var decoded []json.RawMessage
+		if err := json.Unmarshal(params, &decoded); err != nil {
+			t.Fatalf("decode fundrawtransaction params: %v", err)
+		}
+		if len(decoded) != 2 {
+			t.Fatalf("expected fee options, got %d params", len(decoded))
+		}
+
+		var options map[string]string
+		if err := json.Unmarshal(decoded[1], &options); err != nil {
+			t.Fatalf("decode fundrawtransaction options: %v", err)
+		}
+		feeRate = options["fee_rate"]
+
+		return map[string]any{"hex": "fundedhex000", "fee": 0.00001}, nil
+	}
+
+	rpcServer := httptest.NewServer(mock)
+	t.Cleanup(rpcServer.Close)
+	svc := testService(t, rpcServer)
+	svc.cfg.PayoutFeeRateSatsPerVB = 0.42
+	svc.db.Create(&db.Transaction{
+		Address:   "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx",
+		IPAddress: "1.2.3.4",
+		AmountBTC: 0.05,
+		Status:    db.TxnStatusPending,
+	})
+
+	svc.processBatch()
+
+	if feeRate != "0.42000000" {
+		t.Fatalf("expected configured fee rate 0.42000000, got %q", feeRate)
+	}
+}
+
 func TestProcessBatch_InsufficientBalance(t *testing.T) {
 	mock := newMockRPC()
 	mock.handlers["getbalances"] = func(_ json.RawMessage) (any, *rpcErr) {

templates/admin_dashboard.html

@@ -461,6 +461,7 @@ <h2>Configuration</h2>
                     <tr><td style="color: #999;">Max Consolidation UTXOs</td><td>{{.MaxConsolidationUTXOs}}</td></tr>
                     <tr><td style="color: #999;">Auto Consolidation Interval</td><td>{{if gt .AutoConsolidationInterval 0}}{{.AutoConsolidationInterval}}{{else}}disabled{{end}}</td></tr>
                     <tr><td style="color: #999;">Batch Interval</td><td>{{.BatchInterval}}</td></tr>
+					<tr><td style="color: #999;">Payout Fee Rate</td><td>{{if eq .PayoutFeeRateSatsPerVB 0.0}}Bitcoin Core wallet default{{else}}{{printf "%.8f" .PayoutFeeRateSatsPerVB}} sat/vB{{end}}</td></tr>
 					<tr><td style="color: #999;">Max Withdrawals per IP (24h)</td><td>{{.MaxWithdrawalsPerIP24h}}</td></tr>
 					<tr><td style="color: #999;">Max Deposits per Address</td><td>{{.MaxDepositsPerAddress}}</td></tr>
 					<tr><td style="color: #999;">Client IP Source</td><td>{{if .ClientIPHeader}}{{.ClientIPHeader}} header{{else}}direct peer address{{end}}</td></tr>