NAME

lightning-bkpr-listaccountevents -- Command for listing recorded bookkeeping events

SYNOPSIS

bkpr-listaccountevents [account] [payment_id]

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.

If the optional parameter payment_id is set, we only emit events which have that value as payment hash or as transaction id.

The parameters account and payment_id are mutually exclusive.

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.

• account (string, optional): Receive events for the specified account.

• payment_id (string, optional): Receive events for the specified payment id. (added v24.08)

RETURN VALUE

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) (one of "onchain_fee", "chain", "channel"): Coin movement type.

• 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. - description (string, optional): The description of this event. - 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. - is_rebalance (boolean, optional): Is this payment part of a rebalance. - payment_id (hex, optional): Lightning payment identifier. For an htlc, this will be the preimage. - part_id (u32, optional): Counter for multi-part payments.

AUTHOR

Lisa Neigut <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

EXAMPLES

Example 1:

Request:

$ lightning-cli bkpr-listaccountevents "channelid0230200230200230200230200230200230200230200230200230200"

{


  "id": "example:bkpr-listaccountevents#1",


  "method": "bkpr-listaccountevents",


  "params": [


    "channelid0230200230200230200230200230200230200230200230200230200"


  ]
}

Response:

{


  "events": [


    {


      "account": "channelid0230200230200230200230200230200230200230200230200230200",


      "type": "chain",


      "tag": "channel_open",


      "credit_msat": 0,


      "debit_msat": 0,


      "currency": "bcrt",


      "outpoint": "txidbk0101010101010101010101010101010101010101010101010101010101:1",


      "timestamp": 1738500000,


      "blockheight": 123


    }


  ]
}

Example 2:

Request:

$ lightning-cli bkpr-listaccountevents

{


  "id": "example:bkpr-listaccountevents#2",


  "method": "bkpr-listaccountevents",


  "params": {}
}

Response:

{


  "events": [


    {


      "account": "external",


      "origin": "channelid0340000340000340000340000340000340000340000340000340000",


      "type": "chain",


      "tag": "to_them",


      "credit_msat": 510010000,


      "debit_msat": 0,


      "currency": "bcrt",


      "outpoint": "txidbk0202020202020202020202020202020202020202020202020202020202:1",


      "timestamp": 1738520000,


      "blockheight": 142


    },


    {


      "account": "wallet",


      "type": "chain",


      "tag": "deposit",


      "credit_msat": 200000000000,


      "debit_msat": 0,


      "currency": "bcrt",


      "outpoint": "txidbk0101010101010101010101010101010101010101010101010101010101:1",


      "timestamp": 1738510000,


      "blockheight": 141,


      "description": "edited utxo description"


    },


    {


      "account": "channelid0230000230000230000230000230000230000230000230000230000",


      "type": "chain",


      "tag": "channel_open",


      "credit_msat": 0,


      "debit_msat": 0,


      "currency": "bcrt",


      "outpoint": "txidbk0303030303030303030303030303030303030303030303030303030303:1",


      "timestamp": 1738530000,


      "blockheight": 143


    }


  ]
}