mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00
Code Issues Projects Releases Wiki Activity

bkpr: add docs, change names to 'bkpr-*'

Browse Source 
Adds schema definitions and manpages for bkpr- commands; also renames
the commands to all start with 'bkpr-', so they're easier to identify/
make runes about.
This commit is contained in:
niftynei 2022-07-19 17:04:39 +09:30 committed by Rusty Russell
parent 6dfba2468a
commit 563910e667
18 changed files with 1049 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Makefile
View File

@ -9,6 +9,12 @@ MANPAGES := doc/lightning-cli.1 \
doc/lightningd-config.5 \
doc/lightning-addgossip.7 \
doc/lightning-autocleaninvoice.7 \
doc/lightning-bkpr-channelsapy.7 \
doc/lightning-bkpr-dumpincomecsv.7 \
doc/lightning-bkpr-inspect.7 \
doc/lightning-bkpr-listaccountevents.7 \
doc/lightning-bkpr-listbalances.7 \
doc/lightning-bkpr-listincome.7 \
doc/lightning-check.7 \
doc/lightning-checkmessage.7 \
doc/lightning-close.7 \

6
doc/index.rst
View File

@ -31,6 +31,12 @@ Core Lightning Documentation
lightning-addgossip <lightning-addgossip.7.md>
lightning-autocleaninvoice <lightning-autocleaninvoice.7.md>
lightning-bkpr-channelsapy <lightning-bkpr-channelsapy.7.md>
lightning-bkpr-dumpincomecsv <lightning-bkpr-dumpincomecsv.7.md>
lightning-bkpr-inspect <lightning-bkpr-inspect.7.md>
lightning-bkpr-listaccountevents <lightning-bkpr-listaccountevents.7.md>
lightning-bkpr-listbalances <lightning-bkpr-listbalances.7.md>
lightning-bkpr-listincome <lightning-bkpr-listincome.7.md>
lightning-check <lightning-check.7.md>
lightning-checkmessage <lightning-checkmessage.7.md>
lightning-cli <lightning-cli.1.md>

67
doc/lightning-bkpr-channelsapy.7.md Normal file
View File

@ -0,0 +1,67 @@
lightning-bkpr-channelsapy -- Command to list stats on channel earnings
==================================================================
SYNOPSIS
--------
**bkpr-channelsapy** \[*start_time*\] \[*end_time*\]
DESCRIPTION
-----------
The **bkpr-channelsapy** RPC command lists stats on routing income, leasing income,
and various calculated APYs for channel routed funds.
The **start_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **channels_apy** is returned. It is an array of objects, where each object contains:
- **account** (string): The account name. If the account is a channel, the channel_id. The 'net' entry is the rollup of all channel accounts
- **routed_out_msat** (msat): Sats routed (outbound)
- **routed_in_msat** (msat): Sats routed (inbound)
- **lease_fee_paid_msat** (msat): Sats paid for leasing inbound (liquidity ads)
- **lease_fee_earned_msat** (msat): Sats earned for leasing outbound (liquidity ads)
- **pushed_out_msat** (msat): Sats pushed to peer at open
- **pushed_in_msat** (msat): Sats pushed in from peer at open
- **our_start_balance_msat** (msat): Starting balance in channel at funding. Note that if our start ballance is zero, any _initial field will be omitted (can't divide by zero)
- **channel_start_balance_msat** (msat): Total starting balance at funding
- **fees_out_msat** (msat): Fees earned on routed outbound
- **utilization_out** (string): Sats routed outbound / total start balance
- **utilization_in** (string): Sats routed inbound / total start balance
- **apy_out** (string): Fees earned on outbound routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)
- **apy_in** (string): Fees earned on inbound routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)
- **apy_total** (string): Total fees earned on routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)
- **fees_in_msat** (msat, optional): Fees earned on routed inbound
- **utilization_out_initial** (string, optional): Sats routed outbound / our start balance
- **utilization_in_initial** (string, optional): Sats routed inbound / our start balance
- **apy_out_initial** (string, optional): Fees earned on outbound routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)
- **apy_in_initial** (string, optional): Fees earned on inbound routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)
- **apy_total_initial** (string, optional): Total fees earned on routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)
- **apy_lease** (string, optional): Lease fees earned over total amount leased for the lease term, amortized to a year (APY). Only appears if channel was leased out by us
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-bkpr-listincome(7), lightning-bkpr-listfunds(7),
lightning-bkpr-listaccountevents(7),
lightning-bkpr-dumpincomecsv(7), lightning-listpeers(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:435fd03765ef0a8bcaef7f309673cdac9cb7c8ba776ac77de21aea8d702998a3)

59
doc/lightning-bkpr-dumpincomecsv.7.md Normal file
View File

