Member DB refactor - 01/29/24

Refactored prism operations: create, update, list, show

  • Prisms are now stored in the db as:
      "key": [
       "generation": 3,
       "hex": "7b22707269736d5f6964223a202265656236396164342d363833622d346639632d623538372d663536663937636430373564222c2022707269736d5f6d656d62657273223a205b2231643461663636632d356434362d343161312d613764372d353961643136626236363335222c202230363362626561362d393933302d346238382d613263662d613232616136383263383431222c202263353466353831652d343365322d346363612d623261622d663539333666653565343838225d7d",
         "string": "{\"prism_id\": \"eeb69ad4-683b-4f9c-b587-f56f97cd075d\", \"prism_members\": [\"1d4af66c-5d46-41a1-a7d7-59ad16bb6635\", \"063bbea6-9930-4b88-a2cf-a22aa682c841\", \"c54f581e-43e2-4cca-b2ab-f5936fe5e488\"]}"
  • Members are now stored in the db as:
         "key": [
         "generation": 0,
         "hex": "7b226d656d6265725f6964223a202231643461663636632d356434362d343161312d613764372d353961643136626236363335222c20226c6162656c223a20226361726f6c207b4356527d222c202264657374696e6174696f6e223a20226c6e6f317167737176676e7767636733357a36656532683379637a726164646d373278726675613975766532726c726d39646575377879667a7263327073367232766a337861343935356d637839703876393370717463687064676e687274666d65796b67357a617137646c717761666e347278326a346d32756477676333773470396c3370397036222c202273706c6974223a20312c2022666565735f696e6375727265645f6279223a202272656d6f7465222c20227061796f75745f7468726573686f6c64223a2022306d736174227d",
         "string": "{\"member_id\": \"1d4af66c-5d46-41a1-a7d7-59ad16bb6635\", \"label\": \"carol\", \"destination\": \"lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2ps6r2vj3xa4955mcx9p8v93pqtchpdgnhrtfmeykg5zaq7dlqwafn4rx2j4m2udwgc3w4p9l3p9p6\", \"split\": 1, \"fees_incurred_by\": \"remote\", \"payout_threshold\": \"0msat\"}"

Bolt11 Bindings

When we subscribe to the cln invoice_payment event, the information that we get from the event is the same for invoices generated from offers, and manually generated invoices.

{'msat': '234234msat', 'preimage': '5aed1e906bb8463a48d802506fce4bb2d10184c014ff11e17348bf4c3ba6767c', 'label': 'ldahgskdj'}

The primary difference is that the label of an invoice generated by a bolt12 offer includes the ID of the offer that generated the invoice.

Bolt12 bindings:

Currently, bolt12 bindings are referenced by the offer ID. This is how it should be. We can simply check if the label includes something that looks like an offer ID and if it does, then we check if there are any bindings.

If no bolt12 binding is found, we probably should then follow the below flow to check if there are any bolt11 bindings.

Bolt11 bindings:

We should bind bolt11's to the payment hash of the invoice. The payment_hash can be supplied directly to prism-bindingadd or obtained from the invoice itself. When an invoice is paid the notification that the plugin gets (above) includes the preimage meaning that we can hash the preimage and check if there are any bolt11 bindings matching the hash of the preimage.

Possible downside: we have to hash the preimage of every invoice that gets paid on our node.

Nevermind... This is how we should do bolt 11 bindings:

We should only look up payments by the invoice label given to us by the invoice_payment notification.

If the invoice was generated from a bolt12, then the result of listinvoices <label> will include a local_offer_id, and if it was not generated from a bolt12, then local_offer_id will not be present, and there will be a bolt11 property.

This means we bind bolt12s to offer_id and invoices to labels.


  • all invoices bound to prisms will be generated from our nod
  • all invoices have labels.
  • all invoices have unique labels

Prism Bindings Explained:

Bindings exists in the CLN database at:

  • [..., "bind", "bolt12", <offer_id>]
  • [..., "bind", "bolt11", <invoice_label>]

When creating a binding, a payment method is being associated with a prism. When a binding is paid, the prism is executed.

When creating or showing bindings, both the bolt_version and bind_to must be specified where bind_to is the identifier used to bind the payment method to the prism.


  • Refactor members into own database hierarchy/key
  • BOLT11 bindings
  • wire up payments



developing = building + learning