reputation: Rename and reformat

* Rename:
  - SendLocalTrust → AnnounceLocalTrust
  - SendIntermediateResult → AnnounceIntermediateResult

  Those methods don't expect to Send anything, but to further announce
  the trust information from the node.

* Change PeerID to explicitly use public key as a node identifier

* Minor comments reformat

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>

reputation/service.proto

@@ -8,27 +8,30 @@ option csharp_namespace = "Neo.FileStorage.API.Reputation";
 import "reputation/types.proto";
 import "session/types.proto";
 
-// `ReputationService` provides mechanisms for exchanging
+// `ReputationService` provides mechanisms for exchanging trust values with
-// trust values within NeoFS Reputation system .
+// other NeoFS nodes. Nodes rate each other's reputation based on how good they
+// process requests and set a trust level based on that rating. The trust
+// information is passed to the next nodes to check and aggregate unless the
+// final result is recorded.
 service ReputationService {
-    // Sends local client trust to any peer from NeoFS network.
+    // Announce local client trust information to any node in NeoFS network.
-    rpc SendLocalTrust (SendLocalTrustRequest) returns (SendLocalTrustResponse);
+    rpc AnnounceLocalTrust (AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse);
 
-    // Sends the intermediate result of the iterative algorithm
+    // Announces the intermediate result of the iterative algorithm for
-    // for calculating the global reputation of the node.
+    // calculating the global reputation of the node in NeoFS network.
-    rpc SendIntermediateResult (SendIntermediateResultRequest) returns (SendIntermediateResultResponse);
+    rpc AnnounceIntermediateResult (AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse);
 }
 
-// Request to send local trust.
+// Announce node's local trust information.
-message SendLocalTrustRequest {
+message AnnounceLocalTrustRequest {
-    // Request body structure.
+    // Announce node's local trust information.
     message Body {
-        // The number of the epoch in which the trust was assessed.
+        // Trust assessment Epoch number
         uint64 epoch = 1;
 
-        // List of normalized local trust values of the client to the NeoFS peers.
+        // List of normalized local trust values to other NeoFS nodes. The value
-        // The value is calculated according to EigenTrust++ algorithm
+        // is calculated according to EigenTrust++ algorithm and must be a
-        // and must be in the range [0;1].
+        // floating point number in the [0;1] range.
         repeated Trust trusts = 2;
     }
 
@@ -45,9 +48,11 @@ message SendLocalTrustRequest {
     neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
 }
 
-// Response to request to send local trust.
+// Node's local trust information announce response.
-message SendLocalTrustResponse {
+message AnnounceLocalTrustResponse {
-    // Response body structure.
+    // Response to the node's local trust information announce has an empty body
+    // because the trust exchange operation is asynchronous. If Trust information
+    // will not pass sanity checks it is silently ignored.
     message Body {
     }
 
@@ -64,17 +69,17 @@ message SendLocalTrustResponse {
     neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
 }
 
-// Request to send intermediate global trust.
+// Announce intermediate global trust information.
-message SendIntermediateResultRequest {
+message AnnounceIntermediateResultRequest {
-    // Request body structure.
+    // Announce intermediate global trust information.
     message Body {
-        // The number of the epoch in which the iteration was executed.
+        // Iteration execution Epoch number
         uint64 epoch = 1;
 
-        // Sequence number of the iteration.
+        // Iteration sequence number
         uint32 iteration = 2;
 
-        // Current global trust value computed at the specified iteration.
+        // Current global trust value calculated at the specified iteration
         PeerToPeerTrust trust = 3;
     }
 
@@ -91,9 +96,11 @@ message SendIntermediateResultRequest {
     neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
 }
 
-// Response to request to send intermediate global trust.
+// Intermediate global trust information announce response.
-message SendIntermediateResultResponse {
+message AnnounceIntermediateResultResponse {
-    // Response body structure.
+    // Response to the node's intermediate global trust information announce has
+    // an empty body because the trust exchange operation is asynchronous. If
+    // Trust information will not pass sanity checks it is silently ignored.
     message Body {
     }
 

reputation/types.proto

@@ -7,10 +7,8 @@ option csharp_namespace = "Neo.FileStorage.API.Reputation";
 
 import "refs/types.proto";
 
-// NeoFS unique peer identifier.
+// NeoFS unique peer identifier is 33 byte long compressed public key of the
-//
+// node, the same as the one stored in the network map.
-// `PeerID` is a 33 byte long compressed public key of the node
-// stored in network map.
 //
 // String presentation is
 // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
@@ -21,44 +19,43 @@ import "refs/types.proto";
 // [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
 // with/without paddings are accepted.
 message PeerID {
-    // Peer identifier in a binary format.
+    // Peer node's public key
-    bytes value = 1 [json_name = "value"];
+    bytes public_key = 1 [json_name = "publicKey"];
 }
 
-// Trust value to NeoFS network peer.
+// Trust level to a NeoFS network peer.
 message Trust {
-    // Identifier of the trusted peer.
+    // Identifier of the trusted peer
     PeerID peer = 1 [json_name = "peer"];
 
-    // Trust value.
+    // Trust level in [0:1] range
     double value = 2 [json_name = "value"];
 }
 
-// Trust value of a peer to a peer.
+// Trust level of a peer to a peer.
 message PeerToPeerTrust {
-    // Identifier of the trusting peer.
+    // Identifier of the trusting peer
     PeerID trusting_peer = 1 [json_name = "trustingPeer"];
 
-    // Trust value.
+    // Trust level
     Trust trust = 2 [json_name = "trust"];
 }
 
-// Global trust value to NeoFS network peer.
+// Global trust level to NeoFS node.
 message GlobalTrust {
     // Message format version. Effectively the version of API library used to create
     // the message.
     neo.fs.v2.refs.Version version = 1 [json_name = "version"];
-
     // Message body structure.
     message Body {
-      // Node manager ID.
+      // Node manager ID
       PeerID manager = 1 [json_name = "manager"];
 
-      // Global trust value.
+      // Global trust level
       Trust trust = 2 [json_name = "trust"];
     }
 
-    // Message body.
+    // Message body
     Body body = 2 [json_name = "body"];
 
     // Signature of the binary `body` field by the manager.