Skip to content

Commit

Permalink
Update Documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@farscapian
farscapian committed May 16, 2024
1 parent c877fe2 commit 965bd4f
Showing 1 changed file with 110 additions and 63 deletions.
173 changes: 110 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,56 +48,95 @@ The `prism_id` is optional. If left unspecified, a unique prism id will be assig

MEMBERS_JSON=
```json
[{"label" : "Lead-Singer", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtyh3ua3crhn6me89spfupgp40nxkdfkhp0j2zjk63qgsdxp230ss", "split": 1},{"label" : "Drummer", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqw2ugunkxkzckdwkme9wkzfmjf4f2hm3852906gwsk05lxm0s29fu", "split": 1},{"label" : "Guitarist", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvqlu8pa98q4wqrvdvyg0svtunw8pa5vj0j9r5mnpzcrjyx8tm7jw", "split": 1}]
[{"label" : "Carol", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtrvcsycd8dqycyzsqp3nf8kjtjw448ad2sxclmsqe4yv2ry885pw", "split": 1, "payout_threshold_msat": "500000"},{"label" : "Dave", "destination": "02ffefcc4240dd5f339e6e451f0eceadd7e1f2d3c3b74ae256f53b6ae8f575d91a", "split": 1, "payout_threshold_msat": "500000"},{"label" : "Erin", "destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq2a9lj8dwfgefqvnl7yc8jyhtcxxhzdzq5memcz7769ja3c0jzvys", "split": 1, "payout_threshold_msat": "500000"}]'
```

```bash
lightning-cli prism-create -k members="$MEMBERS_JSON"
```

### Delete a prism

Need to delete a prism from the database? Use `prism-delete prism_id`. Be sure to remove any bindings first (see below)!

### List prisms

Run the following command to view a prism policy. (Note that you can omit the `prism_id` and all prisms will be returned.)

`lightning-cli prism-list prism1`

```json
{
"prism_id": "prism1",
"timestamp": 1714759630,
"timestamp": 1715877268,
"outlay_factor": 0.8,
"prism_members": [
{
"member_id": "e2548e67-f0a6-4203-b43d-d0edc0c2964a",
"member_id": "1c00f7de-fd5e-4b21-a869-2a79226e8275",
"label": "Carol",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvdt6lccaa4fw3dgw4dczt8ae8v69999j0uyrrsfhepg7tqwg2k4z",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqvqmtjepktzl0sqz6fhadxphh7mmnrjxc6sjlf0schhjmm86yd57x",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
},
{
"member_id": "9a64efaa-3ac8-4b2d-af4b-36ab1846acdd",
"member_id": "841f869b-1a8b-4153-9a44-1fd50ce53989",
"label": "Dave",
"destination": "03e5700104d1b6e2602a2dfda5b497d9c6862597865d46e3ded8404bf4067250e2",
"destination": "023fe8d7f9fddf9568cc31c1b0cf339d965a522166f9d1e3185186023d311922cf",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
},
{
"member_id": "4faf43bc-5595-4239-90d1-576cbe1caf91",
"member_id": "28c5107d-e18b-4b99-8706-dac6ad8017cb",
"label": "Erin",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqdeza5wk7pdd674uv2nzcgprvlwxjtjxman4ezl6j3ghh0wq65u7v",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq0nqkyg3z3hh6mhse7naf8njpdyzuw0067zj35vcelp6u8r3zkc3j",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
}
]
}
```

Setting the `outlay_factor` to `0.8` means that total outlays will be only 80% of the incoming amount. This is an implicit "pay-to-self". This feature allows a Prism member to host a prism.

### Delete a prism

Need to delete a prism from the database? Use `prism-delete prism_id`. Be sure to remove any bindings first (see below)!

### List prisms

Run the following command to view a prism policy. (Note that you can add a `prism_id` and specific prism will be returned.)

`lightning-cli prism-list`

```json
{
"prisms": {
"prism_id": "prism1",
"timestamp": 1715879764,
"outlay_factor": 0.8,
"prism_members": [
{
"member_id": "088db12c-5bbc-4ecd-bd9f-66553f6dc277",
"label": "Carol",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtrvcsycd8dqycyzsqp3nf8kjtjw448ad2sxclmsqe4yv2ry885pw",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "500000"
},
{
"member_id": "1cfa8bf2-f251-4891-ae08-b812d214fa07",
"label": "Dave",
"destination": "02ffefcc4240dd5f339e6e451f0eceadd7e1f2d3c3b74ae256f53b6ae8f575d91a",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "500000"
},
{
"member_id": "fb639dd9-8d07-4ca9-9fbc-5ae08505627a",
"label": "Erin",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq2a9lj8dwfgefqvnl7yc8jyhtcxxhzdzq5memcz7769ja3c0jzvys",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "500000"
}
]
}
}
```

