diff --git a/.github/markdown.tmpl b/.github/markdown.tmpl
new file mode 100644
index 00000000..f945c137
--- /dev/null
+++ b/.github/markdown.tmpl
@@ -0,0 +1,83 @@
+# Protocol Documentation
+
+
+## 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}}
+
+Top
+
+## {{.Name}}
+{{.Description}}
+
+{{range .Services}}
+
+
+
+### 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}}
+
+{{range .Messages}}
+
+
+### 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}}
+
+{{range .Enums}}
+
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+ | {{.Name}} | {{.Number}} | {{nobr .Description}} |
+{{end}}
+
+{{end}}
+
+{{end}}
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+{{range .Scalars -}}
+ | {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} |
+{{end}}
diff --git a/Makefile b/Makefile
index c17477a8..64b09397 100644
--- a/Makefile
+++ b/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
diff --git a/README.md b/README.md
index 9247a10f..a6662c35 100644
--- a/README.md
+++ b/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
diff --git a/accounting/service.pb.go b/accounting/service.pb.go
index 8708db37..ea86a8ea 100644
Binary files a/accounting/service.pb.go and b/accounting/service.pb.go differ
diff --git a/accounting/service.proto b/accounting/service.proto
index b75bf9c9..f975c232 100644
--- a/accounting/service.proto
+++ b/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;
}
diff --git a/accounting/types.pb.go b/accounting/types.pb.go
index cb4b0c8a..dd020ec9 100644
Binary files a/accounting/types.pb.go and b/accounting/types.pb.go differ
diff --git a/accounting/types.proto b/accounting/types.proto
index 1b4e7838..ac512b91 100644
--- a/accounting/types.proto
+++ b/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;
}
diff --git a/accounting/withdraw.pb.go b/accounting/withdraw.pb.go
index 967a2ce0..b50bc1c3 100644
Binary files a/accounting/withdraw.pb.go and b/accounting/withdraw.pb.go differ
diff --git a/accounting/withdraw.proto b/accounting/withdraw.proto
index c099ef7c..33ce402f 100644
--- a/accounting/withdraw.proto
+++ b/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 {}
diff --git a/bootstrap/service.pb.go b/bootstrap/service.pb.go
index 2fcdb4d2..14f8e9e8 100644
Binary files a/bootstrap/service.pb.go and b/bootstrap/service.pb.go differ
diff --git a/bootstrap/service.proto b/bootstrap/service.proto
index 3c9dcedc..a0f82dca 100644
--- a/bootstrap/service.proto
+++ b/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;
}
diff --git a/bootstrap/types.pb.go b/bootstrap/types.pb.go
index a90de05b..f2799198 100644
Binary files a/bootstrap/types.pb.go and b/bootstrap/types.pb.go differ
diff --git a/bootstrap/types.proto b/bootstrap/types.proto
index 4d6e458b..5a566dae 100644
--- a/bootstrap/types.proto
+++ b/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"];
}
diff --git a/container/service.pb.go b/container/service.pb.go
index bc2e8315..9cc6991a 100644
Binary files a/container/service.pb.go and b/container/service.pb.go differ
diff --git a/container/service.proto b/container/service.proto
index a3b72ca8..72c08993 100644
--- a/container/service.proto
+++ b/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];
}
diff --git a/container/types.proto b/container/types.proto
index b05001fb..efcaee82 100644
--- a/container/types.proto
+++ b/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.
}
diff --git a/decimal/decimal.pb.go b/decimal/decimal.pb.go
index e125af41..d2bed7d3 100644
Binary files a/decimal/decimal.pb.go and b/decimal/decimal.pb.go differ
diff --git a/decimal/decimal.proto b/decimal/decimal.proto
index 31bb9636..42cf2df4 100644
--- a/decimal/decimal.proto
+++ b/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;
}
diff --git a/docs/.gitkeep b/docs/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/accounting.md b/docs/accounting.md
new file mode 100644
index 00000000..f08bd52d
--- /dev/null
+++ b/docs/accounting.md
@@ -0,0 +1,488 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## accounting/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+### 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. |
+
+
+
+
+
+
+
+
+Top
+
+## accounting/types.proto
+
+
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message Balances
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots |
+
+
+
+
+### Message ContainerCreateTarget
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) | | CID is container identifier |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### Message WithdrawTarget
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Cheque | [string](#string) | | Cheque is a string representation of cheque id |
+
+
+
+
+
+
+### Lifetime.Unit
+Unit can be Unlimited, based on NeoFS epoch or Neo block
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unlimited | 0 | |
+| NeoFSEpoch | 1 | |
+| NeoBlock | 2 | |
+
+
+
+
+
+### Tx.Type
+Type can be withdrawal, payIO or inner
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Unknown | 0 | |
+| Withdraw | 1 | |
+| PayIO | 2 | |
+| Inner | 3 | |
+
+
+
+
+
+
+
+Top
+
+## accounting/withdraw.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message DeleteResponse
+DeleteResponse is empty
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Withdraw | [Item](#accounting.Item) | | Item is cheque with meta information |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### Message ListResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Items | [Item](#accounting.Item) | repeated | Item is a set of cheques with meta information |
+
+
+
+
+### 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 |
+
+
+
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ID | [bytes](#bytes) | | ID is cheque identifier |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/bootstrap.md b/docs/bootstrap.md
new file mode 100644
index 00000000..dfada2c6
--- /dev/null
+++ b/docs/bootstrap.md
@@ -0,0 +1,132 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## bootstrap/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+
+
+
+
+Top
+
+## bootstrap/types.proto
+
+
+
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/container.md b/docs/container.md
new file mode 100644
index 00000000..5ff0d891
--- /dev/null
+++ b/docs/container.md
@@ -0,0 +1,232 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## container/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message DeleteResponse
+DeleteResponse is empty because delete operation is asynchronous and done
+via consensus in inner ring nodes
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Container | [Container](#container.Container) | | Container is a structure that contains placement rules and owner id |
+
+
+
+
+### 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 |
+
+
+
+
+### Message ListResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) | repeated | CID (container id) is list of SHA256 hashes of the container structures |
+
+
+
+
+### 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 |
+
+
+
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| CID | [bytes](#bytes) | | CID (container id) is a SHA256 hash of the container structure |
+
+
+
+
+
+
+
+
+Top
+
+## container/types.proto
+
+
+
+
+
+
+
+### 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. |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/decimal.md b/docs/decimal.md
new file mode 100644
index 00000000..62acb863
--- /dev/null
+++ b/docs/decimal.md
@@ -0,0 +1,61 @@
+# Protocol Documentation
+
+
+## Table of Contents
+
+- [decimal/decimal.proto](#decimal/decimal.proto)
+
+ - Messages
+ - [Decimal](#decimal.Decimal)
+
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+
+Top
+
+## decimal/decimal.proto
+
+
+
+
+
+
+
+### 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 |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/object.md b/docs/object.md
new file mode 100644
index 00000000..5ba1845b
--- /dev/null
+++ b/docs/object.md
@@ -0,0 +1,566 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## object/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message DeleteResponse
+DeleteResponse is empty because we cannot guarantee permanent object removal
+in distributed system.
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message GetRangeHashResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Hashes | [bytes](#bytes) | repeated | Homomorphic hashes of all ranges |
+
+
+
+
+### 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 |
+
+
+
+
+### Message GetRangeResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Fragments | [bytes](#bytes) | repeated | Fragments of object's payload |
+
+
+
+
+### 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 |
+
+
+
+
+### Message GetResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| object | [Object](#object.Object) | | Object header and some payload |
+| Chunk | [bytes](#bytes) | | Chunk of remaining payload |
+
+
+
+
+### 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 |
+
+
+
+
+### Message HeadResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Object | [Object](#object.Object) | | Object without payload |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### Message PutResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Address | [refs.Address](#refs.Address) | | Address of object (container id + object id) |
+
+
+
+
+### 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 |
+
+
+
+
+### Message SearchResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Addresses | [refs.Address](#refs.Address) | repeated | Addresses of found objects |
+
+
+
+
+
+
+
+
+Top
+
+## object/types.proto
+
+
+
+
+
+
+
+### Message CreationPoint
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| UnixTime | [int64](#int64) | | Date of creation in unixtime format |
+| Epoch | [uint64](#uint64) | | Date of creation in NeoFS epochs |
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+### Message Link
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Link.Type](#object.Link.Type) | | Link type |
+| ID | [bytes](#bytes) | | Object id |
+
+
+
+
+### 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 |
+
+
+
+
+### Message Range
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Offset | [uint64](#uint64) | | Offset of the data range |
+| Length | [uint64](#uint64) | | Length of the data range |
+
+
+
+
+### 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 |
+
+
+
+
+### Message StorageGroup.Lifetime
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| unit | [StorageGroup.Lifetime.Unit](#object.StorageGroup.Lifetime.Unit) | | Lifetime type |
+| Value | [int64](#int64) | | Lifetime value |
+
+
+
+
+### 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 |
+
+
+
+
+### Message Tombstone
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Epoch | [uint64](#uint64) | | Epoch when tombstone was created |
+
+
+
+
+### Message Transform
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [Transform.Type](#object.Transform.Type) | | Type of object transformation |
+
+
+
+
+### Message UserHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Key | [string](#string) | | Key of the user's header |
+| Value | [string](#string) | | Value of the user's header |
+
+
+
+
+
+
+### 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 |
+
+
+
+
+
+### 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 |
+
+
+
+
+
+### 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 |
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/query.md b/docs/query.md
new file mode 100644
index 00000000..9deb2c19
--- /dev/null
+++ b/docs/query.md
@@ -0,0 +1,86 @@
+# Protocol Documentation
+
+
+## Table of Contents
+
+- [query/types.proto](#query/types.proto)
+
+ - Messages
+ - [Filter](#query.Filter)
+ - [Query](#query.Query)
+
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+
+Top
+
+## query/types.proto
+
+
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message Query
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| Filters | [Filter](#query.Filter) | repeated | Filters is set of filters, should not be empty |
+
+
+
+
+
+
+### Filter.Type
+Type can be Exact or Regex
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| Exact | 0 | |
+| Regex | 1 | |
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/refs.md b/docs/refs.md
new file mode 100644
index 00000000..c3051ab2
--- /dev/null
+++ b/docs/refs.md
@@ -0,0 +1,61 @@
+# Protocol Documentation
+
+
+## Table of Contents
+
+- [refs/types.proto](#refs/types.proto)
+
+ - Messages
+ - [Address](#refs.Address)
+
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+
+Top
+
+## refs/types.proto
+
+
+
+
+
+
+
+### 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 |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/session.md b/docs/session.md
new file mode 100644
index 00000000..8ea703e9
--- /dev/null
+++ b/docs/session.md
@@ -0,0 +1,149 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## session/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### 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 |
+
+
+
+
+### 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 |
+
+
+
+
+
+
+
+
+Top
+
+## session/types.proto
+
+
+
+
+
+
+
+### 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) |
+
+
+
+
+### Message VerificationHeader
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| PublicKey | [bytes](#bytes) | | Session public key |
+| KeySignature | [bytes](#bytes) | | Session public key signature. Signed by trusted side |
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/docs/state.md b/docs/state.md
new file mode 100644
index 00000000..6d240c1d
--- /dev/null
+++ b/docs/state.md
@@ -0,0 +1,137 @@
+# Protocol Documentation
+
+
+## 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)
+
+
+
+
+Top
+
+## state/service.proto
+
+
+
+
+
+
+### 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) |
+
+
+
+
+
+### Message HealthRequest
+HealthRequest message to check current state
+
+
+
+
+
+### 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 |
+
+
+
+
+### Message MetricsRequest
+MetricsRequest message to request node metrics
+
+
+
+
+
+### 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 | |
+
+
+
+
+### Message NetmapRequest
+NetmapRequest message to request current node netmap
+
+
+
+
+
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| double | | double | double | float |
+| float | | float | float | float |
+| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| sfixed32 | Always four bytes. | int32 | int | int |
+| sfixed64 | Always eight bytes. | int64 | long | int/long |
+| bool | | bool | boolean | boolean |
+| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/object/service.pb.go b/object/service.pb.go
index aede5cda..8301ebb6 100644
Binary files a/object/service.pb.go and b/object/service.pb.go differ
diff --git a/object/service.proto b/object/service.proto
index 0a033838..6f13d55c 100644
--- a/object/service.proto
+++ b/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
}
diff --git a/object/types.proto b/object/types.proto
index a7cbd8c7..30e468ec 100644
--- a/object/types.proto
+++ b/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
}
diff --git a/query/types.pb.go b/query/types.pb.go
index 51f682eb..8fa3dbeb 100644
Binary files a/query/types.pb.go and b/query/types.pb.go differ
diff --git a/query/types.proto b/query/types.proto
index 5f460724..884a6bd1 100644
--- a/query/types.proto
+++ b/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];
}
diff --git a/refs/types.pb.go b/refs/types.pb.go
index 33f7578a..87f3fced 100644
Binary files a/refs/types.pb.go and b/refs/types.pb.go differ
diff --git a/refs/types.proto b/refs/types.proto
index e607f349..15355ae0 100644
--- a/refs/types.proto
+++ b/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];
}
diff --git a/session/service.pb.go b/session/service.pb.go
index da85708c..4961b0d2 100644
Binary files a/session/service.pb.go and b/session/service.pb.go differ
diff --git a/session/service.proto b/session/service.proto
index ee56a220..484425bc 100644
--- a/session/service.proto
+++ b/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;
}
}
diff --git a/session/types.pb.go b/session/types.pb.go
index ce0e0a4e..d39961e8 100644
Binary files a/session/types.pb.go and b/session/types.pb.go differ
diff --git a/session/types.proto b/session/types.proto
index 8989040d..bf804bf4 100644
--- a/session/types.proto
+++ b/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];
}
diff --git a/state/service.pb.go b/state/service.pb.go
index f71dad6b..a3684101 100644
Binary files a/state/service.pb.go and b/state/service.pb.go differ
diff --git a/state/service.proto b/state/service.proto
index d0e59b4f..3c85d860 100644
--- a/state/service.proto
+++ b/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;
}