docs: use ABNF to describe SignedPacket and relay payload

pubky · May 30, 2024 · f2ce322 · f2ce322
1 parent 8135948
commit f2ce322
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 13 deletions.
diff --git a/design/base.md b/design/base.md
@@ -20,12 +20,14 @@ Implementations should be able to parse both `pk:<zbase32 encoded key>`, standal
 
 The canonical serialization then for Signed Pkarr packet is as follows:
 
-| part       |  length  |         Note                              |
-| ---------- | -------- | ----------------------------------------- | 
-| public_key | 32       | ed25519 public key                        |
-| signature  | 64       | ed25519 signature over encoded dns packet |
-| timestamp  | 8        | big-endian timestamp in microseconds      |
-| DNS packet | variable | compressed encoded DNS answer packet      |
+```abnf
+SignedPacket = public-key signature timestamp dns-packet
+
+public-key  = 32 OCTET ; ed25519 public key
+signature   = 64 OCTET ; ed25519 signature over encoded DNS packet
+timestamp   =  8 OCTET ; big-endian UNIX timestamp in microseconds
+dns-packet  =  * OCTET ; compressed encoded DNS answer packet, less than 1000 bytes
+```
 
 ### DNS packet
 

diff --git a/design/relays.md b/design/relays.md
@@ -15,7 +15,7 @@ PUT /:z-base32-encoded-key HTTP/2
 Access-Control-Allow-Origin: *
 Access-Control-Allow-Methods: GET, PUT, OPTIONS
 
-<signature><timestamp>[<dns packet>]
+<body>
 ```
 
 Body is described at [Payload](#Payload) encoding section.
@@ -49,7 +49,7 @@ Access-Control-Allow-Methods: GET, PUT, OPTIONS
 Content-Type: application/pkarr.org/relays#payload
 Cache-Control: public, max-age=300
 
-<signature><timestamp>[<dns packet>]
+<body>
 ```
 
 `Cache-Control` header would help browsers reduce their reliance on the relay, the `max-age` should be set to be the minimum `ttl` in the resource records in the packet or some minimum ttl chosen by the relay.
@@ -70,12 +70,13 @@ On receiving a GET request, the relay server should:
 
 Relay payload is a subset of the [Canonical encoding](./base.md#Encoding), omitting the leading public key:
 
-| part       |  length  |         Note                         |
-| ---------- | -------- | ------------------------------------ | 
-| signature  | 64       | ed25519                              |
-| timestamp  | 8        | big-endian timestamp in microseconds |
-| DNS packet | variable | compressed DNS answer packet.        |
+```abnf
+RelayPayload = signature timestamp dns-packet
 
+signature   = 64 OCTET ; ed25519 signature over encoded DNS packet
+timestamp   =  8 OCTET ; big-endian UNIX timestamp in microseconds
+dns-packet  =  * OCTET ; compressed encoded DNS answer packet, less than 1000 bytes
+```
 
 ## Relation to resolvers