28 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, container
is added into smart contract storage.
| 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, container
is added into smart contract storage.
| Name | Input | Output |
|---|---|---|
| Delete | DeleteRequest | DeleteResponse |
Method Get
Returns container structure from Container smart contract storage.
| Name | Input | Output |
|---|---|---|
| Get | GetRequest | GetResponse |
Method List
Returns all owner's containers from 'Container` smart contract' storage.
| 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, Extended ACL changes are added into smart contract storage.
| Name | Input | Output |
|---|---|---|
| SetExtendedACL | SetExtendedACLRequest | SetExtendedACLResponse |
Method GetExtendedACL
Returns Extended ACL table and signature from Container smart contract
storage.
| Name | Input | Output |
|---|---|---|
| GetExtendedACL | GetExtendedACLRequest | GetExtendedACLResponse |
Method AnnounceUsedSpace
Announce container used space values for P2P synchronization.
| 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, then announcements transferred in a batch. |
Message AnnounceUsedSpaceRequest.Body.Announcement
Announcement contains used space information about single container.
| Field | Type | Label | Description |
|---|---|---|---|
| epoch | uint64 | Epoch number for which 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 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 a signed ContainerID as a proof of
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.Signature | 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 did not have Extended ACL Table attached or Extended ACL was not allowed at container creation.
| Field | Type | Label | Description |
|---|---|---|---|
| eacl | neo.fs.v2.acl.EACLTable | Extended ACL requested, if available | |
| signature | neo.fs.v2.refs.Signature | 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 was already verified on container creation.
| Field | Type | Label | Description |
|---|---|---|---|
| container | Container | Requested container structure | |
| signature | neo.fs.v2.refs.Signature | Signature of a stable-marshalled container according to RFC-6979 | |
| session_token | neo.fs.v2.session.SessionToken | Session token if the container was created within a 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.Signature | 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 was 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 container | |
| signature | neo.fs.v2.refs.Signature | 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 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. ID of the 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 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 owner, system, others groups and 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 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 container's storage subnet. Container can be attached to only one subnet.
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 |