multi: add DeleteForwardingEvents to selectively purge old forwarding history

lnrpc/routerrpc/router.proto

@@ -202,6 +202,18 @@ service Router {
     */
     rpc XFindBaseLocalChanAlias (FindBaseAliasRequest)
         returns (FindBaseAliasResponse);
+
+    /* lncli: `deletefwdhistory`
+    DeleteForwardingHistory allows the caller to delete forwarding history
+    events older than a specified time. This is useful for implementing data
+    retention policies for privacy purposes. The call deletes events in batches
+    and returns statistics including the total number of events deleted and the
+    aggregate fees earned from those events. The deletion is performed in a
+    transaction-safe manner with configurable batch sizes to avoid holding
+    large database locks.
+    */
+    rpc DeleteForwardingHistory (DeleteForwardingHistoryRequest)
+        returns (DeleteForwardingHistoryResponse);
 }
 
 message SendPaymentRequest {
@@ -1133,4 +1145,40 @@ message FindBaseAliasRequest {
 message FindBaseAliasResponse {
     // The base scid that resulted from the base scid look up.
     uint64 base = 1;
+}
+
+message DeleteForwardingHistoryRequest {
+    // Specify the time before which to delete forwarding events using one of
+    // the following options:
+    oneof time_spec {
+        // Absolute Unix timestamp (seconds) - delete events before this time.
+        uint64 delete_before_time = 1;
+
+        // Relative duration string supporting both standard Go format and
+        // custom units for convenience.
+        // Standard Go: "-24h" for 1 day, "-1.5h" for 1.5 hours
+        // Custom units: "-1d", "-1w", "-1M", "-1y"
+        // Supported: ns, us/µs, ms, s, m, h, d (days), w (weeks),
+        // M (months=30.44d), y (years=365.25d).
+        // Use negative values to specify time in the past.
+        string duration = 2;
+    }
+
+    // Batch size for deletion (default 10000, max 50000).
+    // Controls how many events are deleted per database transaction to avoid
+    // holding large locks.
+    uint32 batch_size = 3;
+}
+
+message DeleteForwardingHistoryResponse {
+    // Number of forwarding events deleted.
+    uint64 events_deleted = 1;
+
+    // Total fees earned from deleted events (in millisatoshis).
+    // This is the sum of (amt_in - amt_out) for all deleted events, which
+    // can be used for accounting purposes.
+    int64 total_fee_msat = 2;
+
+    // Status message.
+    string status = 3;
 }

lnrpc/routerrpc/router_backend.go

@@ -14,6 +14,7 @@ import (
 	"github.com/btcsuite/btcd/chaincfg"
 	"github.com/btcsuite/btcd/wire"
 	sphinx "github.com/lightningnetwork/lightning-onion"
+	"github.com/lightningnetwork/lnd/channeldb"
 	"github.com/lightningnetwork/lnd/clock"
 	"github.com/lightningnetwork/lnd/feature"
 	"github.com/lightningnetwork/lnd/fn/v2"
@@ -123,6 +124,23 @@ type RouterBackend struct {
 	// Clock is the clock used to validate payment requests expiry.
 	// It is useful for testing.
 	Clock clock.Clock
+
+	// ForwardingLog provides access to forwarding log database operations.
+	ForwardingLog ForwardingLogDB
+}
+
+// ForwardingLogDB defines the interface for forwarding log database operations.
+// This interface allows the router RPC to interact with the forwarding log
+// without depending directly on the channeldb implementation, making testing
+// and future refactoring easier.
+type ForwardingLogDB interface {
+	// DeleteForwardingEvents deletes all forwarding events older than the
+	// specified endTime. The deletion is performed in batches of the given
+	// size to avoid holding large database locks. It returns statistics
+	// about the deletion including the number of events deleted and the
+	// total fees earned from those events.
+	DeleteForwardingEvents(endTime time.Time, batchSize int) (
+		channeldb.DeleteStats, error)
 }
 
 // MissionControl defines the mission control dependencies of routerrpc.