From 45693704749e221e15d4d3d1c68617a82001bdc9 Mon Sep 17 00:00:00 2001 From: Derek Smith Date: Wed, 3 Jul 2024 16:29:08 -0600 Subject: [PATCH] Update readme with latest updates. --- README.md | 196 +++++++++++++++++++++++++++++------------------------- 1 file changed, 106 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index ae5f926..cb957e9 100644 --- a/README.md +++ b/README.md @@ -47,43 +47,43 @@ Find your c-lightning config file and add MEMBERS_JSON= ```json -[{"description" : "Guitarist", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtk39j62x7m9qvkfep23m6euet54xfyp5xsyye7lavp0jmug06zxy", "split": 0.333333, "payout_threshold_msat": "5000000", "fees_incurred_by": "local"},{"description" : "Drums", "destination": "02e4cc35ff6e7d43edc71db8146ae558f5b00a6d1e783e9ab10ad63bd82975502c", "split": 0.333333, "payout_threshold_msat": "10000000", "fees_incurred_by": "remote"},{"description" : "Tuba", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq0s2x4jx6v7jtwzu4zf3f3nst03z3wcnwdjamr7mlk8axt70hvkd6", "split": 0.333333, "payout_threshold_msat": "5000000", "fees_incurred_by": "local"}] +[{"description" : "Drummer", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwtzkujnk4t5hteur6cn8aqyt3v38u300ldryz6z2fw7zwr4gjxcq", "split": 1.0, "payout_threshold_msat": "0", "fees_incurred_by": "local"},{"description" : "Guitarist", "destination": "02dbfb1d0a6fbc717ae3f28e4dc185d812e399ee33055587eeb06469c94e4326e5", "split": 1.0, "payout_threshold_msat": "0", "fees_incurred_by": "remote"},{"description" : "Tuba", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvzk2archeau0slmv7dlsvwlrcra6pxml6mdwxetsml0hhcp9w4cu", "split": 1.0, "payout_threshold_msat": "0", "fees_incurred_by": "local"}]' ``` ```bash -lightning-cli prism-create -k description="Band Prism" members="$MEMBERS_JSON" outlay_factor="0.8" +lightning-cli prism-create -k description="Band Prism" members="$MEMBERS_JSON" outlay_factor="0.75" ``` ```json { - "prism_id": "f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d", + "prism_id": "a59afe3927e6cdce218fb82415574204df4f762bb9c2c535a420488b3fa5fbf5", "description": "Band Prism", - "timestamp": 1718764199, - "outlay_factor": 0.8, + "timestamp": 1720044718, + "outlay_factor": 0.75, "prism_members": [ { - "member_id": "c0772494d0d83318cf47ea1dbabcf3e37df2218090f9f20585867f135c241279", - "description": "Guitarist", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtk39j62x7m9qvkfep23m6euet54xfyp5xsyye7lavp0jmug06zxy", - "split": 0.333333, + "member_id": "95256245897c5423f9c319afbcd224dba9902cb829991a2435e2902631810389", + "description": "Drummer", + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwtzkujnk4t5hteur6cn8aqyt3v38u300ldryz6z2fw7zwr4gjxcq", + "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 }, { - "member_id": "d624d9b334b06d84560f1095d153001cb8ae829a8270d6fe29fa6d715efd538d", - "description": "Drums", - "destination": "02e4cc35ff6e7d43edc71db8146ae558f5b00a6d1e783e9ab10ad63bd82975502c", - "split": 0.333333, + "member_id": "412c79d6feafdf907a348ddb15627ba057d2c3ac3615f8f41680acd176d8bc2d", + "description": "Guitarist", + "destination": "02dbfb1d0a6fbc717ae3f28e4dc185d812e399ee33055587eeb06469c94e4326e5", + "split": 1.0, "fees_incurred_by": "remote", - "payout_threshold_msat": 10000000 + "payout_threshold_msat": 0 }, { - "member_id": "3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b", + "member_id": "ebc13b1be16346e8e08571cbde85f5eb604cd76233181b5edbd559e3f35858ab", "description": "Tuba", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq0s2x4jx6v7jtwzu4zf3f3nst03z3wcnwdjamr7mlk8axt70hvkd6", - "split": 0.333333, + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvzk2archeau0slmv7dlsvwlrcra6pxml6mdwxetsml0hhcp9w4cu", + "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 } ] } @@ -105,34 +105,34 @@ Run the following command to view a prism policy. (Note that you can add a `pris { "prisms": [ { - "prism_id": "f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d", - "description": "prism1", - "timestamp": 1718722200, - "outlay_factor": 0.8, + "prism_id": "4cf1e1b3e7bea1d0b8f9612ed138f164a03abe4541b1e82c8cde16af050b4f53", + "description": "Band Prism", + "timestamp": 1720042032, + "outlay_factor": 0.75, "prism_members": [ { - "member_id": "b2dd7d8a70567a0e23308a6a77b38d603eaf2baca5da320082184a9951063a95", - "description": "Carol", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq0d9gxlr2q2c9rp0lkqjyztvwcl8g7gzjgu2trnwll8lraquy35vq", + "member_id": "547d51d513aec15dc2229047d6d912b63d39416e3682b6dee4d6ae686f88b9b4", + "description": "Drummer", + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwt5tgjxynmyjjx0zjcssjx9z5h377kewwa4k2zqtu0k8k47sscvv", "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 }, { - "member_id": "809a721743350c0c49a7b444ad3aeaf1341fdd48d1bf510e08b008edab72dc70", - "description": "Dave", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwv5lnjcufs7jmsh2r7wmj45mp35z822tz69n2j07gy64qn475j2c", + "member_id": "1fdda73dbdd4d3dda4057cf302ec10dedfc55466163133fd236e313a60a52204", + "description": "Guitarist", + "destination": "030e7553729959098adc3b63df389be92fbe0ca756a5469ba71364fc44c1338ac7", "split": 1.0, "fees_incurred_by": "remote", - "payout_threshold_msat": 10000000 + "payout_threshold_msat": 0 }, { - "member_id": "849dc45741d52a071b0ed4ca14b7a182e82fcad6a60cf9b0025c903411263085", - "description": "Erin", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwfg6tm3xapdfr0q0lqr3q5sujzznv3f9ff6wfvhl36m6scf3wzpy", + "member_id": "22dad0bd9cfcf4adfa367d2627e80a7a92e531b60a3d7c006495258c57b9db5e", + "description": "Tuba", + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq2zlvjv9s9she2fpj0msp6jz0sgrl7wgm425fc6rhdkhcqtqlggks", "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 } ] } @@ -142,7 +142,7 @@ Run the following command to view a prism policy. (Note that you can add a `pris ## Prism-Pay - Executes a Payout -`lightning-cli prism-pay -k prism_id=f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d amount_msat=10000000` +`lightning-cli prism-pay -k prism_id=a59afe3927e6cdce218fb82415574204df4f762bb9c2c535a420488b3fa5fbf5 amount_msat=10000000` When run, this RPC command will execute (i.e., pay-out) a prism. @@ -167,18 +167,36 @@ When run, this RPC command will execute (i.e., pay-out) a prism. "created_at": 1718764200.7018805, "parts": 1, "amount_msat": 2666666, - "amount_sent_msat": 2666666, - "payment_preimage": "3ac15217d8f62c4c5d301b0f3a22794f9bfcaad496a20488fbc64318da893091", + { + "prism_member_payouts": { + "95256245897c5423f9c319afbcd224dba9902cb829991a2435e2902631810389": { + "destination": "03962b7253b5574baf3c1eb133f4045c5913f22f7fda320b42525de13875448d80", + "payment_hash": "e6dd62613b51366ce39ad9ee588e1e76a82cdd887634ffeb32f84ca9d4ead3fc", + "created_at": 1720044718.095364, + "parts": 1, + "amount_msat": 2500000, + "amount_sent_msat": 2500000, + "payment_preimage": "c7f0222fe6bc3df4ed14146aca88cbd79360662683d1edb71a824338add87be2", "status": "complete" }, - "3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b": { - "destination": "03e0a35646d33d25b85ca89314c6705be228bb137365dd8fdbfd8fd32fcfbb2cdd", - "payment_hash": "97f31109bc0fcb07491a4b73b6d63d0a5d8ccdc3234123d70dd2cfd651825168", - "created_at": 1718764201.6202407, + "412c79d6feafdf907a348ddb15627ba057d2c3ac3615f8f41680acd176d8bc2d": { + "destination": "02dbfb1d0a6fbc717ae3f28e4dc185d812e399ee33055587eeb06469c94e4326e5", + "payment_hash": "2a121e2ca5c6a37fe51521c8f27c30284d6469d664b9527df88ebddb29818e39", + "created_at": 1720044719.0942972, "parts": 1, - "amount_msat": 2666666, - "amount_sent_msat": 2666666, - "payment_preimage": "11ccae76acd177b40ebc324de0a1fb29c79b97e0d6ad3adc61883d8a4c6ee5bb", + "amount_msat": 2500000, + "amount_sent_msat": 2500000, + "payment_preimage": "23f75fbeb05d9a7940cb16cbf1844bb1d03046d094da131847cf9742b64a7a3d", + "status": "complete" + }, + "ebc13b1be16346e8e08571cbde85f5eb604cd76233181b5edbd559e3f35858ab": { + "destination": "0305657478be7bc7c3fb679bf831df1e07dd04dbfeb6d71b2b86fefbdf012bab8e", + "payment_hash": "c8ad412c5f71547d0d9f62a4693c3e1a2889093e2bac06f1db696409d4122fb4", + "created_at": 1720044720.0844057, + "parts": 1, + "amount_msat": 2500000, + "amount_sent_msat": 2500000, + "payment_preimage": "a404ece612b6dd056f337ee8e30999044652e5a676aca5f31e5c1a00e470d9c3", "status": "complete" } } @@ -193,47 +211,47 @@ Often you will want your prisms to be paid out whenever you have an incoming pay ### Create a binding -`lightning-cli prism-bindingadd -k offer_id=c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d prism_id=f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d` +`lightning-cli prism-bindingadd -k offer_id=70761889e73c049ce243b3ac73e06533830e4cdf8dbc3a5717b05bab93c7af64 prism_id=a59afe3927e6cdce218fb82415574204df4f762bb9c2c535a420488b3fa5fbf5` The above command binds a prism (`prism_id`) to a bolt12 offer with the specified `offer_id`. ```json { "status": "must-create", - "timestamp": 1718764200, - "offer_id": "c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d", - "prism_id": "f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d", + "timestamp": 1720044718, + "offer_id": "70761889e73c049ce243b3ac73e06533830e4cdf8dbc3a5717b05bab93c7af64", + "prism_id": "a59afe3927e6cdce218fb82415574204df4f762bb9c2c535a420488b3fa5fbf5", "prism_binding_key": [ "prism", - "v2", + "v2.1", "bind", "bolt12", - "c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d" + "70761889e73c049ce243b3ac73e06533830e4cdf8dbc3a5717b05bab93c7af64" ], "prism_members": [ { - "member_id": "c0772494d0d83318cf47ea1dbabcf3e37df2218090f9f20585867f135c241279", - "description": "Guitarist", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtk39j62x7m9qvkfep23m6euet54xfyp5xsyye7lavp0jmug06zxy", - "split": 0.333333, + "member_id": "95256245897c5423f9c319afbcd224dba9902cb829991a2435e2902631810389", + "description": "Drummer", + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwtzkujnk4t5hteur6cn8aqyt3v38u300ldryz6z2fw7zwr4gjxcq", + "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 }, { - "member_id": "d624d9b334b06d84560f1095d153001cb8ae829a8270d6fe29fa6d715efd538d", - "description": "Drums", - "destination": "02e4cc35ff6e7d43edc71db8146ae558f5b00a6d1e783e9ab10ad63bd82975502c", - "split": 0.333333, + "member_id": "412c79d6feafdf907a348ddb15627ba057d2c3ac3615f8f41680acd176d8bc2d", + "description": "Guitarist", + "destination": "02dbfb1d0a6fbc717ae3f28e4dc185d812e399ee33055587eeb06469c94e4326e5", + "split": 1.0, "fees_incurred_by": "remote", - "payout_threshold_msat": 10000000 + "payout_threshold_msat": 0 }, { - "member_id": "3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b", + "member_id": "ebc13b1be16346e8e08571cbde85f5eb604cd76233181b5edbd559e3f35858ab", "description": "Tuba", - "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq0s2x4jx6v7jtwzu4zf3f3nst03z3wcnwdjamr7mlk8axt70hvkd6", - "split": 0.333333, + "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvzk2archeau0slmv7dlsvwlrcra6pxml6mdwxetsml0hhcp9w4cu", + "split": 1.0, "fees_incurred_by": "local", - "payout_threshold_msat": 5000000 + "payout_threshold_msat": 0 } ] } @@ -243,27 +261,27 @@ The above command binds a prism (`prism_id`) to a bolt12 offer with the specifie Want to see your bindings? Run `prism-bindinglist`. Add an `offer_id` to view a specific binding. -`lightning-cli -k prism-bindinglist -k offer_id=c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d` +`lightning-cli -k prism-bindinglist -k offer_id=dfa361b51238e8ffc4c5db74105d618090e1c7fd48442d3e735dcaaf35347b6f` ```json { "bolt12_prism_bindings": [ { - "offer_id": "c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d", - "prism_id": "f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d", - "timestamp": 1718764200, + "offer_id": "dfa361b51238e8ffc4c5db74105d618090e1c7fd48442d3e735dcaaf35347b6f", + "prism_id": "4cf1e1b3e7bea1d0b8f9612ed138f164a03abe4541b1e82c8cde16af050b4f53", + "timestamp": 1720042032, "member_outlays": [ { - "member_id": "c0772494d0d83318cf47ea1dbabcf3e37df2218090f9f20585867f135c241279", - "outlay_msat": 0 + "member_id": "547d51d513aec15dc2229047d6d912b63d39416e3682b6dee4d6ae686f88b9b4", + "outlay_msat": 50000000 }, { - "member_id": "d624d9b334b06d84560f1095d153001cb8ae829a8270d6fe29fa6d715efd538d", - "outlay_msat": 5333330 + "member_id": "1fdda73dbdd4d3dda4057cf302ec10dedfc55466163133fd236e313a60a52204", + "outlay_msat": 0 }, { - "member_id": "3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b", - "outlay_msat": -1866669 + "member_id": "22dad0bd9cfcf4adfa367d2627e80a7a92e531b60a3d7c006495258c57b9db5e", + "outlay_msat": 0 } ] } @@ -273,34 +291,32 @@ Want to see your bindings? Run `prism-bindinglist`. Add an `offer_id` to view a The `outlay_msat` property is how the prism plugin deals with failed payments and to account for payout fees. When a prism binding has an incoming payment, prism member outlays in the binding are increased according the prism policy and incoming amount. When `fees_incurred_by=remote` and a payment to a prism member succeeds, the outlay is decremented by the total amount of the payment including fees paid. When `fees_incurred_by=local`, fees are paid by the node operator hosting the prism. -Prism member payouts occur when outlays exceed the `payout_threshold_msat` in the respective prism policy. Until then, outlays accumulate and eventually get paid-out. - -If a payment to a prism member fails for whatever reason, the outlay remains unchanged and payout is deferred. +Prism member payouts occur when outlays exceed the `payout_threshold_msat` in the respective prism policy. Until then, outlays accumulate. Similarly, if a payout to a prism member fails for whatever reason, the outlay remains unchanged and payout is deferred. ### Set a Binding Member Outlay -Say you have outstanding outlays that aren't clearing for whatever reason (e.g., unreachable node in offer). If you know the individual, you can always remit the sats with another wallet. In those cases, you will want to first zeroize the outlays for that member in the binding: +Say you have outstanding outlays that aren't clearing for whatever reason (e.g., unreachable node in offer). If you know the individual, you can always remit the sats with another wallet. In those cases, you will want to first zeroize the outlays for that member in the binding using the `prism-setoutlay` method. -`lightning-cli prism-bindingmemberoutlayreset -k offer_id=c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d member_id=3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b new_outlay_msat="-2500000"` +`lightning-cli prism-setoutlay -k offer_id=dfa361b51238e8ffc4c5db74105d618090e1c7fd48442d3e735dcaaf35347b6f member_id=547d51d513aec15dc2229047d6d912b63d39416e3682b6dee4d6ae686f88b9b4 new_outlay_msat=0` ```json { "bolt12_prism_bindings": { - "offer_id": "c618514017a44b7bcce8edd842ad057bfde4fe0fdef0b00cec840c7264c8e08d", - "prism_id": "f0ab738d7a7dd92004e8c0f2bd9426d33b22288f2964c5634e019000cfd8353d", - "timestamp": 1718764200, + "offer_id": "dfa361b51238e8ffc4c5db74105d618090e1c7fd48442d3e735dcaaf35347b6f", + "prism_id": "4cf1e1b3e7bea1d0b8f9612ed138f164a03abe4541b1e82c8cde16af050b4f53", + "timestamp": 1720042032, "member_outlays": [ { - "member_id": "c0772494d0d83318cf47ea1dbabcf3e37df2218090f9f20585867f135c241279", - "outlay_msat": 1066666 + "member_id": "547d51d513aec15dc2229047d6d912b63d39416e3682b6dee4d6ae686f88b9b4", + "outlay_msat": 0 }, { - "member_id": "d624d9b334b06d84560f1095d153001cb8ae829a8270d6fe29fa6d715efd538d", - "outlay_msat": 6399996 + "member_id": "1fdda73dbdd4d3dda4057cf302ec10dedfc55466163133fd236e313a60a52204", + "outlay_msat": 0 }, { - "member_id": "3f921a0dc8b927d8389aed3536e2b4596c4bcfac752bc674ac1025523c25e42b", - "outlay_msat": -2500000 + "member_id": "22dad0bd9cfcf4adfa367d2627e80a7a92e531b60a3d7c006495258c57b9db5e", + "outlay_msat": 0 } ] } @@ -315,4 +331,4 @@ You can remove a binding by running `prism-bindingremove offer_id`. ## How to contribute -There is a copy of the [startup_regtest](https://github.com/ElementsProject/lightning/blob/master/contrib/startup_regtest.sh) script from the c-lightning repo [contrib dir](./contrib/) for local development. Consider joining our Telegram group at [roygbiv.guide/contact](https://www.roygbiv.guide/contact). \ No newline at end of file +There is a copy of the [startup_regtest](https://github.com/ElementsProject/lightning/blob/master/contrib/startup_regtest.sh) script from the c-lightning repo [contrib dir](./contrib/) for local development. Consider joining our Telegram group at [roygbiv.guide/contribute](https://www.roygbiv.guide/contribute). \ No newline at end of file