From 5befe14968a3b5eff2db684299830748a2b1ac36 Mon Sep 17 00:00:00 2001 From: Evgeniy Kulikov Date: Wed, 20 Nov 2019 18:57:51 +0300 Subject: [PATCH] docs: add accounting proto documentation --- accounting/service.proto | 8 ++++++ accounting/types.proto | 54 ++++++++++++++++++++++++++------------- accounting/withdraw.proto | 33 ++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 18 deletions(-) diff --git a/accounting/service.proto b/accounting/service.proto index b75bf9c9..f975c232 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -8,16 +8,24 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Accounting is a service that provides access for accounting balance +// information service Accounting { + // Balance returns current balance status of the NeoFS user rpc Balance(BalanceRequest) returns (BalanceResponse); } message BalanceRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } message BalanceResponse { + // Balance contains current account balance state 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; } diff --git a/accounting/types.proto b/accounting/types.proto index 1b4e7838..ac512b91 100644 --- a/accounting/types.proto +++ b/accounting/types.proto @@ -7,61 +7,63 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; -// Snapshot accounting messages message Account { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Address is identifier of accounting record string Address = 2; + // ParentAddress is identifier of parent accounting record string ParentAddress = 3; + // ActiveFunds is amount of active (non locked) funds for account decimal.Decimal ActiveFunds = 4; + // Lifetime is time until account is valid (used for lock accounts) Lifetime Lifetime = 5 [(gogoproto.nullable) = false]; + // LockTarget is the purpose of lock funds (it might be withdraw or payment for storage) LockTarget LockTarget = 6; + // LockAccounts contains child accounts with locked funds repeated Account LockAccounts = 7; } +// LockTarget must be one of two options message LockTarget { oneof Target { + // WithdrawTarget used when user requested withdraw WithdrawTarget WithdrawTarget = 1; + // ContainerCreateTarget used when user requested creation of container ContainerCreateTarget ContainerCreateTarget = 2; } } -// Snapshot balance messages message Balances { + // Accounts contains multiple account snapshots repeated Account Accounts = 1 [(gogoproto.nullable) = false]; } -// PayIn / PayOut messages message PayIO { + // BlockID contains id of the NEO block where withdraw or deposit + // call was invoked uint64 BlockID = 1; + // Transactions contains all transactions that founded in block + // and used for PayIO 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 { + // Unit can be Unlimited, based on NeoFS epoch or Neo block enum Unit { Unlimited = 0; NeoFSEpoch = 1; NeoBlock = 2; } + // Unit describes how lifetime is measured in account Unit unit = 1 [(gogoproto.customname) = "Unit"]; + // Value describes how long lifetime will be valid int64 Value = 2; } -// Transaction messages message Tx { + // Type can be withdrawal, payIO or inner enum Type { Unknown = 0; Withdraw = 1; @@ -69,38 +71,54 @@ message Tx { Inner = 3; } + // Type describes target of transaction Type type = 1 [(gogoproto.customname) = "Type"]; + // From describes sender of funds string From = 2; + // To describes receiver of funds string To = 3; + // Amount describes amount of funds decimal.Decimal Amount = 4; - bytes PublicKeys = 5; // of sender + // PublicKeys contains public key of sender + bytes PublicKeys = 5; } message Settlement { message Receiver { + // To is the address of funds recipient string To = 1; + // Amount is the amount of funds that will be sent decimal.Decimal Amount = 2; } message Container { + // CID is container identifier 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]; } message Tx { + // From is the address of the sender of funds string From = 1; + // Container that successfully had passed the audit Container Container = 2 [(gogoproto.nullable) = false]; + // Receivers is a set of addresses of funds recipients repeated Receiver Receivers = 3 [(gogoproto.nullable) = false]; } + // Epoch contains an epoch when settlement was accepted uint64 Epoch = 1; + // Transactions is a set of transactions repeated Tx Transactions = 2; } message ContainerCreateTarget { + // CID is container identifier bytes CID = 1 [(gogoproto.customtype) = "CID", (gogoproto.nullable) = false]; } message WithdrawTarget { + // Cheque is a string representation of cheque id string Cheque = 1; } diff --git a/accounting/withdraw.proto b/accounting/withdraw.proto index c099ef7c..33ce402f 100644 --- a/accounting/withdraw.proto +++ b/accounting/withdraw.proto @@ -7,55 +7,88 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto"; option (gogoproto.stable_marshaler_all) = true; +// Withdraw is a service that provides withdraw assets operations from the NeoFS service Withdraw { + // Get returns cheque if it was signed by inner ring nodes rpc Get(GetRequest) returns (GetResponse); + // Put ask inner ring nodes to sign a cheque for withdraw invoke rpc Put(PutRequest) returns (PutResponse); + // List shows all user's checks rpc List(ListRequest) returns (ListResponse); + // Delete allows user to remove unused cheque rpc Delete(DeleteRequest) returns (DeleteResponse); } message Item { + // ID is a cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Amount of funds decimal.Decimal Amount = 3; + // Height is the neo blockchain height until the cheque is valid uint64 Height = 4; + // Payload contains cheque representation in bytes bytes Payload = 5; } message GetRequest { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address bytes OwnerID = 2 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 3; } + message GetResponse { + // Item is cheque with meta information Item Withdraw = 1; } message PutRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // Amount of funds decimal.Decimal Amount = 2; + // Height is the neo blockchain height until the cheque is valid uint64 Height = 3; + // MessageID is a nonce for uniq request (UUIDv4) bytes MessageID = 4 [(gogoproto.customtype) = "MessageID", (gogoproto.nullable) = false]; + // Signature is a signature of the sent request bytes Signature = 5; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 6; } message PutResponse { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; } message ListRequest { + // OwnerID is a wallet address bytes OwnerID = 1 [(gogoproto.customtype) = "OwnerID", (gogoproto.nullable) = false]; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 2; } + message ListResponse { + // Item is a set of cheques with meta information repeated Item Items = 1; } message DeleteRequest { + // ID is cheque identifier bytes ID = 1 [(gogoproto.customtype) = "ChequeID", (gogoproto.nullable) = false]; + // OwnerID is a wallet address 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]; + // Signature is a signature of the sent request bytes Signature = 4; + // TTL must be larger than zero, it decreased in every neofs-node uint32 TTL = 5; } + +// DeleteResponse is empty message DeleteResponse {}