Skip to content

doc: Add new createrune example #8033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 4, 2025
Merged

doc: Add new createrune example #8033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
430 changes: 396 additions & 34 deletions contrib/msggen/msggen/schema.json
View file
Open in desktop

Large diffs are not rendered by default.

121 changes: 121 additions & 0 deletions doc/schemas/lightning-commando-listrunes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,127 @@
}
],
"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"
},
{
"rune": "iP1FQEsFmPsu-XW7w8uXIJaJb7jU9PqOfkmXlOyWMuA9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
"unique_id": "5",
"restrictions": [
{
"alternatives": [
{
"fieldname": "method",
"value": "list",
"condition": "^",
"english": "method starts with list"
},
{
"fieldname": "method",
"value": "get",
"condition": "^",
"english": "method starts with get"
},
{
"fieldname": "method",
"value": "summary",
"condition": "=",
"english": "method equal to summary"
},
{
"fieldname": "method",
"value": "pay",
"condition": "=",
"english": "method equal to pay"
},
{
"fieldname": "method",
"value": "xpay",
"condition": "=",
"english": "method equal to xpay"
}
],
"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"
},
{
"alternatives": [
{
"fieldname": "method",
"value": "listdatastore",
"condition": "/",
"english": "method unequal to listdatastore"
}
],
"english": "method unequal to listdatastore"
},
{
"alternatives": [
{
"fieldname": "method",
"value": "pay",
"condition": "/",
"english": "method unequal to pay"
},
{
"fieldname": "per",
"value": "1day",
"condition": "=",
"english": "per equal to 1day"
}
],
"english": "method unequal to pay OR per equal to 1day"
},
{
"alternatives": [
{
"fieldname": "method",
"value": "pay",
"condition": "/",
"english": "method unequal to pay"
},
{
"fieldname": "pnameamount_msat",
"value": "100000001",
"condition": "<",
"english": "pnameamount_msat < 100000001"
}
],
"english": "method unequal to pay OR pnameamount_msat < 100000001"
},
{
"alternatives": [
{
"fieldname": "method",
"value": "xpay",
"condition": "/",
"english": "method unequal to xpay"
},
{
"fieldname": "per",
"value": "1day",
"condition": "=",
"english": "per equal to 1day"
}
],
"english": "method unequal to xpay OR per equal to 1day"
},
{
"alternatives": [
{
"fieldname": "method",
"value": "xpay",
"condition": "/",
"english": "method unequal to xpay"
},
{
"fieldname": "pnameamount_msat",
"value": "100000001",
"condition": "<",
"english": "pnameamount_msat < 100000001"
}
],
"english": "method unequal to xpay OR pnameamount_msat < 100000001"
}
],
"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"
}
]
}
Expand Down
94 changes: 77 additions & 17 deletions doc/schemas/lightning-commando-rune.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,25 @@
"* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.",
"Every other operator except `#` fails if *name* does not exist!"
],
"sharing_runes": [
"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.",
"",
"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."
],
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
"",
"Christian Decker came up with the name \"commando\", which almost excuses his previous adoption of the name \"Eltoo\"."
],
"see_also": [
"lightning-commando(7)",
"lightning-decode(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
],
"usage": [
"You can use lightning-decode(7) to examine runes you have been given:",
"- You can use lightning-decode(7) to examine runes you have been given:",
"",
"```shell",
"lightning-cli decode tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y",
Expand Down Expand Up @@ -155,24 +172,13 @@
" ],",
" \"valid\": true",
"}",
"```"
],
"sharing_runes": [
"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.",
"```",
"",
"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."
],
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
"- You can use lightning-checkrune(7) to verify whether a rune is valid for a specific method and its parameters:",
"",
"Christian Decker came up with the name \"commando\", which almost excuses his previous adoption of the name \"Eltoo\"."
],
"see_also": [
"lightning-commando(7)",
"lightning-decode(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
"```shell",
"lightning-cli checkrune -k 'rune'=tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y 'method'='invoice' 'params'='{\"amount_msat\": 100000001, \"label\": \"invoicelabel\"', \"description\": \"Checking rune validity\"}'",
"```"
],
"examples": [
{
Expand Down Expand Up @@ -366,6 +372,60 @@
"rune": "7nvN7uG2CyTOXe3dYQL38YVdGsnD6d5VNNyeHVl6inc9NCZpZD0wMjY2ZTQ1OThkMWQzYzQxNWY1NzJhODQ4ODgzMGI2MGY3ZTc0NGVkOTIzNWViMGIxYmE5MzI4M2IzMTVjMDM1MTgmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1N3xwYXJyMF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZ0aW1lPCIkKCgkKGRhdGUgKyVzKSArIDI0KjYwKjYwKSkifHJhdGU9Mg==",
"unique_id": "4"
}
},
{
"description": [
"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:",
"",
"`[[\"method^list or method^get or ((method=pay or method=xpay) and per=1day and pnameamount\\_msat<100000001)\"],[\"method/listdatastore\"]]`.",
"",
"However, since brackets and AND conditions within OR are currently not supported for rune creation, we can restructure the conditions as follows:",
"",
"- method^list|method^get|method=summary|method=pay|method=xpay",
"- method/listdatastore",
"- method/pay|per=1day",
"- method/pay|pnameamount\\_msat<100000001",
"- method/xpay|per=1day",
"- method/xpay|pnameamount\\_msat<100000001"
],
"request": {
"id": "example:commando-rune#9",
"method": "commando-rune",
"params": {
"restrictions": [
[
"method^list",
"method^get",
"method=summary",
"method=pay",
"method=xpay"
],
[
"method/listdatastore"
],
[
"method/pay",
"per=1day"
],
[
"method/pay",
"pnameamount_msat<100000001"
],
[
"method/xpay",
"per=1day"
],
[
"method/xpay",
"pnameamount_msat<100000001"
]
]
}
},
"response": {
"rune": "QqgK4ZNJOwMjhUAQhHcnkTBXRoLghhPcJVR_Zew97ug9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
"unique_id": "5"
}
}
]
}
94 changes: 77 additions & 17 deletions doc/schemas/lightning-createrune.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,25 @@
"* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.",
"Every other operator except `#` fails if *name* does not exist!"
],
"sharing_runes": [
"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.",
"",
"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."
],
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
"",
"Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible for migrating commando-rune to createrune."
],
"see_also": [
"lightning-commando-rune(7)",
"lightning-checkrune(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
],
"usage": [
"You can use lightning-decode(7) to examine runes you have been given:",
"- You can use lightning-decode(7) to examine runes you have been given:",
"",
"```shell",
"lightning-cli decode tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y",
Expand Down Expand Up @@ -158,24 +175,13 @@
" ],",
" \"valid\": true",
"}",
"```"
],
"sharing_runes": [
"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.",
"```",
"",
"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."
],
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
"- You can use lightning-checkrune(7) to verify whether a rune is valid for a specific method and its parameters:",
"",
"Shahana Farooqui <<sfarooqui@blockstream.com>> is mainly responsible for migrating commando-rune to createrune."
],
"see_also": [
"lightning-commando-rune(7)",
"lightning-checkrune(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
"```shell",
"lightning-cli checkrune -k 'rune'=tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y 'method'='invoice' 'params'='{\"amount_msat\": 100000001, \"label\": \"invoicelabel\"', \"description\": \"Checking rune validity\"}'",
"```"
],
"examples": [
{
Expand Down Expand Up @@ -369,6 +375,60 @@
"rune": "GJb2PC-4jYslzIVz6-425bOtpkz_A_zaEhekPlrXdj09NCZpZD0wMjY2ZTQ1OThkMWQzYzQxNWY1NzJhODQ4ODgzMGI2MGY3ZTc0NGVkOTIzNWViMGIxYmE5MzI4M2IzMTVjMDM1MTgmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1N3xwYXJyMF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZ0aW1lPCIkKCgkKGRhdGUgKyVzKSArIDI0KjYwKjYwKSkifHJhdGU9Mg==",
"unique_id": "4"
}
},
{
"description": [
"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:",
"",
"`[[\"method^list or method^get or ((method=pay or method=xpay) and per=1day and pnameamount\\_msat<100000001)\"],[\"method/listdatastore\"]]`.",
"",
"However, since brackets and AND conditions within OR are currently not supported for rune creation, we can restructure the conditions as follows:",
"",
"- method^list|method^get|method=summary|method=pay|method=xpay",
"- method/listdatastore",
"- method/pay|per=1day",
"- method/pay|pnameamount\\_msat<100000001",
"- method/xpay|per=1day",
"- method/xpay|pnameamount\\_msat<100000001"
],
"request": {
"id": "example:createrune#9",
"method": "createrune",
"params": {
"restrictions": [
[
"method^list",
"method^get",
"method=summary",
"method=pay",
"method=xpay"
],
[
"method/listdatastore"
],
[
"method/pay",
"per=1day"
],
[
"method/pay",
"pnameamount_msat<100000001"
],
[
"method/xpay",
"per=1day"
],
[
"method/xpay",
"pnameamount_msat<100000001"
]
]
}
},
"response": {
"rune": "iP1FQEsFmPsu-XW7w8uXIJaJb7jU9PqOfkmXlOyWMuA9NSZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5fG1ldGhvZD1wYXl8bWV0aG9kPXhwYXkmbWV0aG9kL2xpc3RkYXRhc3RvcmUmbWV0aG9kL3BheXxwZXI9MWRheSZtZXRob2QvcGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAxJm1ldGhvZC94cGF5fHBlcj0xZGF5Jm1ldGhvZC94cGF5fHBuYW1lYW1vdW50X21zYXQ8MTAwMDAwMDAx",
"unique_id": "5"
}
}
]
}
Loading