30 KiB
Protocol Documentation
Table of Contents
-
Services
-
Messages
- AnnounceUsedSpaceRequest
- AnnounceUsedSpaceRequest.Body
- AnnounceUsedSpaceRequest.Body.Announcement
- AnnounceUsedSpaceResponse
- AnnounceUsedSpaceResponse.Body
- DeleteRequest
- DeleteRequest.Body
- DeleteResponse
- DeleteResponse.Body
- GetExtendedACLRequest
- GetExtendedACLRequest.Body
- GetExtendedACLResponse
- GetExtendedACLResponse.Body
- GetRequest
- GetRequest.Body
- GetResponse
- GetResponse.Body
- ListRequest
- ListRequest.Body
- ListResponse
- ListResponse.Body
- PutRequest
- PutRequest.Body
- PutResponse
- PutResponse.Body
- SetExtendedACLRequest
- SetExtendedACLRequest.Body
- SetExtendedACLResponse
- SetExtendedACLResponse.Body
-
- Messages
container/service.proto
Service "neo.fs.v2.container.ContainerService"
ContainerService provides API to interact with Container smart contract
in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
equivalently by directly issuing transactions and RPC calls to sidechain
nodes.
rpc Put(PutRequest) returns (PutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Get(GetRequest) returns (GetResponse);
rpc List(ListRequest) returns (ListResponse);
rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse);
Method Put
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, the container
is added into smart contract storage.
Statuses:
- OK (0, SECTION_SUCCESS):
request to save the container has been sent to the sidechain; - Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
|---|---|---|
| Put | PutRequest | PutResponse |
Method Delete
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, the container
is added into smart contract storage.
Statuses:
- OK (0, SECTION_SUCCESS):
request to remove the container has been sent to the sidechain; - Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
|---|---|---|
| Delete | DeleteRequest | DeleteResponse |
Method Get
Returns container structure from Container smart contract storage.
Statuses:
- OK (0, SECTION_SUCCESS):
container has been successfully read; - Common failures (SECTION_FAILURE_COMMON);
- CONTAINER_NOT_FOUND (3072, SECTION_CONTAINER):
requested container not found.
| Name | Input | Output |
|---|---|---|
| Get | GetRequest | GetResponse |
Method List
Returns all owner's containers from 'Container` smart contract' storage.
Statuses:
- OK (0, SECTION_SUCCESS):
container list has been successfully read; - Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
|---|---|---|
| List | ListRequest | ListResponse |
Method SetExtendedACL
Invokes 'SetEACL' method of 'Container` smart contract and returns response immediately. After one more block in sidechain, changes in an Extended ACL are added into smart contract storage.
Statuses:
- OK (0, SECTION_SUCCESS):
request to save container eACL has been sent to the sidechain; - Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
|---|---|---|
| SetExtendedACL | SetExtendedACLRequest | SetExtendedACLResponse |
Method GetExtendedACL
Returns Extended ACL table and signature from Container smart contract
storage.
Statuses:
- OK (0, SECTION_SUCCESS):
container eACL has been successfully read; - Common failures (SECTION_FAILURE_COMMON);
- CONTAINER_NOT_FOUND (3072, SECTION_CONTAINER):
container not found; - EACL_NOT_FOUND (3073, SECTION_CONTAINER):
eACL table not found.
| Name | Input | Output |
|---|---|---|
| GetExtendedACL | GetExtendedACLRequest | GetExtendedACLResponse |
Method AnnounceUsedSpace
Announces the space values used by the container for P2P synchronization.
Statuses:
- OK (0, SECTION_SUCCESS):
estimation of used space has been successfully announced; - Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
|---|---|---|
| AnnounceUsedSpace | AnnounceUsedSpaceRequest | AnnounceUsedSpaceResponse |
Message AnnounceUsedSpaceRequest
Announce container used space
| Field | Type | Label | Description |
|---|---|---|---|
| body | AnnounceUsedSpaceRequest.Body | Body of announce used space request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message AnnounceUsedSpaceRequest.Body
Container used space announcement body.
| Field | Type | Label | Description |
|---|---|---|---|
| announcements | 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 for a single container.
| Field | Type | Label | Description |
|---|---|---|---|
| epoch | uint64 | Epoch number for which the container size estimation was produced. | |
| container_id | neo.fs.v2.refs.ContainerID | Identifier of the container. | |
| used_space | uint64 | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. |
Message AnnounceUsedSpaceResponse
Announce container used space
| Field | Type | Label | Description |
|---|---|---|---|
| body | AnnounceUsedSpaceResponse.Body | Body of announce used space response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message AnnounceUsedSpaceResponse.Body
AnnounceUsedSpaceResponse has an empty body because announcements are
one way communication.
Message DeleteRequest
Container removal request
| Field | Type | Label | Description |
|---|---|---|---|
| body | DeleteRequest.Body | Body of container delete request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message DeleteRequest.Body
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.
| Field | Type | Label | Description |
|---|---|---|---|
| container_id | neo.fs.v2.refs.ContainerID | Identifier of the container to delete from NeoFS | |
| signature | neo.fs.v2.refs.SignatureRFC6979 | ContainerID signed with the container owner's key according to RFC-6979. |
Message DeleteResponse
DeleteResponse has an empty body because delete operation is asynchronous
and done via consensus in Inner Ring nodes.
| Field | Type | Label | Description |
|---|---|---|---|
| body | DeleteResponse.Body | Body of container delete response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message DeleteResponse.Body
DeleteResponse has an empty body because delete operation is asynchronous
and done via consensus in Inner Ring nodes.
Message GetExtendedACLRequest
Get Extended ACL
| Field | Type | Label | Description |
|---|---|---|---|
| body | GetExtendedACLRequest.Body | Body of get extended acl request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message GetExtendedACLRequest.Body
Get Extended ACL request body
| Field | Type | Label | Description |
|---|---|---|---|
| container_id | neo.fs.v2.refs.ContainerID | Identifier of the container having Extended ACL |
Message GetExtendedACLResponse
Get Extended ACL
| Field | Type | Label | Description |
|---|---|---|---|
| body | GetExtendedACLResponse.Body | Body of get extended acl response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message GetExtendedACLResponse.Body
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 |
|---|---|---|---|
| eacl | neo.fs.v2.acl.EACLTable | Extended ACL requested, if available | |
| signature | neo.fs.v2.refs.SignatureRFC6979 | Signature of stable-marshalled Extended ACL according to RFC-6979. | |
| session_token | neo.fs.v2.session.SessionToken | Session token if Extended ACL was set within a session |
Message GetRequest
Get container structure
| Field | Type | Label | Description |
|---|---|---|---|
| body | GetRequest.Body | Body of container get request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message GetRequest.Body
Get container structure request body.
| Field | Type | Label | Description |
|---|---|---|---|
| container_id | neo.fs.v2.refs.ContainerID | Identifier of the container to get |
Message GetResponse
Get container structure
| Field | Type | Label | Description |
|---|---|---|---|
| body | GetResponse.Body | Body of container get response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message GetResponse.Body
Get container response body does not have container structure signature. It has been already verified upon container creation.
| Field | Type | Label | Description |
|---|---|---|---|
| container | Container | Requested container structure | |
| signature | neo.fs.v2.refs.SignatureRFC6979 | Signature of a stable-marshalled container according to RFC-6979. | |
| session_token | neo.fs.v2.session.SessionToken | Session token if the container has been created within the session |
Message ListRequest
List containers
| Field | Type | Label | Description |
|---|---|---|---|
| body | ListRequest.Body | Body of list containers request message | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message ListRequest.Body
List containers request body.
| Field | Type | Label | Description |
|---|---|---|---|
| owner_id | neo.fs.v2.refs.OwnerID | Identifier of the container owner |
Message ListResponse
List containers
| Field | Type | Label | Description |
|---|---|---|---|
| body | ListResponse.Body | Body of list containers response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message ListResponse.Body
List containers response body.
| Field | Type | Label | Description |
|---|---|---|---|
| container_ids | neo.fs.v2.refs.ContainerID | repeated | List of ContainerIDs belonging to the requested OwnerID |
Message PutRequest
New NeoFS Container creation request
| Field | Type | Label | Description |
|---|---|---|---|
| body | PutRequest.Body | Body of container put request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message PutRequest.Body
Container creation request has container structure's signature as a
separate field. It's not stored in sidechain, just verified on container
creation by Container smart contract. ContainerID is a SHA256 hash of
the stable-marshalled container strucutre, hence there is no need for
additional signature checks.
| Field | Type | Label | Description |
|---|---|---|---|
| container | Container | Container structure to register in NeoFS | |
| signature | neo.fs.v2.refs.SignatureRFC6979 | Signature of a stable-marshalled container according to RFC-6979. |
Message PutResponse
New NeoFS Container creation response
| Field | Type | Label | Description |
|---|---|---|---|
| body | PutResponse.Body | Body of container put response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message PutResponse.Body
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 has been done as expected.
| Field | Type | Label | Description |
|---|---|---|---|
| container_id | neo.fs.v2.refs.ContainerID | Unique identifier of the newly created container |
Message SetExtendedACLRequest
Set Extended ACL
| Field | Type | Label | Description |
|---|---|---|---|
| body | SetExtendedACLRequest.Body | Body of set extended acl request message. | |
| meta_header | neo.fs.v2.session.RequestMetaHeader | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.RequestVerificationHeader | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message SetExtendedACLRequest.Body
Set Extended ACL request body does not have separate ContainerID
reference. It will be taken from EACLTable.container_id field.
| Field | Type | Label | Description |
|---|---|---|---|
| eacl | neo.fs.v2.acl.EACLTable | Extended ACL table to set for the container | |
| signature | neo.fs.v2.refs.SignatureRFC6979 | Signature of stable-marshalled Extended ACL table according to RFC-6979. |
Message SetExtendedACLResponse
Set Extended ACL
| Field | Type | Label | Description |
|---|---|---|---|
| body | SetExtendedACLResponse.Body | Body of set extended acl response message. | |
| meta_header | neo.fs.v2.session.ResponseMetaHeader | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | |
| verify_header | neo.fs.v2.session.ResponseVerificationHeader | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
Message SetExtendedACLResponse.Body
SetExtendedACLResponse has an empty body because the operation is
asynchronous and the update should be reflected in Container smart contract's
storage after next block is issued in sidechain.
container/types.proto
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. 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 | Container format version. Effectively, the version of API library used to create the container. | |
| owner_id | neo.fs.v2.refs.OwnerID | Identifier of the container owner | |
| nonce | bytes | Nonce is a 16 byte UUIDv4, used to avoid collisions of ContainerIDs |
|
| basic_acl | 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 | repeated | Attributes represent immutable container's meta data |
| placement_policy | neo.fs.v2.netmap.PlacementPolicy | Placement policy for the object inside the container |
Message Container.Attribute
Attribute is a user-defined Key-Value metadata pair attached to the
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 values will be considered invalid.
There are some "well-known" attributes affecting system behaviour:
- __NEOFS__SUBNET
String ID of a container's storage subnet. Any container can be attached to one subnet only. - __NEOFS__NAME
String of a human-friendly container name registered as a domain in NNS contract. - __NEOFS__ZONE
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:
- Name
Human-friendly name - Timestamp
User-defined local time of container creation in Unix Timestamp format
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | Attribute name key | |
| value | string | Attribute value |
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 |