@ -0,0 +1,59 @@
lightning-bkpr-dumpincomecsv -- Command to emit a CSV of income events
=================================================================
SYNOPSIS
--------
**bkpr-dumpincomecsv** *csv_format* \[*csv_file*\] \[*consolidate_fees*\] \[*start_time*\] \[*end_time*\]
DESCRIPTION
-----------
The **bkpr-dumpincomcsv** RPC command writes a CSV file to disk at *csv_file*
location. This is a formatted output of the **listincome** RPC command.
**csv_format** is which CSV format to use. See RETURN VALUE for options.
**csv_file** is the on-disk destination of the generated CSV file.
If **consolidate_fees** is true, we emit a single, consolidated event for
any onchain-fees for a txid and account. Otherwise, events for every update to
the onchain fee calculation for this account and txid will be printed.
Defaults to true. Note that this means that the events emitted are
non-stable, i.e. calling **dumpincomecsv** twice may result in different
onchain fee events being emitted, depending on how much information we've
logged for that transaction.
The **start_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
- **csv_file** (string): File that the csv was generated to
- **csv_format** (string): Format to print csv as (one of "cointracker", "koinly", "harmony", "quickbooks")
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-bkpr-listincome(7), lightning-bkpr-listfunds(7),
lightning-bkpr-listaccountevents(7),
lightning-bkpr-channelsapy(7), lightning-listpeers(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:e6000f40905c4fa23a5115e8bc82f4f1556f55118fb4ede41dd5e54957da0fa3)

54
doc/lightning-bkpr-inspect.7.md Normal file
View File

@ -0,0 +1,54 @@
lightning-bkpr-inspect -- Command to show onchain footprint of a channel
===================================================================
SYNOPSIS
--------
**bkpr-inspect** *account*
DESCRIPTION
-----------
The **bkpr-inspect** RPC command lists all known on-chain transactions and
associated events for the provided account. Useful for inspecting unilateral
closes for a given channel account. Only valid for channel accounts.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **txs** is returned. It is an array of objects, where each object contains:
- **txid** (txid): transaction id
- **fees_paid_msat** (msat): Amount paid in sats for this tx
- **outputs** (array of objects):
- **account** (string): Account this output affected
- **outnum** (u32): Index of output
- **output_value_msat** (msat): Value of the output
- **currency** (string): human-readable bech32 part for this coin type
- **credit_msat** (msat, optional): Amount credited to account
- **debit_msat** (msat, optional): Amount debited from account
- **originating_account** (string, optional): Account this output originated from
- **output_tag** (string, optional): Description of output creation event
- **spend_tag** (string, optional): Description of output spend event
- **spending_txid** (txid, optional): Transaction this output was spent in
- **payment_id** (hex, optional): lightning payment identifier. For an htlc, this will be the preimage.
- **blockheight** (u32, optional): Blockheight of transaction
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-listbalances(7), lightning-listfunds(7), lightning-listpeers(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:9df98d40e1ed1b0c72f4a4e8c00d243e10f159b99c534818f04631ec3d17a445)

68
doc/lightning-bkpr-listaccountevents.7.md Normal file
View File

@ -0,0 +1,68 @@
lightning-bkpr-listaccountevents -- Command for listing recorded bookkeeping events
=============================================================================
SYNOPSIS
--------
**bkpr-listaccountevents** [\*account\*]
DESCRIPTION
-----------
The **bkpr-listaccountevents** RPC command is a list of all bookkeeping events that have been recorded for this node.
If the optional parameter **account** is set, we only emit events for the
specified account, if exists.
Note that the type **onchain_fees** that are emitted are of opposite credit/debit than as they appear in **listincome**, as **listincome** shows all events from the perspective of the node, whereas **listaccountevents** just dumps the event data as we've got it. Onchain fees are updated/recorded as we get more information about input and output spends -- the total onchain fees that were recorded for a transaction for an account can be found by summing all onchain fee events and taking the difference between the **credit_msat** and **debit_msat** for these events. We do this so that successive calls to **listaccountevents** always
produce the same list of events -- no previously emitted event will be
subsequently updated, rather we add a new event to the list.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **events** is returned. It is an array of objects, where each object contains:
- **account** (string): The account name. If the account is a channel, the channel_id
- **type** (string): Coin movement type (one of "onchain_fee", "chain", "channel")
- **tag** (string): Description of movement
- **credit_msat** (msat): Amount credited
- **debit_msat** (msat): Amount debited
- **currency** (string): human-readable bech32 part for this coin type
- **timestamp** (u32): Timestamp this event was recorded by the node. For consolidated events such as onchain_fees, the most recent timestamp
If **type** is "chain":
- **outpoint** (string): The txid:outnum for this event
- **blockheight** (u32): For chain events, blockheight this occured at
- **origin** (string, optional): The account this movement originated from
- **payment_id** (hex, optional): lightning payment identifier. For an htlc, this will be the preimage.
- **txid** (txid, optional): The txid of the transaction that created this event
If **type** is "onchain_fee":
- **txid** (txid): The txid of the transaction that created this event
If **type** is "channel":
- **fees_msat** (msat, optional): Amount paid in fees
- **payment_id** (hex, optional): lightning payment identifier. For an htlc, this will be the preimage.
- **part_id** (u32, optional): Counter for multi-part payments
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-bkpr-listincome(7), lightning-listfunds(7),
lightning-bkpr-listbalances(7), lightning-bkpr-channelsapy(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:dd72cc73e685daa6877984be8edede76dfec2f9d85df9a88ab1b031a93b20549)

