Skip to content
Snippets Groups Projects
Commit b82409e0 authored by Éloïs's avatar Éloïs
Browse files

[enh] add EXTENDED feature

parent a4f618a0
No related branches found
No related tags found
1 merge request!8WIP: WS2P v2
Show whitespace changes
Inline Side-by-side
Showing
with 66 additions and 46 deletions
rfc/0006_ws2p_v2.md
+ 66
− 46
View file @ b82409e0
...@@ -162,8 +162,8 @@ _*the `null` value is essential, it allows the user to synchronize his node with ...@@ -162,8 +162,8 @@ _*the `null` value is essential, it allows the user to synchronize his node with
| path_size | 1 | u8 | | path_size | 1 | u8 |
| api_name | 1/api_size | specific | | api_name | 1/api_size | specific |
| api_version | 2 | u16 | | api_version | 2 | u16 |
| network_features | 2 | specific | | network_features | 2/+ | specific |
| api_features | 2 | specific | | api_features | 2/+ | specific |
| ip_v4 | 4 | [u8; 4] | | ip_v4 | 4 | [u8; 4] |
| ip_v6 | 16 | [u16; 8] | | ip_v6 | 16 | [u16; 8] |
| host | host_size | utf8 | | host | host_size | utf8 |
...@@ -190,11 +190,13 @@ The 16 bits represent booleans to define the presence or absence of 16 network f ...@@ -190,11 +190,13 @@ The 16 bits represent booleans to define the presence or absence of 16 network f
Network features : Network features :
| bit | feature | | bit | feature |
|:-------------------:|---------| |:-------------------:|----------|
| 0000_0000 0000_0001 | ip_v4 | | 0000_0000 0000_0001 | ip_v4 |
| 0000_0000 0000_0010 | ip_v6 | | 0000_0000 0000_0010 | ip_v6 |
| 0000_0000 0000_0100 | S | | 0000_0000 0000_0100 | S |
| 0000_0000 0000_1000 | TOR | | 0000_0000 0000_1000 | TOR |
| ... | ... |
| 1000_0000 0000_0000 | EXTENDED |
The first two features are a bit special because they must be read to parse the endpoint, indicating if the ipv4 and ipv6 fields are present or not. The first two features are a bit special because they must be read to parse the endpoint, indicating if the ipv4 and ipv6 fields are present or not.
...@@ -202,22 +204,30 @@ S := This feature indicates that the endpoint should be contacted with an SSL/TL ...@@ -202,22 +204,30 @@ S := This feature indicates that the endpoint should be contacted with an SSL/TL
TOR := This feature indicates that the endpoint must be contacted via the tor network (hidden service). TOR := This feature indicates that the endpoint must be contacted via the tor network (hidden service).
EXTENDED := Indicates that the `network_features` field contains 2 additional bytes to store 16 more features.
#### api_features #### api_features
The interpretation of this field depends on the API because it represents API-specific features. Here is the interpretation for the WS2P API : The interpretation of this field depends on the API because it represents API-specific features. Here is the interpretation for the WS2P API :
WS2P API features : WS2PFeatures type definition :
| bit | feature | | bit | feature |
|:-----------------:|-----------| |:-------------------:|-----------|
| 00_0000 0000_0001 | DEFLATE | | 0000_0000 0000_0001 | DEFLATE |
| 00_0000 0000_0010 | LOW | | 0000_0000 0000_0010 | LOW |
| 00_0000 0000_0100 | RBF | | 0000_0000 0000_0100 | RBF |
| ... | ... |
| 1000_0000 0000_0000 | EXTENDED |
DEFLATE := Supports permessage-deflate extension DEFLATE := Supports permessage-deflate extension
LOW := Accept low speed connection requests LOW := Accept low speed connection requests
RBF := Accept rust binary format RBF := Accept rust binary format
EXTENDED := Indicates that the `api_features` field contains 2 additional bytes to store 16 more features.
WS2P v2 uses only 3 of 16 features. The 13 free bits can be used for future versions of WS2P. WS2P v2 uses only 3 of 16 features. The 13 free bits can be used for future versions of WS2P.
### Endpoint utf8 format ### Endpoint utf8 format
...@@ -257,7 +267,7 @@ Same endpoint in binary format : ...@@ -257,7 +267,7 @@ Same endpoint in binary format :
### Peer card binary format ### Peer card binary format
| data name | size in bytes | data type | | data name | size in bytes | data type |
|:-----------------:|---------------|-----------------------------| |:-----------------:|---------------|------------------------------------|
| peer_card_size | 2 | u16 | | peer_card_size | 2 | u16 |
| version | 1 | u8 | | version | 1 | u8 |
| endpoints_count | 1 | u8 | | endpoints_count | 1 | u8 |
...@@ -265,9 +275,11 @@ Same endpoint in binary format : ...@@ -265,9 +275,11 @@ Same endpoint in binary format :
| node_id | 4 | u32 | | node_id | 4 | u32 |
| issuer_public_key | 32 | [u8; 32] | | issuer_public_key | 32 | [u8; 32] |
| blockstamp | 36 | Blockstamp | | blockstamp | 36 | Blockstamp |
| endpoints_datas | calculate* | [endpoint; endpoints_count] | | endpoints_datas | calculate* | [(u16, endpoint); endpoints_count] |
| signature | 64 | [u8; 64] | | signature | 64 | [u8; 64] |
endpoints_datas := tuples table (endpoint_size, endpoint).
`endpoint` type is defined above (See "Endpoint format"). `endpoint` type is defined above (See "Endpoint format").
The document is represented by an array of bytes containing (peer_card_size + 2) bytes. The document is represented by an array of bytes containing (peer_card_size + 2) bytes.
...@@ -355,10 +367,10 @@ for each connection attempt, the process is as follows: ...@@ -355,10 +367,10 @@ for each connection attempt, the process is as follows:
### CONNECT message ### CONNECT message
| data name | size in bytes | data type | | data name | size in bytes | data type |
|:-------------:|---------------|-----------| |:-------------:|---------------|--------------|
| challenge | 32 | [u8; 32] | | challenge | 32 | [u8; 32] |
| api_features | 2 | u16 | | api_features | 2/+ | WS2PFeatures |
| flags_queries | 1 | u8 | | flags_queries | 1/+ | WS2PFlags |
| peer_card | ? | Peer card | | peer_card | ? | Peer card |
| chunk_id* | 4 | u32 | | chunk_id* | 4 | u32 |
| chunk_hash* | 32 | [u8; 32] | | chunk_hash* | 32 | [u8; 32] |
...@@ -367,7 +379,7 @@ challenge := random hash generated by the sending node of the CONNECT message, t ...@@ -367,7 +379,7 @@ challenge := random hash generated by the sending node of the CONNECT message, t
api_features := This is exactly the same type as the field of the same name in the endpoints. But private WS2P nodes do not declare endpoints, so they must be able to indicate in the CONNECT message which features they support. Public WS2P nodes also fill this field, so any changes in the configuration of a public node will be applied on the 1st new connection. (If this was not the case, we would have to wait for the update of the peer record). api_features := This is exactly the same type as the field of the same name in the endpoints. But private WS2P nodes do not declare endpoints, so they must be able to indicate in the CONNECT message which features they support. Public WS2P nodes also fill this field, so any changes in the configuration of a public node will be applied on the 1st new connection. (If this was not the case, we would have to wait for the update of the peer record).
flags_queries := See "flags_queries interpretations" below. flags_queries := See "WS2PFlags type definition" below.
peer_card := This field is optional, if it's not present it must be replaced by 2 bytes filled with zeros. Why two bytes ? Because the first field of any peer card, `peer_card_size`, is 2 bytes long. peer_card := This field is optional, if it's not present it must be replaced by 2 bytes filled with zeros. Why two bytes ? Because the first field of any peer card, `peer_card_size`, is 2 bytes long.
...@@ -376,13 +388,15 @@ _*Fiels `chunk_id` and `chunk_hash` are present only if flag `ASK_SYNC_CHUNK` is ...@@ -376,13 +388,15 @@ _*Fiels `chunk_id` and `chunk_hash` are present only if flag `ASK_SYNC_CHUNK` is
chunk_id := Last block number of the chunk. chunk_id := Last block number of the chunk.
chunk_hash := Last block hash of the chunk. chunk_hash := Last block hash of the chunk.
#### flags_queries interpretations #### WS2PFlags type definition
| bit | flag | | bit | flag |
|:---------:|-----------------| |:---------:|-----------------|
| 0000_0001 | SYNC | | 0000_0001 | SYNC |
| 0000_0010 | ASK_SYNC_CHUNK | | 0000_0010 | ASK_SYNC_CHUNK |
| 0000_0100 | RES_SYNC_CHUNK | | 0000_0100 | RES_SYNC_CHUNK |
| ... | ... |
| 1000_0000 | EXTENDED |
SYNC := Boolean indicating whether the connection corresponds to a synchronization request or not. In case of a synchronization request, the connection will necessarily be accepted but temporary. Whereas in the normal case the connection may or may not be accepted according to classic ws2p rules, but it will be permanent. SYNC := Boolean indicating whether the connection corresponds to a synchronization request or not. In case of a synchronization request, the connection will necessarily be accepted but temporary. Whereas in the normal case the connection may or may not be accepted according to classic ws2p rules, but it will be permanent.
...@@ -390,6 +404,8 @@ ASK_SYNC_CHUNK := So that the synchronization is not too slow, the nodes to whic ...@@ -390,6 +404,8 @@ ASK_SYNC_CHUNK := So that the synchronization is not too slow, the nodes to whic
RES_SYNC_CHUNK := A WS2P Public node that asks to synchronize sends its PeerCard to the network, which can then contact it spontaneously to send chunk, the node in synchronization will accept in priority this type of connections. RES_SYNC_CHUNK := A WS2P Public node that asks to synchronize sends its PeerCard to the network, which can then contact it spontaneously to send chunk, the node in synchronization will accept in priority this type of connections.
EXTENDED := Indicates that the field contain one additional byte to store 8 more features.
### ACK message ### ACK message
| data name | size in bytes | data type | | data name | size in bytes | data type |
...@@ -402,18 +418,20 @@ challenge_sig := Signature of the challenge given by the other node. ...@@ -402,18 +418,20 @@ challenge_sig := Signature of the challenge given by the other node.
### FLAGS message ### FLAGS message
| data name | size in bytes | data type | | data name | size in bytes | data type |
|:-------------:|---------------|-----------| |:-------------:|---------------|-----------------|
| flags | 2 | b16 | | flags | 1/+ | WS2PSecretFlags |
| member_proof | 64 | [u8; 64] | | member_proof | 64 | [u8; 64] |
| member_pubkey | 32 | [u8; 32] | | member_pubkey | 32 | [u8; 32] |
#### flags interpretation #### WS2PSecretFlags type definition
| bit | flag | | bit | flag |
|:-------------------:|-----------------| |:-------- :|-----------------|
| 0000_0000 0000_0001 | LOW_FLOW_DEMAND | | 0000_0001 | LOW_FLOW_DEMAND |
| 0000_0000 0000_0010 | MEMBER_PUBKEY | | 0000_0010 | MEMBER_PUBKEY |
| 0000_0000 0000_0100 | MEMBER_PROOF | | 0000_0100 | MEMBER_PROOF |
| ... | ... |
| 1000_0000 | EXTENDED |
LOW_FLOW_DEMAND := The sender node of this message indicates that it's behind a low speed connection and therefore care must be taken to transmit low volumes of data to it. LOW_FLOW_DEMAND := The sender node of this message indicates that it's behind a low speed connection and therefore care must be taken to transmit low volumes of data to it.
...@@ -422,6 +440,8 @@ MEMBER_PUBKEY: Indicates whether or not the member_pubkey field is present in th ...@@ -422,6 +440,8 @@ MEMBER_PUBKEY: Indicates whether or not the member_pubkey field is present in th
MEMBER_PROOF := Indicates that the message contains proof that the sender node is a member. If this boolean is false, then the member_proof field must not be present. MEMBER_PROOF := Indicates that the message contains proof that the sender node is a member. If this boolean is false, then the member_proof field must not be present.
If this boolean is true, the "member_proof" must contain a signature must sign the following datas : If this boolean is true, the "member_proof" must contain a signature must sign the following datas :
EXTENDED := Indicates that the field contain one additional byte to store 8 more features.
| data name | size in bytes | data type | | data name | size in bytes | data type |
|:--------------:|---------------|-----------| |:--------------:|---------------|-----------|
| flags | 2 | b16 | | flags | 2 | b16 |
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment