frostfs-api-go/docs/accounting.md

Protocol Documentation

Table of Contents

• accounting/service.proto

• Services

  • Accounting

• Messages

  • BalanceRequest
  • BalanceResponse

• accounting/types.proto

  • Messages
    • Account
    • Balances
    • ContainerCreateTarget
    • Lifetime
    • LockTarget
    • PayIO
    • Settlement
    • Settlement.Container
    • Settlement.Receiver
    • Settlement.Tx
    • Tx
    • WithdrawTarget

• accounting/withdraw.proto

• Services

  • Withdraw

• Messages

  • DeleteRequest
  • DeleteResponse
  • GetRequest
  • GetResponse
  • Item
  • ListRequest
  • ListResponse
  • PutRequest
  • PutResponse

• Scalar Value Types

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