docs: add accounting proto documentation

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;
 }

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;
 }

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 {}