carpawell/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update accounting package docs

Browse source 
Adding comments on the formats used in messages.

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev 2020-10-13 12:57:07 +03:00 committed by Stanislav Bogatyrev
parent 28a917028d
commit 99e701e70d
2 changed files with 32 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
accounting/service.proto
View file

@ -9,25 +9,25 @@ import "accounting/types.proto";
import "refs/types.proto"; import "refs/types.proto";
import "session/types.proto"; import "session/types.proto";
// The service provides methods for obtaining information // Accounting service provides methods for interaction with NeoFS sidechain via
// about the account balance in NeoFS system. // other NeoFS nodes to get information about the account balance. Deposit and
// Withdraw operations can't be implemented here, as they require Mainnet NeoFS
// smart contract invocation. Transfer operations between internal NeoFS
// accounts are possible, if both use the same token type.
service AccountingService { service AccountingService {
// Returns the amount of funds for the requested NeoFS account. // Returns the amount of funds in GAS token for the requested NeoFS account.
rpc Balance (BalanceRequest) returns (BalanceResponse); rpc Balance (BalanceRequest) returns (BalanceResponse);
} }
// Message defines the request body of Balance method. // BalanceRequest message
//
// To indicate the account for which the balance is requested, it's identifier
// is used.
//
// To gain access to the requested information, the request body must be formed
// according to the requirements from the system specification.
message BalanceRequest { message BalanceRequest {
//Request body // To indicate the account for which the balance is requested, it's identifier
// is used. It can be any existing account in NeoFS sidechain `Balance` smart
// contract. If omitted, client implementation MUST set it to the request's
// signer `OwnerID`.
message Body { message Body {
// Carries user identifier in NeoFS system for which the balance // Valid user identifier in `OwnerID` format for which the balance is
// is requested. // requested. Required field.
neo.fs.v2.refs.OwnerID owner_id = 1; neo.fs.v2.refs.OwnerID owner_id = 1;
} }
// Body of the balance request message. // Body of the balance request message.
@ -38,18 +38,17 @@ message BalanceRequest {
neo.fs.v2.session.RequestMetaHeader meta_header = 2; neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to // Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness // authenticate the nodes of the message route and check the correctness of
// of transmission. // transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3; neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
} }
// Message defines the response body of Balance method. // BalanceResponse message
//
// The amount of funds is calculated in decimal numbers.
message BalanceResponse { message BalanceResponse {
//Request body // The amount of funds in GAS token for the `OwnerID`'s account requested.
// Balance is `Decimal` format to avoid precision issues with rounding.
message Body { message Body {
// Carries the amount of funds on the account. // Amount of funds in GAS token for the requested account.
Decimal balance = 1; Decimal balance = 1;
} }
// Body of the balance response message. // Body of the balance response message.
@ -60,7 +59,7 @@ message BalanceResponse {
neo.fs.v2.session.ResponseMetaHeader meta_header = 2; neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to // Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness // authenticate the nodes of the message route and check the correctness of
// of transmission. // transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
} }

13
accounting/types.proto
View file

@ -5,11 +5,18 @@ package neo.fs.v2.accounting;
option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting"; option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting";
option csharp_namespace = "NeoFS.API.v2.Accounting"; option csharp_namespace = "NeoFS.API.v2.Accounting";
// Decimal represents the decimal numbers. // Standard floating point data type can't be used in NeoFS due to inexactness
// of the result when doing lots of small number operations. To solve the lost
// precision issue, special `Decimal` format is used for monetary computations.
//
// Please see [The General Decimal Arithmetic
// Specification](http://speleotrove.com/decimal/) for detailed problem
// description.
message Decimal { message Decimal {
// value carries number value. // Number in smallest Token fractions.
int64 value = 1; int64 value = 1;
// precision carries value precision. // Precision value indicating how many smallest fractions can be in one
// integer.
uint32 precision = 2; uint32 precision = 2;
} }