Skip to main content

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 MethodPath
POST /v1/switch

Code Samples

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>,
// }

Messages

lnrpc.ForwardingHistoryRequest

Source: lightning.proto

FieldgRPC TypeREST TypeREST Placement
start_time
uint64stringbody
end_time
uint64stringbody
index_offset
uint32integerbody
num_max_events
uint32integerbody
peer_alias_lookup
boolbooleanbody

lnrpc.ForwardingHistoryResponse

Source: lightning.proto

FieldgRPC TypeREST Type
forwarding_events
ForwardingEvent[]array
last_offset_index
uint32integer

Nested Messages

lnrpc.ForwardingEvent

FieldgRPC TypeREST Type
timestampdeprecated
uint64string
chan_id_in
uint64string
chan_id_out
uint64string
amt_in
uint64string
amt_out
uint64string
fee
uint64string
fee_msat
uint64string
amt_in_msat
uint64string
amt_out_msat
uint64string
timestamp_ns
uint64string
peer_alias_in
stringstring
peer_alias_out
stringstring