docs: add accounting proto documentation

This commit is contained in:
Evgeniy Kulikov 2019-11-20 18:57:51 +03:00 committed by alexvanin
parent 04a5b80550
commit 5befe14968
3 changed files with 77 additions and 18 deletions

View file

@ -8,16 +8,24 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Accounting is a service that provides access for accounting balance
// information
service Accounting { service Accounting {
// Balance returns current balance status of the NeoFS user
rpc Balance(BalanceRequest) returns (BalanceResponse); rpc Balance(BalanceRequest) returns (BalanceResponse);
} }
message BalanceRequest { message BalanceRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
message BalanceResponse { message BalanceResponse {
// Balance contains current account balance state
decimal.Decimal Balance = 1; decimal.Decimal Balance = 1;
// LockAccounts contains information about locked funds. Locked funds appear
// when user pays for storage or withdraw assets.
repeated Account LockAccounts = 2; repeated Account LockAccounts = 2;
} }

View file

@ -7,61 +7,63 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Snapshot accounting messages
message Account { message Account {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Address is identifier of accounting record
string Address = 2; string Address = 2;
// ParentAddress is identifier of parent accounting record
string ParentAddress = 3; string ParentAddress = 3;
// ActiveFunds is amount of active (non locked) funds for account
decimal.Decimal ActiveFunds = 4; decimal.Decimal ActiveFunds = 4;
// Lifetime is time until account is valid (used for lock accounts)
Lifetime Lifetime = 5 [(gogoproto.nullable) = false]; Lifetime Lifetime = 5 [(gogoproto.nullable) = false];
// LockTarget is the purpose of lock funds (it might be withdraw or payment for storage)
LockTarget LockTarget = 6; LockTarget LockTarget = 6;
// LockAccounts contains child accounts with locked funds
repeated Account LockAccounts = 7; repeated Account LockAccounts = 7;
} }
// LockTarget must be one of two options
message LockTarget { message LockTarget {
oneof Target { oneof Target {
// WithdrawTarget used when user requested withdraw
WithdrawTarget WithdrawTarget = 1; WithdrawTarget WithdrawTarget = 1;
// ContainerCreateTarget used when user requested creation of container
ContainerCreateTarget ContainerCreateTarget = 2; ContainerCreateTarget ContainerCreateTarget = 2;
} }
} }
// Snapshot balance messages
message Balances { message Balances {
// Accounts contains multiple account snapshots
repeated Account Accounts = 1 [(gogoproto.nullable) = false]; repeated Account Accounts = 1 [(gogoproto.nullable) = false];
} }
// PayIn / PayOut messages
message PayIO { message PayIO {
// BlockID contains id of the NEO block where withdraw or deposit
// call was invoked
uint64 BlockID = 1; uint64 BlockID = 1;
// Transactions contains all transactions that founded in block
// and used for PayIO
repeated Tx Transactions = 2 [(gogoproto.nullable) = false]; repeated Tx Transactions = 2 [(gogoproto.nullable) = false];
} }
// Clearing messages
message Clearing {
repeated Tx Transactions = 1 [(gogoproto.nullable) = false];
}
// Clearing messages
message Withdraw {
string ID = 1;
uint64 Epoch = 2;
Tx Transaction = 3;
}
// Lifetime of locks
message Lifetime { message Lifetime {
// Unit can be Unlimited, based on NeoFS epoch or Neo block
enum Unit { enum Unit {
Unlimited = 0; Unlimited = 0;
NeoFSEpoch = 1; NeoFSEpoch = 1;
NeoBlock = 2; NeoBlock = 2;
} }
// Unit describes how lifetime is measured in account
Unit unit = 1 [(gogoproto.customname) = "Unit"]; Unit unit = 1 [(gogoproto.customname) = "Unit"];
// Value describes how long lifetime will be valid
int64 Value = 2; int64 Value = 2;
} }
// Transaction messages
message Tx { message Tx {
// Type can be withdrawal, payIO or inner
enum Type { enum Type {
Unknown = 0; Unknown = 0;
Withdraw = 1; Withdraw = 1;
@ -69,38 +71,54 @@ message Tx {
Inner = 3; Inner = 3;
} }
// Type describes target of transaction
Type type = 1 [(gogoproto.customname) = "Type"]; Type type = 1 [(gogoproto.customname) = "Type"];
// From describes sender of funds
string From = 2; string From = 2;
// To describes receiver of funds
string To = 3; string To = 3;
// Amount describes amount of funds
decimal.Decimal Amount = 4; decimal.Decimal Amount = 4;
bytes PublicKeys = 5; // of sender // PublicKeys contains public key of sender
bytes PublicKeys = 5;
} }
message Settlement { message Settlement {
message Receiver { message Receiver {
// To is the address of funds recipient
string To = 1; string To = 1;
// Amount is the amount of funds that will be sent
decimal.Decimal Amount = 2; decimal.Decimal Amount = 2;
} }
message Container { message Container {
// CID is container identifier
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
// SGIDs is a set of storage groups that successfully passed the audit
repeated bytes SGIDs = 2 [(gogoproto.customtype) = "SGID", (gogoproto.nullable) = false]; repeated bytes SGIDs = 2 [(gogoproto.customtype) = "SGID", (gogoproto.nullable) = false];
} }
message Tx { message Tx {
// From is the address of the sender of funds
string From = 1; string From = 1;
// Container that successfully had passed the audit
Container Container = 2 [(gogoproto.nullable) = false]; Container Container = 2 [(gogoproto.nullable) = false];
// Receivers is a set of addresses of funds recipients
repeated Receiver Receivers = 3 [(gogoproto.nullable) = false]; repeated Receiver Receivers = 3 [(gogoproto.nullable) = false];
} }
// Epoch contains an epoch when settlement was accepted
uint64 Epoch = 1; uint64 Epoch = 1;
// Transactions is a set of transactions
repeated Tx Transactions = 2; repeated Tx Transactions = 2;
} }
message ContainerCreateTarget { message ContainerCreateTarget {
// CID is container identifier
bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false];
} }
message WithdrawTarget { message WithdrawTarget {
// Cheque is a string representation of cheque id
string Cheque = 1; string Cheque = 1;
} }

View file

@ -7,55 +7,88 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.stable_marshaler_all) = true; option (gogoproto.stable_marshaler_all) = true;
// Withdraw is a service that provides withdraw assets operations from the NeoFS
service Withdraw { service Withdraw {
// Get returns cheque if it was signed by inner ring nodes
rpc Get(GetRequest) returns (GetResponse); rpc Get(GetRequest) returns (GetResponse);
// Put ask inner ring nodes to sign a cheque for withdraw invoke
rpc Put(PutRequest) returns (PutResponse); rpc Put(PutRequest) returns (PutResponse);
// List shows all user's checks
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
// Delete allows user to remove unused cheque
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
} }
message Item { message Item {
// ID is a cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Amount of funds
decimal.Decimal Amount = 3; decimal.Decimal Amount = 3;
// Height is the neo blockchain height until the cheque is valid
uint64 Height = 4; uint64 Height = 4;
// Payload contains cheque representation in bytes
bytes Payload = 5; bytes Payload = 5;
} }
message GetRequest { message GetRequest {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 3; uint32 TTL = 3;
} }
message GetResponse { message GetResponse {
// Item is cheque with meta information
Item Withdraw = 1; Item Withdraw = 1;
} }
message PutRequest { message PutRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// Amount of funds
decimal.Decimal Amount = 2; decimal.Decimal Amount = 2;
// Height is the neo blockchain height until the cheque is valid
uint64 Height = 3; uint64 Height = 3;
// MessageID is a nonce for uniq request (UUIDv4)
bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
// Signature is a signature of the sent request
bytes Signature = 5; bytes Signature = 5;
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 6; uint32 TTL = 6;
} }
message PutResponse { message PutResponse {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
} }
message ListRequest { message ListRequest {
// OwnerID is a wallet address
bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 2; uint32 TTL = 2;
} }
message ListResponse { message ListResponse {
// Item is a set of cheques with meta information
repeated Item Items = 1; repeated Item Items = 1;
} }
message DeleteRequest { message DeleteRequest {
// ID is cheque identifier
bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false];
// OwnerID is a wallet address
bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false];
// MessageID is a nonce for uniq request (UUIDv4)
bytes MessageID = 3 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; bytes MessageID = 3 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false];
// Signature is a signature of the sent request
bytes Signature = 4; bytes Signature = 4;
// TTL must be larger than zero, it decreased in every neofs-node
uint32 TTL = 5; uint32 TTL = 5;
} }
// DeleteResponse is empty
message DeleteResponse {} message DeleteResponse {}