Skip to content

Commit 4a85c53

Browse files
ShahanaFarooquiShahanaFarooqui
committed
doc: Add new createrune example
- Moved the `Usage` section further down in `createrune` and `commando-rune` for improved UX. - Added a new example for creating a rune with `read-only` restrictions, extending it to allow only payments of `less than 100,000 sats per day` using the `pay` or `xpay` methods. - Adjusted formatting by appending an extra space after the `dependentUpon` condition, fixing `[*start* [*end*]][*relist*]` to `[*start* [*end*]] [*relist*]`. - Relocated `Examples` from the expandable section to a standard heading, as examples are now already placed at the end of the page. Changelog-None.
1 parent 0c6aa38 commit 4a85c53

File tree

8 files changed

+835
-94
lines changed

8 files changed

+835
-94
lines changed

‎contrib/msggen/msggen/schema.json‎

Lines changed: 396 additions & 34 deletions
Large diffs are not rendered by default.

‎doc/schemas/lightning-commando-listrunes.json‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,127 @@
399399
}
400400
],
401401
"restrictions_as_english": "id equal to 0266e4598d1d3c415f572a8488830b60f7e744ed9235eb0b1ba93283b315c03518 AND method equal to listpeers AND pnum equal to 1 AND pnameid starts with 0266e4598d1d3c415f57 OR parr0 starts with 0266e4598d1d3c415f57"
402+
},
403+
{
404+
"rune": "iP1FQEsFmPsu-XW7w8uXIJaJb7jU9PqOfkmXlOyWMuA9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
405+
"unique_id": "5",
406+
"restrictions": [
407+
{
408+
"alternatives": [
409+
{
410+
"fieldname": "method",
411+
"value": "list",
412+
"condition": "^",
413+
"english": "method starts with list"
414+
},
415+
{
416+
"fieldname": "method",
417+
"value": "get",
418+
"condition": "^",
419+
"english": "method starts with get"
420+
},
421+
{
422+
"fieldname": "method",
423+
"value": "summary",
424+
"condition": "=",
425+
"english": "method equal to summary"
426+
},
427+
{
428+
"fieldname": "method",
429+
"value": "pay",
430+
"condition": "=",
431+
"english": "method equal to pay"
432+
},
433+
{
434+
"fieldname": "method",
435+
"value": "xpay",
436+
"condition": "=",
437+
"english": "method equal to xpay"
438+
}
439+
],
440+
"english": "method starts with list OR method starts with get OR method equal to summary OR method equal to pay OR method equal to xpay"
441+
},
442+
{
443+
"alternatives": [
444+
{
445+
"fieldname": "method",
446+
"value": "listdatastore",
447+
"condition": "/",
448+
"english": "method unequal to listdatastore"
449+
}
450+
],
451+
"english": "method unequal to listdatastore"
452+
},
453+
{
454+
"alternatives": [
455+
{
456+
"fieldname": "method",
457+
"value": "pay",
458+
"condition": "/",
459+
"english": "method unequal to pay"
460+
},
461+
{
462+
"fieldname": "per",
463+
"value": "1day",
464+
"condition": "=",
465+
"english": "per equal to 1day"
466+
}
467+
],
468+
"english": "method unequal to pay OR per equal to 1day"
469+
},
470+
{
471+
"alternatives": [
472+
{
473+
"fieldname": "method",
474+
"value": "pay",
475+
"condition": "/",
476+
"english": "method unequal to pay"
477+
},
478+
{
479+
"fieldname": "pnameamount_msat",
480+
"value": "100000001",
481+
"condition": "<",
482+
"english": "pnameamount_msat < 100000001"
483+
}
484+
],
485+
"english": "method unequal to pay OR pnameamount_msat < 100000001"
486+
},
487+
{
488+
"alternatives": [
489+
{
490+
"fieldname": "method",
491+
"value": "xpay",
492+
"condition": "/",
493+
"english": "method unequal to xpay"
494+
},
495+
{
496+
"fieldname": "per",
497+
"value": "1day",
498+
"condition": "=",
499+
"english": "per equal to 1day"
500+
}
501+
],
502+
"english": "method unequal to xpay OR per equal to 1day"
503+
},
504+
{
505+
"alternatives": [
506+
{
507+
"fieldname": "method",
508+
"value": "xpay",
509+
"condition": "/",
510+
"english": "method unequal to xpay"
511+
},
512+
{
513+
"fieldname": "pnameamount_msat",
514+
"value": "100000001",
515+
"condition": "<",
516+
"english": "pnameamount_msat < 100000001"
517+
}
518+
],
519+
"english": "method unequal to xpay OR pnameamount_msat < 100000001"
520+
}
521+
],
522+
"restrictions_as_english": "method starts with list OR method starts with get OR method equal to summary OR method equal to pay OR method equal to xpay AND method unequal to listdatastore AND method unequal to pay OR per equal to 1day AND method unequal to pay OR pnameamount_msat < 100000001 AND method unequal to xpay OR per equal to 1day AND method unequal to xpay OR pnameamount_msat < 100000001"
402523
}
403524
]
404525
}

