diff --git a/rfc/0006_ws2p_v2.md b/rfc/0006_ws2p_v2.md index 0215a7a5caf53f68b8aa90a25c9412ccba9cf700..57d00e5d24bfed3ec2e3361da319f9cbff1a5b51 100644 --- a/rfc/0006_ws2p_v2.md +++ b/rfc/0006_ws2p_v2.md @@ -162,8 +162,8 @@ _*the `null` value is essential, it allows the user to synchronize his node with | path_size | 1 | u8 | | api_name | 1/api_size | specific | | api_version | 2 | u16 | -| network_features | 2 | specific | -| api_features | 2 | specific | +| network_features | 2/+ | specific | +| api_features | 2/+ | specific | | ip_v4 | 4 | [u8; 4] | | ip_v6 | 16 | [u16; 8] | | host | host_size | utf8 | @@ -189,12 +189,14 @@ The 16 bits represent booleans to define the presence or absence of 16 network f Network features : -| bit | feature | -|:-------------------:|---------| -| 0000_0000 0000_0001 | ip_v4 | -| 0000_0000 0000_0010 | ip_v6 | -| 0000_0000 0000_0100 | S | -| 0000_0000 0000_1000 | TOR | +| bit | feature | +|:-------------------:|----------| +| 0000_0000 0000_0001 | ip_v4 | +| 0000_0000 0000_0010 | ip_v6 | +| 0000_0000 0000_0100 | S | +| 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. @@ -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). +EXTENDED := Indicates that the `network_features` field contains 2 additional bytes to store 16 more 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 : -WS2P API features : +WS2PFeatures type definition : -| bit | feature | -|:-----------------:|-----------| -| 00_0000 0000_0001 | DEFLATE | -| 00_0000 0000_0010 | LOW | -| 00_0000 0000_0100 | RBF | +| bit | feature | +|:-------------------:|-----------| +| 0000_0000 0000_0001 | DEFLATE | +| 0000_0000 0000_0010 | LOW | +| 0000_0000 0000_0100 | RBF | +| ... | ... | +| 1000_0000 0000_0000 | EXTENDED | DEFLATE := Supports permessage-deflate extension + LOW := Accept low speed connection requests + 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. ### Endpoint utf8 format @@ -256,17 +266,19 @@ Same endpoint in binary format : ### Peer card binary format -| data name | size in bytes | data type | -|:-----------------:|---------------|-----------------------------| -| peer_card_size | 2 | u16 | -| version | 1 | u8 | -| endpoints_count | 1 | u8 | -| currency_code | 2 | u16 | -| node_id | 4 | u32 | -| issuer_public_key | 32 | [u8; 32] | -| blockstamp | 36 | Blockstamp | -| endpoints_datas | calculate* | [endpoint; endpoints_count] | -| signature | 64 | [u8; 64] | +| data name | size in bytes | data type | +|:-----------------:|---------------|------------------------------------| +| peer_card_size | 2 | u16 | +| version | 1 | u8 | +| endpoints_count | 1 | u8 | +| currency_code | 2 | u16 | +| node_id | 4 | u32 | +| issuer_public_key | 32 | [u8; 32] | +| blockstamp | 36 | Blockstamp | +| endpoints_datas | calculate* | [(u16, endpoint); endpoints_count] | +| signature | 64 | [u8; 64] | + +endpoints_datas := tuples table (endpoint_size, endpoint). `endpoint` type is defined above (See "Endpoint format"). @@ -354,20 +366,20 @@ for each connection attempt, the process is as follows: ### CONNECT message -| data name | size in bytes | data type | -|:-------------:|---------------|-----------| -| challenge | 32 | [u8; 32] | -| api_features | 2 | u16 | -| flags_queries | 1 | u8 | -| peer_card | ? | Peer card | -| chunk_id* | 4 | u32 | -| chunk_hash* | 32 | [u8; 32] | +| data name | size in bytes | data type | +|:-------------:|---------------|--------------| +| challenge | 32 | [u8; 32] | +| api_features | 2/+ | WS2PFeatures | +| flags_queries | 1/+ | WS2PFlags | +| peer_card | ? | Peer card | +| chunk_id* | 4 | u32 | +| chunk_hash* | 32 | [u8; 32] | 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. 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. @@ -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_hash := Last block hash of the chunk. -#### flags_queries interpretations +#### WS2PFlags type definition | bit | flag | |:---------:|-----------------| | 0000_0001 | SYNC | | 0000_0010 | ASK_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. @@ -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. +EXTENDED := Indicates that the field contain one additional byte to store 8 more features. + ### ACK message | data name | size in bytes | data type | @@ -401,19 +417,21 @@ challenge_sig := Signature of the challenge given by the other node. ### FLAGS message -| data name | size in bytes | data type | -|:-------------:|---------------|-----------| -| flags | 2 | b16 | -| member_proof | 64 | [u8; 64] | -| member_pubkey | 32 | [u8; 32] | +| data name | size in bytes | data type | +|:-------------:|---------------|-----------------| +| flags | 1/+ | WS2PSecretFlags | +| member_proof | 64 | [u8; 64] | +| member_pubkey | 32 | [u8; 32] | -#### flags interpretation +#### WS2PSecretFlags type definition -| bit | flag | -|:-------------------:|-----------------| -| 0000_0000 0000_0001 | LOW_FLOW_DEMAND | -| 0000_0000 0000_0010 | MEMBER_PUBKEY | -| 0000_0000 0000_0100 | MEMBER_PROOF | +| bit | flag | +|:-------- :|-----------------| +| 0000_0001 | LOW_FLOW_DEMAND | +| 0000_0010 | MEMBER_PUBKEY | +| 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. @@ -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. 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 | |:--------------:|---------------|-----------| | flags | 2 | b16 |