decode: support decoding runes.

This is a bit weird since it lives in the offers plugin, but it works well. This should make runes much more approachable for people! Signed-off-by: Rusty Russell <[email protected]>
ElementsProject · Jul 16, 2022 · cb200ed · cb200ed
1 parent 77a79dd
commit cb200ed
Show file tree

Hide file tree

Showing 5 changed files with 355 additions and 10 deletions.
diff --git a/doc/lightning-commando-rune.7.md b/doc/lightning-commando-rune.7.md
@@ -120,6 +120,56 @@ time in seconds:
        "unique_id": "3"
     }
 
+You can also use lightning-decode(7) to examine runes you have been given:
+
+    $ .lightning-cli decode tU-RLjMiDpY2U0o3W1oFowar36RFGpWloPbW9-RuZdo9MyZpZD0wMjRiOWExZmE4ZTAwNmYxZTM5MzdmNjVmNjZjNDA4ZTZkYThlMWNhNzI4ZWE0MzIyMmE3MzgxZGYxY2M0NDk2MDUmbWV0aG9kPWxpc3RwZWVycyZwbnVtPTEmcG5hbWVpZF4wMjRiOWExZmE4ZTAwNmYxZTM5M3xwYXJyMF4wMjRiOWExZmE4ZTAwNmYxZTM5MyZ0aW1lPDE2NTY5MjA1MzgmcmF0ZT0y
+    {
+       "type": "rune",
+       "unique_id": "3",
+       "string": "b54f912e33220e9636534a375b5a05a306abdfa4451a95a5a0f6d6f7e46e65da:=3&id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605&method=listpeers&pnum=1&pnameid^024b9a1fa8e006f1e393|parr0^024b9a1fa8e006f1e393&time<1656920538&rate=2",
+       "restrictions": [
+          {
+             "alternatives": [
+                "id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605"
+             ],
+             "summary": "id (of commanding peer) equal to '024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605'"
+          },
+          {
+             "alternatives": [
+                "method=listpeers"
+             ],
+             "summary": "method (of command) equal to 'listpeers'"
+          },
+          {
+             "alternatives": [
+                "pnum=1"
+             ],
+             "summary": "pnum (number of command parameters) equal to 1"
+          },
+          {
+             "alternatives": [
+                "pnameid^024b9a1fa8e006f1e393",
+                "parr0^024b9a1fa8e006f1e393"
+             ],
+             "summary": "pnameid (object parameter 'id') starts with '024b9a1fa8e006f1e393' OR parr0 (array parameter #0) starts with '024b9a1fa8e006f1e393'"
+          },
+          {
+             "alternatives": [
+                "time<1656920538"
+             ],
+             "summary": "time (in seconds since 1970) less than 1656920538 (approximately 19 hours 18 minutes from now)"
+          },
+          {
+             "alternatives": [
+                "rate=2"
+             ],
+             "summary": "rate (max per minute) equal to 2"
+          }
+       ],
+       "valid": true
+    }
+
+
 SHARING RUNES
 -------------
 
@@ -157,11 +207,11 @@ excuses his previous adoption of the name "Eltoo".
 SEE ALSO
 --------
 
-lightning-commando(7)
+lightning-commando(7), lightning-decode(7)
 
 RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:3f154c7127bc015ee8ff775ae30964238c101788f6b64029aabf1d7bf7a6bb9b)
+[comment]: # ( SHA256STAMP:598337212d2e8a6833698e931f838d8cb424c353af4d7adf6891803ff0ee604b)
diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md
@@ -9,17 +9,21 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-The **decode** RPC command checks and parses a *bolt11* or *bolt12*
-string (optionally prefixed by `lightning:` or `LIGHTNING:`) as
-specified by the BOLT 11 and BOLT 12 specifications.  It may decode
-other formats in future.
+The **decode** RPC command checks and parses:
+
+- a *bolt11* or *bolt12* string (optionally prefixed by `lightning:`
+  or `LIGHTNING:`) as specified by the BOLT 11 and BOLT 12
+  specifications.
+- a *rune* as created by lightning-commando-rune(7).
+
+It may decode other formats in future.
 
 RETURN VALUE
 ------------
 
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
-- **type** (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice")
+- **type** (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice", "rune")
 - **valid** (boolean): if this is false, you *MUST* not use the result except for diagnostics!
 
 If **type** is "bolt12 offer", and **valid** is *true*:
@@ -159,6 +163,16 @@ If **type** is "bolt11 invoice", and **valid** is *true*:
     - **tag** (string): The bech32 letter which identifies this field (always 1 characters)
     - **data** (string): The bech32 data for this field
 
+If **type** is "rune":
+  - **string** (string): the string encoding of the rune
+  - **restrictions** (array of objects): restrictions built into the rune: all must pass:
+    - **alternatives** (array of strings): each way restriction can be met: any can pass:
+      - the alternative of form fieldname condition fieldname
+    - **summary** (string): human-readable summary of this restriction
+  - **unique_id** (string, optional): unique id (always a numeric id on runes we create)
+  - **version** (string, optional): rune version, not currently set on runes we create
+  - **valid** (boolean, optional) (always *true*)
+
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
@@ -169,7 +183,7 @@ Rusty Russell <<[email protected]>> is mainly responsible.
 SEE ALSO
 --------
 
-lightning-pay(7), lightning-offer(7), lightning-offerout(7), lightning-fetchinvoice(7), lightning-sendinvoice(7)
+lightning-pay(7), lightning-offer(7), lightning-offerout(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7)
 
 [BOLT \#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md).
 
@@ -181,4 +195,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:bc3778965137591623ce08ff51adf411bc42e6d1a4200692961b69962da39be7)
+[comment]: # ( SHA256STAMP:d1e1f044c2e67ec169728dbc551903c97f9a9daa1f42e9d2f1686fc692d25be8)
diff --git a/doc/schemas/decode.schema.json b/doc/schemas/decode.schema.json
@@ -12,7 +12,8 @@
         "bolt12 offer",
         "bolt12 invoice",
         "bolt12 invoice_request",
-        "bolt11 invoice"
+        "bolt11 invoice",
+        "rune"
       ],
       "description": "what kind of object it decoded to"
     },
@@ -909,6 +910,72 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "rune"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "string",
+          "restrictions"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "unique_id": {
+            "type": "string",
+            "description": "unique id (always a numeric id on runes we create)"
+          },
+          "version": {
+            "type": "string",
+            "description": "rune version, not currently set on runes we create"
+          },
+          "valid": {
+            "type": "boolean",
+            "enum": [
+              true
+            ]
+          },
+          "type": {},
+          "string": {
+            "type": "string",
+            "description": "the string encoding of the rune"
+          },
+          "restrictions": {
+            "type": "array",
+            "description": "restrictions built into the rune: all must pass",
+            "items": {
+              "type": "object",
+              "required": [
+                "alternatives",
+                "summary"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "alternatives": {
+                  "type": "array",
+                  "description": "each way restriction can be met: any can pass",
+                  "items": {
+                    "type": "string",
+                    "description": "the alternative of form fieldname condition fieldname"
+                  }
+                },
+                "summary": {
+                  "type": "string",
+                  "description": "human-readable summary of this restriction"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   ]
 }