frostfs-api/proto-docs/accounting.md

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

## Table of Contents

- [accounting/service.proto](#accounting/service.proto)
 - Services
    - [Accounting](#accounting.Accounting)
    
  - Messages
    - [BalanceRequest](#accounting.BalanceRequest)
    - [BalanceResponse](#accounting.BalanceResponse)
    

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

  - Messages
    - [Account](#accounting.Account)
    - [Balances](#accounting.Balances)
    - [ContainerCreateTarget](#accounting.ContainerCreateTarget)
    - [Lifetime](#accounting.Lifetime)
    - [LockTarget](#accounting.LockTarget)
    - [PayIO](#accounting.PayIO)
    - [Settlement](#accounting.Settlement)
    - [Settlement.Container](#accounting.Settlement.Container)
    - [Settlement.Receiver](#accounting.Settlement.Receiver)
    - [Settlement.Tx](#accounting.Settlement.Tx)
    - [Tx](#accounting.Tx)
    - [WithdrawTarget](#accounting.WithdrawTarget)
    

- [accounting/withdraw.proto](#accounting/withdraw.proto)
 - Services
    - [Withdraw](#accounting.Withdraw)
    
  - Messages
    - [DeleteRequest](#accounting.DeleteRequest)
    - [DeleteResponse](#accounting.DeleteResponse)
    - [GetRequest](#accounting.GetRequest)
    - [GetResponse](#accounting.GetResponse)
    - [Item](#accounting.Item)
    - [ListRequest](#accounting.ListRequest)
    - [ListResponse](#accounting.ListResponse)
    - [PutRequest](#accounting.PutRequest)
    - [PutResponse](#accounting.PutResponse)
    

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



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

## accounting/service.proto




<a name="accounting.Accounting"></a>

### Service "accounting.Accounting"
Accounting is a service that provides access for accounting balance
information

```
rpc Balance(BalanceRequest) returns (BalanceResponse);

```

#### Method Balance

Balance returns current balance status of the NeoFS user

| Name | Input | Output |
| ---- | ----- | ------ |
| Balance | [BalanceRequest](#accounting.BalanceRequest) | [BalanceResponse](#accounting.BalanceResponse) |
 <!-- end services -->


<a name="accounting.BalanceRequest"></a>

### Message BalanceRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [refs.OwnerID](#refs.OwnerID) |  | OwnerID carries user identifier in NeoFS system. |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) |  | RequestMetaHeader contains information about request meta headers (should be embedded into message) |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) |  | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) |


<a name="accounting.BalanceResponse"></a>

### Message BalanceResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Balance | [decimal.Decimal](#decimal.Decimal) |  | Balance contains current account balance state |
| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains information about locked funds. Locked funds appear when user pays for storage or withdraw assets. |

 <!-- end messages -->

 <!-- end enums -->



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

## accounting/types.proto


 <!-- end services -->


<a name="accounting.Account"></a>

### Message Account



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| Address | [string](#string) |  | Address is identifier of accounting record |
| ParentAddress | [string](#string) |  | ParentAddress is identifier of parent accounting record |
| ActiveFunds | [decimal.Decimal](#decimal.Decimal) |  | ActiveFunds is amount of active (non locked) funds for account |
| Lifetime | [Lifetime](#accounting.Lifetime) |  | Lifetime is time until account is valid (used for lock accounts) |
| LockTarget | [LockTarget](#accounting.LockTarget) |  | LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) |
| LockAccounts | [Account](#accounting.Account) | repeated | LockAccounts contains child accounts with locked funds |


<a name="accounting.Balances"></a>

### Message Balances



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Accounts | [Account](#accounting.Account) | repeated | Accounts contains multiple account snapshots |


<a name="accounting.ContainerCreateTarget"></a>

### Message ContainerCreateTarget



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) |  | CID is container identifier |


<a name="accounting.Lifetime"></a>

### Message Lifetime



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| unit | [Lifetime.Unit](#accounting.Lifetime.Unit) |  | Unit describes how lifetime is measured in account |
| Value | [int64](#int64) |  | Value describes how long lifetime will be valid |


<a name="accounting.LockTarget"></a>

### Message LockTarget
LockTarget must be one of two options


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| WithdrawTarget | [WithdrawTarget](#accounting.WithdrawTarget) |  | WithdrawTarget used when user requested withdraw |
| ContainerCreateTarget | [ContainerCreateTarget](#accounting.ContainerCreateTarget) |  | ContainerCreateTarget used when user requested creation of container |


<a name="accounting.PayIO"></a>

### Message PayIO



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| BlockID | [uint64](#uint64) |  | BlockID contains id of the NEO block where withdraw or deposit call was invoked |
| Transactions | [Tx](#accounting.Tx) | repeated | Transactions contains all transactions that founded in block and used for PayIO |


<a name="accounting.Settlement"></a>

### Message Settlement



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Epoch | [uint64](#uint64) |  | Epoch contains an epoch when settlement was accepted |
| Transactions | [Settlement.Tx](#accounting.Settlement.Tx) | repeated | Transactions is a set of transactions |


<a name="accounting.Settlement.Container"></a>

### Message Settlement.Container



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| CID | [bytes](#bytes) |  | CID is container identifier |
| SGIDs | [bytes](#bytes) | repeated | SGIDs is a set of storage groups that successfully passed the audit |


<a name="accounting.Settlement.Receiver"></a>

### Message Settlement.Receiver



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| To | [string](#string) |  | To is the address of funds recipient |
| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount is the amount of funds that will be sent |


<a name="accounting.Settlement.Tx"></a>

### Message Settlement.Tx



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| From | [string](#string) |  | From is the address of the sender of funds |
| Container | [Settlement.Container](#accounting.Settlement.Container) |  | Container that successfully had passed the audit |
| Receivers | [Settlement.Receiver](#accounting.Settlement.Receiver) | repeated | Receivers is a set of addresses of funds recipients |


<a name="accounting.Tx"></a>

### Message Tx



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [Tx.Type](#accounting.Tx.Type) |  | Type describes target of transaction |
| From | [string](#string) |  | From describes sender of funds |
| To | [string](#string) |  | To describes receiver of funds |
| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount describes amount of funds |
| PublicKeys | [bytes](#bytes) |  | PublicKeys contains public key of sender |


<a name="accounting.WithdrawTarget"></a>

### Message WithdrawTarget



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Cheque | [string](#string) |  | Cheque is a string representation of cheque id |

 <!-- end messages -->


<a name="accounting.Lifetime.Unit"></a>

### Lifetime.Unit
Unit can be Unlimited, based on NeoFS epoch or Neo block

| Name | Number | Description |
| ---- | ------ | ----------- |
| Unlimited | 0 |  |
| NeoFSEpoch | 1 |  |
| NeoBlock | 2 |  |



<a name="accounting.Tx.Type"></a>

### Tx.Type
Type can be withdrawal, payIO or inner

| Name | Number | Description |
| ---- | ------ | ----------- |
| Unknown | 0 |  |
| Withdraw | 1 |  |
| PayIO | 2 |  |
| Inner | 3 |  |


 <!-- end enums -->



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

## accounting/withdraw.proto




<a name="accounting.Withdraw"></a>

### Service "accounting.Withdraw"
Withdraw is a service that provides withdraw assets operations from the NeoFS

```
rpc Get(GetRequest) returns (GetResponse);
rpc Put(PutRequest) returns (PutResponse);
rpc List(ListRequest) returns (ListResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);

```

#### Method Get

Get returns cheque if it was signed by inner ring nodes

| Name | Input | Output |
| ---- | ----- | ------ |
| Get | [GetRequest](#accounting.GetRequest) | [GetResponse](#accounting.GetResponse) |
#### Method Put

Put ask inner ring nodes to sign a cheque for withdraw invoke

| Name | Input | Output |
| ---- | ----- | ------ |
| Put | [PutRequest](#accounting.PutRequest) | [PutResponse](#accounting.PutResponse) |
#### Method List

List shows all user's checks

| Name | Input | Output |
| ---- | ----- | ------ |
| List | [ListRequest](#accounting.ListRequest) | [ListResponse](#accounting.ListResponse) |
#### Method Delete

Delete allows user to remove unused cheque

| Name | Input | Output |
| ---- | ----- | ------ |
| Delete | [DeleteRequest](#accounting.DeleteRequest) | [DeleteResponse](#accounting.DeleteResponse) |
 <!-- end services -->


<a name="accounting.DeleteRequest"></a>

### Message DeleteRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) |  | ID is cheque identifier |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| MessageID | [bytes](#bytes) |  | MessageID is a nonce for uniq request (UUIDv4) |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) |  | RequestMetaHeader contains information about request meta headers (should be embedded into message) |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) |  | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) |


<a name="accounting.DeleteResponse"></a>

### Message DeleteResponse
DeleteResponse is empty



<a name="accounting.GetRequest"></a>

### Message GetRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) |  | ID is cheque identifier |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) |  | RequestMetaHeader contains information about request meta headers (should be embedded into message) |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) |  | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) |


<a name="accounting.GetResponse"></a>

### Message GetResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Withdraw | [Item](#accounting.Item) |  | Withdraw is cheque with meta information |


<a name="accounting.Item"></a>

### Message Item



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) |  | ID is a cheque identifier |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount of funds |
| Height | [uint64](#uint64) |  | Height is the neo blockchain height until the cheque is valid |
| Payload | [bytes](#bytes) |  | Payload contains cheque representation in bytes |


<a name="accounting.ListRequest"></a>

### Message ListRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) |  | RequestMetaHeader contains information about request meta headers (should be embedded into message) |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) |  | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) |


<a name="accounting.ListResponse"></a>

### Message ListResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Items | [Item](#accounting.Item) | repeated | Items is a set of cheques with meta information |


<a name="accounting.PutRequest"></a>

### Message PutRequest



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
| Amount | [decimal.Decimal](#decimal.Decimal) |  | Amount of funds |
| Height | [uint64](#uint64) |  | Height is the neo blockchain height until the cheque is valid |
| MessageID | [bytes](#bytes) |  | MessageID is a nonce for uniq request (UUIDv4) |
| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) |  | RequestMetaHeader contains information about request meta headers (should be embedded into message) |
| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) |  | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) |


<a name="accounting.PutResponse"></a>

### Message PutResponse



| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ID | [bytes](#bytes) |  | ID is cheque identifier |

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