diff --git a/status-whisper-usage-spec.md b/status-whisper-usage-spec.md index b60b576..6d7afae 100644 --- a/status-whisper-usage-spec.md +++ b/status-whisper-usage-spec.md @@ -9,18 +9,19 @@ - [Reason](#reason) - [Terminology](#terminology) - [Whisper node configuration](#whisper-node-configuration) + - [Handshake](#handshake) + - [Rate limiting](#rate-limiting) - [Keys management](#keys-management) - [Contact code topic](#contact-code-topic) - [Partitioned topic](#partitioned-topic) - [Public chats](#public-chats) - - [Personal discovery topic](#personal-discovery-topic) - [Generic discovery topic](#generic-discovery-topic) - [One-to-one topic](#one-to-one-topic) - [Group chat topic](#group-chat-topic) - [Message encryption](#message-encryption) - [Whisper V6 extensions](#whisper-v6-extensions) - [Request historic messages](#request-historic-messages) - - [shhext_requestMessages](#shhext_requestmessages) + - [shhext_requestMessages](#shhextrequestmessages) ## Abstract @@ -59,9 +60,42 @@ Whisper's Proof Of Work algorithm is used to deter denial of service and various * proof-of-work requirement not larger than `0.002` * time-to-live not lower than `10` (in seconds) - +## Handshake - +Handshake is a RLP-encoded packet sent to a newly connected peer. It MUST start with a Status Code (`0x00`) and follow up with items: +``` +[ protocolVersion, PoW, bloom, isLightNode, confirmationsEnabled, rateLimits ] +``` + +`protocolVersion`: version of the Whisper protocol +`PoW`: minimum PoW accepted by the peer +`bloom`: bloom filter of Whisper topic accepted by the peer +`isLightNode`: when true, the peer won't forward messages +`confirmationsEnabled`: when true, the peer will send message confirmations +`rateLimits`: is `[ RateLimitIP, RateLimitPeerID, RateLimitTopic ]` where each values is an integer with a number of accepted packets per second per IP, Peer ID, and Topic respectively + +`bloom, isLightNode, confirmationsEnabled, and rateLimits` are all optional arguments in the handshake. However, if you specify optional field you MUST also specify all optional fields preceding it, in order to be unambiguous. +## Rate limiting + +In order to provide an optional very basic Denial-of-Service attack protection, each node SHOULD define its own rate limits. The rate limits SHOULD be applied on IPs, peer IDs, and envelope topics. + +Each node MAY decide to whitelist, i.e. do not rate limit, selected IPs or peer IDs. + +If a peer exceeds node's rate limits, the connection between them MAY be dropped. + +Each node SHOULD broadcast its rate limits to its peers using rate limits packet code (`0x14`). The rate limits is RLP-encoded information: + +``` +[ IP limits, PeerID limits, Topic limits ] +``` + +`IP limits`: 4-byte wide unsigned integer +`PeerID limits`: 4-byte wide unsigned integer +`Topic limits`: 4-byte wide unsigned integer + +The rate limits MAY also be sent as an optional parameter in the handshake. + +Each node SHOULD respect rate limits advertised by its peers. The number of packets SHOULD be throttled in order not to exceed peer's rate limits. If the limit gets exceeded, the connection MAY be dropped by the peer. ## Keys management @@ -145,7 +179,7 @@ for i = 0; i < topicLen; i++ { } ``` - -