Documentation improvements

README.md

@@ -13,8 +13,8 @@
 
 NeoFS-API repository is the basis for language-specific libraries, e.g.:
 
-- [neofs-api-go](https://github.com/nspcc-dev/neofs-api-go)
-- [neofs-api-csharp](https://github.com/nspcc-dev/neofs-api-csharp)
+- [neofs-sdk-go](https://github.com/nspcc-dev/neofs-sdk-go) (see `proto` package there for vanilla API)
+- [neofs-api-csharp](https://github.com/neo-ngd/neofs-api-csharp)
 
 Those libraries contain compiled protocol buffers definitions, wrapped with
 language-specific code. Use them to integrate applications with NeoFS.

accounting/service.proto

@@ -7,7 +7,7 @@ import "refs/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Accounting";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting";
 
 // Accounting service provides methods for interaction with FS chain via
 // other NeoFS nodes to get information about the account balance. Deposit and

accounting/types.proto

@@ -3,7 +3,7 @@ syntax = "proto3";
 package neo.fs.v2.accounting;
 
 option csharp_namespace = "Neo.FileStorage.API.Accounting";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting";
 
 // Standard floating point data type can't be used in NeoFS due to inexactness
 // of the result when doing lots of small number operations. To solve the lost

acl/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.acl;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Acl";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/acl/grpc;acl";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/acl";
 
 // Target role of the access control rule in access control list.
 enum Role {
@@ -226,10 +226,10 @@ message BearerToken {
     // Lifetime parameters of the token. Field names taken from
     // [rfc7519](https://tools.ietf.org/html/rfc7519).
     message TokenLifetime {
-      // Expiration Epoch
+      // Expiration epoch, the last epoch when token is valid.
       uint64 exp = 1 [json_name = "exp"];
 
-      // Not valid before Epoch
+      // Not valid before epoch, the first epoch when token is valid.
       uint64 nbf = 2 [json_name = "nbf"];
 
       // Issued at Epoch

audit/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.audit;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Audit";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/audit/grpc;audit";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/audit";
 
 // DataAuditResult keeps record of conducted Data Audits. The detailed report is
 // generated separately.

container/service.proto

@@ -8,7 +8,7 @@ import "refs/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Container";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/container/grpc;container";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/container";
 
 // `ContainerService` provides API to interact with `Container` smart contract
 // in FS chain via other NeoFS nodes. All of those actions can be done

container/types.proto

@@ -6,7 +6,7 @@ import "netmap/types.proto";
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Container";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/container/grpc;container";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/container";
 
 // Container is a structure that defines object placement behaviour. Objects can
 // be stored only within containers. They define placement rule, attributes and

link/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.link;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Link";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/link/grpc;link";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/link";
 
 // Link is a payload of helper objects that contain the full list of the split
 // chain objects' IDs. It is created only after the whole split chain is known

lock/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.lock;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Lock";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/lock/grpc;lock";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/lock";
 
 // Lock objects protects a list of objects from being deleted. The lifetime of a
 // lock object is limited similar to regular objects in

netmap/service.proto

@@ -7,7 +7,7 @@ import "refs/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Netmap";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/netmap/grpc;netmap";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap";
 
 // `NetmapService` provides methods to work with `Network Map` and the information
 // required to build it. The resulting `Network Map` is stored in FS chain

netmap/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.netmap;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Netmap";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/netmap/grpc;netmap";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap";
 
 // Operations on filters
 enum Operation {

object/service.proto

@@ -8,7 +8,7 @@ import "session/types.proto";
 import "status/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Object";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/object/grpc;object";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/object";
 
 // `ObjectService` provides API for manipulating objects. Object operations do
 // not affect FS chain and are only served by nodes in P2P style.
@@ -84,6 +84,8 @@ service ObjectService {
 
   // Delete the object from a container. There is no immediate removal
   // guarantee. Object will be marked for removal and deleted eventually.
+  // Notice that some types of objects (see ObjectType) can not be removed,
+  // currently it's Tombstone and Lock.
   //
   // Extended headers can change `Delete` behaviour:
   // * __NEOFS__NETMAP_EPOCH \

object/types.proto

@@ -6,7 +6,7 @@ import "refs/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Object";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/object/grpc;object";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/object";
 
 // Type of the object payload content. Only `REGULAR` type objects can be split,
 // hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum
@@ -154,10 +154,10 @@ message ShortHeader {
   // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
   uint64 payload_length = 5 [json_name = "payloadLength"];
 
-  // Hash of payload bytes
+  // SHA256 hash of payload bytes.
   neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"];
 
-  // Homomorphic hash of the object payload
+  // Homomorphic hash of the object payload (Tillich-Zemor).
   neo.fs.v2.refs.Checksum homomorphic_hash = 7 [json_name = "homomorphicHash"];
 }
 
@@ -180,13 +180,13 @@ message Header {
   // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown.
   uint64 payload_length = 5 [json_name = "payloadLength"];
 
-  // Hash of payload bytes
+  // SHA256 hash of payload bytes
   neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"];
 
   // Type of the object payload content
   ObjectType object_type = 7 [json_name = "objectType"];
 
-  // Homomorphic hash of the object payload
+  // Homomorphic hash of the object payload (Tillich-Zemor).
   neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"];
 
   // Session token, if it was used during Object creation. Need it to verify
@@ -204,7 +204,8 @@ message Header {
   // that affect system behaviour:
   //
   // * __NEOFS__EXPIRATION_EPOCH \
-  //   Tells GC to delete object after that epoch
+  //   Tells GC to delete object after that epoch (but object is available
+  //   throughout the epoch specified in this attribute).
   // * __NEOFS__TICK_EPOCH \
   //   Decimal number that defines what epoch must produce
   //   object notification with UTF-8 object address in a

proto-docs/acl.md

@@ -72,8 +72,8 @@ Lifetime parameters of the token. Field names taken from
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| exp | [uint64](#uint64) |  | Expiration Epoch |
-| nbf | [uint64](#uint64) |  | Not valid before Epoch |
+| exp | [uint64](#uint64) |  | Expiration epoch, the last epoch when token is valid. |
+| nbf | [uint64](#uint64) |  | Not valid before epoch, the first epoch when token is valid. |
 | iat | [uint64](#uint64) |  | Issued at Epoch |
 
 

proto-docs/object.md

@@ -173,6 +173,8 @@ been deleted;
 
 Delete the object from a container. There is no immediate removal
 guarantee. Object will be marked for removal and deleted eventually.
+Notice that some types of objects (see ObjectType) can not be removed,
+currently it's Tombstone and Lock.
 
 Extended headers can change `Delete` behaviour:
 * __NEOFS__NETMAP_EPOCH \
@@ -902,9 +904,9 @@ Object Header
 | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Object's owner |
 | creation_epoch | [uint64](#uint64) |  | Object creation Epoch |
 | payload_length | [uint64](#uint64) |  | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. |
-| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Hash of payload bytes |
+| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | SHA256 hash of payload bytes |
 | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) |  | Type of the object payload content |
-| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash of the object payload |
+| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash of the object payload (Tillich-Zemor). |
 | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) |  | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. |
 | attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes. Attributes vary in length from object to object, so keep an eye on the entire Header limit depending on the context. |
 | split | [Header.Split](#neo.fs.v2.object.Header.Split) |  | Position of the object in the split hierarchy |
@@ -924,7 +926,8 @@ There are some "well-known" attributes starting with `__NEOFS__` prefix
 that affect system behaviour:
 
 * __NEOFS__EXPIRATION_EPOCH \
-  Tells GC to delete object after that epoch
+  Tells GC to delete object after that epoch (but object is available
+  throughout the epoch specified in this attribute).
 * __NEOFS__TICK_EPOCH \
   Decimal number that defines what epoch must produce
   object notification with UTF-8 object address in a
@@ -1086,8 +1089,8 @@ Short header fields
 | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Object's owner |
 | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) |  | Type of the object payload content |
 | payload_length | [uint64](#uint64) |  | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
-| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Hash of payload bytes |
-| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash of the object payload |
+| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | SHA256 hash of payload bytes. |
+| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash of the object payload (Tillich-Zemor). |
 
 
 <a name="neo.fs.v2.object.SplitInfo"></a>

proto-docs/session.md

@@ -92,7 +92,7 @@ Session creation request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Session initiating user's or node's key derived `OwnerID` |
-| expiration | [uint64](#uint64) |  | Session expiration `Epoch` |
+| expiration | [uint64](#uint64) |  | Session expiration epoch, the last epoch when session is valid. |
 
 
 <a name="neo.fs.v2.session.CreateResponse"></a>
@@ -270,8 +270,8 @@ Lifetime parameters of the token. Field names taken from rfc7519.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| exp | [uint64](#uint64) |  | Expiration Epoch |
-| nbf | [uint64](#uint64) |  | Not valid before Epoch |
+| exp | [uint64](#uint64) |  | Expiration epoch, the last epoch when token is valid. |
+| nbf | [uint64](#uint64) |  | Not valid before epoch, the first epoch when token is valid. |
 | iat | [uint64](#uint64) |  | Issued at Epoch |
 
 

proto-docs/tombstone.md

@@ -26,7 +26,8 @@
 
 ### Message Tombstone
 Tombstone keeps record of deleted objects for a few epochs until they are
-purged from the NeoFS network.
+purged from the NeoFS network. It is impossible to delete a tombstone object
+via ObjectService.Delete RPC call.
 
 
 | Field | Type | Label | Description |

refs/types.proto

@@ -3,7 +3,7 @@ syntax = "proto3";
 package neo.fs.v2.refs;
 
 option csharp_namespace = "Neo.FileStorage.API.Refs";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/refs/grpc;refs";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/refs";
 
 // Objects in NeoFS are addressed by their ContainerID and ObjectID.
 //

reputation/service.proto

@@ -6,7 +6,7 @@ import "reputation/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Reputation";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/reputation/grpc;reputation";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation";
 
 // `ReputationService` provides mechanisms for exchanging trust values with
 // other NeoFS nodes. Nodes rate each other's reputation based on how good they

reputation/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.reputation;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Reputation";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/reputation/grpc;reputation";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation";
 
 // NeoFS unique peer identifier is a 33 byte long compressed public key of the
 // node, the same as the one stored in the network map.

session/service.proto

@@ -6,7 +6,7 @@ import "refs/types.proto";
 import "session/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Session";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/session/grpc;session";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session";
 
 // `SessionService` allows to establish a temporary trust relationship between
 // two peer nodes and generate a `SessionToken` as the proof of trust to be
@@ -28,7 +28,7 @@ message CreateRequest {
   message Body {
     // Session initiating user's or node's key derived `OwnerID`
     neo.fs.v2.refs.OwnerID owner_id = 1;
-    // Session expiration `Epoch`
+    // Session expiration epoch, the last epoch when session is valid.
     uint64 expiration = 2;
   }
   // Body of a create session token request message.

session/types.proto

@@ -7,7 +7,7 @@ import "refs/types.proto";
 import "status/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Session";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/session/grpc;session";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session";
 
 // Context information for Session Tokens related to ObjectService requests
 message ObjectSessionContext {
@@ -97,10 +97,10 @@ message SessionToken {
 
     // Lifetime parameters of the token. Field names taken from rfc7519.
     message TokenLifetime {
-      // Expiration Epoch
+      // Expiration epoch, the last epoch when token is valid.
       uint64 exp = 1 [json_name = "exp"];
 
-      // Not valid before Epoch
+      // Not valid before epoch, the first epoch when token is valid.
       uint64 nbf = 2 [json_name = "nbf"];
 
       // Issued at Epoch

status/types.proto

@@ -3,7 +3,7 @@ syntax = "proto3";
 package neo.fs.v2.status;
 
 option csharp_namespace = "Neo.FileStorage.API.Status";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/status/grpc;status";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/status";
 
 // Declares the general format of the status returns of the NeoFS RPC protocol.
 // Status is present in all response messages. Each RPC of NeoFS protocol

storagegroup/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.storagegroup;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.StorageGroup";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/storagegroup/grpc;storagegroup";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/storagegroup";
 
 // StorageGroup keeps verification information for Data Audit sessions. Objects
 // that require paid storage guarantees are gathered in `StorageGroups` with

subnet/types.proto

@@ -5,7 +5,7 @@ package neo.fs.v2.subnet;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Subnet";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/subnet/grpc;subnet";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/subnet";
 
 // NeoFS subnetwork description
 //

tombstone/types.proto

@@ -5,10 +5,11 @@ package neo.fs.v2.tombstone;
 import "refs/types.proto";
 
 option csharp_namespace = "Neo.FileStorage.API.Tombstone";
-option go_package = "github.com/nspcc-dev/neofs-api-go/v2/tombstone/grpc;tombstone";
+option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/tombstone";
 
 // Tombstone keeps record of deleted objects for a few epochs until they are
-// purged from the NeoFS network.
+// purged from the NeoFS network. It is impossible to delete a tombstone object
+// via ObjectService.Delete RPC call.
 message Tombstone {
   // Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone
   // creator depending on the current NeoFS network settings.