From 965bd4f818cb64a761edd228e3f783e9abf0fc07 Mon Sep 17 00:00:00 2001 From: Derek Smith Date: Thu, 16 May 2024 13:20:55 -0400 Subject: [PATCH] Update Documentation. --- README.md | 173 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 110 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 7d78ce0..f8ffc95 100644 --- a/README.md +++ b/README.md @@ -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` @@ -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" } } @@ -151,47 +190,47 @@ 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" } ] } @@ -199,24 +238,32 @@ Binds a prism to either a bolt12 offer such that the prism will be executed upon ### 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" } - } - ] + ] + } } ```