Add spec for binary token serialization (#199)

* base spec binary token encoding * version * separated prefixes and encoding * token version * small typos * added tests * Update 00.md * Update 00.md --------- Co-authored-by: Pavol Rusnak <[email protected]> Co-authored-by: callebtc <[email protected]>
cashubtc · Dec 12, 2024 · 77924b6 · 77924b6
1 parent fb3187f
commit 77924b6
Show file tree

Hide file tree

Showing 2 changed files with 80 additions and 0 deletions.
diff --git a/00.md b/00.md
@@ -306,6 +306,18 @@ We serialize this JSON using CBOR which can be seen [here](https://cbor.nemo157.
 cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW-07KaZCvuWHk3WrnnpiDhHki6SCQh88-iYWlIAK0mjE0fWCZhcIKjYWECYXN4QDEzMjNkM2Q0NzA3YTU4YWQyZTIzYWRhNGU5ZjFmNDlmNWE1YjRhYzdiNzA4ZWIwZDYxZjczOGY0ODMwN2U4ZWVhY1ghAjRWqhENhLSsdHrr2Cw7AFrKUL9Ffr1XN6RBT6w659lNo2FhAWFzeEA1NmJjYmNiYjdjYzY0MDZiM2ZhNWQ1N2QyMTc0ZjRlZmY4YjQ0MDJiMTc2OTI2ZDNhNTdkM2MzZGNiYjU5ZDU3YWNYIQJzEpxXGeWZN5qXSmJjY8MzxWyvwObQGr5G1YCCgHicY2FtdWh0dHA6Ly9sb2NhbGhvc3Q6MzMzOGF1Y3NhdA
 ```
 
+#### Binary Token
+
+V3 and V4 Token can be transmitted in a binary format when applicable (for example when transmitting via NFC).
+For this the serialised token is prepended with a prefix and a version byte.
+
+```
+utf8("craw") || utf8(<token_version>) || <serialised_token>
+```
+
+- Token V3 Version: `utf8("craw") || utf8("A") || cbor(token_object)`
+- Token V4 Version: `utf8("craw") || utf8("B") || cbor(token_object)`
+
 [00]: 00.md
 [01]: 01.md
 [02]: 02.md

diff --git a/tests/00-tests.md b/tests/00-tests.md
@@ -191,4 +191,72 @@ Serialized:
 cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW-07KaZCvuWHk3WrnnpiDhHki6SCQh88-iYWlIAK0mjE0fWCZhcIKjYWECYXN4QDEzMjNkM2Q0NzA3YTU4YWQyZTIzYWRhNGU5ZjFmNDlmNWE1YjRhYzdiNzA4ZWIwZDYxZjczOGY0ODMwN2U4ZWVhY1ghAjRWqhENhLSsdHrr2Cw7AFrKUL9Ffr1XN6RBT6w659lNo2FhAWFzeEA1NmJjYmNiYjdjYzY0MDZiM2ZhNWQ1N2QyMTc0ZjRlZmY4YjQ0MDJiMTc2OTI2ZDNhNTdkM2MzZGNiYjU5ZDU3YWNYIQJzEpxXGeWZN5qXSmJjY8MzxWyvwObQGr5G1YCCgHicY2FtdWh0dHA6Ly9sb2NhbGhvc3Q6MzMzOGF1Y3NhdA
 ```
 
+## Raw Token Serialization
+
+### TokenV3
+
+What follows is a TokenV3 Token serialized in its raw binary form. `h''` values are bytes in hex notation.
+
+Token:
+
+```json
+{
+  "token": [
+    {
+      "mint": "https://8333.space:3338",
+      "proofs": [
+        {
+          "amount": 2,
+          "id": "009a1f293253e41e",
+          "secret": "407915bc212be61a77e3e6d2aeb4c727980bda51cd06a6afc29e2861768a7837",
+          "C": "02bc9097997d81afb2cc7346b5e4345a9346bd2a506eb7958598a72f0cf85163ea"
+        },
+        {
+          "amount": 8,
+          "id": "009a1f293253e41e",
+          "secret": "fe15109314e61d7756b0f8ee0f23a624acaa3f4e042f61433c728c7057b931be",
+          "C": "029e8e5050b890a7d6c0968db16bc1d5d5fa040ea1de284f6ec69d61299f671059"
+        }
+      ]
+    }
+  ],
+  "unit": "sat",
+  "memo": "Thank you."
+}
+```
+
+Serialized to raw binary:
+
+`h'6372617741a365746f6b656e81a2646d696e747768747470733a2f2f383333332e73706163653a333333386670726f6f667382a466616d6f756e740262696470303039613166323933323533653431656673656372657478403430373931356263323132626536316137376533653664326165623463373237393830626461353163643036613661666332396532383631373638613738333761437842303262633930393739393764383161666232636337333436623565343334356139333436626432613530366562373935383539386137326630636638353136336561a466616d6f756e74086269647030303961316632393332353365343165667365637265747840666531353130393331346536316437373536623066386565306632336136323461636161336634653034326636313433336337323863373035376239333162656143784230323965386535303530623839306137643663303936386462313662633164356435666130343065613164653238346636656336396436313239396636373130353964756e697463736174646d656d6f6a5468616e6b20796f752e'`
+
+### TokenV4
+
+What follows is a TokenV4 Token serialized in its raw binary form. `h''` values are bytes in hex notation.
+
+Token:
+
+```json
+{
+    "t": [
+        {
+            "i": h'00ad268c4d1f5826',
+            "p": [
+                {
+                    "a": 1,
+                    "s": "9a6dbb847bd232ba76db0df197216b29d3b8cc14553cd27827fc1cc942fedb4e",
+                    "c": h'038618543ffb6b8695df4ad4babcde92a34a96bdcd97dcee0d7ccf98d472126792',
+                },
+            ],
+        },
+    ],
+    "d": "Thank you",
+    "m": "http://localhost:3338",
+    "u": "sat",
+}
+```
+
+Serialized to raw binary:
+
+`h'6372617742a4617481a261694800ad268c4d1f5826617081a3616101617378403961366462623834376264323332626137366462306466313937323136623239643362386363313435353363643237383237666331636339343266656462346561635821038618543ffb6b8695df4ad4babcde92a34a96bdcd97dcee0d7ccf98d4721267926164695468616e6b20796f75616d75687474703a2f2f6c6f63616c686f73743a33333338617563736174'`
+
 [NUT-10]: ../10.md