bkpr-report -- Formatting for all income impacting events

SYNOPSIS

bkpr-report [format] [headers] [escape] [start_time] [end_time]

DESCRIPTION

Command added in v26.04.

The bkpr-report RPC command creates a list of all income impacting events that the bookkeeper plugin has recorded for this node.

It has the useful property that when used with lightning-cli and the escape=csv it can directly produce valid CSV files.

format (string, optional): This format string is used for each income event (note that lightning-cli can get confused if the format begins and ends with { and }, so you may need to add a space). The following tags in braces are replaced:
{account}: account name (channel id, or 'wallet')
{tag}: event tag. This will be one of:
- deposit: an onchain send to the wallet by outpoint.
- htlc_fulfill: an onchain HTLC fulfill (due to unilaterally closed channel) at outpoint.
- invoice: either incoming (positive credit) or outgoing (positive debit) payment.
- invoice_fee: the routing fee paid to pay an outgoing invoice
- journal_entry: an accounting fixup, caused by loss of data (or, a node which predates bookkeeper)
- lease_fee: a fee paid or received to lease a channel via the experimental liquidity advertisement option
- onchain_fee,: a miner fee paid to open/close a channel, or make a bitcoin payment. The txid will correspond to a withdrawal outpoint for withdrawl
- pushed: an amount pushed to or from us on channel open.
- rebalance_fee: routing fee paid for sending a payment to ourselves.
- routed: credit gained from routing a payment
- withdrawal: debit from an onchain spend.
  {description}: description as provided in the invoice, if present
  {credit}: credit amount in BTC
  {debit}: debit amount in BTC
  {fees}: fee amount in BTC
  {localtime}: event timestamp in local time as YYYY-MM-DD HH:MM:SS
  {utctime}: event timestamp in UTC as YYYY-MM-DD HH:MM:SS
  {outpoint}: outpoint, if present
  {txid}: txid, if present
  {payment_id}: payment hash, if present
  {bkpr-currency}: value of bkpr-currency, if any
  {currencyrate}: exchange rate for 1 BTC at that event time, if available
  {creditdebit}: +credit or -debit (or 0) in BTC
  {currencycredit}: credit amount converted into bkpr-currency
  {currencydebit}: debit amount converted into bkpr-currency
  {currencycreditdebit}: +credit or -debit (or 0) in bkpr-currency

If a field is unavailable, it expands to an empty string.

You can provide fallback with ?, including more variable:

{outpoint?NONE}
{payment_id?txid: {txid?UNKNOWN}}
The first one the outpoint, or NONE if that is not available.
The second prints the payment_id, or if that is not available, the string 'txid: ' followed by the txid, or if that is not available, 'txid: UNKNOWN'.

The text after ? is used only if that tag would otherwise be empty.

To include a literal {, write {{.

headers (array of strings, optional): strings to place at the top of the output (useful when creating CSV files directly).:
- (string, optional)
escape (string, optional): How to handle the formatted output fields: if set to csv it will handle fields with commas or double-quotes correctly for that format. Note that text is never escaped (you need to do that), only {} tags. The default is none.
start_time (u32, optional): UNIX timestamp (in seconds) that filters events after the provided timestamp. The default is zero.
end_time (u32, optional): UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. The default is max-int.

RETURN VALUE

On success, an object is returned, containing:

report (array of strings):
- (string, optional): The headers one per entry, followed by the formatted strings for each income event

AUTHOR

Rusty Russell [email protected] is mainly responsible.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning