LIGHTNING-BKPR-LISTACCOUNTEVENTS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 NAME 💖

Okay bestie, welcome to LIGHTNING-BKPR-LISTACCOUNTEVENTS(7) — the manual page for bkpr-listaccountevents, aka the command for listing recorded bookkeeping events. ✨

✨ SYNOPSIS ✨

bkpr-listaccountevents [account] [payment_id]

🦋 DESCRIPTION 🦋

The bkpr-listaccountevents RPC command is literally a list of all the bookkeeping events that have been recorded for this node. No cap. 💅

If the optional parameter account is set, we only emit events for that specified account, if it exists.

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

The parameters account and payment_id are mutually exclusive — pick one, not both. 🫶

⚠️ Note that the type onchain_fees that are emitted are of opposite credit/debit than as they appear in listincome, because 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.
  • currencyrate (number, optional): The value of currencyrate around the time the event occurred. Only present if bkpr-currency is set, and a conversion value is available (added v26.04).

🔥 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 🌸

🌈 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
    }
  ]
}

💖 That’s the whole vibe, bestie: Core Lightning v26.06.9, manual page LIGHTNING-BKPR-LISTACCOUNTEVENTS(7) — and the original footer didn’t show a date, so we’re not inventing one. Periodt. 💖

📦 where this page comes from