54
doc/lightning-bkpr-listbalances.7.md Normal file
View File

@ -0,0 +1,54 @@
lightning-bkpr-listbalances -- Command for listing current channel + wallet balances
===============================================================================
SYNOPSIS
--------
**bkpr-listbalances**
DESCRIPTION
-----------
The **bkpr-listbalances** RPC command is a list of all current and historical account balances. An account is either the on-chain *wallet* or a channel balance.
Any funds sent to an *external* account will not be accounted for here.
Note that any channel that was recorded will be listed. Closed channel balances
will be 0msat.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **accounts** is returned. It is an array of objects, where each object contains:
- **account** (string): The account name. If the account is a channel, the channel_id
- **balances** (array of objects):
- **balance_msat** (msat): Current account balance
- **coin_type** (string): coin type, same as HRP for bech32
If **peer_id** is present:
- **peer_id** (pubkey): Node id for the peer this account is with
- **we_opened** (boolean): Did we initiate this account open (open the channel)
- **account_closed** (boolean):
- **account_resolved** (boolean): Has this channel been closed and all outputs resolved?
- **resolved_at_block** (u32, optional): Blockheight account resolved on chain
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-bkpr-listincome(7), lightning-listfunds(7),
lightning-bkpr-listaccountevents(7),
lightning-bkpr-channelsapy(7), lightning-listpeers(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:a3d1423f12bffc76fd1f2fdb5a07ff8a881290f2ea5eefa528cbb04fc3a7c639)

58
doc/lightning-bkpr-listincome.7.md Normal file
View File

@ -0,0 +1,58 @@
lightning-bkpr-listincome -- Command for listing all income impacting events
=======================================================================
SYNOPSIS
--------
**bkpr-listincome** \[*consolidate_fees*\] \[*start_time*\] \[*end_time*\]
DESCRIPTION
-----------
The **bkpr-listincome** RPC command is a list of all income impacting events that the bookkeeper plugin has recorded for this node.
If **consolidate_fees** is true, we emit a single, consolidated event for
any onchain-fees for a txid and account. Otherwise, events for every update to
the onchain fee calculation for this account and txid will be printed. Defaults to true. Note that this means that the events emitted are non-stable,
i.e. calling **listincome** twice may result in different onchain fee events
being emitted, depending on how much information we've logged for that
transaction.
The **start_time** is a UNIX timestamp (in seconds) that filters events after the provided timestamp. Defaults to zero.
The **end_time** is a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. Defaults to max-int.
RETURN VALUE
------------
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object containing **income_events** is returned. It is an array of objects, where each object contains:
- **account** (string): The account name. If the account is a channel, the channel_id
- **tag** (string): Type of income event
- **credit_msat** (msat): Amount earned (income)
- **debit_msat** (msat): Amount spent (expenses)
- **currency** (string): human-readable bech32 part for this coin type
- **timestamp** (u32): Timestamp this event was recorded by the node. For consolidated events such as onchain_fees, the most recent timestamp
- **outpoint** (string, optional): The txid:outnum for this event, if applicable
- **txid** (txid, optional): The txid of the transaction that created this event, if applicable
- **payment_id** (hex, optional): lightning payment identifier. For an htlc, this will be the preimage.
[comment]: # (GENERATE-FROM-SCHEMA-END)
AUTHOR
------
niftynei <niftynei@gmail.com> is mainly responsible.
SEE ALSO
--------
lightning-bkpr-listaccountevents(7), lightning-listfunds(7),
lightning-bkpr-listbalances(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:400ac5e6719a7ae5ec7078a2cd220d91ab7e66ad45f08b46257e6ec04dcdeb4c)

124
doc/schemas/bkpr-channelsapy.schema.json Normal file
View File