‎doc/schemas/lightning-commando-rune.json‎

Lines changed: 77 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,25 @@
105105
"* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.",
106106
"Every other operator except `#` fails if *name* does not exist!"
107107
],
108+
"sharing_runes": [
109+
"Because anyone can add a restriction to a rune, you can always turn a normal rune into a read-only rune, or restrict access for 30 minutes from the time you give it to someone. Adding restrictions before sharing runes is best practice.",
110+
"",
111+
"If a rune has a ratelimit, any derived rune will have the same id, and thus will compete for that ratelimit. You might want to consider adding a tighter ratelimit to a rune before sharing it, so you will keep the remainder. For example, if you rune has a limit of 60 times per minute, adding a limit of 5 times per minute and handing that rune out means you can still use your original rune 55 times per minute."
112+
],
113+
"author": [
114+
"Rusty Russell <<[email protected]>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
115+
"",
116+
"Christian Decker came up with the name \"commando\", which almost excuses his previous adoption of the name \"Eltoo\"."
117+
],
118+
"see_also": [
119+
"lightning-commando(7)",
120+
"lightning-decode(7)"
121+
],
122+
"resources": [
123+
"Main web site: <https://github.com/ElementsProject/lightning>"
124+
],
108125
"usage": [
109-
"You can use lightning-decode(7) to examine runes you have been given:",
126+
"- You can use lightning-decode(7) to examine runes you have been given:",
110127
"",
111128
"```shell",
112129
"lightning-cli decode tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y",
@@ -155,24 +172,13 @@
155172
" ],",
156173
" \"valid\": true",
157174
"}",
158-
"```"
159-
],
160-
"sharing_runes": [
161-
"Because anyone can add a restriction to a rune, you can always turn a normal rune into a read-only rune, or restrict access for 30 minutes from the time you give it to someone. Adding restrictions before sharing runes is best practice.",
175+
"```",
162176
"",
163-
"If a rune has a ratelimit, any derived rune will have the same id, and thus will compete for that ratelimit. You might want to consider adding a tighter ratelimit to a rune before sharing it, so you will keep the remainder. For example, if you rune has a limit of 60 times per minute, adding a limit of 5 times per minute and handing that rune out means you can still use your original rune 55 times per minute."
164-
],
165-
"author": [
166-
"Rusty Russell <<[email protected]>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
177+
"- You can use lightning-checkrune(7) to verify whether a rune is valid for a specific method and its parameters:",
167178
"",
168-
"Christian Decker came up with the name \"commando\", which almost excuses his previous adoption of the name \"Eltoo\"."
169-
],
170-
"see_also": [
171-
"lightning-commando(7)",
172-
"lightning-decode(7)"
173-
],
174-
"resources": [
175-
"Main web site: <https://github.com/ElementsProject/lightning>"
179+
"```shell",
180+
"lightning-cli checkrune -k 'rune'=tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y 'method'='invoice' 'params'='{\"amount_msat\": 100000001, \"label\": \"invoicelabel\"', \"description\": \"Checking rune validity\"}'",
181+
"```"
176182
],
177183
"examples": [
178184
{
@@ -366,6 +372,60 @@
366372
"rune": "7nvN7uG2CyTOXe3dYQL38YVdGsnD6d5VNNyeHVl6inc9NCZpZD0wMjY2ZTQ1OThkMWQzYzQxNWY1NzJhODQ4ODgzMGI2MGY3ZTc0NGVkOTIzNWViMGIxYmE5MzI4M2IzMTVjMDM1MTgmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1N3xwYXJyMF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZ0aW1lPCIkKCgkKGRhdGUgKyVzKSArIDI0KjYwKjYwKSkifHJhdGU9Mg==",
367373
"unique_id": "4"
368374
}
375+
},
376+
{
377+
"description": [
378+
"Now, let us create a rune with `read-only` restrictions, extended to only allow sending payments of `less than 100,000 sats per day` using either the `pay` or `xpay` method. Ideally, the condition would look something like:",
379+
"",
380+
"`[[\"method^list or method^get or ((method=pay or method=xpay) and per=1day and pnameamount\\_msat<100000001)\"],[\"method/listdatastore\"]]`.",
381+
"",
382+
"However, since brackets and AND conditions within OR are currently not supported for rune creation, we can restructure the conditions as follows:",
383+
"",
384+
"- method^list|method^get|method=summary|method=pay|method=xpay",
385+
"- method/listdatastore",
386+
"- method/pay|per=1day",
387+
"- method/pay|pnameamount\\_msat<100000001",
388+
"- method/xpay|per=1day",
389+
"- method/xpay|pnameamount\\_msat<100000001"
390+
],
391+
"request": {
392+
"id": "example:commando-rune#9",
393+
"method": "commando-rune",
394+
"params": {
395+
"restrictions": [
396+
[
397+
"method^list",
398+
"method^get",
399+
"method=summary",
400+
"method=pay",
401+
"method=xpay"
402+
],
403+
[
404+
"method/listdatastore"
405+
],
406+
[
407+
"method/pay",
408+
"per=1day"
409+
],
410+
[
411+
"method/pay",
412+
"pnameamount_msat<100000001"
413+
],
414+
[
415+
"method/xpay",
416+
"per=1day"
417+
],
418+
[
419+
"method/xpay",
420+
"pnameamount_msat<100000001"
421+
]
422+
]
423+
}
424+
},
425+
"response": {
426+
"rune": "QqgK4ZNJOwMjhUAQhHcnkTBXRoLghhPcJVR_Zew97ug9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
427+
"unique_id": "5"
428+
}
369429
}
370430
]
371431
}

