DeleteForwardingHistory

DeleteForwardingHistory allows the caller to delete forwarding history events with a timestamp at or before 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.

Source: routerrpc/router.proto

gRPC

rpc DeleteForwardingHistory (DeleteForwardingHistoryRequest) returns (DeleteForwardingHistoryResponse);

REST

HTTP Method	Path
POST	/v2/router/fwdhistory/delete

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'routerrpc/router.proto'], loaderOptions);
const routerrpc = grpc.loadPackageDefinition(packageDefinition).routerrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new routerrpc.Router(GRPC_HOST, creds);
let request = {
  delete_before_time: <uint64>,
  delete_before_duration: <string>,
};
client.deleteForwardingHistory(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "events_deleted": <uint64>,
//    "total_fee_msat": <int64>,
//    "status": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the routerrpc/router.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import router_pb2 as routerrpc, router_pb2_grpc as routerstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = routerstub.RouterStub(channel)
request = routerrpc.DeleteForwardingHistoryRequest(
  delete_before_time=<uint64>,
  delete_before_duration=<string>,
)
response = stub.DeleteForwardingHistory(request)
print(response)
# {
#    "events_deleted": <uint64>,
#    "total_fee_msat": <int64>,
#    "status": <string>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightningnetwork/lnd
GRPC_HOST=localhost:10009
LND_DIR=~/.lnd
LND_SOURCE=path/to/lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

grpcurl \
    -import-path $LND_SOURCE/lnrpc/ \
    -proto routerrpc/router.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "delete_before_time": <uint64>, "delete_before_duration": <string> }' \
    $GRPC_HOST \
    routerrpc.Router/DeleteForwardingHistory

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  delete_before_time: <string>, // <uint64> 
  delete_before_duration: <string>, // <string> 
};
let options = {
  url: `https://${REST_HOST}/v2/router/fwdhistory/delete`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "events_deleted": <string>, // <uint64> 
//    "total_fee_msat": <string>, // <int64> 
//    "status": <string>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/router/fwdhistory/delete'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'delete_before_time': <uint64>,
  'delete_before_duration': <string>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "events_deleted": <uint64>,
#    "total_fee_msat": <int64>,
#    "status": <string>,
# }

curl

REST_HOST=localhost:8080
LND_DIR=~/.lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "delete_before_time": <uint64>, "delete_before_duration": <string> }' \
    https://$REST_HOST/v2/router/fwdhistory/delete

lncli

$ lncli deletefwdhistory --help

NAME:
   lncli deletefwdhistory - Delete old forwarding history for privacy.

USAGE:
   lncli deletefwdhistory [command options] age | before

CATEGORY:
   Payments

DESCRIPTION:
   
  Deletes all forwarding history events with a timestamp at or before a
  specified time. This is useful for implementing data retention policies
  for privacy purposes. The command permanently removes old forwarding
  events from the database and returns statistics about the deletion
  including total fees earned.

  Time can be specified in two ways:
  1. Relative age (standard Go or custom units): e.g., "-1w", "-24h", 
     "-1M"
  2. Absolute Unix timestamp: e.g., "1640995200"

  Supported relative time units:
  - Standard Go: ns, us/µs, ms, s, m, h (e.g., "-24h", "-1.5h")
  - Custom units: d (days), w (weeks), M (months=30.44d), 
    y (years=365.25d)

  Examples:
    # Delete events from ~1 month ago and earlier:
    lncli deletefwdhistory --age="-1M"       

     # Delete events from ~1 month ago and earlier
    lncli deletefwdhistory --age="-720h"    

    # Delete events at or before Jan 1, 2022:
    lncli deletefwdhistory --before=1640995200 

  NOTE: As with deletepayments, removing events from the database frees up
  disk space within bbolt, but that space is only reclaimed after 
  compacting the database. Consider enabling auto-compaction 
  (db.bolt.auto-compact=true).

  WARNING: This operation is irreversible. Deleted forwarding history 
  cannot be recovered. A minimum age validation is enforced to prevent 
  accidental deletion of very recent data.
  

OPTIONS:
   --age value     delete events at or before this age in the past (e.g., "-1w", "-1M", "-24h", "-720h")
   --before value  delete events at or before this Unix timestamp (seconds) (default: 0)
   --force, -f     skip the confirmation prompt, useful for scripts
   

Messages

routerrpc.DeleteForwardingHistoryRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
delete_before_time Absolute Unix timestamp (seconds). Events at or before this time are deleted.	uint64	string	body
delete_before_duration Relative duration string indicating how far back to delete, e.g. "-30d" deletes events at or before 30 days ago. Standard Go: "-24h", "-1.5h" 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	string	body

routerrpc.DeleteForwardingHistoryResponse

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
events_deleted Number of forwarding events deleted.	uint64	string
total_fee_msat 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	string
status Status message.	string	string