@ -0,0 +1,124 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [
"channels_apy"
],
"properties": {
"channels_apy": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"account",
"routed_out_msat",
"routed_in_msat",
"lease_fee_paid_msat",
"lease_fee_earned_msat",
"pushed_out_msat",
"pushed_in_msat",
"our_start_balance_msat",
"channel_start_balance_msat",
"fees_out_msat",
"utilization_out",
"utilization_in",
"apy_out",
"apy_in",
"apy_total"
],
"properties": {
"account": {
"type": "string",
"description": "The account name. If the account is a channel, the channel_id. The 'net' entry is the rollup of all channel accounts"
},
"routed_out_msat": {
"type": "msat",
"description": "Sats routed (outbound)"
},
"routed_in_msat": {
"type": "msat",
"description": "Sats routed (inbound)"
},
"lease_fee_paid_msat": {
"type": "msat",
"description": "Sats paid for leasing inbound (liquidity ads)"
},
"lease_fee_earned_msat": {
"type": "msat",
"description": "Sats earned for leasing outbound (liquidity ads)"
},
"pushed_out_msat": {
"type": "msat",
"description": "Sats pushed to peer at open"
},
"pushed_in_msat": {
"type": "msat",
"description": "Sats pushed in from peer at open"
},
"our_start_balance_msat": {
"type": "msat",
"description": "Starting balance in channel at funding. Note that if our start ballance is zero, any _initial field will be omitted (can't divide by zero)"
},
"channel_start_balance_msat": {
"type": "msat",
"description": "Total starting balance at funding"
},
"fees_out_msat": {
"type": "msat",
"description": "Fees earned on routed outbound"
},
"fees_in_msat": {
"type": "msat",
"description": "Fees earned on routed inbound"
},
"utilization_out": {
"type": "string",
"description": "Sats routed outbound / total start balance"
},
"utilization_out_initial": {
"type": "string",
"description": "Sats routed outbound / our start balance"
},
"utilization_in": {
"type": "string",
"description": "Sats routed inbound / total start balance"
},
"utilization_in_initial": {
"type": "string",
"description": "Sats routed inbound / our start balance"
},
"apy_out": {
"type": "string",
"description": "Fees earned on outbound routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_out_initial": {
"type": "string",
"description": "Fees earned on outbound routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_in": {
"type": "string",
"description": "Fees earned on inbound routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_in_initial": {
"type": "string",
"description": "Fees earned on inbound routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_total": {
"type": "string",
"description": "Total fees earned on routed payments / total start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_total_initial": {
"type": "string",
"description": "Total fees earned on routed payments / our start balance for the length of time this channel has been open amortized to a year (APY)"
},
"apy_lease": {
"type": "string",
"description": "Lease fees earned over total amount leased for the lease term, amortized to a year (APY). Only appears if channel was leased out by us"
}
}
}
}
}
}

25
doc/schemas/bkpr-dumpincomecsv.schema.json Normal file
View File

@ -0,0 +1,25 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"unevaluatedProperties": false,
"required": [
"csv_file",
"csv_format"
],
"properties": {
"csv_file": {
"type": "string",
"description": "File that the csv was generated to"
},
"csv_format": {
"type": "string",
"enum": [
"cointracker",
"koinly",
"harmony",
"quickbooks"
],
"description": "Format to print csv as"
}
}
}

150
doc/schemas/bkpr-inspect.schema.json Normal file
View File

@ -0,0 +1,150 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [
"txs"
],
"properties": {
"txs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"txid",
"fees_paid_msat",
"outputs"
],
"properties": {
"txid": {
"type": "txid",
"description": "transaction id"
},
"blockheight": {
"type": "u32",
"description": "Blockheight of transaction"
},
"fees_paid_msat": {
"type": "msat",
"description": "Amount paid in sats for this tx"
},
"outputs": {
"type": "array",
"items": {
"type": "object",
"required": [
"account",
"outnum",
"output_value_msat",
"currency"
],
"additionalProperties": false,
"properties": {
"account": {
"type": "string",
"description": "Account this output affected"
},
"outnum": {
"type": "u32",
"description": "Index of output"
},
"output_value_msat": {
"type": "msat",
"description": "Value of the output"
},
"currency": {
"type": "string",
"description": "human-readable bech32 part for this coin type"
},
"credit_msat": {
"type": "msat",
"description": "Amount credited to account"
},
"debit_msat": {
"type": "msat",
"description": "Amount debited from account"
},
"originating_account": {
"type": "string",
"description": "Account this output originated from"
},
"output_tag": {
"type": "string",
"description": "Description of output creation event"
},
"spend_tag": {
"type": "string",
"description": "Description of output spend event"
},
"spending_txid": {
"type": "txid",
"description": "Transaction this output was spent in"
},
"payment_id": {
"type": "hex",
"description": "lightning payment identifier. For an htlc, this will be the preimage."
}
},
"allOf": [
{
"if": {
"required": [
"credit_msat"
]
},
"then": {
"required": [
"output_tag"
],
"additionalProperties": false,
"properties": {
"account": {},
"outnum": {},
"output_value_msat": {},
"currency": {},
"credit_msat": {},
"originating_account": {},
"debit_msat": {},
"output_tag": {},
"spend_tag": {},
"spending_txid": {},
"payment_id": {}
}
}
},
{
"if": {
"required": [
"spending_txid"
]
},
"then": {
"required": [
"spend_tag",
"debit_msat"
],
"additionalProperties": false,
"properties": {
"account": {},
"outnum": {},
"output_value_msat": {},
"currency": {},
"credit_msat": {},
"originating_account": {},
"debit_msat": {},
"output_tag": {},
"spend_tag": {},
"spending_txid": {},
"payment_id": {}
}
}
}
]
}
}
}
}
}
}
}

178
doc/schemas/bkpr-listaccountevents.schema.json Normal file
View File

