Skip to content

Commit

Permalink
Update readme with latest updates.
Browse files Browse the repository at this point in the history
  • Loading branch information
@farscapian
farscapian committed Jul 3, 2024
1 parent 9ca2d8c commit 4569370
Showing 1 changed file with 106 additions and 90 deletions.
196 changes: 106 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
]
}
Expand All @@ -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
}
]
}
Expand All @@ -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.

Expand All @@ -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"
}
}
Expand All @@ -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
}
]
}
Expand All @@ -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
}
]
}
Expand All @@ -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
}
]
}
Expand All @@ -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).
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).

0 comments on commit 4569370

Please sign in to comment.