‎doc/schemas/lightning-createrune.json‎

Lines changed: 77 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,25 @@
108108
"* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.",
109109
"Every other operator except `#` fails if *name* does not exist!"
110110
],
111+
"sharing_runes": [
112+
"Because anyone can add a restriction to a rune, you can always turn a normal rune into a read-only rune, or restrict access for 30 minutes from the time you give it to someone. Adding restrictions before sharing runes is best practice.",
113+
"",
114+
"If a rune has a ratelimit, any derived rune will have the same id, and thus will compete for that ratelimit. You might want to consider adding a tighter ratelimit to a rune before sharing it, so you will keep the remainder. For example, if your rune has a limit of 60 times per minute, adding a limit of 5 times per minute and handing that rune out means you can still use your original rune 55 times per minute."
115+
],
116+
"author": [
117+
"Rusty Russell <<[email protected]>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
118+
"",
119+
"Shahana Farooqui <<[email protected]>> is mainly responsible for migrating commando-rune to createrune."
120+
],
121+
"see_also": [
122+
"lightning-commando-rune(7)",
123+
"lightning-checkrune(7)"
124+
],
125+
"resources": [
126+
"Main web site: <https://github.com/ElementsProject/lightning>"
127+
],
111128
"usage": [
112-
"You can use lightning-decode(7) to examine runes you have been given:",
129+
"- You can use lightning-decode(7) to examine runes you have been given:",
113130
"",
114131
"```shell",
115132
"lightning-cli decode tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y",
@@ -158,24 +175,13 @@
158175
" ],",
159176
" \"valid\": true",
160177
"}",
161-
"```"
162-
],
163-
"sharing_runes": [
164-
"Because anyone can add a restriction to a rune, you can always turn a normal rune into a read-only rune, or restrict access for 30 minutes from the time you give it to someone. Adding restrictions before sharing runes is best practice.",
178+
"```",
165179
"",
166-
"If a rune has a ratelimit, any derived rune will have the same id, and thus will compete for that ratelimit. You might want to consider adding a tighter ratelimit to a rune before sharing it, so you will keep the remainder. For example, if you rune has a limit of 60 times per minute, adding a limit of 5 times per minute and handing that rune out means you can still use your original rune 55 times per minute."
167-
],
168-
"author": [
169-
"Rusty Russell <<[email protected]>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
180+
"- You can use lightning-checkrune(7) to verify whether a rune is valid for a specific method and its parameters:",
170181
"",
171-
"Shahana Farooqui <<[email protected]>> is mainly responsible for migrating commando-rune to createrune."
172-
],
173-
"see_also": [
174-
"lightning-commando-rune(7)",
175-
"lightning-checkrune(7)"
176-
],
177-
"resources": [
178-
"Main web site: <https://github.com/ElementsProject/lightning>"
182+
"```shell",
183+
"lightning-cli checkrune -k 'rune'=tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y 'method'='invoice' 'params'='{\"amount_msat\": 100000001, \"label\": \"invoicelabel\"', \"description\": \"Checking rune validity\"}'",
184+
"```"
179185
],
180186
"examples": [
181187
{
@@ -369,6 +375,60 @@
369375
"rune": "GJb2PC-4jYslzIVz6-425bOtpkz_A_zaEhekPlrXdj09NCZpZD0wMjY2ZTQ1OThkMWQzYzQxNWY1NzJhODQ4ODgzMGI2MGY3ZTc0NGVkOTIzNWViMGIxYmE5MzI4M2IzMTVjMDM1MTgmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1N3xwYXJyMF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZ0aW1lPCIkKCgkKGRhdGUgKyVzKSArIDI0KjYwKjYwKSkifHJhdGU9Mg==",
370376
"unique_id": "4"
371377
}
378+
},
379+
{
380+
"description": [
381+
"Now, let us create a rune with `read-only` restrictions, extended to only allow sending payments of `less than 100,000 sats per day` using either the `pay` or `xpay` method. Ideally, the condition would look something like:",
382+
"",
383+
"`[[\"method^list or method^get or ((method=pay or method=xpay) and per=1day and pnameamount\\_msat<100000001)\"],[\"method/listdatastore\"]]`.",
384+
"",
385+
"However, since brackets and AND conditions within OR are currently not supported for rune creation, we can restructure the conditions as follows:",
386+
"",
387+
"- method^list|method^get|method=summary|method=pay|method=xpay",
388+
"- method/listdatastore",
389+
"- method/pay|per=1day",
390+
"- method/pay|pnameamount\\_msat<100000001",
391+
"- method/xpay|per=1day",
392+
"- method/xpay|pnameamount\\_msat<100000001"
393+
],
394+
"request": {
395+
"id": "example:createrune#9",
396+
"method": "createrune",
397+
"params": {
398+
"restrictions": [
399+
[
400+
"method^list",
401+
"method^get",
402+
"method=summary",
403+
"method=pay",
404+
"method=xpay"
405+
],
406+
[
407+
"method/listdatastore"
408+
],
409+
[
410+
"method/pay",
411+
"per=1day"
412+
],
413+
[
414+
"method/pay",
415+
"pnameamount_msat<100000001"
416+
],
417+
[
418+
"method/xpay",
419+
"per=1day"
420+
],
421+
[
422+
"method/xpay",
423+
"pnameamount_msat<100000001"
424+
]
425+
]
426+
}
427+
},
428+
"response": {
429+
"rune": "iP1FQEsFmPsu-XW7w8uXIJaJb7jU9PqOfkmXlOyWMuA9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
430+
"unique_id": "5"
431+
}
372432
}
373433
]
374434
}

0 commit comments

Comments
 (0)