@ -0,0 +1,178 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [
"events"
],
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"required": [
"account",
"type",
"tag",
"credit_msat",
"debit_msat",
"currency",
"timestamp"
],
"properties": {
"account": {
"type": "string",
"description": "The account name. If the account is a channel, the channel_id"
},
"type": {
"type": "string",
"enum": [
"onchain_fee",
"chain",
"channel"
],
"description": "Coin movement type"
},
"tag": {
"type": "string",
"description": "Description of movement"
},
"credit_msat": {
"type": "msat",
"description": "Amount credited"
},
"debit_msat": {
"type": "msat",
"description": "Amount debited"
},
"currency": {
"type": "string",
"description": "human-readable bech32 part for this coin type"
},
"timestamp": {
"type": "u32",
"description": "Timestamp this event was recorded by the node. For consolidated events such as onchain_fees, the most recent timestamp"
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"type": "string",
"enum": [
"chain"
]
}
}
},
"then": {
"properties": {
"account": {},
"type": {},
"tag": {},
"credit_msat": {},
"debit_msat": {},
"currency": {},
"timestamp": {},
"outpoint": {
"type": "string",
"description": "The txid:outnum for this event"
},
"blockheight": {
"type": "u32",
"description": "For chain events, blockheight this occured at"
},
"origin": {
"type": "string",
"description": "The account this movement originated from"
},
"payment_id": {
"type": "hex",
"description": "lightning payment identifier. For an htlc, this will be the preimage."
},
"txid": {
"type": "txid",
"description": "The txid of the transaction that created this event"
}
},
"required": [
"outpoint",
"blockheight"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"type": {
"type": "string",
"enum": [
"onchain_fee"
]
}
}
},
"then": {
"properties": {
"account": {},
"type": {},
"tag": {},
"credit_msat": {},
"debit_msat": {},
"currency": {},
"timestamp": {},
"txid": {
"type": "txid",
"description": "The txid of the transaction that created this event"
}
},
"required": [
"txid"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"type": {
"type": "string",
"enum": [
"channel"
]
}
}
},
"then": {
"properties": {
"account": {},
"type": {},
"tag": {},
"credit_msat": {},
"debit_msat": {},
"currency": {},
"timestamp": {},
"fees_msat": {
"type": "msat",
"description": "Amount paid in fees"
},
"payment_id": {
"type": "hex",
"description": "lightning payment identifier. For an htlc, this will be the preimage."
},
"part_id": {
"type": "u32",
"description": "Counter for multi-part payments"
}
},
"additionalProperties": false
}
}
]
}
}
}
}

95
doc/schemas/bkpr-listbalances.schema.json Normal file
View File

@ -0,0 +1,95 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [
"accounts"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"required": [
"account",
"balances"
],
"properties": {
"account": {
"type": "string",
"description": "The account name. If the account is a channel, the channel_id"
},
"balances": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"balance_msat",
"coin_type"
],
"properties": {
"balance_msat": {
"type": "msat",
"description": "Current account balance"
},
"coin_type": {
"type": "string",
"description": "coin type, same as HRP for bech32"
}
}
}
}
},
"if": {
"required": [
"peer_id"
]
},
"then": {
"required": [
"account",
"balances",
"peer_id",
"we_opened",
"account_closed",
"account_resolved"
],
"additionalProperties": false,
"properties": {
"account": {},
"balances": {},
"peer_id": {
"type": "pubkey",
"description": "Node id for the peer this account is with"
},
"we_opened": {
"type": "boolean",
"description": "Did we initiate this account open (open the channel)"
},
"account_closed": {
"type": "boolean",
"description": ""
},
"account_resolved": {
"type": "boolean",
"description": "Has this channel been closed and all outputs resolved?"
},
"resolved_at_block": {
"type": "u32",
"description": "Blockheight account resolved on chain"
}
}
},
"else": {
"properties": {
"account": {},
"balances": {}
},
"additionalProperties": false
}
}
}
}
}

63
doc/schemas/bkpr-listincome.schema.json Normal file
View File

@ -0,0 +1,63 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": [
"income_events"
],
"properties": {
"income_events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"account",
"tag",
"credit_msat",
"debit_msat",
"currency",
"timestamp"
],
"properties": {
"account": {
"type": "string",
"description": "The account name. If the account is a channel, the channel_id"
},
"tag": {
"type": "string",
"description": "Type of income event"
},
"credit_msat": {
"type": "msat",
"description": "Amount earned (income)"
},
"debit_msat": {
"type": "msat",
"description": "Amount spent (expenses)"
},
"currency": {
"type": "string",
"description": "human-readable bech32 part for this coin type"
},
"timestamp": {
"type": "u32",
"description": "Timestamp this event was recorded by the node. For consolidated events such as onchain_fees, the most recent timestamp"
},
"outpoint": {
"type": "string",
"description": "The txid:outnum for this event, if applicable"
},
"txid": {
"type": "txid",
"description": "The txid of the transaction that created this event, if applicable"
},
"payment_id": {
"type": "hex",
"description": "lightning payment identifier. For an htlc, this will be the preimage."
}
}
}
}
}
}

14
plugins/bkpr/bookkeeper.c
View File

