From 154adda51d2d5663315b47a62b4637876a8a5aad Mon Sep 17 00:00:00 2001
From: Hugo Trentesaux <hugo@trentesaux.fr>
Date: Sat, 9 Nov 2019 14:50:59 +0100
Subject: [PATCH] wip CBOR
---
rfc/0006_ws2p_v2.md | 105 ++++++++++++++++++++++++++++++++++++--------
1 file changed, 86 insertions(+), 19 deletions(-)
diff --git a/rfc/0006_ws2p_v2.md b/rfc/0006_ws2p_v2.md
index 32ec732..e00977a 100644
--- a/rfc/0006_ws2p_v2.md
+++ b/rfc/0006_ws2p_v2.md
@@ -89,7 +89,29 @@ The PEG grammars of raw formats are presented according to the [pest syntax] (a
[PEG grammar]: https://en.wikipedia.org/wiki/Parsing_expression_grammar
[pest syntax]: https://pest.rs/book/grammars/syntax.html
+## Common structures
+A certain number of structure like hash appear repeatedly in the messages. Here we describe it once and refer to it later.
+
+### 32 byte number
+
+A 32-bytes number is represented in JSON by an array of 32 8-bits numbers.
+
+```json
+[8, 56, 211, ..., 12] // array of 32 8-bits numbers
+```
+
+### 64 byte number
+
+A 64-bytes number is represented in JSON by an array of 64 8-bits numbers.
+
+```json
+[8, 56, 211, ..., 12] // array of 64 8-bits numbers
+```
+
+### Hash, Pubkey, Signature
+
+Hashes or pubkeys or signatures are just numbers, most often 32B or 64B one.
## Message encapsulation
@@ -108,7 +130,7 @@ All WS2Pv2 messages are structured as follows (CBOR format) :
"issuer_node_id": 395,
"issuer_pubkey": {
"algo": "Ed25519",
- "content": [52, 147, .., 93], // Array of 32 bytes
+ "content": [52, 147, .., 93], // 32 bytes pubkey
},
"payload": {
"type": "MESSAGE_TYPE_NAME",
@@ -238,7 +260,7 @@ The signed key must be signed with the blockstamp corresponding to the date of s
"currency_name": "g1",
"issuer": {
"algo": "Ed25519",
- "content": [122, 11, .., 95] // Array of 32 bytes numbers
+ "content": [122, 11, .., 95] // 32 bytes pubkey
},
"node_id": 10623,
"created_on": 542,
@@ -246,21 +268,21 @@ The signed key must be signed with the blockstamp corresponding to the date of s
"endpoints_str": [], // Array of Strings (endpoitn v2 in utf8 format)
"sig": {
"algo": "Ed25519",
- "content": [187, 7, .., 23] // Array of 64 bytes numbers
+ "content": [187, 7, .., 23] // 64 bytes signature
},
"certifiers": [
{
"certifier": {
"algo": "Ed25519",
- "content": [122, 11, .., 95] // Array of 32 bytes numbers
+ "content": [122, 11, .., 95] // 32 bytes pubkey
},
"blockstamp": {
"id": 327,
- "hash": [85, 132, .., 27] // Array of 32 bytes numbers
+ "hash": [85, 132, .., 27] // 32 bytes hash
},
"sig": {
"algo": "Ed25519",
- "content": [187, 7, .., 23] // Array of 64 bytes numbers
+ "content": [187, 7, .., 23] // 64 bytes signature
},
}
]
@@ -296,21 +318,21 @@ Peer card v11 PEG grammar :
hexa_upper = @{ ASCII_DIGIT | 'A'..'F' }
base58 = { !("O" | "I" | "l") ~ ASCII_ALPHANUMERIC }
base64 = { ASCII_ALPHANUMERIC | "+" | "/" }
-
+
// Numbers rules
tens = @{ '1'..'9' ~ ASCII_DIGIT }
u8_hundreds = @{ ("2" ~ ('0'..'4' ~ ASCII_DIGIT | ('0'..'5'){2})) | ("1" ~ ASCII_DIGIT{2}) }
u8 = @{ u8_hundreds | tens | ASCII_DIGIT }
no_zero_u_int = @{ '1'..'9' ~ ASCII_DIGIT* }
u_int = @{ "0" | no_zero_u_int }
-
+
// Usefull types rules
currency = @{ ASCII_ALPHA ~ (ASCII_ALPHANUMERIC | "-" | "_"){,255} }
block_id = @{ u_int }
hash = @{ hexa_upper{64} }
pubkey = @{ base58{43,44} }
ed25519_sig = @{ base64{88} | (base64{87} ~ "=") | (base64{86} ~ "==") }
-
+
// IP v6 rules
ip6_seg = _{ hexa_lower{1,4} }
ip6_full = _{ (ip6_seg ~ ":"){7} ~ ip6_seg }
@@ -323,7 +345,7 @@ Peer card v11 PEG grammar :
}
ip6_inner = @{ ip6_full | ip6_no_full }
ip6 = _{ "[" ~ ip6_inner ~ "] " }
-
+
// Endpoint v2 rules
api_version_inner = @{ no_zero_u_int }
api_version = _{ "V" ~ api_version_inner ~ " " }
@@ -344,7 +366,7 @@ Peer card v11 PEG grammar :
ip4 = _{ ip4_inner ~ " " }
path = _{ " " ~ path_inner }
endpoint_v2 = ${ api_name ~ " " ~ (api_version)? ~ (network_features)? ~ (api_features)? ~ ip4? ~ ip6? ~ domain_name? ~ port ~ path? }
-
+
// Peer v11 rules
peer_v11 = ${ "11:" ~ currency ~ ":" ~ node_id ~ ":" ~ pubkey ~ ":" ~ block_id ~ nl ~ (endpoint_v2 ~ nl)+ ~ ed25519_sig? }
```
@@ -436,7 +458,12 @@ WARNING: independently of all these rules, each implementation must integrate it
### CONNECT message
```json
- {} // TODO
+ {
+ "challenge": [...], // 32 bytes hash
+ "api_features": [...], // list of 4 integers corresponding to api_features (see in endpoint definition)
+ "connect_type": {...}, // see below
+ "peer_card": {...} // look at the peercard definition above
+ }
```
challenge := random hash generated by the sending node of the CONNECT message, the receiving node will then have to sign this challenge and then send this signature in its ACK message to prove that it has the corresponding private key to the public key it indicates.
@@ -449,12 +476,42 @@ peer_card := See PeerCard above
#### ConnectType type definition
-TODO
+ConnectType represent the connection type. It can be:
+
+- Incoming: *connect message sent when receiving an incoming websocket connection*
+- Client: *connect message sent by a client*
+- Server: *connect message sent between nodes for a normal connection*
+- Sync: *connect message sent for a synchronization request*
+- SyncAskChunk: *connect message sent for a chunk request*
+
+Incoming, Client and Server are represented by a string.
+
+Sync is represented by an object
+
+```
+{
+ "Sync": {
+ "from_blockstamp": "128310-000002A569DCEED62227CAC0ABDFE6B2647B21B3193A40398CD12BC2A95C24D9"
+ }
+},
+```
+
+SyncAskChunk is reprensented by an object
+
+```json
+{
+ "SyncAskChunk": "128310-000002A569DCEED62227CAC0ABDFE6B2647B21B3193A40398CD12BC2A95C24D9",
+}
+```
+
+
### ACK message
```json
- {} // TODO
+ {
+ "hash": [...] // 32 bytes hash
+ }
```
Each node must sign the challenge of the other to prove that it's in possession of the private key corresponding to the public key under which it identifies.
@@ -465,7 +522,7 @@ The message is already signed at the container level, so there is no need to rep
TODO
-If its valued, the `member_proof` field must contain a signature of the challenge* send by other node in their CONNECT message.
+If it is valued, the `member_proof` field must contain a signature of the challenge* send by other node in their CONNECT message.
_*It's the remote challenge for the signatory, and the local challenge for the verifier._
@@ -479,11 +536,13 @@ LOW_FLOW_DEMAND := The sender node of this message indicates that it's behind a
### OK message
-In most cases, the OK message is empty (=3 zero-bytes), it simply indicates that the remote node accepts the connection establishment. If the local node has also sent an OK message, then it considers the connection as fully established.
+In most cases, the OK message is empty, it simply indicates that the remote node accepts the connection establishment. If the local node has also sent an OK message, then it considers the connection as fully established.
But sometimes the OK message can also transmit additional informations :
```json
- {} // TODO
+ {
+ "prefix": ... // null or non-zero integer
+ }
```
prefix := In ws2p v2, member nodes have the option of not publicly communicating their prefix. It will only reveal their prefix to the node of their choice among those with which they establish a connection. For example, a member node may decide to share its prefix only with other member nodes of the same key.
@@ -492,7 +551,15 @@ If this field is zero, it means that the remote node does not want to reveal its
#### SYNC_INFO message
```json
- {} // TODO
+ {
+ "chunk_size": 500,
+ "target_blockstamp": {
+ "id": 0,
+ "hash": [...] // 32 bytes hash
+ },
+ "milestones": [...], // list of 32 bytes hashes
+ "peer_cards": [...] // list of peercards
+ }
```
chunk_size := defines the size of the block used in milestones. A 1000-block chunk is a good compromise between efficiency of compression and duration of transfer
@@ -506,7 +573,7 @@ peer_cards := see [definition of binary peer card](#peer-card-binary-format)
### KO message
```json
- {} // TODO
+ 0 // number representing reason
```
#### reason
--
GitLab