ForwardingHistory

ForwardingHistory allows the caller to query the htlcswitch for a record of all HTLCs forwarded within the target time range, and integer offset within that time range, for a maximum number of events. If no maximum number of events is specified, up to 100 events will be returned. If no time-range is specified, then events will be returned in the order that they occured.

A list of forwarding events are returned. The size of each forwarding event is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB. As a result each message can only contain 50k entries. Each response has the index offset of the last entry. The index offset can be provided to the request to allow the caller to skip a series of records.

Source: lightning.proto

gRPC

rpc ForwardingHistory (ForwardingHistoryRequest) returns (ForwardingHistoryResponse);

REST

HTTP Method	Path
POST	/v1/switch

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', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
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 lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  start_time: <uint64>,
  end_time: <uint64>,
  index_offset: <uint32>,
  num_max_events: <uint32>,
  peer_alias_lookup: <bool>,
};
client.forwardingHistory(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "forwarding_events": <ForwardingEvent>,
//    "last_offset_index": <uint32>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

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 = lightningstub.LightningStub(channel)
request = lnrpc.ForwardingHistoryRequest(
  start_time=<uint64>,
  end_time=<uint64>,
  index_offset=<uint32>,
  num_max_events=<uint32>,
  peer_alias_lookup=<bool>,
)
response = stub.ForwardingHistory(request)
print(response)
# {
#    "forwarding_events": <ForwardingEvent>,
#    "last_offset_index": <uint32>,
# }

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 = {
  start_time: <string>, // <uint64> 
  end_time: <string>, // <uint64> 
  index_offset: <integer>, // <uint32> 
  num_max_events: <integer>, // <uint32> 
  peer_alias_lookup: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/switch`,
  // 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:
//  {
//    "forwarding_events": <array>, // <ForwardingEvent> 
//    "last_offset_index": <integer>, // <uint32> 
//  }

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}/v1/switch'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'start_time': <uint64>,
  'end_time': <uint64>,
  'index_offset': <uint32>,
  'num_max_events': <uint32>,
  'peer_alias_lookup': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "forwarding_events": <ForwardingEvent>,
#    "last_offset_index": <uint32>,
# }

Shell

$ lncli fwdinghistory --help

NAME:
   lncli fwdinghistory - Query the history of all forwarded HTLCs.

USAGE:
   lncli fwdinghistory [command options] start_time [end_time] [index_offset] [max_events]

CATEGORY:
   Payments

DESCRIPTION:
   
  Query the HTLC switch's internal forwarding log for all completed
  payment circuits (HTLCs) over a particular time range (--start_time and
  --end_time). The start and end times are meant to be expressed in
  seconds since the Unix epoch.
  Alternatively negative time ranges can be used, e.g. "-3d". Supports
  s(seconds), m(minutes), h(ours), d(ays), w(eeks), M(onths), y(ears).
  Month equals 30.44 days, year equals 365.25 days.
  If --start_time isn't provided, then 24 hours ago is used. If
  --end_time isn't provided, then the current time is used.

  The max number of events returned is 50k. The default number is 100,
  callers can use the --max_events param to modify this value.

  Finally, callers can skip a series of events using the --index_offset
  parameter. Each response will contain the offset index of the last
  entry. Using this callers can manually paginate within a time slice.
  

OPTIONS:
   --start_time value        the starting time for the query as unix timestamp or relative e.g. "-1w"
   --end_time value          the end time for the query as unix timestamp or relative e.g. "-1w"
   --index_offset value      the number of events to skip (default: 0)
   --max_events value        the max number of events to return (default: 0)
   --skip_peer_alias_lookup  skip the peer alias lookup per forwarding event in order to improve performance
   

Messages

lnrpc.ForwardingHistoryRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
start_time Start time is the starting point of the forwarding history request. All records beyond this point will be included, respecting the end time, and the index offset.	uint64	string	body
end_time End time is the end point of the forwarding history request. The response will carry at most 50k records between the start time and the end time. The index offset can be used to implement pagination.	uint64	string	body
index_offset Index offset is the offset in the time series to start at. As each response can only contain 50k records, callers can use this to skip around within a packed time series.	uint32	integer	body
num_max_events The max number of events to return in the response to this query.	uint32	integer	body
peer_alias_lookup Informs the server if the peer alias should be looked up for each forwarding event.	bool	boolean	body

lnrpc.ForwardingHistoryResponse

Source: lightning.proto

Field	gRPC Type	REST Type
forwarding_events A list of forwarding events from the time slice of the time series specified in the request.	ForwardingEvent[]	array
last_offset_index The index of the last time in the set of returned forwarding events. Can be used to seek further, pagination style.	uint32	integer

Nested Messages

lnrpc.ForwardingEvent

Field	gRPC Type	REST Type
timestampdeprecated Timestamp is the time (unix epoch offset) that this circuit was completed. Deprecated by timestamp_ns.	uint64	string
chan_id_in The incoming channel ID that carried the HTLC that created the circuit.	uint64	string
chan_id_out The outgoing channel ID that carried the preimage that completed the circuit.	uint64	string
amt_in The total amount (in satoshis) of the incoming HTLC that created half the circuit.	uint64	string
amt_out The total amount (in satoshis) of the outgoing HTLC that created the second half of the circuit.	uint64	string
fee The total fee (in satoshis) that this payment circuit carried.	uint64	string
fee_msat The total fee (in milli-satoshis) that this payment circuit carried.	uint64	string
amt_in_msat The total amount (in milli-satoshis) of the incoming HTLC that created half the circuit.	uint64	string
amt_out_msat The total amount (in milli-satoshis) of the outgoing HTLC that created the second half of the circuit.	uint64	string
timestamp_ns The number of nanoseconds elapsed since January 1, 1970 UTC when this circuit was completed.	uint64	string
peer_alias_in The peer alias of the incoming channel.	string	string
peer_alias_out The peer alias of the outgoing channel.	string	string