@ -85,7 +85,7 @@ getblockheight_done(struct command *cmd, const char *buf,
net_apys->total_start_bal = AMOUNT_MSAT(0);
res = jsonrpc_stream_success(cmd);
json_array_start(res, "channel_apys");
json_array_start(res, "channels_apy");
for (size_t i = 0; i < tal_count(apys); i++) {
json_add_channel_apy(res, apys[i]);
@ -1474,14 +1474,14 @@ const struct plugin_notification notifs[] = {
static const struct plugin_command commands[] = {
{
"listbalances",
"bkpr-listbalances",
"bookkeeping",
"List current account balances",
"List of current accounts and their balances",
json_list_balances
},
{
"listaccountevents",
"bkpr-listaccountevents",
"bookkeeping",
"List all events for an {account}",
"List all events for an {account} (or all accounts, if"
@ -1489,21 +1489,21 @@ static const struct plugin_command commands[] = {
json_list_account_events
},
{
"inspect",
"bkpr-inspect",
"utilities",
"See the current on-chain graph of an {account}",
"Prints out the on-chain footprint of a given {account}.",
json_inspect
},
{
"listincome",
"bkpr-listincome",
"bookkeeping",
"List all income impacting events",
"List all events for this node that impacted income",
json_list_income
},
{
"dumpincomecsv",
"bkpr-dumpincomecsv",
"bookkeeping",
"Print out all the income events to a csv file in "
" {csv_format",
@ -1513,7 +1513,7 @@ static const struct plugin_command commands[] = {
json_dump_income
},
{
"channelsapy",
"bkpr-channelsapy",
"bookkeeping",
"Stats on channel fund usage",
"Print out stats on chanenl fund usage",

60
tests/test_bookkeeper.py
View File

@ -48,7 +48,7 @@ def test_bookkeeping_closing_trimmed_htlcs(node_factory, bitcoind, executor):
sync_blockheight(bitcoind, [l1])
l1.daemon.wait_for_log(r'All outputs resolved.*')
evs = l1.rpc.listaccountevents()['events']
evs = l1.rpc.bkpr_listaccountevents()['events']
close = find_first_tag(evs, 'channel_close')
delayed_to = find_first_tag(evs, 'delayed_to_us')
@ -59,7 +59,7 @@ def test_bookkeeping_closing_trimmed_htlcs(node_factory, bitcoind, executor):
assert close_fee[0]['credit_msat'] + delayed_to['credit_msat'] == close['debit_msat']
# l2's fees should equal the trimmed htlc out
evs = l2.rpc.listaccountevents()['events']
evs = l2.rpc.bkpr_listaccountevents()['events']
close = find_first_tag(evs, 'channel_close')
deposit = find_first_tag(evs, 'deposit')
fees = find_tags(evs, 'onchain_fee')
@ -89,7 +89,7 @@ def test_bookkeeping_closing_subsat_htlcs(node_factory, bitcoind, chainparams):
bitcoind.generate_block(80)
sync_blockheight(bitcoind, [l1, l2])
evs = l1.rpc.listaccountevents()['events']
evs = l1.rpc.bkpr_listaccountevents()['events']
# check that closing equals onchain deposits + fees
close = find_first_tag(evs, 'channel_close')
delayed_to = find_first_tag(evs, 'delayed_to_us')
@ -98,7 +98,7 @@ def test_bookkeeping_closing_subsat_htlcs(node_factory, bitcoind, chainparams):
assert len(close_fee) == 1
assert close_fee[0]['credit_msat'] + delayed_to['credit_msat'] == close['debit_msat']
evs = l2.rpc.listaccountevents()['events']
evs = l2.rpc.bkpr_listaccountevents()['events']
close = find_first_tag(evs, 'channel_close')
deposit = find_first_tag(evs, 'deposit')
fees = find_tags(evs, 'onchain_fee')
@ -134,7 +134,7 @@ def test_bookkeeping_external_withdraws(node_factory, bitcoind):
withdrawal = [u for u in unspent if u['txid'] == out['txid']]
assert withdrawal[0]['amount'] == Decimal('0.00555555')
incomes = l1.rpc.listincome()['income_events']
incomes = l1.rpc.bkpr_listincome()['income_events']
# There should only be two income events: deposits to wallet
# for {amount}
assert len(incomes) == 2
@ -142,13 +142,13 @@ def test_bookkeeping_external_withdraws(node_factory, bitcoind):
assert inc['account'] == 'wallet'
assert inc['tag'] == 'deposit'
assert inc['credit_msat'] == amount_msat
# The event should show up in the 'listaccountevents' however
events = l1.rpc.listaccountevents()['events']
# The event should show up in the 'bkpr_listaccountevents' however
events = l1.rpc.bkpr_listaccountevents()['events']
assert len(events) == 3
external = [e for e in events if e['account'] == 'external'][0]
assert external['credit_msat'] == Millisatoshi(amount // 2 * 1000)
btc_balance = only_one(only_one(l1.rpc.listbalances()['accounts'])['balances'])
btc_balance = only_one(only_one(l1.rpc.bkpr_listbalances()['accounts'])['balances'])
assert btc_balance['balance_msat'] == amount_msat * 2
# Restart the node, issues a balance snapshot
@ -157,15 +157,15 @@ def test_bookkeeping_external_withdraws(node_factory, bitcoind):
l1.restart()
# the number of account + income events should be unchanged
incomes = l1.rpc.listincome()['income_events']
incomes = l1.rpc.bkpr_listincome()['income_events']
assert len(find_tags(incomes, 'journal_entry')) == 0
assert len(incomes) == 2
events = l1.rpc.listaccountevents()['events']
events = l1.rpc.bkpr_listaccountevents()['events']
assert len(events) == 3
assert len(find_tags(events, 'journal_entry')) == 0
# the wallet balance should be unchanged
btc_balance = only_one(only_one(l1.rpc.listbalances()['accounts'])['balances'])
btc_balance = only_one(only_one(l1.rpc.bkpr_listbalances()['accounts'])['balances'])
assert btc_balance['balance_msat'] == amount_msat * 2
# ok now we mine a block
@ -174,7 +174,7 @@ def test_bookkeeping_external_withdraws(node_factory, bitcoind):
# expect the withdrawal to appear in the incomes
# and there should be an onchain fee
incomes = l1.rpc.listincome()['income_events']
incomes = l1.rpc.bkpr_listincome()['income_events']
# 2 wallet deposits, 1 wallet withdrawal, 1 onchain_fee
assert len(incomes) == 4
withdraw_amt = find_tags(incomes, 'withdrawal')[0]['debit_msat']
@ -185,7 +185,7 @@ def test_bookkeeping_external_withdraws(node_factory, bitcoind):
fees = fee_events[0]['debit_msat']
# wallet balance is decremented now
btc_balance = only_one(only_one(l1.rpc.listbalances()['accounts'])['balances'])
btc_balance = only_one(only_one(l1.rpc.bkpr_listbalances()['accounts'])['balances'])
assert btc_balance['balance_msat'] == amount_msat * 2 - withdraw_amt - fees
@ -214,9 +214,9 @@ def test_bookkeeping_external_withdraw_missing(node_factory, bitcoind):
l1.rpc.withdraw(waddr, amount // 2)
# There should only be two income events: deposits to wallet
assert len(l1.rpc.listincome()['income_events']) == 2
assert len(l1.rpc.bkpr_listincome()['income_events']) == 2
# There are three account events: 2 wallet deposits, 1 external deposit
assert len(l1.rpc.listaccountevents()['events']) == 3
assert len(l1.rpc.bkpr_listaccountevents()['events']) == 3
# Stop node and remove the accounts data
l1.stop()
@ -224,15 +224,15 @@ def test_bookkeeping_external_withdraw_missing(node_factory, bitcoind):
l1.start()
# the number of income events should be unchanged
assert len(l1.rpc.listincome()['income_events']) == 2
assert len(l1.rpc.bkpr_listincome()['income_events']) == 2
# we're now missing the external deposit
events = l1.rpc.listaccountevents()['events']
events = l1.rpc.bkpr_listaccountevents()['events']
assert len(events) == 2
assert len([e for e in events if e['account'] == 'external']) == 0
assert len(find_tags(events, 'journal_entry')) == 0
# the wallet balance should be unchanged
btc_balance = only_one(only_one(l1.rpc.listbalances()['accounts'])['balances'])
btc_balance = only_one(only_one(l1.rpc.bkpr_listbalances()['accounts'])['balances'])
assert btc_balance['balance_msat'] == amount_msat * 2
# ok now we mine a block
@ -241,7 +241,7 @@ def test_bookkeeping_external_withdraw_missing(node_factory, bitcoind):
# expect the withdrawal to appear in the incomes
# and there should be an onchain fee
incomes = l1.rpc.listincome()['income_events']
incomes = l1.rpc.bkpr_listincome()['income_events']
# 2 wallet deposits, 1 onchain_fee
assert len(incomes) == 3
assert len(find_tags(incomes, 'withdrawal')) == 0
@ -252,7 +252,7 @@ def test_bookkeeping_external_withdraw_missing(node_factory, bitcoind):
assert fees > Millisatoshi(amount // 2 * 1000)
# wallet balance is decremented now
bal = only_one(only_one(l1.rpc.listbalances()['accounts'])['balances'])
bal = only_one(only_one(l1.rpc.bkpr_listbalances()['accounts'])['balances'])
assert bal['balance_msat'] == amount_msat * 2 - fees
@ -269,8 +269,8 @@ def test_bookkeeping_rbf_withdraw(node_factory, bitcoind):
bitcoind.rpc.sendtoaddress(addr, amount / 10**8)
bitcoind.generate_block(1)
wait_for(lambda: len(l1.rpc.listfunds()['outputs']) == 1)
assert len(l1.rpc.listaccountevents()['events']) == 1
assert len(l1.rpc.listincome()['income_events']) == 1
assert len(l1.rpc.bkpr_listaccountevents()['events']) == 1
assert len(l1.rpc.bkpr_listincome()['income_events']) == 1
# Ok, now we send some funds to an external address
waddr = l1.bitcoin.rpc.getnewaddress()
@ -280,8 +280,8 @@ def test_bookkeeping_rbf_withdraw(node_factory, bitcoind):
assert out1['txid'] in list(mempool.keys())
# another account event, still one income event
assert len(l1.rpc.listaccountevents()['events']) == 2
assert len(l1.rpc.listincome()['income_events']) == 1
assert len(l1.rpc.bkpr_listaccountevents()['events']) == 2
assert len(l1.rpc.bkpr_listincome()['income_events']) == 1
# unreserve the existing output
l1.rpc.unreserveinputs(out1['psbt'], 200)
@ -293,14 +293,14 @@ def test_bookkeeping_rbf_withdraw(node_factory, bitcoind):
assert out2['txid'] in list(mempool.keys())
# another account event, still one income event
assert len(l1.rpc.listaccountevents()['events']) == 3
assert len(l1.rpc.listincome()['income_events']) == 1
assert len(l1.rpc.bkpr_listaccountevents()['events']) == 3
assert len(l1.rpc.bkpr_listincome()['income_events']) == 1
# ok now we mine a block
bitcoind.generate_block(1)
sync_blockheight(bitcoind, [l1])
acct_evs = l1.rpc.listaccountevents()['events']
acct_evs = l1.rpc.bkpr_listaccountevents()['events']
externs = [e for e in acct_evs if e['account'] == 'external']
assert len(externs) == 2
assert externs[0]['outpoint'][:-2] == out1['txid']
@ -308,7 +308,7 @@ def test_bookkeeping_rbf_withdraw(node_factory, bitcoind):
assert externs[1]['outpoint'][:-2] == out2['txid']
assert externs[1]['blockheight'] > 0
withdraws = find_tags(l1.rpc.listincome()['income_events'], 'withdrawal')
withdraws = find_tags(l1.rpc.bkpr_listincome()['income_events'], 'withdrawal')
assert len(withdraws) == 1
assert withdraws[0]['outpoint'][:-2] == out2['txid']
@ -318,7 +318,7 @@ def test_bookkeeping_rbf_withdraw(node_factory, bitcoind):
for fee in fees:
assert fee['txid'] == out2['txid']
fees = find_tags(l1.rpc.listincome(consolidate_fees=False)['income_events'], 'onchain_fee')
fees = find_tags(l1.rpc.bkpr_listincome(consolidate_fees=False)['income_events'], 'onchain_fee')
assert len(fees) == 2
fees = find_tags(l1.rpc.listincome(consolidate_fees=True)['income_events'], 'onchain_fee')
fees = find_tags(l1.rpc.bkpr_listincome(consolidate_fees=True)['income_events'], 'onchain_fee')
assert len(fees) == 1

4
tests/test_closing.py
View File

@ -984,7 +984,7 @@ def test_channel_lease_unilat_closes(node_factory, bitcoind):
assert l3.daemon.is_in_log('Broadcasting OUR_DELAYED_RETURN_TO_WALLET')
# We were making a journal_entry for anchors, but now we ignore them
incomes = l2.rpc.listincome()['income_events']
incomes = l2.rpc.bkpr_listincome()['income_events']
assert 'journal_entry' not in [x['tag'] for x in incomes]
@ -1760,7 +1760,7 @@ def test_penalty_rbf_burn(node_factory, bitcoind, executor, chainparams):
check_utxos_channel(l2, [channel_id], expected_2)
# Make sure that l2's account is considered closed (has a fee output)
fees = [e for e in l2.rpc.listincome()['income_events'] if e['tag'] == 'onchain_fee']
fees = [e for e in l2.rpc.bkpr_listincome()['income_events'] if e['tag'] == 'onchain_fee']
assert len(fees) == 1

6
tests/test_pay.py
View File

@ -1305,17 +1305,17 @@ def test_forward_pad_fees_and_cltv(node_factory, bitcoind):
# Do some checks of the bookkeeper's records
def _income_tagset(node, tagset):
incomes = node.rpc.listincome()['income_events']
incomes = node.rpc.bkpr_listincome()['income_events']
return [e for e in incomes if e['tag'] in tagset]
tags = ['invoice', 'invoice_fee']
wait_for(lambda: len(_income_tagset(l1, tags)) == 2)
incomes = _income_tagset(l1, tags)
# the balance on l3 should equal the invoice
bal = only_one(only_one(l3.rpc.listbalances()['accounts'])['balances'])['balance']
bal = only_one(only_one(l3.rpc.bkpr_listbalances()['accounts'])['balances'])['balance_msat']
assert incomes[0]['tag'] == 'invoice'
assert Millisatoshi(bal) == incomes[0]['debit_msat']
inve = only_one([e for e in l1.rpc.listaccountevents()['events'] if e['tag'] == 'invoice'])
inve = only_one([e for e in l1.rpc.bkpr_listaccountevents()['events'] if e['tag'] == 'invoice'])
assert inve['debit_msat'] == incomes[0]['debit_msat'] + incomes[1]['debit_msat']