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

## Table of Contents

- [apemanager/service.proto](#apemanager/service.proto)
  - Services
      - [APEManagerService](#frost.fs.apemanager.APEManagerService)

  - Messages
      - [AddChainRequest](#frost.fs.apemanager.AddChainRequest)
      - [AddChainRequest.Body](#frost.fs.apemanager.AddChainRequest.Body)
      - [AddChainResponse](#frost.fs.apemanager.AddChainResponse)
      - [AddChainResponse.Body](#frost.fs.apemanager.AddChainResponse.Body)
      - [ListChainsRequest](#frost.fs.apemanager.ListChainsRequest)
      - [ListChainsRequest.Body](#frost.fs.apemanager.ListChainsRequest.Body)
      - [ListChainsResponse](#frost.fs.apemanager.ListChainsResponse)
      - [ListChainsResponse.Body](#frost.fs.apemanager.ListChainsResponse.Body)
      - [RemoveChainRequest](#frost.fs.apemanager.RemoveChainRequest)
      - [RemoveChainRequest.Body](#frost.fs.apemanager.RemoveChainRequest.Body)
      - [RemoveChainResponse](#frost.fs.apemanager.RemoveChainResponse)
      - [RemoveChainResponse.Body](#frost.fs.apemanager.RemoveChainResponse.Body)


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



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

## apemanager/service.proto




<a name="frost.fs.apemanager.APEManagerService"></a>

### Service "frost.fs.apemanager.APEManagerService"
`APEManagerService` provides API to manage rule chains within sidechain's
`Policy` smart contract.

```
rpc AddChain(AddChainRequest) returns (AddChainResponse);
rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse);
rpc ListChains(ListChainsRequest) returns (ListChainsResponse);

```

#### Method AddChain

Add a rule chain for a specific target to `Policy` smart contract.

Statuses:
- **OK** (0, SECTION_SUCCESS): \
  the chain has been successfully added;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  container (as target) not found;
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  the operation is denied by the service.

| Name | Input | Output |
| ---- | ----- | ------ |
| AddChain | [AddChainRequest](#frost.fs.apemanager.AddChainRequest) | [AddChainResponse](#frost.fs.apemanager.AddChainResponse) |
#### Method RemoveChain

Remove a rule chain for a specific target from `Policy` smart contract.
RemoveChain is an idempotent operation: removal of non-existing rule chain
also means success.

Statuses:
- **OK** (0, SECTION_SUCCESS): \
  the chain has been successfully removed;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  container (as target) not found;
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  the operation is denied by the service.

| Name | Input | Output |
| ---- | ----- | ------ |
| RemoveChain | [RemoveChainRequest](#frost.fs.apemanager.RemoveChainRequest) | [RemoveChainResponse](#frost.fs.apemanager.RemoveChainResponse) |
#### Method ListChains

List chains defined for a specific target from `Policy` smart contract.

Statuses:
- **OK** (0, SECTION_SUCCESS): \
  chains have been successfully listed;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
  container (as target) not found;
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
  the operation is denied by the service.

| Name | Input | Output |
| ---- | ----- | ------ |
| ListChains | [ListChainsRequest](#frost.fs.apemanager.ListChainsRequest) | [ListChainsResponse](#frost.fs.apemanager.ListChainsResponse) |
 <!-- end services -->


<a name="frost.fs.apemanager.AddChainRequest"></a>

### Message AddChainRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [AddChainRequest.Body](#frost.fs.apemanager.AddChainRequest.Body) |  | The request's body. |
| 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.apemanager.AddChainRequest.Body"></a>

### Message AddChainRequest.Body



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| target | [frost.fs.ape.ChainTarget](#frost.fs.ape.ChainTarget) |  | A target for which a rule chain is added. |
| chain | [frost.fs.ape.Chain](#frost.fs.ape.Chain) |  | The chain to set for the target. |


<a name="frost.fs.apemanager.AddChainResponse"></a>

### Message AddChainResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [AddChainResponse.Body](#frost.fs.apemanager.AddChainResponse.Body) |  | The response's body. |
| 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.apemanager.AddChainResponse.Body"></a>

### Message AddChainResponse.Body



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| chain_id | [bytes](#bytes) |  | Chain ID assigned for the added rule chain. If chain ID is left empty in the request, then it will be generated. |


<a name="frost.fs.apemanager.ListChainsRequest"></a>

### Message ListChainsRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [ListChainsRequest.Body](#frost.fs.apemanager.ListChainsRequest.Body) |  | The request's body. |
| 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.apemanager.ListChainsRequest.Body"></a>

### Message ListChainsRequest.Body



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| target | [frost.fs.ape.ChainTarget](#frost.fs.ape.ChainTarget) |  | Target for which rule chains are listed. |


<a name="frost.fs.apemanager.ListChainsResponse"></a>

### Message ListChainsResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [ListChainsResponse.Body](#frost.fs.apemanager.ListChainsResponse.Body) |  | The response's body. |
| 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.apemanager.ListChainsResponse.Body"></a>

### Message ListChainsResponse.Body



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| chains | [frost.fs.ape.Chain](#frost.fs.ape.Chain) | repeated | The list of chains defined for the reqeusted target. |


<a name="frost.fs.apemanager.RemoveChainRequest"></a>

### Message RemoveChainRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [RemoveChainRequest.Body](#frost.fs.apemanager.RemoveChainRequest.Body) |  | The request's body. |
| 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.apemanager.RemoveChainRequest.Body"></a>

### Message RemoveChainRequest.Body



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| target | [frost.fs.ape.ChainTarget](#frost.fs.ape.ChainTarget) |  | Target for which a rule chain is removed. |
| chain_id | [bytes](#bytes) |  | Chain ID assigned for the rule chain. |


<a name="frost.fs.apemanager.RemoveChainResponse"></a>

### Message RemoveChainResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| body | [RemoveChainResponse.Body](#frost.fs.apemanager.RemoveChainResponse.Body) |  | The response's body. |
| 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.apemanager.RemoveChainResponse.Body"></a>

### Message RemoveChainResponse.Body
Since RemoveChain is an idempotent operation, then the only indicator that
operation could not be performed is an error returning to a client.


 <!-- 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 |