RevenueReport

Get a pairwise revenue report for a channel.

Example request: http://localhost:8466/v1/faraday/revenue

Source: faraday.proto

gRPC

rpc RevenueReport (RevenueReportRequest) returns (RevenueReportResponse);

REST

HTTP Method	Path
GET	/v1/faraday/revenue

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:8465'
const MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
const TLS_PATH = 'FARADAY_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
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 frdrpc.FaradayServer(GRPC_HOST, creds);
let request = {
  chan_points: <string>,
  start_time: <uint64>,
  end_time: <uint64>,
};
client.revenueReport(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "reports": <RevenueReport>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the faraday.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub

GRPC_HOST = 'localhost:8465'
MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
TLS_PATH = 'FARADAY_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 = faradaystub.FaradayServerStub(channel)
request = frdrpc.RevenueReportRequest(
  chan_points=<string>,
  start_time=<uint64>,
  end_time=<uint64>,
)
response = stub.RevenueReport(request)
print(response)
# {
#    "reports": <RevenueReport>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8082'
const MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/faraday/revenue`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "reports": <array>, // <RevenueReport> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8082'
MACAROON_PATH = 'FARADAY_DIR/regtest/faraday.macaroon'
TLS_PATH = 'FARADAY_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/faraday/revenue'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "reports": <RevenueReport>,
# }

Shell

$ frcli revenue --help

NAME:
   frcli revenue - Get a pairwise revenue report for a channel.

USAGE:
   frcli revenue [command options] [arguments...]

CATEGORY:
   insights

OPTIONS:
   --chan_points value  (optional) A set of channels to generate a revenue report for. If not specified, reports will be created for all channels that forwarded payments over the period provided. A single channel can be set directly using --chan_points=txid:outpoint,multiple channels should be specified usinga comma separated list in braces --chan_points={chan, chan}
   --start_time value   (optional) The unix timestamp in seconds from which the report should be generated.If not set, the report will be generated from the time of channel open. (default: 0)
   --end_time value     (optional) The unix timestamp in secondsuntil which the report should be generated.If not set, the report will be produced until the present. (default: 0)
   

Messages

frdrpc.RevenueReportRequest

Source: faraday.proto

Field	gRPC Type	REST Type	REST Placement
chan_points The funding transaction outpoints for the channels to generate a revenue report for. If this is empty, it will be generated for all open and closed channels. Channel funding points should be expressed with the format fundingTxID:outpoint.	string[]	array	query
start_time Start time is beginning of the range over which the report will be generated, expressed as unix epoch offset in seconds.	uint64	string	query
end_time End time is end of the range over which the report will be generated, expressed as unix epoch offset in seconds.	uint64	string	query

frdrpc.RevenueReportResponse

Source: faraday.proto

Field	gRPC Type	REST Type
reports Reports is a set of pairwise revenue report generated for the channel(s) over the period specified.	RevenueReport[]	array

Nested Messages

frdrpc.PairReport

Field	gRPC Type	REST Type
amount_outgoing_msat Amount outgoing msat is the amount in millisatoshis that arrived on the pair channel to be forwarded onwards by our channel.	int64	string
fees_outgoing_msat Fees outgoing is the amount of fees in millisatoshis that we attribute to the channel for its role as the outgoing channel in forwards.	int64	string
amount_incoming_msat Amount incoming msat is the amount in millisatoshis that arrived on our channel to be forwarded onwards by the pair channel.	int64	string
fees_incoming_msat Fees incoming is the amount of fees in millisatoshis that we attribute to the channel for its role as the incoming channel in forwards.	int64	string

frdrpc.RevenueReport

Field	gRPC Type	REST Type
target_channel Target channel is the channel that the report is generated for; incoming fields in the report mean that this channel was the incoming channel, and the pair as the outgoing, outgoing fields mean that this channel was the outgoing channel and the peer was the incoming channel.	string	string
pair_reports Pair reports maps the channel point of a peer that we generated revenue with to a report detailing the revenue.	PairReportsEntry[]	object

frdrpc.RevenueReport.PairReportsEntry

Field	gRPC Type	REST Type
key	string	unknown
value	PairReport	unknown