diff --git a/proto-docs/reputation.md b/proto-docs/reputation.md new file mode 100644 index 0000000..12a9d57 --- /dev/null +++ b/proto-docs/reputation.md @@ -0,0 +1,279 @@ +# Protocol Documentation + + +## Table of Contents + +- [reputation/service.proto](#reputation/service.proto) + - Services + - [ReputationService](#neo.fs.v2.reputation.ReputationService) + + - Messages + - [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) + - [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body) + - [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) + - [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body) + - [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) + - [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body) + - [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) + - [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body) + + +- [reputation/types.proto](#reputation/types.proto) + + - Messages + - [GlobalTrust](#neo.fs.v2.reputation.GlobalTrust) + - [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) + - [PeerID](#neo.fs.v2.reputation.PeerID) + - [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust) + - [Trust](#neo.fs.v2.reputation.Trust) + + +- [Scalar Value Types](#scalar-value-types) + + + + +
+ +## reputation/service.proto + + + + + + +### Service "neo.fs.v2.reputation.ReputationService" +`ReputationService` provides mechanisms for exchanging trust values with +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. + +``` +rpc AnnounceLocalTrust(AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse); +rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse); + +``` + +#### Method AnnounceLocalTrust + +Announce local client trust information to any node in NeoFS network. + +| Name | Input | Output | +| ---- | ----- | ------ | +| AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) | +#### Method AnnounceIntermediateResult + +Announces the intermediate result of the iterative algorithm for +calculating the global reputation of the node in NeoFS network. + +| Name | Input | Output | +| ---- | ----- | ------ | +| AnnounceIntermediateResult | [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) | [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) | + + + + + +### Message AnnounceIntermediateResultRequest +Announce intermediate global trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body) | | Body of the request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceIntermediateResultRequest.Body +Announce intermediate global trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Iteration execution Epoch number | +| iteration | [uint32](#uint32) | | Iteration sequence number | +| trust | [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust) | | Current global trust value calculated at the specified iteration | + + + + +### Message AnnounceIntermediateResultResponse +Intermediate global trust information announce response. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body) | | Body of the response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceIntermediateResultResponse.Body +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 AnnounceLocalTrustRequest +Announce node's local trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body) | | Body of the request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceLocalTrustRequest.Body +Announce node's local trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Trust assessment Epoch number | +| trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in the [0;1] range. | + + + + +### Message AnnounceLocalTrustResponse +Node's local trust information announce response. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body) | | Body of the response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceLocalTrustResponse.Body +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. + + + + + + + + + + + +## reputation/types.proto + + + + + + + +### Message GlobalTrust +Global trust level to NeoFS node. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively the version of API library used to create the message. | +| body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body | +| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. | + + + + +### Message GlobalTrust.Body +Message body structure. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| manager | [PeerID](#neo.fs.v2.reputation.PeerID) | | Node manager ID | +| trust | [Trust](#neo.fs.v2.reputation.Trust) | | Global trust level | + + + + +### Message PeerID +NeoFS unique peer identifier is 33 byte long compressed public key of the +node, the same as the one stored in the network map. + +String presentation is +[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. + +JSON value will be the data encoded as a string using standard base64 +encoding with paddings. Either +[standard](https://tools.ietf.org/html/rfc4648#section-4) or +[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding +with/without paddings are accepted. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| public_key | [bytes](#bytes) | | Peer node's public key | + + + + +### Message PeerToPeerTrust +Trust level of a peer to a peer. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| trusting_peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusting peer | +| trust | [Trust](#neo.fs.v2.reputation.Trust) | | Trust level | + + + + +### Message Trust +Trust level to a NeoFS network peer. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusted peer | +| value | [double](#double) | | Trust level in [0:1] range | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | +