From 1bc50fc2a9382de4728fee0b2ed8c12d251e6b4a Mon Sep 17 00:00:00 2001 From: Pavel Karpy Date: Tue, 21 Jun 2022 14:32:14 +0300 Subject: [PATCH] [#227] *: Regenerate docs Signed-off-by: Pavel Karpy --- proto-docs/accounting.md | 8 +-- proto-docs/acl.md | 26 ++++---- proto-docs/audit.md | 8 +-- proto-docs/container.md | 62 +++++++++--------- proto-docs/lock.md | 5 +- proto-docs/netmap.md | 30 ++++----- proto-docs/object.md | 125 ++++++++++++++++++++++++++++--------- proto-docs/refs.md | 25 ++++---- proto-docs/reputation.md | 24 +++---- proto-docs/session.md | 22 +++---- proto-docs/status.md | 8 ++- proto-docs/storagegroup.md | 6 +- proto-docs/tombstone.md | 6 +- 13 files changed, 214 insertions(+), 141 deletions(-) diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index 6d36189..94de765 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -39,7 +39,7 @@ Accounting service provides methods for interaction with NeoFS sidechain via other NeoFS nodes to get information about the account balance. Deposit and Withdraw operations can't be implemented here, as they require Mainnet NeoFS smart contract invocation. Transfer operations between internal NeoFS -accounts are possible, if both use the same token type. +accounts are possible if both use the same token type. ``` rpc Balance(BalanceRequest) returns (BalanceResponse); @@ -77,7 +77,7 @@ BalanceRequest message ### Message BalanceRequest.Body -To indicate the account for which the balance is requested, it's identifier +To indicate the account for which the balance is requested, its identifier is used. It can be any existing account in NeoFS sidechain `Balance` smart contract. If omitted, client implementation MUST set it to the request's signer `OwnerID`. @@ -105,7 +105,7 @@ BalanceResponse message ### Message BalanceResponse.Body The amount of funds in GAS token for the `OwnerID`'s account requested. -Balance is `Decimal` format to avoid precision issues with rounding. +Balance is given in the `Decimal` format to avoid precision issues with rounding. | Field | Type | Label | Description | @@ -141,7 +141,7 @@ description. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| value | [int64](#int64) | | Number in smallest Token fractions. | +| value | [int64](#int64) | | Number in the smallest Token fractions. | | precision | [uint32](#uint32) | | Precision value indicating how many smallest fractions can be in one integer. | diff --git a/proto-docs/acl.md b/proto-docs/acl.md index 943dae4..80416c5 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -38,8 +38,8 @@ like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be used in the similar use cases, like providing authorisation to externally authenticated party. -BearerToken can be issued only by container's owner and must be signed using -the key associated with container's `OwnerID`. +BearerToken can be issued only by the container's owner and must be signed using +the key associated with the container's `OwnerID`. | Field | Type | Label | Description | @@ -51,14 +51,14 @@ the key associated with container's `OwnerID`. ### Message BearerToken.Body -Bearer Token body structure contains Extended ACL table issued by container -owner with additional information preventing token's abuse. +Bearer Token body structure contains Extended ACL table issued by the container +owner with additional information preventing token abuse. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container | -| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` to whom the token was issued. Must match the request originator's `OwnerID`. If empty, any token bearer will be accepted. | +| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container. If it contains `container_id` field, bearer token is only valid for this specific container. Otherwise, any container of the same owner is allowed. | +| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` defines to whom the token was issued. It must match the request originator's `OwnerID`. If empty, any token bearer will be accepted. | | lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters | @@ -93,7 +93,7 @@ Describes a single eACL rule. ### Message EACLRecord.Filter -Filter to check particular properties of the request or object. +Filter to check particular properties of the request or the object. By default `key` field refers to the corresponding object's `Attribute`. Some Object's header fields can also be accessed by adding `$Object:` @@ -149,15 +149,15 @@ keys to match. ### Message EACLTable -Extended ACL rules table. Defined a list of ACL rules additionally to Basic -ACL. Extended ACL rules can be attached to the container and can be updated +Extended ACL rules table. A list of ACL rules defined additionally to Basic +ACL. Extended ACL rules can be attached to a container and can be updated or may be defined in `BearerToken` structure. Please see the corresponding -NeoFS Technical Specification's section for detailed description. +NeoFS Technical Specification section for detailed description. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | eACL format version. Effectively the version of API library used to create eACL Table. | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | eACL format version. Effectively, the version of API library used to create eACL Table. | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container that should use given access control rules | | records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules | @@ -233,8 +233,8 @@ Target role of the access control rule in access control list. | ---- | ------ | ----------- | | ROLE_UNSPECIFIED | 0 | Unspecified role, default value | | USER | 1 | User target rule is applied if sender is the owner of the container | -| SYSTEM | 2 | System target rule is applied if sender is the storage node within the container or inner ring node | -| OTHERS | 3 | Others target rule is applied if sender is not user nor system target | +| SYSTEM | 2 | System target rule is applied if sender is a storage node within the container or an inner ring node | +| OTHERS | 3 | Others target rule is applied if sender is neither a user nor a system target | diff --git a/proto-docs/audit.md b/proto-docs/audit.md index 073c2cb..b8d2010 100644 --- a/proto-docs/audit.md +++ b/proto-docs/audit.md @@ -31,7 +31,7 @@ generated separately. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Data Audit Result format version. Effectively the version of API library used to report DataAuditResult structure. | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Data Audit Result format version. Effectively, the version of API library used to report DataAuditResult structure. | | audit_epoch | [fixed64](#fixed64) | | Epoch number when the Data Audit was conducted | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container under audit | | public_key | [bytes](#bytes) | | Public key of the auditing InnerRing node in a binary format | @@ -40,9 +40,9 @@ generated separately. | retries | [uint32](#uint32) | | Number of retries done at PoR stage | | pass_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that passed audit PoR stage | | fail_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that failed audit PoR stage | -| hit | [uint32](#uint32) | | Number of sampled objects under audit placed in an optimal way according to the containers placement policy when checking PoP | -| miss | [uint32](#uint32) | | Number of sampled objects under audit placed in suboptimal way according to the containers placement policy, but still at a satisfactory level when checking PoP | -| fail | [uint32](#uint32) | | Number of sampled objects under audit stored in a way not confirming placement policy or not found at all when checking PoP | +| hit | [uint32](#uint32) | | Number of sampled objects under the audit placed in an optimal way according to the containers placement policy when checking PoP | +| miss | [uint32](#uint32) | | Number of sampled objects under the audit placed in suboptimal way according to the containers placement policy, but still at a satisfactory level when checking PoP | +| fail | [uint32](#uint32) | | Number of sampled objects under the audit stored inconsistently with the placement policy or not found at all when checking PoP | | pass_nodes | [bytes](#bytes) | repeated | List of storage node public keys that passed at least one PDP | | fail_nodes | [bytes](#bytes) | repeated | List of storage node public keys that failed at least one PDP | diff --git a/proto-docs/container.md b/proto-docs/container.md index a0e9684..d11243d 100644 --- a/proto-docs/container.md +++ b/proto-docs/container.md @@ -81,7 +81,7 @@ rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceRespon `Put` invokes `Container` smart contract's `Put` method and returns response immediately. After a new block is issued in sidechain, request is -verified by Inner Ring nodes. After one more block in sidechain, container +verified by Inner Ring nodes. After one more block in sidechain, the container is added into smart contract storage. Statuses: @@ -96,7 +96,7 @@ Statuses: `Delete` invokes `Container` smart contract's `Delete` method and returns response immediately. After a new block is issued in sidechain, request is -verified by Inner Ring nodes. After one more block in sidechain, container +verified by Inner Ring nodes. After one more block in sidechain, the container is added into smart contract storage. Statuses: @@ -136,7 +136,7 @@ Statuses: #### Method SetExtendedACL Invokes 'SetEACL' method of 'Container` smart contract and returns response -immediately. After one more block in sidechain, Extended ACL changes are +immediately. After one more block in sidechain, changes in an Extended ACL are added into smart contract storage. Statuses: @@ -164,7 +164,7 @@ Statuses: | GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) | #### Method AnnounceUsedSpace -Announce container used space values for P2P synchronization. +Announces the space values used by the container for P2P synchronization. Statuses: - **OK** (0, SECTION_SUCCESS): \ @@ -198,20 +198,20 @@ Container used space announcement body. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, then announcements transferred in a batch. | +| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, announcements are transferred in a batch. | ### Message AnnounceUsedSpaceRequest.Body.Announcement -Announcement contains used space information about single container. +Announcement contains used space information for a single container. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| epoch | [uint64](#uint64) | | Epoch number for which container size estimation was produced. | +| epoch | [uint64](#uint64) | | Epoch number for which the container size estimation was produced. | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. | -| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of specified container, stored in the node. It must not include inhumed objects. | +| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. | @@ -251,8 +251,8 @@ Container removal request ### Message DeleteRequest.Body -Container removal request body has a signed `ContainerID` as a proof of -container owner's intent. The signature will be verified by `Container` +Container removal request body has signed `ContainerID` as a proof of +the container owner's intent. The signature will be verified by `Container` smart contract, so signing algorithm must be supported by NeoVM. @@ -324,9 +324,9 @@ Get Extended ACL ### Message GetExtendedACLResponse.Body -Get Extended ACL Response body can be empty if the requested container did -not have Extended ACL Table attached or Extended ACL was not allowed at -container creation. +Get Extended ACL Response body can be empty if the requested container does +not have Extended ACL Table attached or Extended ACL has not been allowed at +the time of container creation. | Field | Type | Label | Description | @@ -377,14 +377,14 @@ Get container structure ### Message GetResponse.Body Get container response body does not have container structure signature. It -was already verified on container creation. +has been already verified upon container creation. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | container | [Container](#neo.fs.v2.container.Container) | | Requested container structure | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. | -| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if the container was created within a session | +| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if the container has been created within the session | @@ -483,7 +483,7 @@ New NeoFS Container creation response Container put response body contains information about the newly registered container as seen by `Container` smart contract. `ContainerID` can be calculated beforehand from the container structure and compared to the one -returned here to make sure everything was done as expected. +returned here to make sure everything has been done as expected. | Field | Type | Label | Description | @@ -513,7 +513,7 @@ reference. It will be taken from `EACLTable.container_id` field. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for container | +| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for the container | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. | @@ -534,7 +534,7 @@ Set Extended ACL ### Message SetExtendedACLResponse.Body `SetExtendedACLResponse` has an empty body because the operation is -asynchronous and update should be reflected in `Container` smart contract's +asynchronous and the update should be reflected in `Container` smart contract's storage after next block is issued in sidechain. @@ -558,16 +558,16 @@ storage after next block is issued in sidechain. ### Message Container Container is a structure that defines object placement behaviour. Objects can be stored only within containers. They define placement rule, attributes and -access control information. ID of the container is a 32 byte long SHA256 hash +access control information. An ID of a container is a 32 byte long SHA256 hash of stable-marshalled container message. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Container format version. Effectively the version of API library used to create container. | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Container format version. Effectively, the version of API library used to create the container. | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the container owner | | nonce | [bytes](#bytes) | | Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s | -| basic_acl | [uint32](#uint32) | | `BasicACL` contains access control rules for owner, system, others groups and permission bits for `BearerToken` and `Extended ACL` | +| basic_acl | [uint32](#uint32) | | `BasicACL` contains access control rules for the owner, system and others groups, as well as permission bits for `BearerToken` and `Extended ACL` | | attributes | [Container.Attribute](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data | | placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) | | Placement policy for the object inside the container | @@ -576,8 +576,8 @@ of stable-marshalled container message. ### Message Container.Attribute `Attribute` is a user-defined Key-Value metadata pair attached to the -container. Container attributes are immutable. They are set at container -creation and can never be added or updated. +container. Container attributes are immutable. They are set at the moment of +container creation and can never be added or updated. Key name must be a container-unique valid UTF-8 string. Value can't be empty. Containers with duplicated attribute names or attributes with empty @@ -586,14 +586,20 @@ values will be considered invalid. There are some "well-known" attributes affecting system behaviour: * __NEOFS__SUBNET \ - String ID of container's storage subnet. Container can be attached to - only one subnet. + String ID of a container's storage subnet. Any container can be attached to + one subnet only. * __NEOFS__NAME \ - String of human-friendly container name registered as the domain in + String of a human-friendly container name registered as a domain in NNS contract. * __NEOFS__ZONE \ - String of zone for `__NEOFS__NAME`. Used as TLD of domain name in NNS - contract. If zone is not specified, use default zone: `container`. + String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS + contract. If no zone is specified, use default zone: `container`. +* __NEOFS__DISABLE_HOMOMORPHIC_HASHING \ + Disables homomorphic hashing for the container if the value equals "true" string. + Any other values are interpreted as missing attribute. Container could be + accepted in a NeoFS network only if the global network hashing configuration + value corresponds with that attribute's value. After container inclusion, network + setting is ignored. And some well-known attributes used by applications only: diff --git a/proto-docs/lock.md b/proto-docs/lock.md index b23c734..3bbbf79 100644 --- a/proto-docs/lock.md +++ b/proto-docs/lock.md @@ -25,9 +25,10 @@ ### Message Lock -Lock objects protects a list of objects from being deleted. Lifetime of the +Lock objects protects a list of objects from being deleted. The lifetime of a lock object is limited similar to regular objects in -`__NEOFS__EXPIRATION_EPOCH` attribute. +`__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch. +It is impossible to delete a lock object via ObjectService.Delete RPC call. | Field | Type | Label | Description | diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index a74d41f..c029442 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -47,7 +47,7 @@ ### Service "neo.fs.v2.netmap.NetmapService" -`NetmapService` provides methods to work with `Network Map` and information +`NetmapService` provides methods to work with `Network Map` and the information required to build it. The resulting `Network Map` is stored in sidechain `Netmap` smart contract, while related information can be obtained from other NeoFS nodes. @@ -60,11 +60,11 @@ rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse); #### Method LocalNodeInfo -Get NodeInfo structure from the particular node directly. Node information -can be taken from `Netmap` smart contract, but in some cases the one may -want to get recent information directly, or to talk to the node not yet -present in `Network Map` to find out what API version can be used for -further communication. Can also be used to check if node is up and running. +Get NodeInfo structure from the particular node directly. +Node information can be taken from `Netmap` smart contract. In some cases, though, +one may want to get recent information directly or to talk to the node not yet +present in the `Network Map` to find out what API version can be used for +further communication. This can be also used to check if a node is up and running. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -92,7 +92,7 @@ information about the current network state has been successfully read; ### Message LocalNodeInfoRequest -Get NodeInfo structure from the particular node directly +Get NodeInfo structure directly from a particular node | Field | Type | Label | Description | @@ -137,7 +137,7 @@ Local Node Info, including API Version in use. ### Message NetworkInfoRequest -Get NetworkInfo structure with the network view from particular node. +Get NetworkInfo structure with the network view from a particular node. | Field | Type | Label | Description | @@ -196,13 +196,13 @@ Information about the network. ### Message Filter -Filter will return the subset of nodes from `NetworkMap` or another filter's -results, that will satisfy filter's conditions. +This filter will return the subset of nodes from `NetworkMap` or another filter's +results that will satisfy filter's conditions. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| name | [string](#string) | | Name of the filter or a reference to the named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter | +| name | [string](#string) | | Name of the filter or a reference to a named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter | | key | [string](#string) | | Key to filter | | op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation | | value | [string](#string) | | Value to match | @@ -332,7 +332,7 @@ explicitly set: automatically from `UN-LOCODE` attribute. For detailed description of each well-known attribute please see the -corresponding section in NeoFS Technical specification. +corresponding section in NeoFS Technical Specification. | Field | Type | Label | Description | @@ -363,7 +363,7 @@ storage policy definition languages. ### Message Replica Number of object replicas in a set of nodes from the defined selector. If no -selector set the root bucket containing all possible nodes will be used by +selector set, the root bucket containing all possible nodes will be used by default. @@ -385,7 +385,7 @@ to the provided `ContainerID` by hash distance. | name | [string](#string) | | Selector name to reference in object placement section | | count | [uint32](#uint32) | | How many nodes to select from the bucket | | clause | [Clause](#neo.fs.v2.netmap.Clause) | | Selector modifier showing how to form a bucket | -| attribute | [string](#string) | | Attribute bucket to select from | +| attribute | [string](#string) | | Bucket attribute to select from | | filter | [string](#string) | | Filter reference to select from | @@ -400,7 +400,7 @@ hash distance. | Name | Number | Description | | ---- | ------ | ----------- | -| CLAUSE_UNSPECIFIED | 0 | No modifier defined. Will select nodes from bucket randomly. | +| CLAUSE_UNSPECIFIED | 0 | No modifier defined. Nodes will be selected from the bucket randomly | | SAME | 1 | SAME will select only nodes having the same value of bucket attribute | | DISTINCT | 2 | DISTINCT will select nodes having different values of bucket attribute | diff --git a/proto-docs/object.md b/proto-docs/object.md index a483e8c..025f41f 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -70,7 +70,7 @@ ### Service "neo.fs.v2.object.ObjectService" `ObjectService` provides API for manipulating objects. Object operations do -not interact with sidechain and are only served by nodes in p2p style. +not affect the sidechain and are only served by nodes in p2p style. ``` rpc Get(GetRequest) returns (stream GetResponse); @@ -86,11 +86,22 @@ rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); #### Method Get Receive full object structure, including Headers and payload. Response uses -gRPC stream. First response message carries object with requested address. +gRPC stream. First response message carries the object with the requested address. Chunk messages are parts of the object's payload if it is needed. All -messages, except the first one, carry payload chunks. Requested object can +messages, except the first one, carry payload chunks. The requested object can be restored by concatenation of object message payload and all chunks -keeping receiving order. +keeping the receiving order. + +Extended headers can change `Get` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. +* __NEOFS__NETMAP_LOOKUP_DEPTH \ + Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or + the latest one otherwise) of Network Map to find an object until the depth + limit is reached. + +Please refer to detailed `XHeader` description. Statuses: - **OK** (0, SECTION_SUCCESS): \ @@ -117,7 +128,14 @@ SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see session package). Chunk messages are considered by server as a part of an object payload. All messages, except first one, SHOULD be payload chunks. -Chunk messages SHOULD be sent in direct order of fragmentation. +Chunk messages SHOULD be sent in the direct order of fragmentation. + +Extended headers can change `Put` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. + +Please refer to detailed `XHeader` description. Statuses: - **OK** (0, SECTION_SUCCESS): \ @@ -147,6 +165,13 @@ been deleted; Delete the object from a container. There is no immediate removal guarantee. Object will be marked for removal and deleted eventually. +Extended headers can change `Delete` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. + +Please refer to detailed `XHeader` description. + Statuses: - **OK** (0, SECTION_SUCCESS): \ object has been successfully marked to be removed from the container; @@ -167,7 +192,14 @@ Statuses: Returns the object Headers without data payload. By default full header is returned. If `main_only` request field is set, the short header with only -the very minimal information would be returned instead. +the very minimal information will be returned instead. + +Extended headers can change `Head` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. + +Please refer to detailed `XHeader` description. Statuses: - **OK** (0, SECTION_SUCCESS): \ @@ -193,6 +225,13 @@ Search objects in container. Search query allows to match by Object Header's filed values. Please see the corresponding NeoFS Technical Specification section for more details. +Extended headers can change `Search` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. + +Please refer to detailed `XHeader` description. + Statuses: - **OK** (0, SECTION_SUCCESS): \ objects have been successfully selected; @@ -211,9 +250,19 @@ Statuses: Get byte range of data payload. Range is set as an (offset, length) tuple. Like in `Get` method, the response uses gRPC stream. Requested range can be -restored by concatenation of all received payload chunks keeping receiving +restored by concatenation of all received payload chunks keeping the receiving order. +Extended headers can change `GetRange` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. +* __NEOFS__NETMAP_LOOKUP_DEPTH \ + Will try older versions of Network Map to find an object until the depth + limit is reached. + +Please refer to detailed `XHeader` description. + Statuses: - **OK** (0, SECTION_SUCCESS): \ data range of the object payload has been successfully read; @@ -228,6 +277,8 @@ Statuses: provided session token has expired; - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ the requested object has been marked as deleted. +- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ + the requested range is out of bounds. | Name | Input | Output | | ---- | ----- | ------ | @@ -236,8 +287,18 @@ Statuses: Returns homomorphic or regular hash of object's payload range after applying XOR operation with the provided `salt`. Ranges are set of (offset, -length) tuples. Hashes order in response corresponds to ranges order in -request. Note that hash is calculated for XORed data. +length) tuples. Hashes order in response corresponds to the ranges order in +the request. Note that hash is calculated for XORed data. + +Extended headers can change `GetRangeHash` behaviour: +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement + calculation. +* __NEOFS__NETMAP_LOOKUP_DEPTH \ + Will try older versions of Network Map to find an object until the depth + limit is reached. + +Please refer to detailed `XHeader` description. Statuses: - **OK** (0, SECTION_SUCCESS): \ @@ -249,6 +310,8 @@ Statuses: access to operation RANGEHASH of the object is denied; - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ object not found in container; +- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ + the requested range is out of bounds. - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -533,12 +596,12 @@ Object HEAD response body ### Message HeaderWithSignature -Tuple of full object header and signature of `ObjectID`. \ +Tuple of a full object header and signature of an `ObjectID`. \ Signed `ObjectID` is present to verify full header's authenticity through the following steps: -1. Calculate `SHA-256` of marshalled `Header` structure -2. Check if the resulting hash matched `ObjectID` +1. Calculate `SHA-256` of the marshalled `Header` structure +2. Check if the resulting hash matches `ObjectID` 3. Check if `ObjectID` signature in `signature` field is correct @@ -653,13 +716,13 @@ Object Search request body ### Message SearchRequest.Body.Filter -Filter structure checks if object header field or attribute content +Filter structure checks if the object header field or the attribute content matches a value. -If no filters set, search request will return all objects of the +If no filters are set, search request will return all objects of the container, including Regular object, Tombstones and Storage Group objects. Most human users expect to get only object they can directly -work with. In that case the `$Object:ROOT` filter should be used. +work with. In that case, `$Object:ROOT` filter should be used. By default `key` field refers to the corresponding object's `Attribute`. Some Object's header fields can also be accessed by adding `$Object:` @@ -692,10 +755,10 @@ There are some well-known filter aliases to match objects by certain properties: * $Object:ROOT \ - Returns only `REGULAR` type objects that are not split or are the top + Returns only `REGULAR` type objects that are not split or that are the top level root objects in a split hierarchy. This includes objects not present physically, like large objects split into smaller objects - without separate top-level root object. Other type objects like + without a separate top-level root object. Objects of other types like StorageGroups and Tombstones will not be shown. This filter may be useful for listing objects like `ls` command of some virtual file system. This filter is activated if the `key` exists, disregarding the @@ -762,7 +825,7 @@ Object Header | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively the version of API library used to create particular object | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Object's container | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner | | creation_epoch | [uint64](#uint64) | | Object creation Epoch | @@ -778,10 +841,10 @@ Object Header ### Message Header.Attribute -`Attribute` is a user-defined Key-Value metadata pair attached to the +`Attribute` is a user-defined Key-Value metadata pair attached to an object. -Key name must be a object-unique valid UTF-8 string. Value can't be empty. +Key name must be an object-unique valid UTF-8 string. Value can't be empty. Objects with duplicated attribute names or attributes with empty values will be considered invalid. @@ -812,7 +875,7 @@ And some well-known attributes used by applications only: MIME Content Type of object's payload For detailed description of each well-known attribute please see the -corresponding section in NeoFS Technical specification. +corresponding section in NeoFS Technical Specification. | Field | Type | Label | Description | @@ -844,8 +907,8 @@ must be within the same container. ### Message Object Object structure. Object is immutable and content-addressed. It means -`ObjectID` will change if header or payload changes. It's calculated as a -hash of header field, which contains hash of object's payload. +`ObjectID` will change if the header or the payload changes. It's calculated as a +hash of header field which contains hash of the object's payload. For non-regular object types payload format depends on object type specified in the header. @@ -867,7 +930,7 @@ Short header fields | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively the version of API library used to create particular object. | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Object format version. Effectively, the version of API library used to create particular object. | | creation_epoch | [uint64](#uint64) | | Epoch when the object was created | | 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 | @@ -879,17 +942,17 @@ Short header fields ### Message SplitInfo -Meta information of split hierarchy for object assembly. With last part -one can traverse linked list of split hierarchy back to first part and -assemble original object. With linking object one can assembly object -straight away from the object parts. +Meta information of split hierarchy for object assembly. With the last part +one can traverse linked list of split hierarchy back to the first part and +assemble the original object. With a linking object one can assemble an object +right from the object parts. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. | -| last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the last object in split hierarchy parts. It contains split header with original object header. | -| link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of linking object for split hierarchy parts. It contains split header with original object header and sorted list of object parts. | +| last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of the last object in split hierarchy parts. It contains split header with the original object header. | +| link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The identifier of a linking object for split hierarchy parts. It contains split header with the original object header and a sorted list of object parts. | @@ -913,7 +976,7 @@ Type of match expression ### ObjectType Type of the object payload content. Only `REGULAR` type objects can be split, -hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by maximal +hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum object size. String presentation of object type is the same as definition: diff --git a/proto-docs/refs.md b/proto-docs/refs.md index abb2f6f..651822f 100644 --- a/proto-docs/refs.md +++ b/proto-docs/refs.md @@ -35,7 +35,7 @@ ### Message Address Objects in NeoFS are addressed by their ContainerID and ObjectID. -String presentation of `Address` is the concatenation of string encoded +String presentation of `Address` is a concatenation of string encoded `ContainerID` and `ObjectID` delimited by '/' character. @@ -49,7 +49,7 @@ String presentation of `Address` is the concatenation of string encoded ### Message Checksum Checksum message. -Depending on checksum algorithm type the string presentation may vary: +Depending on checksum algorithm type, the string presentation may vary: * TZ \ Hex encoded string without `0x` prefix @@ -73,10 +73,10 @@ content-addressed. [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of stable-marshalled container message. -String presentation is +String presentation is a [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. -JSON value will be the data encoded as a string using standard base64 +JSON value will be data encoded as a string using standard base64 encoding with paddings. Either [standard](https://tools.ietf.org/html/rfc4648#section-4) or [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding @@ -92,17 +92,17 @@ with/without paddings are accepted. ### Message ObjectID NeoFS Object unique identifier. Objects are immutable and content-addressed. -It means `ObjectID` will change if `header` or `payload` changes. +It means `ObjectID` will change if the `header` or the `payload` changes. `ObjectID` is a 32 byte long [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of -object's `header` field, which, in it's turn, contains hash of object's +the object's `header` field, which, in it's turn, contains the hash of the object's payload. -String presentation is +String presentation is a [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. -JSON value will be the data encoded as a string using standard base64 +JSON value will be data encoded as a string using standard base64 encoding with paddings. Either [standard](https://tools.ietf.org/html/rfc4648#section-4) or [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding @@ -124,10 +124,10 @@ be directly used as `OwnerID`. `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte followed by 20 bytes of ScrptHash and 4 bytes of checksum. -String presentation is [Base58 +String presentation is a [Base58 Check](https://en.bitcoin.it/wiki/Base58Check_encoding) Encoded string. -JSON value will be the data encoded as a string using standard base64 +JSON value will be data encoded as a string using standard base64 encoding with paddings. Either [standard](https://tools.ietf.org/html/rfc4648#section-4) or [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding @@ -171,7 +171,7 @@ NeoFS subnetwork identifier. String representation of a value is base-10 integer. -JSON representation is an object containing single `value` number field. +JSON representation is an object containing a single `value` number field. | Field | Type | Label | Description | @@ -185,7 +185,7 @@ JSON representation is an object containing single `value` number field. API version used by a node. String presentation is a Semantic Versioning 2.0.0 compatible version string -with 'v' prefix. I.e. `vX.Y`, where `X` - major number, `Y` - minor number. +with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number. | Field | Type | Label | Description | @@ -218,6 +218,7 @@ Signature scheme describes digital signing scheme used for (key, signature) pair | ---- | ------ | ----------- | | ECDSA_SHA512 | 0 | ECDSA with SHA-512 hashing (FIPS 186-3) | | ECDSA_RFC6979_SHA256 | 1 | Deterministic ECDSA with SHA-256 hashing (RFC 6979) | +| ECDSA_RFC6979_SHA256_WALLET_CONNECT | 2 | Deterministic ECDSA with SHA-256 hashing using WalletConnect API. Here the algorithm is the same, but the message format differs. | diff --git a/proto-docs/reputation.md b/proto-docs/reputation.md index 3802c39..19558f3 100644 --- a/proto-docs/reputation.md +++ b/proto-docs/reputation.md @@ -69,7 +69,7 @@ local trust has been successfully announced; | AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) | #### Method AnnounceIntermediateResult -Announces the intermediate result of the iterative algorithm for +Announce the intermediate result of the iterative algorithm for calculating the global reputation of the node in NeoFS network. Statuses: @@ -112,7 +112,7 @@ Announce intermediate global trust information. ### Message AnnounceIntermediateResultResponse -Intermediate global trust information announce response. +Intermediate global trust information announcement response. | Field | Type | Label | Description | @@ -125,9 +125,9 @@ Intermediate global trust information announce response. ### Message AnnounceIntermediateResultResponse.Body -Response to the node's intermediate global trust information announce has +Response to the node's intermediate global trust information announcement has an empty body because the trust exchange operation is asynchronous. If -Trust information will not pass sanity checks it is silently ignored. +Trust information does not pass sanity checks, it is silently ignored. @@ -153,13 +153,13 @@ Announce node's local trust information. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | epoch | [uint64](#uint64) | | Trust assessment Epoch number | -| trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in the [0;1] range. | +| trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in [0;1] range. | ### Message AnnounceLocalTrustResponse -Node's local trust information announce response. +Node's local trust information announcement response. | Field | Type | Label | Description | @@ -172,9 +172,9 @@ Node's local trust information announce response. ### Message AnnounceLocalTrustResponse.Body -Response to the node's local trust information announce has an empty body +Response to the node's local trust information announcement has an empty body because the trust exchange operation is asynchronous. If Trust information -will not pass sanity checks it is silently ignored. +does not pass sanity checks, it is silently ignored. @@ -200,7 +200,7 @@ Global trust level to NeoFS node. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively the version of API library used to create the message. | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively, the version of API library used to create the message. | | body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. | @@ -220,13 +220,13 @@ Message body structure. ### Message PeerID -NeoFS unique peer identifier is 33 byte long compressed public key of the +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. -String presentation is +String presentation is a [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. -JSON value will be the data encoded as a string using standard base64 +JSON value will be data encoded as a string using standard base64 encoding with paddings. Either [standard](https://tools.ietf.org/html/rfc4648#section-4) or [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding diff --git a/proto-docs/session.md b/proto-docs/session.md index 683777b..40a48e2 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -56,7 +56,7 @@ rpc Create(CreateRequest) returns (CreateResponse); #### Method Create -Opens a new session between two peers. +Open a new session between two peers. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -77,7 +77,7 @@ Information necessary for opening a session. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| body | [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) | | Body of create session token request message. | +| body | [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) | | Body of a create session token request message. | | meta_header | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | | verify_header | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | @@ -180,12 +180,12 @@ request meta headers are folded in matryoshka style. ### Message RequestVerificationHeader -Verification info for request signed by all intermediate nodes. +Verification info for the request signed by all intermediate nodes. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by request initiator. | +| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by the request initiator. | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by each intermediate node | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops | | origin | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Chain of previous hops signatures | @@ -210,12 +210,12 @@ Information about the response ### Message ResponseVerificationHeader -Verification info for response signed by all intermediate nodes +Verification info for the response signed by all intermediate nodes | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by answering node. | +| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by an answering node. | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by each intermediate node | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops | | origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures | @@ -265,10 +265,10 @@ Lifetime parameters of the token. Field names taken from rfc7519. ### Message XHeader -Extended headers for Request/Response. May contain any user-defined headers +Extended headers for Request/Response. They may contain any user-defined headers to be interpreted on application level. -Key name must be unique valid UTF-8 string. Value can't be empty. Requests or +Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or Responses with duplicated header names or headers with empty values will be considered invalid. @@ -281,9 +281,9 @@ affect system behaviour: current epoch only will be used. * __NEOFS__NETMAP_LOOKUP_DEPTH \ If object can't be found using current epoch's netmap, this header limits - how many past epochs back the node can lookup. The `value` is string - encoded `uint64` in decimal presentation. If set to '0' or not set, the - current epoch only will be used. + how many past epochs the node can look up through. The `value` is string + encoded `uint64` in decimal presentation. If set to '0' or not set, only the + current epoch will be used. | Field | Type | Label | Description | diff --git a/proto-docs/status.md b/proto-docs/status.md index ea97ac7..1d02903 100644 --- a/proto-docs/status.md +++ b/proto-docs/status.md @@ -44,12 +44,12 @@ is defined for each section. Values can be referred to in the following ways: All outcomes are divided into successful and failed, which corresponds to the success or failure of the operation. The definition of success -follows from the semantics of RPC and the description of its purpose. -The server must not attach code that is the opposite of outcome type. +follows the semantics of RPC and the description of its purpose. +The server must not attach code that is the opposite of the outcome type. See the set of return codes in the description for calls. -Each status can carry developer-facing error message. It should be human +Each status can carry a developer-facing error message. It should be a human readable text in English. The server should not transmit (and the client should not expect) useful information in the message. Field `details` should make the return more detailed. @@ -88,6 +88,7 @@ Section of failed statuses independent of the operation. | ---- | ------ | ----------- | | INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed. If the server cannot match failed outcome to the code, it should use this code. | | WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). | +| SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. | @@ -114,6 +115,7 @@ Section of statuses for object-related operations. | LOCKED | 2 | [**2050**] Operation rejected by the object lock. | | LOCK_NON_REGULAR_OBJECT | 3 | [**2051**] Locking an object with a non-REGULAR type rejected. | | OBJECT_ALREADY_REMOVED | 4 | [**2052**] Object has been marked deleted. | +| OUT_OF_RANGE | 5 | [**2053**] Invalid range has been requested for an object. | diff --git a/proto-docs/storagegroup.md b/proto-docs/storagegroup.md index 4428595..3bc0b5e 100644 --- a/proto-docs/storagegroup.md +++ b/proto-docs/storagegroup.md @@ -26,8 +26,8 @@ ### Message StorageGroup StorageGroup keeps verification information for Data Audit sessions. Objects -that require payed storage guaranties are gathered in `StorageGroups` with -additional information used for proof of storage. `StorageGroup` only +that require paid storage guarantees are gathered in `StorageGroups` with +additional information used for the proof of storage. `StorageGroup` only contains objects from the same container. Being an object payload, StorageGroup may have expiration Epoch set with @@ -41,7 +41,7 @@ deleted by Storage Nodes. | validation_data_size | [uint64](#uint64) | | Total size of the payloads of objects in the storage group | | validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the `members` field. | | expiration_epoch | [uint64](#uint64) | | DEPRECATED. Last NeoFS epoch number of the storage group lifetime | -| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects | +| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects. Members MUST be unique | diff --git a/proto-docs/tombstone.md b/proto-docs/tombstone.md index 1dca62a..4657935 100644 --- a/proto-docs/tombstone.md +++ b/proto-docs/tombstone.md @@ -25,14 +25,14 @@ ### Message Tombstone -Tombstone keeps record of deleted objects for few epochs until they are +Tombstone keeps record of deleted objects for a few epochs until they are purged from the NeoFS network. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by tombstone creator depending on current NeoFS network settings. Tombstone object must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` attribute. Otherwise tombstone will be rejected by storage node. | -| split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside container. All objects participating in the split must have the same `split_id` value. | +| expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current NeoFS network settings. A tombstone object must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` attribute. Otherwise, the tombstone will be rejected by a storage node. | +| split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside a container. All objects participating in the split must have the same `split_id` value. | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. |