moves toward making clightning more accountant friendly

[niftynei]

I'd like to make it easier to audit the movement of funds through a c-lightning node. Here's my proposal for how to do this.

Introducing... coin movements, a new event generated by a conclusive movement of funds.

Coin Movements

Here's a list of events that would generate a new coin movement notification

• withdraw successfully sent to chain (chain_mvt, -)
• deposit found on chain (chain_mvt, +)
• channel opens (chain_mvt/channel_mvt, -/+)
• channel closes (chain_mvt/channel_mvt, +/-)
• htlc_settled (channel_mvt, +/-)
  • invoice paid (->, -)
  • invoice paid (<-, +)
• penalty tx (chain_mvt?/channel_mvt, +/-)
• chain_fees (chain_mvt, -)

Specification of the coin_movement

• account_id, string. [wallet,external,<channel_id>]
• movement_type, enum. [chain_mvt,channel_mvt]
• identifier (differ depending on movement type)
  • chain_mvt:
    • txid, string.
    • index, u32. may be null
    • index_type, enum. [vin,vout,none]
  • channel_mvt:
    • payment_hash, (hex)string.
• mvt_tag, enum. [chain_fees,withdrawal,deposit,penalty,invoice?,routed?]
• credit, u64. (unit is msat)
• debit, u64. (unit is msat)
• unit_of_account, string. (BTC,L-BTC,etc)
• timestamp, u64. seconds since unix epoch
• blockheight, u32. (only for chain_mvts??)
• version, u16. coin movement format version
• node_id, string. id of the node generating this movement
• counter, u64. id of event, global for node.

Rationale, Explanation, etc

• onchain coin movements are scoped to the level of utxos
  • in other words, every utxo update incurs a coin movement event
• we introduce the concept of 'movement_types': channel + chain
• funds issued to/received from unknown addresses are classified as belonging to an 'external' wallet
  • future improvements may include importing an xpub for providing more robust labels for the account_id
• every channel is identified by its channel_id
• htlc's invoke money movements at settlement (onchain or in channel)
• some htlc money movements are tied to invoices we control. this is reflected in the mvt_tag.
• routing fees are not explicit money mvts.
  • they can be derived from the set of coin movements by finding the difference between
    two channel mvts with the same payment_hash (decorrelated hops will change this?!)
• chain fees are onchain. their index-type is none and the index is blank
• a channel open is (at least) two coin movements:
  • a withdrawal from an onchain account, and
  • a deposit into a channel account
• a channel closure is (at least) two coin movements:
  • a withdrawal from a channel account, and
  • a deposit into an onchain account (may be external)
• funds in onchain but unswept htlc's are not counted until swept. the balance remains 'in channel' until swept
  • this is the same treatment as 'unsettled htlc' balances
• blockheight is included as a timestamp and a reconciliation for tool in case of reorgs
• any reorg reconciliation will need to be handled manually (money mvts are append only)
• penalties only have onchain mvts if they're in our favor (to us)

Questions (and Some Answers)

• Q: how are chain fees for htlc txs (onchain) accounted?
  • A: should be decremented from channel balance as a chain_mvt when utxo is sent to chain
• Q: how are chain fees for unilateral closes accounted?
  • A: should be decremented from channel balance as a chain_mvt when utxo is sent to chain
• Q: should invoice and routed be included as movement categories?
  • A: I'm not sure about this. Having these movements tagged will make it easier to filter for routing_fee generating movements and a list of paid + received invoices, so I lean towards yes, we should include them.
• Q: should channel_mvts include a blockheight?
• Q: how will decorrelated hops change the way we account for routing fees?

[ZmnSCPxj]

Q: should channel_mvts include a blockheight?

Yes.

Q: how will decorrelated hops change the way we account for routing fees?

Not at all. Fee earned is still outgoing - incoming, and the information about forwarding correlations (which out comes from which in) is leaked in our logs anyway.

Your alternative would be to put incoming and outgoing separately, but the timing of the resolution of such things can still be recorded and the information about incoming and outgoing amounts, and their timing, can still be extracted from a timed log of incoming and outgoing amounts; and of course any accountant would want to know when each + / - event occurs, so they would still know about forwards, indirectly.

[ZmnSCPxj]

any reorg reconciliation will need to be handled manually

How does a plugin detect a reorg? Should we add an event for reorgs as well?