frostfs-api-go/docs/accounting.md
2019-11-21 16:16:34 +03:00

16 KiB

Protocol Documentation

Table of Contents

Top

accounting/service.proto

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 BalanceResponse

Message BalanceRequest

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

Message BalanceResponse

Field Type Label Description
Balance decimal.Decimal Balance contains current account balance state
LockAccounts Account repeated LockAccounts contains information about locked funds. Locked funds appear when user pays for storage or withdraw assets.

Top

accounting/types.proto

Message Account

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

Message Balances

Field Type Label Description
Accounts Account repeated Accounts contains multiple account snapshots

Message ContainerCreateTarget

Field Type Label Description
CID bytes CID is container identifier

Message Lifetime

Field Type Label Description
unit Lifetime.Unit Unit describes how lifetime is measured in account
Value int64 Value describes how long lifetime will be valid

Message LockTarget

LockTarget must be one of two options

Field Type Label Description
WithdrawTarget WithdrawTarget WithdrawTarget used when user requested withdraw
ContainerCreateTarget ContainerCreateTarget ContainerCreateTarget used when user requested creation of container

Message PayIO

Field Type Label Description
BlockID uint64 BlockID contains id of the NEO block where withdraw or deposit call was invoked
Transactions Tx repeated Transactions contains all transactions that founded in block and used for PayIO

Message Settlement

Field Type Label Description
Epoch uint64 Epoch contains an epoch when settlement was accepted
Transactions Settlement.Tx repeated Transactions is a set of transactions

Message Settlement.Container

Field Type Label Description
CID bytes CID is container identifier
SGIDs bytes repeated SGIDs is a set of storage groups that successfully passed the audit

Message Settlement.Receiver

Field Type Label Description
To string To is the address of funds recipient
Amount decimal.Decimal Amount is the amount of funds that will be sent

Message Settlement.Tx

Field Type Label Description
From string From is the address of the sender of funds
Container Settlement.Container Container that successfully had passed the audit
Receivers Settlement.Receiver repeated Receivers is a set of addresses of funds recipients

Message Tx

Field Type Label Description
type Tx.Type Type describes target of transaction
From string From describes sender of funds
To string To describes receiver of funds
Amount decimal.Decimal Amount describes amount of funds
PublicKeys bytes PublicKeys contains public key of sender

Message WithdrawTarget

Field Type Label Description
Cheque string Cheque is a string representation of cheque id

Lifetime.Unit

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

Name Number Description
Unlimited 0
NeoFSEpoch 1
NeoBlock 2

Tx.Type

Type can be withdrawal, payIO or inner

Name Number Description
Unknown 0
Withdraw 1
PayIO 2
Inner 3

Top

accounting/withdraw.proto

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 GetResponse

Method Put

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

Name Input Output
Put PutRequest PutResponse

Method List

List shows all user's checks

Name Input Output
List ListRequest ListResponse

Method Delete

Delete allows user to remove unused cheque

Name Input Output
Delete DeleteRequest DeleteResponse

Message DeleteRequest

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

Message DeleteResponse

DeleteResponse is empty

Message GetRequest

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

Message GetResponse

Field Type Label Description
Withdraw Item Withdraw is cheque with meta information

Message Item

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

Message ListRequest

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

Message ListResponse

Field Type Label Description
Items Item repeated Items is a set of cheques with meta information

Message PutRequest

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

Message PutResponse

Field Type Label Description
ID bytes ID is cheque identifier

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