Merge pull request #3 from nspcc-dev/documentation

Prepare documentation for NeoFS Proto library

.github/markdown.tmpl

@@ -0,0 +1,83 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+{{range .Files}}
+{{$file_name := .Name}}- [{{.Name}}](#{{.Name}})
+{{if .Services}} - Services
+    {{range .Services}}- [{{.Name}}](#{{.FullName}})
+    {{end}}{{end}}
+{{if .Messages}}  - Messages
+    {{range .Messages}}- [{{.LongName}}](#{{.FullName}})
+    {{end}}{{end}}
+{{end}}
+- [Scalar Value Types](#scalar-value-types)
+
+{{range .Files}}
+{{$file_name := .Name}}
+<a name="{{.Name}}"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## {{.Name}}
+{{.Description}}
+
+{{range .Services}}
+
+<a name="{{.FullName}}"></a>
+
+### Service "{{.FullName}}"
+{{.Description}}
+
+```
+{{range .Methods -}}
+  rpc {{.Name}}({{if .RequestStreaming}}stream {{end}}{{.RequestLongType}}) returns ({{if .ResponseStreaming}}stream {{end}}{{.ResponseLongType}});
+{{end}}
+```
+
+{{range .Methods -}}
+#### Method {{.Name}}
+
+{{.Description}}
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}) | [{{.ResponseLongType}}](#{{.ResponseFullType}}) |
+{{end}}{{end}} <!-- end services -->
+
+{{range .Messages}}
+<a name="{{.FullName}}"></a>
+
+### Message {{.LongName}}
+{{.Description}}
+
+{{if .HasFields}}
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+{{range .Fields -}}
+  | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+{{end}}{{end}}
+{{end}} <!-- end messages -->
+
+{{range .Enums}}
+<a name="{{.FullName}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+  | {{.Name}} | {{.Number}} | {{nobr .Description}} |
+{{end}}
+
+{{end}} <!-- end enums -->
+
+{{end}}
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+{{range .Scalars -}}
+  | <a name="{{.ProtoType}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} |
+{{end}}

Makefile

@@ -1,3 +1,26 @@
+B=\033[0;1m
+G=\033[0;92m
+R=\033[0m
+
+# Reformat code
+format:
+	@[ ! -z `which goimports` ] || (echo "install goimports" && exit 2)
+	@for f in `find . -type f -name '*.go' -not -path './vendor/*' -not -name '*.pb.go' -prune`; do \
+		echo "${B}${G}⇒ Processing $$f ${R}"; \
+		goimports -w $$f; \
+	done
+
+# Regenerate documentation for protot files:
+docgen:
+	@for f in `find . -type f -name '*.proto' -not -path './vendor/*' -exec dirname {} \; | sort -u `; do \
+		echo "${B}${G}⇒ Documentation for $$(basename $$f) ${R}"; \
+		protoc \
+			--doc_opt=.github/markdown.tmpl,$${f}.md \
+			--proto_path=.:./vendor:/usr/local/include \
+			--doc_out=docs/ $${f}/*.proto; \
+	done
+
+# Regenerate proto files:
 protoc:
 	@go mod tidy -v
 	@go mod vendor
@@ -6,7 +29,9 @@ protoc:
 	# Install specific version for protobuf lib
 	@go list -f '{{.Path}}/...@{{.Version}}' -m  github.com/golang/protobuf | xargs go get -v
 	# Protoc generate
-	@find . -type f -name '*.proto' -not -path './vendor/*' \
-		-exec protoc \
-		--proto_path=.:./vendor \
-		--gofast_out=plugins=grpc,paths=source_relative:. '{}' \;
+	@for f in `find . -type f -name '*.proto' -not -path './vendor/*'`; do \
+		echo "${B}${G}⇒ Processing $$f ${R}"; \
+		protoc \
+			--proto_path=.:./vendor:/usr/local/include \
+			--gofast_out=plugins=grpc,paths=source_relative:. $$f; \
+	done

README.md

@@ -9,6 +9,8 @@ Repository contains 13 packages that implement NeoFS core structures. These
 packages mostly contain protobuf files with service and structure definitions 
 or NeoFS core types with complemented functions. 
 
+There is a auto-generated documentation for protobuf files in [docs](docs).
+
 ### Accounting
 
 Accounting package defines services and structures for accounting operations: 
@@ -17,11 +19,22 @@ with inner ring signatures, which approve that user can withdraw requested
 amount of assets. NeoFS smart contract takes binary formatted `cheque` as a 
 parameter in withdraw call. 
 
+#### API
+Accounting package defines: 
+- [Accounting service](docs/accounting.md#accounting.Accounting)
+- [Withdraw service](docs/accounting.md#accounting.Withdraw)
+
+
 ### Bootstrap
 
 Bootstrap package defines bootstrap service which is used by storage nodes to
 connect to the storage network. 
 
+#### API
+Bootstrap package defines:
+- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap)
+
+
 ### Chain
 
 Chain package contains util functions for operations with NEO Blockchain types:
@@ -33,6 +46,10 @@ Container package defines service and structures for operations with containers.
 Objects in NeoFS are stored in containers. Container defines storage 
 policy for the objects. 
 
+#### API
+Bootstrap package defines:
+- [Container service](docs/container.md#container.Service)
+
 ### Decimal
 
 Decimal defines custom decimal implementation which is used in accounting
@@ -53,6 +70,10 @@ Object package defines service and structures for object operations. Object is
 a core storage structure in NeoFS. Package contains detailed information
 about object internal structure.
 
+#### API
+Object package defines:
+- [Object service](docs/object.md#object.Service)
+
 ### Query
 
 Query package defines structure for object search requests. 
@@ -72,10 +93,18 @@ Session package defines service and structures for session obtain. Object
 operations require an established session with pair of session keys signed by 
 owner of the object. 
 
+#### API
+Session package defines:
+- [Session service](docs/session.md#session.Session)
+
 ### State
 
 State package defines service and structures for metrics gathering. 
 
+#### API
+State package defines:
+- [Status service](docs/state.md#state.Status)
+
 ## How to use
 
 NeoFS-proto packages contain godoc documentation. Examples of using most of 

accounting/service.proto

@@ -8,16 +8,24 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+// Accounting is a service that provides access for accounting balance
+// information
 service Accounting {
+    // Balance returns current balance status of the NeoFS user
     rpc Balance(BalanceRequest) returns (BalanceResponse);
 }
 
 message BalanceRequest {
+    // OwnerID is a wallet address
     bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL    = 2;
 }
 
 message BalanceResponse {
+    // Balance contains current account balance state
     decimal.Decimal Balance       = 1;
+    // LockAccounts contains information about locked funds. Locked funds appear
+    // when user pays for storage or withdraw assets.
     repeated Account LockAccounts = 2;
 }

accounting/types.proto

@@ -7,61 +7,63 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
-// Snapshot accounting messages
 message Account {
+    // OwnerID is a wallet address
     bytes OwnerID                 = 1 [(gogoproto.customtype) = "OwnerID",  (gogoproto.nullable) = false];
+    // Address is identifier of accounting record
     string Address                = 2;
+    // ParentAddress is identifier of parent accounting record
     string ParentAddress          = 3;
+    // ActiveFunds is amount of active (non locked) funds for account
     decimal.Decimal ActiveFunds   = 4;
+    // Lifetime is time until account is valid (used for lock accounts)
     Lifetime Lifetime             = 5 [(gogoproto.nullable) = false];
+    // LockTarget is the purpose of lock funds (it might be withdraw or payment for storage)
     LockTarget LockTarget         = 6;
+    // LockAccounts contains child accounts with locked funds
     repeated Account LockAccounts = 7;
 }
 
+// LockTarget must be one of two options
 message LockTarget {
     oneof Target {
+        // WithdrawTarget used when user requested withdraw
         WithdrawTarget WithdrawTarget = 1;
+        // ContainerCreateTarget used when user requested creation of container
         ContainerCreateTarget ContainerCreateTarget = 2;
     }
 }
 
-// Snapshot balance messages
 message Balances {
+    // Accounts contains multiple account snapshots
     repeated Account Accounts = 1 [(gogoproto.nullable) = false];
 }
 
-// PayIn / PayOut messages
 message PayIO {
+    // BlockID contains id of the NEO block where withdraw or deposit
+    // call was invoked
     uint64 BlockID = 1;
+    // Transactions contains all transactions that founded in block
+    // and used for PayIO
     repeated Tx Transactions = 2 [(gogoproto.nullable) = false];
 }
 
-// Clearing messages
-message Clearing {
-    repeated Tx Transactions = 1 [(gogoproto.nullable) = false];
-}
-
-// Clearing messages
-message Withdraw {
-    string ID = 1;
-    uint64 Epoch = 2;
-    Tx Transaction = 3;
-}
-
-// Lifetime of locks
 message Lifetime {
+    // Unit can be Unlimited, based on NeoFS epoch or Neo block
     enum Unit {
         Unlimited = 0;
         NeoFSEpoch = 1;
         NeoBlock = 2;
     }
 
+    // Unit describes how lifetime is measured in account
     Unit unit = 1 [(gogoproto.customname) = "Unit"];
+    // Value describes how long lifetime will be valid
     int64 Value = 2;
 }
 
-// Transaction messages
 message Tx {
+    // Type can be withdrawal, payIO or inner
     enum Type {
         Unknown  = 0;
         Withdraw = 1;
@@ -69,38 +71,54 @@ message Tx {
         Inner    = 3;
     }
 
+    // Type describes target of transaction
     Type type              = 1 [(gogoproto.customname) = "Type"];
+    // From describes sender of funds
     string From            = 2;
+    // To describes receiver of funds
     string To              = 3;
+    // Amount describes amount of funds
     decimal.Decimal Amount = 4;
-    bytes PublicKeys       = 5; // of sender
+    // PublicKeys contains public key of sender
+    bytes PublicKeys       = 5;
 }
 
 message Settlement {
     message Receiver {
+        // To is the address of funds recipient 
         string To              = 1;
+        // Amount is the amount of funds that will be sent
         decimal.Decimal Amount = 2;
     }
 
     message Container {
+        // CID is container identifier
         bytes CID            = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
+        // SGIDs is a set of storage groups that successfully passed the audit
         repeated bytes SGIDs = 2 [(gogoproto.customtype) = "SGID", (gogoproto.nullable) = false];
     }
 
     message Tx {
+        // From is the address of the sender of funds
         string From                 = 1;
+        // Container that successfully had passed the audit
         Container Container         = 2 [(gogoproto.nullable) = false];
+        // Receivers is a set of addresses of funds recipients
         repeated Receiver Receivers = 3 [(gogoproto.nullable) = false];
     }
 
+    // Epoch contains an epoch when settlement was accepted
     uint64 Epoch             = 1;
+    // Transactions is a set of transactions
     repeated Tx Transactions = 2;
 }
 
 message ContainerCreateTarget {
+    // CID is container identifier
     bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
 }
 
 message WithdrawTarget {
+    // Cheque is a string representation of cheque id
     string Cheque = 1;
 }

accounting/withdraw.proto

@@ -7,55 +7,88 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+// Withdraw is a service that provides withdraw assets operations from the NeoFS
 service Withdraw {
+    // Get returns cheque if it was signed by inner ring nodes
     rpc Get(GetRequest) returns (GetResponse);
+    // Put ask inner ring nodes to sign a cheque for withdraw invoke
     rpc Put(PutRequest) returns (PutResponse);
+    // List shows all user's checks
     rpc List(ListRequest) returns (ListResponse);
+    // Delete allows user to remove unused cheque
     rpc Delete(DeleteRequest) returns (DeleteResponse);
 }
 
 message Item {
+    // ID is a cheque identifier
     bytes ID               = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
+    // OwnerID is a wallet address
     bytes OwnerID          = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // Amount of funds
     decimal.Decimal Amount = 3;
+    // Height is the neo blockchain height until the cheque is valid
     uint64 Height          = 4;
+    // Payload contains cheque representation in bytes
     bytes Payload          = 5;
 }
 
 message GetRequest {
+    // ID is cheque identifier
     bytes ID      = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
+    // OwnerID is a wallet address
     bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL    = 3;
 }
+
 message GetResponse {
+    // Item is cheque with meta information
     Item Withdraw = 1;
 }
 
 message PutRequest {
+    // OwnerID is a wallet address
     bytes OwnerID          = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // Amount of funds
     decimal.Decimal Amount = 2;
+    // Height is the neo blockchain height until the cheque is valid
     uint64 Height          = 3;
+    // MessageID is a nonce for uniq request (UUIDv4)
     bytes MessageID        = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
+    // Signature is a signature of the sent request
     bytes Signature        = 5;
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL             = 6;
 }
 message PutResponse {
+    // ID is cheque identifier
     bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
 }
 
 message ListRequest {
+    // OwnerID is a wallet address
     bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL    = 2;
 }
+
 message ListResponse {
+    // Item is a set of cheques with meta information
     repeated Item Items = 1;
 }
 
 message DeleteRequest {
+    // ID is cheque identifier
     bytes ID        = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
+    // OwnerID is a wallet address
     bytes OwnerID   = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // MessageID is a nonce for uniq request (UUIDv4)
     bytes MessageID = 3 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
+    // Signature is a signature of the sent request
     bytes Signature = 4;
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL      = 5;
 }
+
+// DeleteResponse is empty
 message DeleteResponse {}

bootstrap/service.proto

@@ -7,14 +7,19 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
-// The Bootstrap service definition.
+// Bootstrap service allows neofs-node to connect to the network. Node should
+// perform at least one bootstrap request in the epoch to stay in the network
+// for the next epoch.
 service Bootstrap {
+    // Process is method that allows to register node in the network and receive actual netmap
     rpc Process(Request) returns (bootstrap.SpreadMap);
 }
 
-// Request message to communicate between DHT nodes
 message Request {
+    // Type is NodeType, can be InnerRingNode (type=1) or StorageNode (type=2)
     int32              type = 1 [(gogoproto.customname) = "Type" , (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeType"];
+    // Info contains information about node
     bootstrap.NodeInfo info = 2 [(gogoproto.nullable) = false];
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL           = 3;
 }

bootstrap/types.proto

@@ -10,13 +10,19 @@ option (gogoproto.stringer_all) =  false;
 option (gogoproto.goproto_stringer_all) = false;
 
 message SpreadMap {
+    // Epoch is current epoch for netmap
     uint64 Epoch = 1;
+    // NetMap is a set of NodeInfos
     repeated NodeInfo NetMap = 2 [(gogoproto.nullable) = false];
 }
 
 message NodeInfo {
+    // Address is a node [multi-address](https://github.com/multiformats/multiaddr)
     string Address          = 1 [(gogoproto.jsontag) = "address"];
+    // PubKey is a compressed public key representation in bytes
     bytes PubKey            = 2 [(gogoproto.jsontag) = "pubkey,omitempty"];
+    // Options is set of node optional information, such as storage capacity, node location, price and etc
     repeated string Options = 3 [(gogoproto.jsontag) = "options,omitempty"];
+    // Status is bitmap status of the node
     uint64 Status           = 4 [(gogoproto.jsontag) = "status", (gogoproto.nullable) = false, (gogoproto.customtype) = "NodeStatus"];
 }

container/service.proto

@@ -8,61 +8,87 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+// Container service provides API for manipulating with the container.
 service Service {
-    // Create container
+    // Put request proposes container to the inner ring nodes. They will
+    // accept new container if user has enough deposit. All containers
+    // are accepted by the consensus, therefore it is asynchronous process.
     rpc Put(PutRequest) returns (PutResponse);
 
-    // Delete container ... discuss implementation later
+    // Delete container removes it from the inner ring container storage. It
+    // also asynchronous process done by consensus.
     rpc Delete(DeleteRequest) returns (DeleteResponse);
 
-    // Get container
+    // Get container returns container instance
     rpc Get(GetRequest) returns (GetResponse);
 
+    // List returns all user's containers
     rpc List(ListRequest) returns (ListResponse);
 }
 
-// NewRequest message to create new container
 message PutRequest {
+    // MessageID is a nonce for uniq container id calculation
     bytes MessageID            = 1 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
-    uint64 Capacity            = 2; // not actual size in megabytes, but probability of storage availability
+
+    // Capacity defines amount of data that can be stored in the container (doesn't used for now).
+    uint64 Capacity            = 2;
+
+    // OwnerID is a wallet address
     bytes OwnerID              = 3 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+
+    // Rules define storage policy for the object inside the container.
     netmap.PlacementRule rules = 4 [(gogoproto.nullable) = false];
+
+    // Signature of the user (owner id)
     bytes Signature            = 5;
+
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL                 = 6;
 }
 
-// PutResponse message to respond about container uuid
 message PutResponse {
+    // CID (container id) is a SHA256 hash of the container structure
     bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
 }
 
 message DeleteRequest {
+    // CID (container id) is a SHA256 hash of the container structure
     bytes CID       = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
+
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL      = 2;
+
+    // Signature of the container owner
     bytes Signature = 3;
 }
 
+// DeleteResponse is empty because delete operation is asynchronous and done
+// via consensus in inner ring nodes
 message DeleteResponse { }
 
 
-// GetRequest message to fetch container placement rules
 message GetRequest {
+    // CID (container id) is a SHA256 hash of the container structure
     bytes CID  = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
+
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL = 2;
 }
 
-// GetResponse message with container structure
 message GetResponse {
+    // Container is a structure that contains placement rules and owner id
     container.Container Container = 1;
 }
 
-// ListRequest message to list containers for user
 message ListRequest {
+    // OwnerID is a wallet address
     bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+
+    // TTL must be larger than zero, it decreased in every neofs-node
     uint32 TTL    = 2;
 }
 
-// ListResponse message to respond about all user containers
 message ListResponse {
+    // CID (container id) is list of SHA256 hashes of the container structures
     repeated bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
 }

container/types.proto

@@ -9,8 +9,8 @@ option (gogoproto.stable_marshaler_all) = true;
 
 // The Container service definition.
 message Container {
-    bytes OwnerID              = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
-    bytes Salt                 = 2 [(gogoproto.customtype) = "UUID",    (gogoproto.nullable) = false];
-    uint64 Capacity            = 3;
-    netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false];
+    bytes OwnerID              = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; // OwnerID is a wallet address.
+    bytes Salt                 = 2 [(gogoproto.customtype) = "UUID",    (gogoproto.nullable) = false]; // Salt is a nonce for unique container id calculation.
+    uint64 Capacity            = 3; // Capacity defines amount of data that can be stored in the container (doesn't used for now).
+    netmap.PlacementRule Rules = 4 [(gogoproto.nullable) = false]; // Rules define storage policy for the object inside the container.
 }

decimal/decimal.proto

@@ -6,9 +6,12 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+// Decimal is a structure used for representation of assets amount
 message Decimal {
     option (gogoproto.goproto_stringer) = false;
 
+    // Value is value number
     int64 Value = 1;
+    // Precision is precision number
     uint32 Precision = 2;
 }

docs/accounting.md

@@ -0,0 +1,488 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [accounting/service.proto](#accounting/service.proto)
+ - Services
+    - [Accounting](#accounting.Accounting)
+    
+  - Messages
+    - [BalanceRequest](#accounting.BalanceRequest)
+    - [BalanceResponse](#accounting.BalanceResponse)
+    
+
+- [accounting/types.proto](#accounting/types.proto)
+
+  - Messages
+    - [Account](#accounting.Account)
+    - [Balances](#accounting.Balances)
+    - [ContainerCreateTarget](#accounting.ContainerCreateTarget)
+    - [Lifetime](#accounting.Lifetime)
+    - [LockTarget](#accounting.LockTarget)
+    - [PayIO](#accounting.PayIO)
+    - [Settlement](#accounting.Settlement)
+    - [Settlement.Container](#accounting.Settlement.Container)
+    - [Settlement.Receiver](#accounting.Settlement.Receiver)
+    - [Settlement.Tx](#accounting.Settlement.Tx)
+    - [Tx](#accounting.Tx)
+    - [WithdrawTarget](#accounting.WithdrawTarget)
+    
+
+- [accounting/withdraw.proto](#accounting/withdraw.proto)
+ - Services
+    - [Withdraw](#accounting.Withdraw)
+    
+  - Messages
+    - [DeleteRequest](#accounting.DeleteRequest)
+    - [DeleteResponse](#accounting.DeleteResponse)
+    - [GetRequest](#accounting.GetRequest)
+    - [GetResponse](#accounting.GetResponse)
+    - [Item](#accounting.Item)
+    - [ListRequest](#accounting.ListRequest)
+    - [ListResponse](#accounting.ListResponse)
+    - [PutRequest](#accounting.PutRequest)
+    - [PutResponse](#accounting.PutResponse)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="accounting/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## accounting/service.proto
+
+
+
+
+<a name="accounting.Accounting"></a>
+
+### Service "accounting.Accounting"
+Accounting is a service that provides access for accounting balance
+information
+
+```
+rpc Balance(BalanceRequest) returns (BalanceResponse);
+
+```
+
+#### Method Balance
+
+Balance returns current balance status of the NeoFS user
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Balance | [BalanceRequest](#accounting.BalanceRequest) | [BalanceResponse](#accounting.BalanceResponse) |
+ <!-- end services -->
+
+
+<a name="accounting.BalanceRequest"></a>
+
+### Message BalanceRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="accounting.BalanceResponse"></a>
+
+### Message BalanceResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Balance | [decimal.Decimal](#decimal.Decimal) |  | Balance contains current account balance state |
+| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains information about locked funds. Locked funds appear when user pays for storage or withdraw assets. |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+<a name="accounting/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## accounting/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="accounting.Account"></a>
+
+### Message Account
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| Address | [string](#string) |  | Address is identifier of accounting record |
+| ParentAddress | [string](#string) |  | ParentAddress is identifier of parent accounting record |
+| ActiveFunds | [decimal.Decimal](#decimal.Decimal) |  | ActiveFunds is amount of active (non locked) funds for account |
+| Lifetime | [Lifetime](#accounting.Lifetime) |  | Lifetime is time until account is valid (used for lock accounts) |
+| LockTarget | [LockTarget](#accounting.LockTarget) |  | LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) |
+| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains child accounts with locked funds |
+
+
+<a name="accounting.Balances"></a>
+
+### Message Balances
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots |
+
+
+<a name="accounting.ContainerCreateTarget"></a>
+
+### Message ContainerCreateTarget
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) |  | CID is container identifier |
+
+
+<a name="accounting.Lifetime"></a>
+
+### Message Lifetime
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| unit | [Lifetime.Unit](#accounting.Lifetime.Unit) |  | Unit describes how lifetime is measured in account |
+| Value | [int64](#int64) |  | Value describes how long lifetime will be valid |
+
+
+<a name="accounting.LockTarget"></a>
+
+### Message LockTarget
+LockTarget must be one of two options
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| WithdrawTarget | [WithdrawTarget](#accounting.WithdrawTarget) |  | WithdrawTarget used when user requested withdraw |
+| ContainerCreateTarget | [ContainerCreateTarget](#accounting.ContainerCreateTarget) |  | ContainerCreateTarget used when user requested creation of container |
+
+
+<a name="accounting.PayIO"></a>
+
+### Message PayIO
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| BlockID | [uint64](#uint64) |  | BlockID contains id of the NEO block where withdraw or deposit call was invoked |
+| Transactions | [Tx](#accounting.Tx) | repeated | Transactions contains all transactions that founded in block and used for PayIO |
+
+
+<a name="accounting.Settlement"></a>
+
+### Message Settlement
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch contains an epoch when settlement was accepted |
+| Transactions | [Settlement.Tx](#accounting.Settlement.Tx) | repeated | Transactions is a set of transactions |
+
+
+<a name="accounting.Settlement.Container"></a>
+
+### Message Settlement.Container
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) |  | CID is container identifier |
+| SGIDs | [bytes](#bytes) | repeated | SGIDs is a set of storage groups that successfully passed the audit |
+
+
+<a name="accounting.Settlement.Receiver"></a>
+
+### Message Settlement.Receiver
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| To | [string](#string) |  | To is the address of funds recipient |
+| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount is the amount of funds that will be sent |
+
+
+<a name="accounting.Settlement.Tx"></a>
+
+### Message Settlement.Tx
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| From | [string](#string) |  | From is the address of the sender of funds |
+| Container | [Settlement.Container](#accounting.Settlement.Container) |  | Container that successfully had passed the audit |
+| Receivers | [Settlement.Receiver](#accounting.Settlement.Receiver) | repeated | Receivers is a set of addresses of funds recipients |
+
+
+<a name="accounting.Tx"></a>
+
+### Message Tx
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Tx.Type](#accounting.Tx.Type) |  | Type describes target of transaction |
+| From | [string](#string) |  | From describes sender of funds |
+| To | [string](#string) |  | To describes receiver of funds |
+| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount describes amount of funds |
+| PublicKeys | [bytes](#bytes) |  | PublicKeys contains public key of sender |
+
+
+<a name="accounting.WithdrawTarget"></a>
+
+### Message WithdrawTarget
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Cheque | [string](#string) |  | Cheque is a string representation of cheque id |
+
+ <!-- end messages -->
+
+
+<a name="accounting.Lifetime.Unit"></a>
+
+### Lifetime.Unit
+Unit can be Unlimited, based on NeoFS epoch or Neo block
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unlimited | 0 |  |
+| NeoFSEpoch | 1 |  |
+| NeoBlock | 2 |  |
+
+
+
+<a name="accounting.Tx.Type"></a>
+
+### Tx.Type
+Type can be withdrawal, payIO or inner
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unknown | 0 |  |
+| Withdraw | 1 |  |
+| PayIO | 2 |  |
+| Inner | 3 |  |
+
+
+ <!-- end enums -->
+
+
+
+<a name="accounting/withdraw.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## accounting/withdraw.proto
+
+
+
+
+<a name="accounting.Withdraw"></a>
+
+### Service "accounting.Withdraw"
+Withdraw is a service that provides withdraw assets operations from the NeoFS
+
+```
+rpc Get(GetRequest) returns (GetResponse);
+rpc Put(PutRequest) returns (PutResponse);
+rpc List(ListRequest) returns (ListResponse);
+rpc Delete(DeleteRequest) returns (DeleteResponse);
+
+```
+
+#### Method Get
+
+Get returns cheque if it was signed by inner ring nodes
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Get | [GetRequest](#accounting.GetRequest) | [GetResponse](#accounting.GetResponse) |
+#### Method Put
+
+Put ask inner ring nodes to sign a cheque for withdraw invoke
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Put | [PutRequest](#accounting.PutRequest) | [PutResponse](#accounting.PutResponse) |
+#### Method List
+
+List shows all user's checks
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| List | [ListRequest](#accounting.ListRequest) | [ListResponse](#accounting.ListResponse) |
+#### Method Delete
+
+Delete allows user to remove unused cheque
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Delete | [DeleteRequest](#accounting.DeleteRequest) | [DeleteResponse](#accounting.DeleteResponse) |
+ <!-- end services -->
+
+
+<a name="accounting.DeleteRequest"></a>
+
+### Message DeleteRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ID | [bytes](#bytes) |  | ID is cheque identifier |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| MessageID | [bytes](#bytes) |  | MessageID is a nonce for uniq request (UUIDv4) |
+| Signature | [bytes](#bytes) |  | Signature is a signature of the sent request |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="accounting.DeleteResponse"></a>
+
+### Message DeleteResponse
+DeleteResponse is empty
+
+
+
+<a name="accounting.GetRequest"></a>
+
+### Message GetRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ID | [bytes](#bytes) |  | ID is cheque identifier |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="accounting.GetResponse"></a>
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Withdraw | [Item](#accounting.Item) |  | Item is cheque with meta information |
+
+
+<a name="accounting.Item"></a>
+
+### Message Item
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ID | [bytes](#bytes) |  | ID is a cheque identifier |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount of funds |
+| Height | [uint64](#uint64) |  | Height is the neo blockchain height until the cheque is valid |
+| Payload | [bytes](#bytes) |  | Payload contains cheque representation in bytes |
+
+
+<a name="accounting.ListRequest"></a>
+
+### Message ListRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="accounting.ListResponse"></a>
+
+### Message ListResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information |
+
+
+<a name="accounting.PutRequest"></a>
+
+### Message PutRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount of funds |
+| Height | [uint64](#uint64) |  | Height is the neo blockchain height until the cheque is valid |
+| MessageID | [bytes](#bytes) |  | MessageID is a nonce for uniq request (UUIDv4) |
+| Signature | [bytes](#bytes) |  | Signature is a signature of the sent request |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="accounting.PutResponse"></a>
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ID | [bytes](#bytes) |  | ID is cheque identifier |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/bootstrap.md

@@ -0,0 +1,132 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [bootstrap/service.proto](#bootstrap/service.proto)
+ - Services
+    - [Bootstrap](#bootstrap.Bootstrap)
+    
+  - Messages
+    - [Request](#bootstrap.Request)
+    
+
+- [bootstrap/types.proto](#bootstrap/types.proto)
+
+  - Messages
+    - [NodeInfo](#bootstrap.NodeInfo)
+    - [SpreadMap](#bootstrap.SpreadMap)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="bootstrap/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bootstrap/service.proto
+
+
+
+
+<a name="bootstrap.Bootstrap"></a>
+
+### Service "bootstrap.Bootstrap"
+Bootstrap service allows neofs-node to connect to the network. Node should
+perform at least one bootstrap request in the epoch to stay in the network
+for the next epoch.
+
+```
+rpc Process(Request) returns (SpreadMap);
+
+```
+
+#### Method Process
+
+Process is method that allows to register node in the network and receive actual netmap
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Process | [Request](#bootstrap.Request) | [SpreadMap](#bootstrap.SpreadMap) |
+ <!-- end services -->
+
+
+<a name="bootstrap.Request"></a>
+
+### Message Request
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [int32](#int32) |  | Type is NodeType, can be InnerRingNode (type=1) or StorageNode (type=2) |
+| info | [NodeInfo](#bootstrap.NodeInfo) |  | Info contains information about node |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+<a name="bootstrap/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bootstrap/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="bootstrap.NodeInfo"></a>
+
+### Message NodeInfo
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Address | [string](#string) |  | Address is a node [multi-address](https://github.com/multiformats/multiaddr) |
+| PubKey | [bytes](#bytes) |  | PubKey is a compressed public key representation in bytes |
+| Options | [string](#string) | repeated | Options is set of node optional information, such as storage capacity, node location, price and etc |
+| Status | [uint64](#uint64) |  | Status is bitmap status of the node |
+
+
+<a name="bootstrap.SpreadMap"></a>
+
+### Message SpreadMap
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is current epoch for netmap |
+| NetMap | [NodeInfo](#bootstrap.NodeInfo) | repeated | NetMap is a set of NodeInfos |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/container.md

@@ -0,0 +1,232 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [container/service.proto](#container/service.proto)
+ - Services
+    - [Service](#container.Service)
+    
+  - Messages
+    - [DeleteRequest](#container.DeleteRequest)
+    - [DeleteResponse](#container.DeleteResponse)
+    - [GetRequest](#container.GetRequest)
+    - [GetResponse](#container.GetResponse)
+    - [ListRequest](#container.ListRequest)
+    - [ListResponse](#container.ListResponse)
+    - [PutRequest](#container.PutRequest)
+    - [PutResponse](#container.PutResponse)
+    
+
+- [container/types.proto](#container/types.proto)
+
+  - Messages
+    - [Container](#container.Container)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="container/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## container/service.proto
+
+
+
+
+<a name="container.Service"></a>
+
+### Service "container.Service"
+Container service provides API for manipulating with the container.
+
+```
+rpc Put(PutRequest) returns (PutResponse);
+rpc Delete(DeleteRequest) returns (DeleteResponse);
+rpc Get(GetRequest) returns (GetResponse);
+rpc List(ListRequest) returns (ListResponse);
+
+```
+
+#### Method Put
+
+Put request proposes container to the inner ring nodes. They will
+accept new container if user has enough deposit. All containers
+are accepted by the consensus, therefore it is asynchronous process.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Put | [PutRequest](#container.PutRequest) | [PutResponse](#container.PutResponse) |
+#### Method Delete
+
+Delete container removes it from the inner ring container storage. It
+also asynchronous process done by consensus.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Delete | [DeleteRequest](#container.DeleteRequest) | [DeleteResponse](#container.DeleteResponse) |
+#### Method Get
+
+Get container returns container instance
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Get | [GetRequest](#container.GetRequest) | [GetResponse](#container.GetResponse) |
+#### Method List
+
+List returns all user's containers
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| List | [ListRequest](#container.ListRequest) | [ListResponse](#container.ListResponse) |
+ <!-- end services -->
+
+
+<a name="container.DeleteRequest"></a>
+
+### Message DeleteRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) |  | CID (container id) is a SHA256 hash of the container structure |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+| Signature | [bytes](#bytes) |  | Signature of the container owner |
+
+
+<a name="container.DeleteResponse"></a>
+
+### Message DeleteResponse
+DeleteResponse is empty because delete operation is asynchronous and done
+via consensus in inner ring nodes
+
+
+
+<a name="container.GetRequest"></a>
+
+### Message GetRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) |  | CID (container id) is a SHA256 hash of the container structure |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="container.GetResponse"></a>
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Container | [Container](#container.Container) |  | Container is a structure that contains placement rules and owner id |
+
+
+<a name="container.ListRequest"></a>
+
+### Message ListRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="container.ListResponse"></a>
+
+### Message ListResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) | repeated | CID (container id) is list of SHA256 hashes of the container structures |
+
+
+<a name="container.PutRequest"></a>
+
+### Message PutRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| MessageID | [bytes](#bytes) |  | MessageID is a nonce for uniq container id calculation |
+| Capacity | [uint64](#uint64) |  | Capacity defines amount of data that can be stored in the container (doesn't used for now). |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| rules | [netmap.PlacementRule](#netmap.PlacementRule) |  | Rules define storage policy for the object inside the container. |
+| Signature | [bytes](#bytes) |  | Signature of the user (owner id) |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="container.PutResponse"></a>
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) |  | CID (container id) is a SHA256 hash of the container structure |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+<a name="container/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## container/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="container.Container"></a>
+
+### Message Container
+The Container service definition.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address. |
+| Salt | [bytes](#bytes) |  | Salt is a nonce for unique container id calculation. |
+| Capacity | [uint64](#uint64) |  | Capacity defines amount of data that can be stored in the container (doesn't used for now). |
+| Rules | [netmap.PlacementRule](#netmap.PlacementRule) |  | Rules define storage policy for the object inside the container. |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/decimal.md

@@ -0,0 +1,61 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [decimal/decimal.proto](#decimal/decimal.proto)
+
+  - Messages
+    - [Decimal](#decimal.Decimal)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="decimal/decimal.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## decimal/decimal.proto
+
+
+ <!-- end services -->
+
+
+<a name="decimal.Decimal"></a>
+
+### Message Decimal
+Decimal is a structure used for representation of assets amount
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Value | [int64](#int64) |  | Value is value number |
+| Precision | [uint32](#uint32) |  | Precision is precision number |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/object.md

@@ -0,0 +1,566 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [object/service.proto](#object/service.proto)
+ - Services
+    - [Service](#object.Service)
+    
+  - Messages
+    - [DeleteRequest](#object.DeleteRequest)
+    - [DeleteResponse](#object.DeleteResponse)
+    - [GetRangeHashRequest](#object.GetRangeHashRequest)
+    - [GetRangeHashResponse](#object.GetRangeHashResponse)
+    - [GetRangeRequest](#object.GetRangeRequest)
+    - [GetRangeResponse](#object.GetRangeResponse)
+    - [GetRequest](#object.GetRequest)
+    - [GetResponse](#object.GetResponse)
+    - [HeadRequest](#object.HeadRequest)
+    - [HeadResponse](#object.HeadResponse)
+    - [PutRequest](#object.PutRequest)
+    - [PutRequest.PutHeader](#object.PutRequest.PutHeader)
+    - [PutResponse](#object.PutResponse)
+    - [SearchRequest](#object.SearchRequest)
+    - [SearchResponse](#object.SearchResponse)
+    
+
+- [object/types.proto](#object/types.proto)
+
+  - Messages
+    - [CreationPoint](#object.CreationPoint)
+    - [Header](#object.Header)
+    - [IntegrityHeader](#object.IntegrityHeader)
+    - [Link](#object.Link)
+    - [Object](#object.Object)
+    - [Range](#object.Range)
+    - [StorageGroup](#object.StorageGroup)
+    - [StorageGroup.Lifetime](#object.StorageGroup.Lifetime)
+    - [SystemHeader](#object.SystemHeader)
+    - [Tombstone](#object.Tombstone)
+    - [Transform](#object.Transform)
+    - [UserHeader](#object.UserHeader)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="object/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## object/service.proto
+
+
+
+
+<a name="object.Service"></a>
+
+### Service "object.Service"
+Object service provides API for manipulating with the object.
+
+```
+rpc Get(GetRequest) returns (stream GetResponse);
+rpc Put(stream PutRequest) returns (PutResponse);
+rpc Delete(DeleteRequest) returns (DeleteResponse);
+rpc Head(HeadRequest) returns (HeadResponse);
+rpc Search(SearchRequest) returns (SearchResponse);
+rpc GetRange(GetRangeRequest) returns (GetRangeResponse);
+rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
+
+```
+
+#### Method Get
+
+Get the object from container. Response uses gRPC stream. First response
+message carry object of requested address. Chunk messages are parts of
+the object's payload if it is needed. All messages except first carry
+chunks. Requested object can be restored by concatenation of object
+message payload and all chunks keeping receiving order.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Get | [GetRequest](#object.GetRequest) | [GetResponse](#object.GetResponse) |
+#### Method Put
+
+Put the object into container. Request uses gRPC stream. First message
+SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD
+BE set. Session token SHOULD BE obtained before put operation (see
+session package). Chunk messages considered by server as part of object
+payload. All messages except first SHOULD BE chunks. Chunk messages
+SHOULD BE sent in direct order of fragmentation.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Put | [PutRequest](#object.PutRequest) | [PutResponse](#object.PutResponse) |
+#### Method Delete
+
+Delete the object from a container
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Delete | [DeleteRequest](#object.DeleteRequest) | [DeleteResponse](#object.DeleteResponse) |
+#### Method Head
+
+Head returns the object without data payload. Object in the
+response has system header only. If full headers flag is set, extended
+headers are also present.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Head | [HeadRequest](#object.HeadRequest) | [HeadResponse](#object.HeadResponse) |
+#### Method Search
+
+Search objects in container. Version of query language format SHOULD BE
+set to 1. Search query represented in serialized format (see query
+package).
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Search | [SearchRequest](#object.SearchRequest) | [SearchResponse](#object.SearchResponse) |
+#### Method GetRange
+
+GetRange of data payload. Ranges are set of pairs (offset, length).
+Fragments order in response corresponds to ranges order in request.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| GetRange | [GetRangeRequest](#object.GetRangeRequest) | [GetRangeResponse](#object.GetRangeResponse) |
+#### Method GetRangeHash
+
+GetRangeHash returns homomorphic hash of object payload range after XOR
+operation. Ranges are set of pairs (offset, length). Hashes order in
+response corresponds to ranges order in request. Homomorphic hash is
+calculated for XORed data.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| GetRangeHash | [GetRangeHashRequest](#object.GetRangeHashRequest) | [GetRangeHashResponse](#object.GetRangeHashResponse) |
+ <!-- end services -->
+
+
+<a name="object.DeleteRequest"></a>
+
+### Message DeleteRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+| Token | [session.Token](#session.Token) |  | Token with session public key and user's signature |
+
+
+<a name="object.DeleteResponse"></a>
+
+### Message DeleteResponse
+DeleteResponse is empty because we cannot guarantee permanent object removal
+in distributed system.
+
+
+
+<a name="object.GetRangeHashRequest"></a>
+
+### Message GetRangeHashRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+| Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to calculate homomorphic hash |
+| Salt | [bytes](#bytes) |  | Salt is used to XOR object's payload ranges before hashing, it can be nil |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="object.GetRangeHashResponse"></a>
+
+### Message GetRangeHashResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Hashes | [bytes](#bytes) | repeated | Homomorphic hashes of all ranges |
+
+
+<a name="object.GetRangeRequest"></a>
+
+### Message GetRangeRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+| Ranges | [Range](#object.Range) | repeated | Ranges of object's payload to return |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="object.GetRangeResponse"></a>
+
+### Message GetRangeResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Fragments | [bytes](#bytes) | repeated | Fragments of object's payload |
+
+
+<a name="object.GetRequest"></a>
+
+### Message GetRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="object.GetResponse"></a>
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| object | [Object](#object.Object) |  | Object header and some payload |
+| Chunk | [bytes](#bytes) |  | Chunk of remaining payload |
+
+
+<a name="object.HeadRequest"></a>
+
+### Message HeadRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+| FullHeaders | [bool](#bool) |  | FullHeaders can be set true for extended headers in the object |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="object.HeadResponse"></a>
+
+### Message HeadResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Object | [Object](#object.Object) |  | Object without payload |
+
+
+<a name="object.PutRequest"></a>
+
+### Message PutRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Header | [PutRequest.PutHeader](#object.PutRequest.PutHeader) |  | Header should be the first message in the stream |
+| Chunk | [bytes](#bytes) |  | Chunk should be a remaining message in stream should be chunks |
+
+
+<a name="object.PutRequest.PutHeader"></a>
+
+### Message PutRequest.PutHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Object | [Object](#object.Object) |  | Object with at least container id and owner id fields |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+| Token | [session.Token](#session.Token) |  | Token with session public key and user's signature |
+
+
+<a name="object.PutResponse"></a>
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Address | [refs.Address](#refs.Address) |  | Address of object (container id + object id) |
+
+
+<a name="object.SearchRequest"></a>
+
+### Message SearchRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch is set by user to 0, node set epoch to the actual value |
+| Version | [uint32](#uint32) |  | Version of search query format |
+| ContainerID | [bytes](#bytes) |  | ContainerID for searching the object |
+| Query | [bytes](#bytes) |  | Query in the binary serialized format |
+| TTL | [uint32](#uint32) |  | TTL must be larger than zero, it decreased in every neofs-node |
+
+
+<a name="object.SearchResponse"></a>
+
+### Message SearchResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+<a name="object/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## object/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="object.CreationPoint"></a>
+
+### Message CreationPoint
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| UnixTime | [int64](#int64) |  | Date of creation in unixtime format |
+| Epoch | [uint64](#uint64) |  | Date of creation in NeoFS epochs |
+
+
+<a name="object.Header"></a>
+
+### Message Header
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Link | [Link](#object.Link) |  | Link to other objects |
+| Redirect | [refs.Address](#refs.Address) |  | RedirectNot used yet |
+| UserHeader | [UserHeader](#object.UserHeader) |  | UserHeader defined by user |
+| Transform | [Transform](#object.Transform) |  | Transform defines transform operation (e.g. payload split) |
+| Tombstone | [Tombstone](#object.Tombstone) |  | Tombstone header that set up in deleted objects |
+| Verify | [session.VerificationHeader](#session.VerificationHeader) |  | Verify header that contains session public key and user's signature |
+| HomoHash | [bytes](#bytes) |  | Homomorphic hash of original object payload |
+| PayloadChecksum | [bytes](#bytes) |  | PayloadChecksum of actual object's payload |
+| Integrity | [IntegrityHeader](#object.IntegrityHeader) |  | Integrity header with checksum of all above headers in the object |
+| StorageGroup | [StorageGroup](#object.StorageGroup) |  | StorageGroup contains meta information for the data audit |
+
+
+<a name="object.IntegrityHeader"></a>
+
+### Message IntegrityHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| HeadersChecksum | [bytes](#bytes) |  | Checksum of all above headers in the object |
+| ChecksumSignature | [bytes](#bytes) |  | User's signature of checksum to verify if it is correct |
+
+
+<a name="object.Link"></a>
+
+### Message Link
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Link.Type](#object.Link.Type) |  | Link type |
+| ID | [bytes](#bytes) |  | Object id |
+
+
+<a name="object.Object"></a>
+
+### Message Object
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| SystemHeader | [SystemHeader](#object.SystemHeader) |  | System header |
+| Headers | [Header](#object.Header) | repeated | Extended headers |
+| Payload | [bytes](#bytes) |  | Object's payload |
+
+
+<a name="object.Range"></a>
+
+### Message Range
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Offset | [uint64](#uint64) |  | Offset of the data range |
+| Length | [uint64](#uint64) |  | Length of the data range |
+
+
+<a name="object.StorageGroup"></a>
+
+### Message StorageGroup
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ValidationDataSize | [uint64](#uint64) |  | Size of the all object's payloads included into storage group |
+| ValidationHash | [bytes](#bytes) |  | Homomorphic hash of all object's payloads included into storage group |
+| lifetime | [StorageGroup.Lifetime](#object.StorageGroup.Lifetime) |  | Time until storage group is valid |
+
+
+<a name="object.StorageGroup.Lifetime"></a>
+
+### Message StorageGroup.Lifetime
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) |  | Lifetime type |
+| Value | [int64](#int64) |  | Lifetime value |
+
+
+<a name="object.SystemHeader"></a>
+
+### Message SystemHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Version | [uint64](#uint64) |  | Version of the object structure |
+| PayloadLength | [uint64](#uint64) |  | Object payload length |
+| ID | [bytes](#bytes) |  | ObjectID is a UUID |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
+| CID | [bytes](#bytes) |  | ContainerID is a SHA256 hash of the container structure |
+| CreatedAt | [CreationPoint](#object.CreationPoint) |  | Timestamp of object creation |
+
+
+<a name="object.Tombstone"></a>
+
+### Message Tombstone
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) |  | Epoch when tombstone was created |
+
+
+<a name="object.Transform"></a>
+
+### Message Transform
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Transform.Type](#object.Transform.Type) |  | Type of object transformation |
+
+
+<a name="object.UserHeader"></a>
+
+### Message UserHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Key | [string](#string) |  | Key of the user's header |
+| Value | [string](#string) |  | Value of the user's header |
+
+ <!-- end messages -->
+
+
+<a name="object.Link.Type"></a>
+
+### Link.Type
+
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unknown | 0 |  |
+| Parent | 1 | Parent object created during object transformation |
+| Previous | 2 | Previous object in the linked list created during object transformation |
+| Next | 3 | Next object in the linked list created during object transformation |
+| Child | 4 | Child object created during object transformation |
+| StorageGroup | 5 | Object that included into this storage group |
+
+
+
+<a name="object.StorageGroup.Lifetime.Unit"></a>
+
+### StorageGroup.Lifetime.Unit
+
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unlimited | 0 | Storage group always valid |
+| NeoFSEpoch | 1 | Storage group is valid until lifetime NeoFS epoch |
+| UnixTime | 2 | Storage group is valid until lifetime unix timestamp |
+
+
+
+<a name="object.Transform.Type"></a>
+
+### Transform.Type
+
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unknown | 0 |  |
+| Split | 1 | Object created after payload split |
+| Sign | 2 | Object created after re-signing (doesn't used) |
+| Mould | 3 | Object created after filling missing headers in the object |
+
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/query.md

@@ -0,0 +1,86 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [query/types.proto](#query/types.proto)
+
+  - Messages
+    - [Filter](#query.Filter)
+    - [Query](#query.Query)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="query/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## query/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="query.Filter"></a>
+
+### Message Filter
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Filter.Type](#query.Filter.Type) |  | Type of filter |
+| Name | [string](#string) |  | Name of field that should be filtered |
+| Value | [string](#string) |  | Value that should be used for filter |
+
+
+<a name="query.Query"></a>
+
+### Message Query
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Filters | [Filter](#query.Filter) | repeated | Filters is set of filters, should not be empty |
+
+ <!-- end messages -->
+
+
+<a name="query.Filter.Type"></a>
+
+### Filter.Type
+Type can be Exact or Regex
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Exact | 0 |  |
+| Regex | 1 |  |
+
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/refs.md

@@ -0,0 +1,61 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [refs/types.proto](#refs/types.proto)
+
+  - Messages
+    - [Address](#refs.Address)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="refs/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## refs/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="refs.Address"></a>
+
+### Message Address
+Address of object (container id + object id)
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ObjectID | [bytes](#bytes) |  | ObjectID is an object identifier |
+| CID | [bytes](#bytes) |  | CID is container identifier |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/session.md

@@ -0,0 +1,149 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [session/service.proto](#session/service.proto)
+ - Services
+    - [Session](#session.Session)
+    
+  - Messages
+    - [CreateRequest](#session.CreateRequest)
+    - [CreateResponse](#session.CreateResponse)
+    
+
+- [session/types.proto](#session/types.proto)
+
+  - Messages
+    - [Token](#session.Token)
+    - [VerificationHeader](#session.VerificationHeader)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="session/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## session/service.proto
+
+
+
+
+<a name="session.Session"></a>
+
+### Service "session.Session"
+Open a trusted session to manipulate an object. In order to put or
+delete object client have to obtain session token with trusted node.
+Trusted node will modify client's object (add missing headers, checksums,
+homomorphic hash) and sign id with session key. Session is established
+during 4-step handshake in one gRPC stream
+
+```
+rpc Create(stream CreateRequest) returns (stream CreateResponse);
+
+```
+
+#### Method Create
+
+
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Create | [CreateRequest](#session.CreateRequest) | [CreateResponse](#session.CreateResponse) |
+ <!-- end services -->
+
+
+<a name="session.CreateRequest"></a>
+
+### Message CreateRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Init | [Token](#session.Token) |  | Message to init session opening. Carry: owner of manipulation object; ID of manipulation object; token lifetime bounds. |
+| Signed | [Token](#session.Token) |  | Signed Init message response (Unsigned) from server with user private key |
+
+
+<a name="session.CreateResponse"></a>
+
+### Message CreateResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Unsigned | [Token](#session.Token) |  | Unsigned token with token ID and session public key generated on server side |
+| Result | [Token](#session.Token) |  | Resulting token which can be used for object placing through an trusted intermediary |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+<a name="session/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## session/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="session.Token"></a>
+
+### Message Token
+User token granting rights for object manipulation
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Header | [VerificationHeader](#session.VerificationHeader) |  | Header carries verification data of session key |
+| OwnerID | [bytes](#bytes) |  | Owner of manipulation object |
+| FirstEpoch | [uint64](#uint64) |  | Initial epoch of token lifetime |
+| LastEpoch | [uint64](#uint64) |  | Last epoch of token lifetime |
+| ObjectID | [bytes](#bytes) | repeated | ID of manipulation object |
+| Signature | [bytes](#bytes) |  | Token signature. Signed by owner of manipulation object |
+| ID | [bytes](#bytes) |  | Token ID (UUID) |
+
+
+<a name="session.VerificationHeader"></a>
+
+### Message VerificationHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| PublicKey | [bytes](#bytes) |  | Session public key |
+| KeySignature | [bytes](#bytes) |  | Session public key signature. Signed by trusted side |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

docs/state.md

@@ -0,0 +1,137 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [state/service.proto](#state/service.proto)
+ - Services
+    - [Status](#state.Status)
+    
+  - Messages
+    - [HealthRequest](#state.HealthRequest)
+    - [HealthResponse](#state.HealthResponse)
+    - [MetricsRequest](#state.MetricsRequest)
+    - [MetricsResponse](#state.MetricsResponse)
+    - [NetmapRequest](#state.NetmapRequest)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="state/service.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## state/service.proto
+
+
+
+
+<a name="state.Status"></a>
+
+### Service "state.Status"
+Status service provides node's healthcheck and status info
+
+```
+rpc Netmap(NetmapRequest) returns (.bootstrap.SpreadMap);
+rpc Metrics(MetricsRequest) returns (MetricsResponse);
+rpc HealthCheck(HealthRequest) returns (HealthResponse);
+
+```
+
+#### Method Netmap
+
+Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap)
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Netmap | [NetmapRequest](#state.NetmapRequest) | [.bootstrap.SpreadMap](#bootstrap.SpreadMap) |
+#### Method Metrics
+
+Metrics request allows to receive metrics in prometheus format
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Metrics | [MetricsRequest](#state.MetricsRequest) | [MetricsResponse](#state.MetricsResponse) |
+#### Method HealthCheck
+
+HealthCheck request allows to check health status of the node.
+If node unhealthy field Status would contains detailed info.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| HealthCheck | [HealthRequest](#state.HealthRequest) | [HealthResponse](#state.HealthResponse) |
+ <!-- end services -->
+
+
+<a name="state.HealthRequest"></a>
+
+### Message HealthRequest
+HealthRequest message to check current state
+
+
+
+<a name="state.HealthResponse"></a>
+
+### Message HealthResponse
+HealthResponse message with current state
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Healthy | [bool](#bool) |  | Healthy is true when node alive and healthy |
+| Status | [string](#string) |  | Status contains detailed information about health status |
+
+
+<a name="state.MetricsRequest"></a>
+
+### Message MetricsRequest
+MetricsRequest message to request node metrics
+
+
+
+<a name="state.MetricsResponse"></a>
+
+### Message MetricsResponse
+MetricsResponse contains [][]byte,
+every []byte is marshaled MetricFamily proto message
+from github.com/prometheus/client_model/metrics.proto
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Metrics | [bytes](#bytes) | repeated |  |
+
+
+<a name="state.NetmapRequest"></a>
+
+### Message NetmapRequest
+NetmapRequest message to request current node netmap
+
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> 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 |
+| <a name="int64" /> 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 |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

object/service.proto

@@ -9,111 +9,132 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+// Object service provides API for manipulating with the object.
 service Service {
-    // Get the object from a container
+
+    // Get the object from container. Response uses gRPC stream. First response
+    // message carry object of requested address. Chunk messages are parts of
+    // the object's payload if it is needed. All messages except first carry
+    // chunks. Requested object can be restored by concatenation of object
+    // message payload and all chunks keeping receiving order.
     rpc Get(GetRequest) returns (stream GetResponse);
 
-    // Put the object into a container
+    // Put the object into container. Request uses gRPC stream. First message
+    // SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD
+    // BE set. Session token SHOULD BE obtained before put operation (see
+    // session package). Chunk messages considered by server as part of object
+    // payload. All messages except first SHOULD BE chunks. Chunk messages
+    // SHOULD BE sent in direct order of fragmentation.
     rpc Put(stream PutRequest) returns (PutResponse);
 
     // Delete the object from a container
     rpc Delete(DeleteRequest) returns (DeleteResponse);
 
-    // Get MetaInfo
+    // Head returns the object without data payload. Object in the
+    // response has system header only. If full headers flag is set, extended
+    // headers are also present.
     rpc Head(HeadRequest) returns (HeadResponse);
 
-    // Search by MetaInfo
+    // Search objects in container. Version of query language format SHOULD BE
+    // set to 1. Search query represented in serialized format (see query
+    // package).
     rpc Search(SearchRequest) returns (SearchResponse);
 
-    // Get ranges of object payload
+    // GetRange of data payload. Ranges are set of pairs (offset, length).
+    // Fragments order in response corresponds to ranges order in request.
     rpc GetRange(GetRangeRequest) returns (GetRangeResponse);
 
-    // Get hashes of object ranges
+    // GetRangeHash returns homomorphic hash of object payload range after XOR
+    // operation. Ranges are set of pairs (offset, length). Hashes order in
+    // response corresponds to ranges order in request. Homomorphic hash is
+    // calculated for XORed data.
     rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
 }
 
 message GetRequest {
-    uint64 Epoch         = 1;
-    refs.Address Address = 2 [(gogoproto.nullable) = false];
-    uint32 TTL           = 3;
+    uint64 Epoch         = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
+    uint32 TTL           = 3; // TTL must be larger than zero, it decreased in every neofs-node
 }
 
 message GetResponse {
     oneof R {
-        Object object = 1;
-        bytes Chunk   = 2;
+        Object object = 1; // Object header and some payload
+        bytes Chunk   = 2; // Chunk of remaining payload
     }
 }
 
 message PutRequest {
     message PutHeader {
-        uint64 Epoch        = 1;
-        Object Object       = 2;
-        uint32 TTL          = 3;
-        session.Token Token = 4;
+        uint64 Epoch        = 1; // Epoch is set by user to 0, node set epoch to the actual value
+        Object Object       = 2; // Object with at least container id and owner id fields
+        uint32 TTL          = 3; // TTL must be larger than zero, it decreased in every neofs-node
+        session.Token Token = 4; // Token with session public key and user's signature
     }
 
     oneof R {
-        PutHeader Header = 1;
-        bytes Chunk      = 2;
+        PutHeader Header = 1; // Header should be the first message in the stream
+        bytes Chunk      = 2; // Chunk should be a remaining message in stream should be chunks
     }
 }
 
 message PutResponse {
-    refs.Address Address = 1 [(gogoproto.nullable) = false];
+    refs.Address Address = 1 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
 }
 message DeleteRequest {
-    uint64 Epoch         = 1;
-    refs.Address Address = 2 [(gogoproto.nullable) = false];
-    bytes OwnerID        = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"];
-    uint32 TTL           = 4;
-    session.Token Token  = 5;
+    uint64 Epoch         = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    refs.Address Address = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
+    bytes OwnerID        = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "OwnerID"]; // OwnerID is a wallet address
+    uint32 TTL           = 4; // TTL must be larger than zero, it decreased in every neofs-node
+    session.Token Token  = 5; // Token with session public key and user's signature
 }
+
+// DeleteResponse is empty because we cannot guarantee permanent object removal
+// in distributed system.
 message DeleteResponse {}
 
-// HeadRequest.FullHeader == true, for fetch all headers
 message HeadRequest {
-    uint64 Epoch         = 1;
-    refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"];
-    bool FullHeaders     = 3;
-    uint32 TTL           = 4;
+    uint64 Epoch         = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    refs.Address Address = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "Address"]; // Address of object (container id + object id)
+    bool FullHeaders     = 3; // FullHeaders can be set true for extended headers in the object
+    uint32 TTL           = 4; // TTL must be larger than zero, it decreased in every neofs-node
 }
 message HeadResponse {
-    Object Object = 1;
+    Object Object = 1; // Object without payload
 }
 
 message SearchRequest {
-    uint64 Epoch         = 1;
-    uint32 Version       = 2;
-    bytes ContainerID    = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"];
-    bytes Query          = 4;
-    uint32 TTL           = 5;
+    uint64 Epoch         = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    uint32 Version       = 2; // Version of search query format
+    bytes ContainerID    = 3 [(gogoproto.nullable) = false, (gogoproto.customtype) = "CID"]; // ContainerID for searching the object
+    bytes Query          = 4; // Query in the binary serialized format
+    uint32 TTL           = 5; // TTL must be larger than zero, it decreased in every neofs-node
 }
 
 message SearchResponse {
-    repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false];
+    repeated refs.Address Addresses = 1 [(gogoproto.nullable) = false]; // Addresses of found objects
 }
 
 message GetRangeRequest {
-    uint64 Epoch          = 1;
-    refs.Address Address  = 2 [(gogoproto.nullable) = false];
-    repeated Range Ranges = 3 [(gogoproto.nullable) = false];
-    uint32 TTL            = 4;
+    uint64 Epoch          = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    refs.Address Address  = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
+    repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to return
+    uint32 TTL            = 4; // TTL must be larger than zero, it decreased in every neofs-node
 }
 
 message GetRangeResponse {
-    repeated bytes Fragments = 1;
+    repeated bytes Fragments = 1; // Fragments of object's payload
 }
 
 message GetRangeHashRequest {
-    uint64 Epoch          = 1;
-    refs.Address Address  = 2 [(gogoproto.nullable) = false];
-    repeated Range Ranges = 3 [(gogoproto.nullable) = false];
-    bytes Salt            = 4;
-    uint32 TTL            = 5;
+    uint64 Epoch          = 1; // Epoch is set by user to 0, node set epoch to the actual value
+    refs.Address Address  = 2 [(gogoproto.nullable) = false]; // Address of object (container id + object id)
+    repeated Range Ranges = 3 [(gogoproto.nullable) = false]; // Ranges of object's payload to calculate homomorphic hash
+    bytes Salt            = 4; // Salt is used to XOR object's payload ranges before hashing, it can be nil
+    uint32 TTL            = 5; // TTL must be larger than zero, it decreased in every neofs-node
 }
 
 message GetRangeHashResponse {
-    repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false];
+    repeated bytes Hashes = 1 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hashes of all ranges
 }
 

object/types.proto

@@ -9,99 +9,97 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 option (gogoproto.stable_marshaler_all) = true;
 
 message Range {
-    uint64 Offset = 1;
-    uint64 Length = 2;
+    uint64 Offset = 1; // Offset of the data range
+    uint64 Length = 2; // Length of the data range
 }
 
 message UserHeader {
-    string Key = 1;
-    string Value = 2;
+    string Key   = 1; // Key of the user's header
+    string Value = 2; // Value of the user's header
 }
 
 message Header {
     oneof Value {
-        Link Link                         = 1;
-        refs.Address Redirect             = 2;
-        UserHeader UserHeader             = 3;
-        Transform Transform               = 4;
-        Tombstone Tombstone               = 5;
-        // session-related info: session.VerificationHeader
-        session.VerificationHeader Verify = 6;
-        // integrity-related info
-        bytes HomoHash                    = 7 [(gogoproto.customtype) = "Hash"];
-        bytes PayloadChecksum             = 8;
-        IntegrityHeader Integrity         = 9;
-        StorageGroup StorageGroup         = 10;
+        Link Link                         = 1;  // Link to other objects
+        refs.Address Redirect             = 2;  // RedirectNot used yet
+        UserHeader UserHeader             = 3;  // UserHeader defined by user
+        Transform Transform               = 4;  // Transform defines transform operation (e.g. payload split)
+        Tombstone Tombstone               = 5;  // Tombstone header that set up in deleted objects
+        session.VerificationHeader Verify = 6;  // Verify header that contains session public key and user's signature
+        bytes HomoHash                    = 7 [(gogoproto.customtype) = "Hash"]; // Homomorphic hash of original object payload
+        bytes PayloadChecksum             = 8;  // PayloadChecksum of actual object's payload
+        IntegrityHeader Integrity         = 9;  // Integrity header with checksum of all above headers in the object
+        StorageGroup StorageGroup         = 10; // StorageGroup contains meta information for the data audit
     }
 }
 
 message Tombstone {
-    uint64 Epoch = 1;
+    uint64 Epoch = 1; // Epoch when tombstone was created
 }
 
 message SystemHeader {
-    uint64 Version       = 1;
-    uint64 PayloadLength = 2;
+    uint64 Version       = 1; // Version of the object structure
+    uint64 PayloadLength = 2; // Object payload length
 
-    bytes ID        = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false];
-    bytes OwnerID   = 4 [(gogoproto.customtype) = "OwnerID",  (gogoproto.nullable) = false];
-    bytes CID       = 5 [(gogoproto.customtype) = "CID",      (gogoproto.nullable) = false];
-    CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false];
+    bytes ID        = 3 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // ObjectID is a UUID
+    bytes OwnerID   = 4 [(gogoproto.customtype) = "OwnerID",  (gogoproto.nullable) = false]; // OwnerID is a wallet address
+    bytes CID       = 5 [(gogoproto.customtype) = "CID",      (gogoproto.nullable) = false]; // ContainerID is a SHA256 hash of the container structure
+    CreationPoint CreatedAt = 6 [(gogoproto.nullable) = false]; // Timestamp of object creation
 }
 
 message CreationPoint {
-    int64 UnixTime = 1;
-    uint64 Epoch = 2;
+    int64 UnixTime = 1; // Date of creation in unixtime format
+    uint64 Epoch   = 2; // Date of creation in NeoFS epochs
 }
 
 message IntegrityHeader {
-    bytes HeadersChecksum   = 1;
-    bytes ChecksumSignature = 2;
+    bytes HeadersChecksum   = 1; // Checksum of all above headers in the object
+    bytes ChecksumSignature = 2; // User's signature of checksum to verify if it is correct
 }
 
 message Link {
     enum Type {
         Unknown      = 0;
-        Parent       = 1;
-        Previous     = 2;
-        Next         = 3;
-        Child        = 4;
-        StorageGroup = 5;
+        Parent       = 1; // Parent object created during object transformation
+        Previous     = 2; // Previous object in the linked list created during object transformation
+        Next         = 3; // Next object in the linked list created during object transformation
+        Child        = 4; // Child object created during object transformation
+        StorageGroup = 5; // Object that included into this storage group
     }
-    Type type  = 1;
-    bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false];
+    Type type  = 1; // Link type
+    bytes ID = 2 [(gogoproto.customtype) = "ID", (gogoproto.nullable) = false]; // Object id
 }
 
 message Transform {
     enum Type {
         Unknown = 0;
-        Split   = 1;
-        Sign    = 2;
-        Mould   = 3;
+        Split   = 1; // Object created after payload split
+        Sign    = 2; // Object created after re-signing (doesn't used)
+        Mould   = 3; // Object created after filling missing headers in the object
     }
-    Type type  = 1;
+    Type type  = 1; // Type of object transformation
 }
 
 message Object {
-    SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false];
-    repeated Header Headers   = 2 [(gogoproto.nullable) = false];
-    bytes Payload             = 3;
+    SystemHeader SystemHeader = 1 [(gogoproto.nullable) = false]; // System header
+    repeated Header Headers   = 2 [(gogoproto.nullable) = false]; // Extended headers
+    bytes Payload             = 3; // Object's payload
 }
 
 message StorageGroup {
-    uint64 ValidationDataSize = 1;
-    bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false];
+    uint64 ValidationDataSize = 1; // Size of the all object's payloads included into storage group
+    bytes ValidationHash = 2 [(gogoproto.customtype) = "Hash", (gogoproto.nullable) = false]; // Homomorphic hash of all object's payloads included into storage group
 
     message Lifetime {
         enum Unit {
-            Unlimited = 0;
-            NeoFSEpoch = 1;
-            UnixTime = 2;
+            Unlimited = 0;  // Storage group always valid
+            NeoFSEpoch = 1; // Storage group is valid until lifetime NeoFS epoch
+            UnixTime = 2;   // Storage group is valid until lifetime unix timestamp
         }
 
-        Unit unit = 1 [(gogoproto.customname) = "Unit"];
-        int64 Value = 2;
+        Unit unit = 1 [(gogoproto.customname) = "Unit"]; // Lifetime type
+        int64 Value = 2; // Lifetime value
     }
 
-    Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"];
+    Lifetime lifetime = 3 [(gogoproto.customname) = "Lifetime"]; // Time until storage group is valid
 }

query/types.proto

@@ -9,17 +9,23 @@ option (gogoproto.stable_marshaler_all) = true;
 message Filter {
     option (gogoproto.goproto_stringer) = false;
 
+    // Type can be Exact or Regex
     enum Type {
         Exact = 0;
         Regex = 1;
     }
+
+    // Type of filter
     Type type = 1 [(gogoproto.customname) = "Type"];
+    // Name of field that should be filtered
     string Name = 2;
+    // Value that should be used for filter
     string Value = 3;
 }
 
 message Query {
     option (gogoproto.goproto_stringer) = false;
 
+    // Filters is set of filters, should not be empty
     repeated Filter Filters = 1 [(gogoproto.nullable) = false];
 }

refs/types.proto

@@ -9,7 +9,10 @@ option (gogoproto.stable_marshaler_all) = true;
 option (gogoproto.stringer_all) =  false;
 option (gogoproto.goproto_stringer_all) = false;
 
+// Address of object (container id + object id)
 message Address {
-    bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false]; // UUID
-    bytes CID      = 2[(gogoproto.customtype) = "CID",      (gogoproto.nullable) = false]; // sha256
+    // ObjectID is an object identifier
+    bytes ObjectID = 1[(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
+    // CID is container identifier
+    bytes CID      = 2[(gogoproto.customtype) = "CID",      (gogoproto.nullable) = false];
 }

session/service.proto

@@ -7,21 +7,41 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
+
 service Session {
+    // Open a trusted session to manipulate an object. In order to put or
+    // delete object client have to obtain session token with trusted node.
+    // Trusted node will modify client's object (add missing headers, checksums,
+    // homomorphic hash) and sign id with session key. Session is established
+    // during 4-step handshake in one gRPC stream
+
+    // - First client stream message SHOULD BE type of `CreateRequest_Init`.
+    // - First server stream message SHOULD BE type of `CreateResponse_Unsigned`.
+    // - Second client stream message SHOULD BE type of `CreateRequest_Signed`.
+    // - Second server stream message SHOULD BE type of `CreateResponse_Result`.
+
     rpc Create (stream CreateRequest) returns (stream CreateResponse);
 }
 
 
 message CreateRequest {
+    // Message should be one of
     oneof Message {
+        // Message to init session opening. Carry:
+        // owner of manipulation object;
+        // ID of manipulation object;
+        // token lifetime bounds.
         session.Token Init = 1;
+        // Signed Init message response (Unsigned) from server with user private key
         session.Token Signed = 2;
     }
 }
 
 message CreateResponse {
     oneof Message {
+        // Unsigned token with token ID and session public key generated on server side
         session.Token Unsigned = 1;
+        // Resulting token which can be used for object placing through an trusted intermediary
         session.Token Result = 2;
     }
 }

session/types.proto

@@ -7,16 +7,26 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 option (gogoproto.stable_marshaler_all) = true;
 
 message VerificationHeader {
+    // Session public key
     bytes PublicKey = 1;
+    // Session public key signature. Signed by trusted side
     bytes KeySignature = 2;
 }
 
+// User token granting rights for object manipulation
 message Token {
+    // Header carries verification data of session key
     VerificationHeader Header = 1 [(gogoproto.nullable) = false];
+    // Owner of manipulation object
     bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
+    // Initial epoch of token lifetime
     uint64 FirstEpoch = 3;
+    // Last epoch of token lifetime
     uint64 LastEpoch = 4;
+    // ID of manipulation object
     repeated bytes ObjectID = 5 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
+    // Token signature. Signed by owner of manipulation object
     bytes Signature = 6;
+    // Token ID (UUID)
     bytes ID = 7 [(gogoproto.customtype) = "TokenID", (gogoproto.nullable) = false];
 }

state/service.proto

@@ -7,10 +7,14 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
-// The Status service definition.
+// Status service provides node's healthcheck and status info
 service Status {
+    // Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap)
     rpc Netmap(NetmapRequest) returns (bootstrap.SpreadMap);
+    // Metrics request allows to receive metrics in prometheus format
     rpc Metrics(MetricsRequest) returns (MetricsResponse);
+    // HealthCheck request allows to check health status of the node.
+    // If node unhealthy field Status would contains detailed info.
     rpc HealthCheck(HealthRequest) returns (HealthResponse);
 }
 
@@ -32,6 +36,8 @@ message HealthRequest {}
 
 // HealthResponse message with current state
 message HealthResponse {
+    // Healthy is true when node alive and healthy
     bool Healthy  = 1;
+    // Status contains detailed information about health status
     string Status = 2;
 }