frostfs-api/proto-docs/container.md

# Protocol Documentation
<a name="top"></a>

## Table of Contents

- [container/service.proto](#container/service.proto)
  - Services
      - [ContainerService](#frost.fs.container.ContainerService)

  - Messages
      - [DeleteRequest](#frost.fs.container.DeleteRequest)
      - [DeleteRequest.Body](#frost.fs.container.DeleteRequest.Body)
      - [DeleteResponse](#frost.fs.container.DeleteResponse)
      - [DeleteResponse.Body](#frost.fs.container.DeleteResponse.Body)
      - [GetRequest](#frost.fs.container.GetRequest)
      - [GetRequest.Body](#frost.fs.container.GetRequest.Body)
      - [GetResponse](#frost.fs.container.GetResponse)
      - [GetResponse.Body](#frost.fs.container.GetResponse.Body)
      - [ListRequest](#frost.fs.container.ListRequest)
      - [ListRequest.Body](#frost.fs.container.ListRequest.Body)
      - [ListResponse](#frost.fs.container.ListResponse)
      - [ListResponse.Body](#frost.fs.container.ListResponse.Body)
      - [PutRequest](#frost.fs.container.PutRequest)
      - [PutRequest.Body](#frost.fs.container.PutRequest.Body)
      - [PutResponse](#frost.fs.container.PutResponse)
      - [PutResponse.Body](#frost.fs.container.PutResponse.Body)


- [container/types.proto](#container/types.proto)

  - Messages
      - [Container](#frost.fs.container.Container)
      - [Container.Attribute](#frost.fs.container.Container.Attribute)


- [Scalar Value Types](#scalar-value-types)



<a name="container/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>

## container/service.proto




<a name="frost.fs.container.ContainerService"></a>

### Service "frost.fs.container.ContainerService"
`ContainerService` provides API to interact with `Container` smart contract
in FrostFS sidechain via other FrostFS 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);

```

#### 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);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  container create access denied.

| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#frost.fs.container.PutRequest) | [PutResponse](#frost.fs.container.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);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  container delete access denied.

| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#frost.fs.container.DeleteRequest) | [DeleteResponse](#frost.fs.container.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;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  access to container is denied.

| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#frost.fs.container.GetRequest) | [GetResponse](#frost.fs.container.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);
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
  container list access denied.

| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#frost.fs.container.ListRequest) | [ListResponse](#frost.fs.container.ListResponse) |
 <!-- end services -->


<a name="frost.fs.container.DeleteRequest"></a>

### Message DeleteRequest
Container removal request


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [DeleteRequest.Body](#frost.fs.container.DeleteRequest.Body) |  | Body of container delete request message. |
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.DeleteRequest.Body"></a>

### 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 | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) |  | Identifier of the container to delete from FrostFS |
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) |  | `ContainerID` signed with the container owner's key according to RFC-6979. |


<a name="frost.fs.container.DeleteResponse"></a>

### 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](#frost.fs.container.DeleteResponse.Body) |  | Body of container delete response message. |
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) |  | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) |  | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.DeleteResponse.Body"></a>

### Message DeleteResponse.Body
`DeleteResponse` has an empty body because delete operation is asynchronous
and done via consensus in Inner Ring nodes.



<a name="frost.fs.container.GetRequest"></a>

### Message GetRequest
Get container structure


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [GetRequest.Body](#frost.fs.container.GetRequest.Body) |  | Body of container get request message. |
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.GetRequest.Body"></a>

### Message GetRequest.Body
Get container structure request body.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_id | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) |  | Identifier of the container to get |


<a name="frost.fs.container.GetResponse"></a>

### Message GetResponse
Get container structure


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [GetResponse.Body](#frost.fs.container.GetResponse.Body) |  | Body of container get response message. |
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) |  | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) |  | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.GetResponse.Body"></a>

### 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](#frost.fs.container.Container) |  | Requested container structure |
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) |  | Signature of a stable-marshalled container according to RFC-6979. |
| session_token | [frost.fs.session.SessionToken](#frost.fs.session.SessionToken) |  | Session token if the container has been created within the session |


<a name="frost.fs.container.ListRequest"></a>

### Message ListRequest
List containers


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [ListRequest.Body](#frost.fs.container.ListRequest.Body) |  | Body of list containers request message |
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.ListRequest.Body"></a>

### Message ListRequest.Body
List containers request body.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| owner_id | [frost.fs.refs.OwnerID](#frost.fs.refs.OwnerID) |  | Identifier of the container owner |


<a name="frost.fs.container.ListResponse"></a>

### Message ListResponse
List containers


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [ListResponse.Body](#frost.fs.container.ListResponse.Body) |  | Body of list containers response message. |
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) |  | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) |  | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.ListResponse.Body"></a>

### Message ListResponse.Body
List containers response body.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| container_ids | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` |


<a name="frost.fs.container.PutRequest"></a>

### Message PutRequest
New FrostFS Container creation request


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [PutRequest.Body](#frost.fs.container.PutRequest.Body) |  | Body of container put request message. |
| meta_header | [frost.fs.session.RequestMetaHeader](#frost.fs.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.RequestVerificationHeader](#frost.fs.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.PutRequest.Body"></a>

### 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](#frost.fs.container.Container) |  | Container structure to register in FrostFS |
| signature | [frost.fs.refs.SignatureRFC6979](#frost.fs.refs.SignatureRFC6979) |  | Signature of a stable-marshalled container according to RFC-6979. |


<a name="frost.fs.container.PutResponse"></a>

### Message PutResponse
New FrostFS Container creation response


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [PutResponse.Body](#frost.fs.container.PutResponse.Body) |  | Body of container put response message. |
| meta_header | [frost.fs.session.ResponseMetaHeader](#frost.fs.session.ResponseMetaHeader) |  | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
| verify_header | [frost.fs.session.ResponseVerificationHeader](#frost.fs.session.ResponseVerificationHeader) |  | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |


<a name="frost.fs.container.PutResponse.Body"></a>

### 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 | [frost.fs.refs.ContainerID](#frost.fs.refs.ContainerID) |  | Unique identifier of the newly created container |

 <!-- end messages -->

 <!-- end enums -->



<a name="container/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>

## container/types.proto


 <!-- end services -->


<a name="frost.fs.container.Container"></a>

### 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 | [frost.fs.refs.Version](#frost.fs.refs.Version) |  | Container format version. Effectively, the version of API library used to create the container. |
| owner_id | [frost.fs.refs.OwnerID](#frost.fs.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 the owner, system and others groups, as well as permission bits for `BearerToken` and `Extended ACL` |
| attributes | [Container.Attribute](#frost.fs.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data |
| placement_policy | [frost.fs.netmap.PlacementPolicy](#frost.fs.netmap.PlacementPolicy) |  | Placement policy for the object inside the container |


<a name="frost.fs.container.Container.Attribute"></a>

### 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:

* [ __SYSTEM__NAME ] \
  String of a human-friendly container name registered as a domain in
  NNS contract.
* [ __SYSTEM__ZONE ]  \
  String of a zone for `__SYSTEM__NAME`.
  Used as a TLD of a domain name in NNS contract. If no zone is specified,
  use default zone: `container`.
* [ __SYSTEM__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 FrostFS 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](#string) |  | Attribute name key |
| value | [string](#string) |  | Attribute value |

 <!-- end messages -->

 <!-- end enums -->



## Scalar Value Types

| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double |  | double | double | float |
| <a name="float" /> float |  | float | float | float |
| <a name="int32" /> 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 |
| <a name="int64" /> 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 |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool |  | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |