Skip to content

Commit 544ef63

Browse files
rustyrussellrustyrussell
committed
bookkeeper: implement flexible "bkpr-report" command.
You can specify the format for each line in a flexible way, using format tags (inclding defaults if they are not set, recursively). Changelog-Added: JSON-RPC: `bkpr-report` allows flexible summaries of bookkeeper income. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
1 parent 990b72f commit 544ef63

13 files changed

Lines changed: 1376 additions & 10 deletions

File tree

‎contrib/msggen/msggen/schema.json‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5105,6 +5105,132 @@
51055105
}
51065106
]
51075107
},
5108+
"bkpr-report.json": {
5109+
"$schema": "../rpc-schema-draft.json",
5110+
"type": "object",
5111+
"added": "v26.04",
5112+
"rpc": "bkpr-report",
5113+
"title": "Formatting for all income impacting events",
5114+
"description": [
5115+
"The **bkpr-report** RPC command creates a list of all income impacting events that the bookkeeper plugin has recorded for this node.",
5116+
"",
5117+
"It has the useful property that when used with `lightning-cli` and the `escape=csv` it can directly produce valid CSV files."
5118+
],
5119+
"request": {
5120+
"required": [],
5121+
"additionalProperties": false,
5122+
"properties": {
5123+
"format": {
5124+
"type": "string",
5125+
"description": [
5126+
"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:",
5127+
"{account}: account name (channel id, or 'wallet')",
5128+
"{tag}: event tag. This will be one of:",
5129+
" * `deposit`: an onchain send to the wallet by `outpoint`.",
5130+
" * `htlc_fulfill`: an onchain HTLC fulfill (due to unilaterally closed channel) at `outpoint`.",
5131+
" * `invoice`: either incoming (positive credit) or outgoing (positive debit) payment.",
5132+
" * `invoice_fee`: the routing fee paid to pay an outgoing invoice",
5133+
" * `journal_entry`: an accounting fixup, caused by loss of data (or, a node which predates bookkeeper)",
5134+
" * `lease_fee`: a fee paid or received to lease a channel via the experimental liquidity advertisement option",
5135+
" * `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",
5136+
" * `pushed`: an amount pushed to or from us on channel open.",
5137+
" * `rebalance_fee`: routing fee paid for sending a payment to ourselves.",
5138+
" * `routed`: credit gained from routing a payment",
5139+
" * `withdrawal`: debit from an onchain spend.",
5140+
"{description}: description as provided in the invoice, if present",
5141+
"{credit}: credit amount in BTC",
5142+
"{debit}: debit amount in BTC",
5143+
"{fees}: fee amount in BTC",
5144+
"{localtime}: event timestamp in local time as YYYY-MM-DD HH:MM:SS",
5145+
"{utctime}: event timestamp in UTC as YYYY-MM-DD HH:MM:SS",
5146+
"{outpoint}: outpoint, if present",
5147+
"{txid}: txid, if present",
5148+
"{payment_id}: payment hash, if present",
5149+
"{bkpr-currency}: value of bkpr-currency, if any",
5150+
"{currencyrate}: exchange rate for 1 BTC at that event time, if available",
5151+
"{creditdebit}: +credit or -debit (or 0) in BTC",
5152+
"{currencycredit}: credit amount converted into bkpr-currency",
5153+
"{currencydebit}: debit amount converted into bkpr-currency",
5154+
"{currencycreditdebit}: +credit or -debit (or 0) in bkpr-currency",
5155+
"",
5156+
"If a field is unavailable, it expands to an empty string.",
5157+
"",
5158+
"You can provide fallback with ?, including more variable:",
5159+
" * {outpoint?NONE}",
5160+
" * {payment_id?txid: {txid?UNKNOWN}}",
5161+
"The first one the outpoint, or NONE if that is not available. ",
5162+
"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'.",
5163+
"",
5164+
"The text after ? is used only if that tag would otherwise be empty.",
5165+
"",
5166+
"To include a literal {, write {{."
5167+
]
5168+
},
5169+
"headers": {
5170+
"type": "array",
5171+
"description": [
5172+
"strings to place at the top of the output (useful when creating CSV files directly)."
5173+
],
5174+
"items": {
5175+
"type": "string"
5176+
}
5177+
},
5178+
"escape": {
5179+
"type": "string",
5180+
"description": [
5181+
"How to handle fields: if set to `csv` it will handle fields with commas or double-quotes correctly for that format."
5182+
],
5183+
"items": {
5184+
"type": "string"
5185+
},
5186+
"default": "none"
5187+
},
5188+
"start_time": {
5189+
"type": "u32",
5190+
"description": [
5191+
"UNIX timestamp (in seconds) that filters events after the provided timestamp."
5192+
],
5193+
"default": "zero"
5194+
},
5195+
"end_time": {
5196+
"type": "u32",
5197+
"description": [
5198+
"UNIX timestamp (in seconds) that filters events up to and at the provided timestamp."
5199+
],
5200+
"default": "max-int"
5201+
}
5202+
}
5203+
},
5204+
"response": {
5205+
"required": [
5206+
"report"
5207+
],
5208+
"additionalProperties": false,
5209+
"properties": {
5210+
"format-hint": {},
5211+
"report": {
5212+
"type": "array",
5213+
"items": {
5214+
"type": "string",
5215+
"description": [
5216+
"The headers one per entry, followed by the formatted strings for each income event"
5217+
]
5218+
}
5219+
}
5220+
}
5221+
},
5222+
"author": [
5223+
"Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
5224+
],
5225+
"see_also": [
5226+
"lightning-bkpr-listaccountevents(7)",
5227+
"lightning-bkpr-listbalances(7)",
5228+
"lightningd-config(5)"
5229+
],
5230+
"resources": [
5231+
"Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
5232+
]
5233+
},
51085234
"blacklistrune.json": {
51095235
"$schema": "../rpc-schema-draft.json",
51105236
"type": "object",

‎doc/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ MARKDOWNPAGES := doc/addgossip.7 \
3030
doc/bkpr-listaccountevents.7 \
3131
doc/bkpr-listbalances.7 \
3232
doc/bkpr-listincome.7 \
33+
doc/bkpr-report.7 \
3334
doc/blacklistrune.7 \
3435
doc/cancelrecurringinvoice.7 \
3536
doc/check.7 \

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Core Lightning Documentation
3838
bkpr-listaccountevents <bkpr-listaccountevents.7.md>
3939
bkpr-listbalances <bkpr-listbalances.7.md>
4040
bkpr-listincome <bkpr-listincome.7.md>
41+
bkpr-report <bkpr-report.7.md>
4142
blacklistrune <blacklistrune.7.md>
4243
cancelrecurringinvoice <cancelrecurringinvoice.7.md>
4344
check <check.7.md>

‎doc/schemas/bkpr-report.json‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
{
2+
"$schema": "../rpc-schema-draft.json",
3+
"type": "object",
4+
"added": "v26.04",
5+
"rpc": "bkpr-report",
6+
"title": "Formatting for all income impacting events",
7+
"description": [
8+
"The **bkpr-report** RPC command creates a list of all income impacting events that the bookkeeper plugin has recorded for this node.",
9+
"",
10+
"It has the useful property that when used with `lightning-cli` and the `escape=csv` it can directly produce valid CSV files."
11+
],
12+
"request": {
13+
"required": [],
14+
"additionalProperties": false,
15+
"properties": {
16+
"format": {
17+
"type": "string",
18+
"description": [
19+
"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:",
20+
"{account}: account name (channel id, or 'wallet')",
21+
"{tag}: event tag. This will be one of:",
22+
" * `deposit`: an onchain send to the wallet by `outpoint`.",
23+
" * `htlc_fulfill`: an onchain HTLC fulfill (due to unilaterally closed channel) at `outpoint`.",
24+
" * `invoice`: either incoming (positive credit) or outgoing (positive debit) payment.",
25+
" * `invoice_fee`: the routing fee paid to pay an outgoing invoice",
26+
" * `journal_entry`: an accounting fixup, caused by loss of data (or, a node which predates bookkeeper)",
27+
" * `lease_fee`: a fee paid or received to lease a channel via the experimental liquidity advertisement option",
28+
" * `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",
29+
" * `pushed`: an amount pushed to or from us on channel open.",
30+
" * `rebalance_fee`: routing fee paid for sending a payment to ourselves.",
31+
" * `routed`: credit gained from routing a payment",
32+
" * `withdrawal`: debit from an onchain spend.",
33+
"{description}: description as provided in the invoice, if present",
34+
"{credit}: credit amount in BTC",
35+
"{debit}: debit amount in BTC",
36+
"{fees}: fee amount in BTC",
37+
"{localtime}: event timestamp in local time as YYYY-MM-DD HH:MM:SS",
38+
"{utctime}: event timestamp in UTC as YYYY-MM-DD HH:MM:SS",
39+
"{outpoint}: outpoint, if present",
40+
"{txid}: txid, if present",
41+
"{payment_id}: payment hash, if present",
42+
"{bkpr-currency}: value of bkpr-currency, if any",
43+
"{currencyrate}: exchange rate for 1 BTC at that event time, if available",
44+
"{creditdebit}: +credit or -debit (or 0) in BTC",
45+
"{currencycredit}: credit amount converted into bkpr-currency",
46+
"{currencydebit}: debit amount converted into bkpr-currency",
47+
"{currencycreditdebit}: +credit or -debit (or 0) in bkpr-currency",
48+
"",
49+
"If a field is unavailable, it expands to an empty string.",
50+
"",
51+
"You can provide fallback with ?, including more variable:",
52+
" * {outpoint?NONE}",
53+
" * {payment_id?txid: {txid?UNKNOWN}}",
54+
"The first one the outpoint, or NONE if that is not available. ",
55+
"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'.",
56+
"",
57+
"The text after ? is used only if that tag would otherwise be empty.",
58+
"",
59+
"To include a literal {, write {{."
60+
]
61+
},
62+
"headers": {
63+
"type": "array",
64+
"description": [
65+
"strings to place at the top of the output (useful when creating CSV files directly)."
66+
],
67+
"items": {
68+
"type": "string"
69+
}
70+
},
71+
"escape": {
72+
"type": "string",
73+
"description": [
74+
"How to handle fields: if set to `csv` it will handle fields with commas or double-quotes correctly for that format."
75+
],
76+
"items": {
77+
"type": "string"
78+
},
79+
"default": "none"
80+
},
81+
"start_time": {
82+
"type": "u32",
83+
"description": [
84+
"UNIX timestamp (in seconds) that filters events after the provided timestamp."
85+
],
86+
"default": "zero"
87+
},
88+
"end_time": {
89+
"type": "u32",
90+
"description": [
91+
"UNIX timestamp (in seconds) that filters events up to and at the provided timestamp."
92+
],
93+
"default": "max-int"
94+
}
95+
}
96+
},
97+
"response": {
98+
"required": [
99+
"report"
100+
],
101+
"additionalProperties": false,
102+
"properties": {
103+
"format-hint": { },
104+
"report": {
105+
"type": "array",
106+
"items": {
107+
"type": "string",
108+
"description": [
109+
"The headers one per entry, followed by the formatted strings for each income event"
110+
]
111+
}
112+
}
113+
}
114+
},
115+
"author": [
116+
"Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
117+
],
118+
"see_also": [
119+
"lightning-bkpr-listaccountevents(7)",
120+
"lightning-bkpr-listbalances(7)",
121+
"lightningd-config(5)"
122+
],
123+
"resources": [
124+
"Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
125+
]
126+
}

‎plugins/bkpr/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ BOOKKEEPER_PLUGIN_SRC := \
1313
plugins/bkpr/onchain_fee.c \
1414
plugins/bkpr/rebalances.c \
1515
plugins/bkpr/recorder.c \
16+
plugins/bkpr/report.c \
1617
plugins/bkpr/sql.c
1718

1819
BOOKKEEPER_SRC := $(BOOKKEEPER_PLUGIN_SRC) $(BOOKKEEPER_DB_QUERIES)

0 commit comments

Comments
 (0)