## Prism-Pay - Executes a Payout

`lighting-cli prism-pay -k prism_id=prism1 amount_msat=1000000`
Expand All @@ -109,34 +148,34 @@ When run, this RPC command will execute (i.e., pay-out) a prism. This is useful
```json
{
"prism_member_payouts": {
"2503e139-760c-48fc-90f0-66e88780ece4": {
"destination": "03ae4baabcf7e547ff58bad3813e31bca65499fa11016aa24c80d896a510727597",
"payment_hash": "055ac5c154baac2032c4c2474521c2c410eb9326cc5d0c8d4345bc33cddc3b09",
"created_at": 1714760131.4795787,
"088db12c-5bbc-4ecd-bd9f-66553f6dc277": {
"destination": "02c6cc409869da026082800319a4f692e4ead4fd6aa06c7f70066a46286439e817",
"payment_hash": "abb1fcaaaacd541969d1edaebd5f9f01c6da75f333daaab124a813c0c3be55fc",
"created_at": 1715879764.8129447,
"parts": 1,
"amount_msat": 3333333,
"amount_sent_msat": 3333333,
"payment_preimage": "c062d69c2ca7f3e1d57de969f992a20880f4a2d01408597dcc386c412bf14450",
"payment_preimage": "b4abf87c99cf6861161083fc35e7483b7d88a685394d8f70fb92324a4afc5fd7",
"status": "complete"
},
"03d6c054-2593-462d-9f68-4fd81bc0aa28": {
"destination": "036c6757c0e30eacd0c8188946b437f5adb5dac5afe1cc5b60b63a56e67be382c0",
"payment_hash": "ae92fe81c2c9d1801c0f27793e3227eeba78a3a11b09732adca0ce2600c7dace",
"created_at": 1714760132.606286,
"1cfa8bf2-f251-4891-ae08-b812d214fa07": {
"destination": "02ffefcc4240dd5f339e6e451f0eceadd7e1f2d3c3b74ae256f53b6ae8f575d91a",
"payment_hash": "ef6c217ce60c2ef048bc308060eb76a39d91c36f4ce36cf579669a056270fe33",
"created_at": 1715879765.7926252,
"parts": 1,
"amount_msat": 3333333,
"amount_sent_msat": 3333333,
"payment_preimage": "801c67c5c3d006b3ef94a2e40c77b4b9cb61432b1e60cb6754aaaf5e0d05dec2",
"payment_preimage": "0f95f40f4ff52ab9b4a22f75f8769e750ac231e142bf1597c449c635f3738610",
"status": "complete"
},
"091a8fe9-a8bc-48ae-8fba-7ac33ebd961b": {
"destination": "02872086d7d910374b7b55c203f37fa7137361dc78c2919ea7d2565779c583ded2",
"payment_hash": "97292fcf635405d33775d55e5362ba591a342b747102ab3dd0414164405be3df",
"created_at": 1714760133.739254,
"fb639dd9-8d07-4ca9-9fbc-5ae08505627a": {
"destination": "02ba5fc8ed7251948193ff8983c8975e0c6b89a205379de05ef68b2ec70f909848",
"payment_hash": "12f4cf34789dfb73d3162b3f204c97d7a28ee6d8c7ff5689db994ed67da4b207",
"created_at": 1715879766.762006,
"parts": 1,
"amount_msat": 3333333,
"amount_sent_msat": 3333333,
"payment_preimage": "99b6fb7097a391e2558afc5b8bee377578c92b2691d18ddebbd79b78afe438aa",
"payment_preimage": "9e82e3ff68a84d8937923028a76052898ec9366d9f08ae7ce0b5a26ac4d6a77f",
"status": "complete"
}
}
Expand All @@ -151,72 +190,80 @@ Often you will want your prisms to be paid out whenever you have an incoming pay

### Create a binding

`lightning-cli -k prism-bindingadd -k offer_id=64b2eaba3882444833eda9bab3535d836f1976753613729427c374bcbba04913 prism_id=prism1`
`lightning-cli -k prism-bindingadd -k offer_id=458f1a21f5d24158dd756c44735f11fe688d4d5d0d97fd8b33235b634a2ca52f prism_id=prism1`

Binds a prism to either a bolt12 offer such that the prism will be executed upon incoming payment.

```json
{
"status": "must-create",
"timestamp": 1714760131,
"bind_to": "ecbb23dd33aeea4ca3c9198bdf459b004b455f13bbe72554be15a5aab4100ce6",
"prism_id": "prism1",
"timestamp": 1715879765,
"bind_to": "2a5afc3132b75e6c30a3ad932507f83c27c57fa96e56a6ff856b67db9e12d9a9",
"prism_id": "prism3",
"prism_binding_key": [
"prism",
"v2",
"bind",
"bolt12",
"ecbb23dd33aeea4ca3c9198bdf459b004b455f13bbe72554be15a5aab4100ce6"
"2a5afc3132b75e6c30a3ad932507f83c27c57fa96e56a6ff856b67db9e12d9a9"
],
"prism_members": [
{
"member_id": "2503e139-760c-48fc-90f0-66e88780ece4",
"member_id": "064e2765-6773-4177-8c83-218e48fce2e4",
"label": "Carol",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqwhyh24u7lj50l6chtfcz033hjn9fx06zyqk4gjvsrvfdfgswf6ew",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pqtrvcsycd8dqycyzsqp3nf8kjtjw448ad2sxclmsqe4yv2ry885pw",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
},
{
"member_id": "03d6c054-2593-462d-9f68-4fd81bc0aa28",
"member_id": "180e2490-c389-4926-8325-819d00d497de",
"label": "Dave",
"destination": "036c6757c0e30eacd0c8188946b437f5adb5dac5afe1cc5b60b63a56e67be382c0",
"destination": "02ffefcc4240dd5f339e6e451f0eceadd7e1f2d3c3b74ae256f53b6ae8f575d91a",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
},
{
"member_id": "091a8fe9-a8bc-48ae-8fba-7ac33ebd961b",
"member_id": "ae1aecc2-ff10-487e-9221-271050ce4949",
"label": "Erin",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq2rjppkhmygrwjmm2hpq8uml5ufhxcwu0rpfr8486ft9w7w9s00dy",
"destination": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2qajx2enpw4k8g93pq2a9lj8dwfgefqvnl7yc8jyhtcxxhzdzq5memcz7769ja3c0jzvys",
"split": 1,
"fees_incurred_by": "remote",
"payout_threshold_msat": "0"
"payout_threshold_msat": "500000"
}
]
}
```

### List Prism Bindings

Want to see all your bindings? Run `prism-bindinglist`. Add an `offer_id` to view a specific binding.
Want to see your bindings? Run `prism-bindinglist`. Add an `offer_id` to view a specific binding.

`lightning-cli -k prism-bindinglist`
`lightning-cli -k prism-bindinglist 2a5afc3132b75e6c30a3ad932507f83c27c57fa96e56a6ff856b67db9e12d9a9`

```json
{
"bolt12_prism_bindings": [
{
"offer_id": "ecbb23dd33aeea4ca3c9198bdf459b004b455f13bbe72554be15a5aab4100ce6",
"prism_id": "prism1",
"timestamp": 1714760131,
"member_outlays": {
"2503e139-760c-48fc-90f0-66e88780ece4": "0msat",
"03d6c054-2593-462d-9f68-4fd81bc0aa28": "0msat",
"091a8fe9-a8bc-48ae-8fba-7ac33ebd961b": "0msat"
"bolt12_prism_bindings": {
"binding_id": "09793f96dc7e633423765f1ecd5f4e4acba10d193a56918a92f482eeef104cd7",
"offer_id": "2a5afc3132b75e6c30a3ad932507f83c27c57fa96e56a6ff856b67db9e12d9a9",
"prism_id": "prism3",
"timestamp": 1715879765,
"member_outlays": [
{
"member_id": "064e2765-6773-4177-8c83-218e48fce2e4",
"outlay_msat": "0"
},
{
"member_id": "180e2490-c389-4926-8325-819d00d497de",
"outlay_msat": "0"
},
{
"member_id": "ae1aecc2-ff10-487e-9221-271050ce4949",
"outlay_msat": "0"
}
}
]
]
}
}
```

Expand Down

0 comments on commit 965bd4f

Please sign in to comment.