NodeAudit

Get a report of your node's activity over a period.

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

Source: faraday.proto

gRPC

rpc NodeAudit (NodeAuditRequest) returns (NodeAuditResponse);

REST

HTTP Method	Path
GET	/v1/faraday/nodeaudit

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 = {
  start_time: <uint64>,
  end_time: <uint64>,
  disable_fiat: <bool>,
  granularity: <Granularity>,
  custom_categories: <CustomCategory>,
  fiat_backend: <FiatBackend>,
  custom_prices: <BitcoinPrice>,
};
client.nodeAudit(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "reports": <ReportEntry>,
//  }

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.NodeAuditRequest(
  start_time=<uint64>,
  end_time=<uint64>,
  disable_fiat=<bool>,
  granularity=<Granularity>,
  custom_categories=<CustomCategory>,
  fiat_backend=<FiatBackend>,
  custom_prices=<BitcoinPrice>,
)
response = stub.NodeAudit(request)
print(response)
# {
#    "reports": <ReportEntry>,
# }

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/nodeaudit`,
  // 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>, // <ReportEntry> 
//  }

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/nodeaudit'
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": <ReportEntry>,
# }

Shell

# There is no CLI command for this RPC

Messages

frdrpc.NodeAuditRequest

Source: faraday.proto

Field	gRPC Type	REST Type	REST Placement
start_time The unix time from which to produce the report, inclusive.	uint64	string	query
end_time The unix time until which to produce the report, exclusive.	uint64	string	query
disable_fiat Set to generate a report without conversion to fiat. If set, fiat values will display as 0.	bool	boolean	query
granularity The level of granularity at which we wish to produce fiat prices. Nested REST Parameters granularity: string in query	Granularity	string	query
custom_categories An optional set of custom categories which can be used to identify bespoke categories in the report. Each category must have a unique name, and may not have common identifier regexes. Transactions that are matched to these categories report the category name in the CustomCategory field.	CustomCategory[]	array	unknown
fiat_backend The api to be used for fiat related queries. Nested REST Parameters fiat_backend: string in query	FiatBackend	string	query
custom_prices Custom price points to use if the CUSTOM FiatBackend option is set.	BitcoinPrice[]	array	unknown

frdrpc.NodeAuditResponse

Source: faraday.proto

Field	gRPC Type	REST Type
reports On chain reports for the period queried.	ReportEntry[]	array

Nested Messages

frdrpc.BitcoinPrice

Field	gRPC Type	REST Type
price The price of 1 BTC, expressed in USD.	string	string
price_timestamp The timestamp for this price price provided.	uint64	string
currency The currency that the price is denoted in.	string	string

frdrpc.CustomCategory

Field	gRPC Type	REST Type
name The name for the custom category which will contain all transactions that are labelled with a string matching one of the regexes provided in label identifiers.	string	string
on_chain Set to true to apply this category to on chain transactions. Can be set in conjunction with off_chain to apply the category to all transactions.	bool	boolean
off_chain Set to true to apply this category to off chain transactions. Can be set in conjunction with on_chain to apply the category to all transactions.	bool	boolean
label_patterns A set of regular expressions which identify transactions by their label as belonging in this custom category. If a label matches any single regex in the set, it is considered to be in the category. These expressions will be matched against various labels that are present in lnd: on chain transactions will be matched against their label field, off chain receipts will be matched against their memo. At present, there is no way to match forwards or off chain payments. These expressions must be unique across custom categories, otherwise faraday will not be able to identify which custom category a transaction belongs in.	string[]	array

frdrpc.ReportEntry

Field	gRPC Type	REST Type
timestamp The unix timestamp of the event.	uint64	string
on_chain Whether the entry occurred on chain or off chain.	bool	boolean
amount The amount of the entry, expressed in millisatoshis.	uint64	string
credit Whether the entry is a credit or a debit.	bool	boolean
asset The asset affected by the entry.	string	string
type The kind of activity that this entry represents.	EntryType	string
custom_category This field will be populated for entry type custom, and represents the name of a custom category that the report was produced with.	string	string
txid The transaction id of the entry.	string	string
fiat The fiat amount of the entry's amount in the currency specified in the btc_price field.	string	string
reference A unique identifier for the entry, if available.	string	string
note An additional note for the entry, providing additional context.	string	string
btc_price The bitcoin price and timestamp used to calculate our fiat value.	BitcoinPrice	object

Enums

frdrpc.EntryType

Name	Number
UNKNOWN	0
LOCAL_CHANNEL_OPEN A channel opening transaction for a channel opened by our node.	1
REMOTE_CHANNEL_OPEN A channel opening transaction for a channel opened by a remote node.	2
CHANNEL_OPEN_FEE The on chain fee paid to open a channel.	3
CHANNEL_CLOSE A channel closing transaction.	4
RECEIPT Receipt of funds. On chain this reflects receives, off chain settlement of invoices.	5
PAYMENT Payment of funds. On chain this reflects sends, off chain settlement of our payments.	6
FEE Payment of fees.	7
CIRCULAR_RECEIPT Receipt of a payment to ourselves.	8
FORWARD A forward through our node.	9
FORWARD_FEE Fees earned from forwarding.	10
CIRCULAR_PAYMENT Sending of a payment to ourselves.	11
CIRCULAR_FEE The fees paid to send an off chain payment to ourselves.	12
SWEEP A transaction that sweeps funds back into our wallet's control.	13
SWEEP_FEE The amount of fees paid for a sweep transaction.	14
CHANNEL_CLOSE_FEE The fees paid to close a channel.	15

frdrpc.FiatBackend

Name	Number
UNKNOWN_FIATBACKEND	0
COINCAP Use the CoinCap API for fiat price information. This API is reached through the following URL: https://api.coincap.io/v2/assets/bitcoin/history	1
COINDESK Use the CoinDesk API for fiat price information. This API is reached through the following URL: https://api.coindesk.com/v1/bpi/historical/close.json	2
CUSTOM Use custom price data provided in a CSV file for fiat price information.	3
COINGECKO Use the CoinGecko API for fiat price information. This API is reached through the following URL: https://api.coingecko.com/api/v3/coins/bitcoin/market_chart	4

frdrpc.Granularity

Name	Number
UNKNOWN_GRANULARITY	0
MINUTE	1
FIVE_MINUTES	2
FIFTEEN_MINUTES	3
THIRTY_MINUTES	4
HOUR	5
SIX_HOURS	6
TWELVE_HOURS	7
DAY	8