MASQ-Project
diff --git a/‎USER-INTERFACE-INTERFACE.md‎
Lines changed: 160 additions & 25 deletions b/‎USER-INTERFACE-INTERFACE.md‎
Lines changed: 160 additions & 25 deletions
diff --git a/‎automap/Cargo.lock‎
Lines changed: 2 additions & 2 deletions b/‎automap/Cargo.lock‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎automap/Cargo.toml‎
Lines changed: 1 addition & 1 deletion b/‎automap/Cargo.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎dns_utility/Cargo.lock‎
Lines changed: 2 additions & 2 deletions b/‎dns_utility/Cargo.lock‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎dns_utility/Cargo.toml‎
Lines changed: 1 addition & 1 deletion b/‎dns_utility/Cargo.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎masq/Cargo.toml‎
Lines changed: 6 additions & 1 deletion b/‎masq/Cargo.toml‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎masq/src/command_factory.rs‎
Lines changed: 31 additions & 1 deletion b/‎masq/src/command_factory.rs‎
Lines changed: 31 additions & 1 deletion
@@ -343,7 +343,7 @@ Another reason the secrets might be missing is that there are not yet any secret
         <string>,
         <string>, ...
     ],
-    "PaymentThresholds": {
+    "paymentThresholds": {
         "debtThresholdGwei": <number>,
         "maturityThresholdSec": <number>,
         "paymentGracePeriodSec": <number>,
@@ -392,7 +392,7 @@ database password. If you want to know whether the password you have is the corr
 * `earningWalletAddressOpt`: The wallet address for the earning wallet. This is not secret, so
   if you don't get this field, it's because it hasn't been set yet.
 
-* `gasPrice`: The Node will not pay more than this number of Gwei for gas to complete a transaction.
+* `gasPrice`: The Node will not pay more than this number of gwei for gas to complete a transaction.
 
 * `neighborhoodMode`: The neighborhood mode being currently used, this parameter has nothing to do with descriptors which 
   may have been used in order to set the Node's nearest neighborhood. It is only informative, to know what mode is running
@@ -417,7 +417,7 @@ database password. If you want to know whether the password you have is the corr
   allowed to remain unpaid, or a pending receivable that won’t cause a ban, decreases linearly from the debtThresholdGwei
   to permanentDebtAllowedGwei or unbanBelowGwei.
 
-* `debtThresholdGwei`: Payables higher than this -- in Gwei of MASQ -- will be suggested for payment immediately upon
+* `debtThresholdGwei`: Payables higher than this -- in gwei of MASQ -- will be suggested for payment immediately upon
   passing the maturityThresholdSec age. Payables less than this can stay unpaid longer. Receivables higher than this
   will be expected to be settled by other Nodes, but will never cause bans until they pass the maturityThresholdSec +
   paymentGracePeriodSec age. Receivables less than this will survive longer without banning.
@@ -428,15 +428,15 @@ database password. If you want to know whether the password you have is the corr
 * `paymentGracePeriodSec`: A large receivable can get as old as maturityThresholdSec + paymentGracePeriodSec -- in seconds
   -- before the Node that owes it will be banned.
 
-* `permanentDebtAllowedGwei`: Receivables this small and smaller -- in Gwei of MASQ -- will not cause bans no matter 
+* `permanentDebtAllowedGwei`: Receivables this small and smaller -- in gwei of MASQ -- will not cause bans no matter 
   how old they get.
 
 * `unbanBelowGwei`: When a delinquent Node has been banned due to non-payment, the receivables balance must be paid
-  below this level -- in Gwei of MASQ -- to cause them to be unbanned. In most cases, you'll want this to be set the
+  below this level -- in gwei of MASQ -- to cause them to be unbanned. In most cases, you'll want this to be set the
   same as permanentDebtAllowedGwei.
 
 * `ratePack`: These four parameters specify your rates that your Node will use for charging other Nodes for your provided
-  services. They are currently denominated in Gwei of MASQ, but will be improved to allow denomination in Wei units.
+  services. They are currently denominated in gwei of MASQ, but will be improved to allow denomination in wei units.
   These are ever present values, no matter if the user's set any value, they have defaults.
 
 * `exitByteRate`: This parameter indicates an amount of MASQ demanded to process 1 byte of routed payload while the Node
@@ -595,45 +595,180 @@ field will be null or absent.
 ##### Correspondent: Node
 ##### Layout:
 ```
-"payload": {}
+"payload": {
+    "statsRequired": <boolean>,
+    "topRecordsOpt": <optional {
+            "count": <positive integer>,
+            "orderedBy": <string>
+        }>,
+    "customQueriesOpt": <optional {
+        "payableOpt" : <optional {
+            "minAgeS": <positive integer>,
+            "maxAgeS": <positive integer>,
+            "minBalanceGwei": <positive integer>,
+            "maxBalanceGwei": <positive integer>
+        }>,
+        "receivableOpt": <optional {
+            "minAgeS": <positive integer>,
+            "maxAgeS": <positive integer>,
+            "minBalanceGwei": <positive integer>,
+            "maxBalanceGwei": <positive integer>
+        }> 
+    }>
+}
 ```
 ##### Description:
-Requests financial statistics from the Node.
+This command requests financial statistics from the Node. Without any parameters specified, it produces a brief summary
+of financial information; but the output can be customized to show more details.
+
+The details can bear on two different account types stored in two tables of the persistent database. Those types are
+payables and receivables.  
+
+One option to get more information about them is a query of the top N records from these financial tables, ordered by
+one's preferences, either by balance or age. This command setup always returns two sets of accounts, one set for each
+type.
+
+In a different query mode, the user provides a customized query for either payables or receivables or both. The user
+will be requested to specify ranges of age and balance to constrain the result set.
+
+The limits for the age range can vary from 0 (as recent as possible) to 9,223,372,036,854,775,807 seconds ago (well
+beyond any reasonable scientific estimate of the age of the universe). The limits for the balance range are similarly
+generous, except that receivable balances can be negative as well as positive.
+
+It needs to be stated that each mode excludes the other one.
+
+While statistics has been considered the foundation of this command, it reports back structured information about
+the Node's historical financial operations. This will include services ordered from other Nodes as well as the opposite,
+services provided for other Nodes, represented by monetary values owed and paid to and from this Node's wallets. 
+
+`statsRequired` should be true if historical total balances (see below) are required, false if they are not necessary.
+If topRecordsOpt and customQueriesOpt are both null, statsRequired must not be false, since it would produce an empty
+response otherwise.
+
+`topRecordsOpt` initiates the request for a given number of top accounts from the tables. An optional feature.
+It is important to note that only accounts with positive balances can be displayed by this mode. Some values might stay
+out of scope since there might be cases where receivable balances are negative.
+
+`count` is the maximum number of records to be returned. It should be a number between 1 and 65535, inclusive.
+
+`orderedBy` allows you to choose whether the results are sorted in descending order either by `Balance` or `Age`.
+It is compulsory to use at least one parameter.
+
+`customQueriesOpt` provides another way to get a subset of accounts, this time by more specific metrics. It works for
+both account types, payables and receivables. Possibly only one of them is queried. This query responds well also for 
+balances with negative values, and therefore this is a good fit for a complete check of receivable accounts going 
+possibly negative. 
+
+`payableOpt` is an optional field with values that configure the customized search for payables. It holds four numbers
+that define two ranges of balance and age used as the scope of the search.
+
+`receivableOpt` is an optional field with values that configure the customized search for receivables. It holds four
+numbers that define two ranges of balance and age used as the scope of the search.
+
+Both `payableOpt` and `receivableOpt` are complex structures containing four subfields. There is a number in each of
+these subfields that represents the end point of the range of either balance or age. Regarding the names of the
+subfields, both structures are identical. The only difference lies in the values that the balance parameters can take
+on. While receivables are valid between -9223372036854775808 and 9223372036854775807, payables only between 0 and
+9223372036854775807.   
+
+`minAgeS` is measured in seconds before the present time and sets a time constraint for the accounts we will be 
+searching over; this is the lower limit for the debt's age, or how long it has been since the last payment.
+
+`maxAgeS` is measured in seconds before the present time and sets a constraint for the accounts we will be
+searching over; this is the upper limit for the debt's age, or how long it has been since the last payment.
 
-This request will report back information about a Node's historical financial operations. This will include both
-services ordered from other Nodes and services provided for other Nodes, represented as monetary values owed and
-paid to and from this Node's wallets.
+`minBalanceGwei` is represented as an amount of gwei. Any records with balance below this value will not be returned.
+
+`maxBalanceGwei` is represented as an amount of gwei. Any records with balance above this value will not be returned.
 
 #### `financials`
 ##### Direction: Response
 ##### Correspondent: Node
 ##### Layout:
 ```
 "payload": {
-    "totalUnpaidAndPendingPayable": <integer>
-    "totalPaidPayable": <nonnegative integer>
-    "totalUnpaidReceivable": <integer>
-    "totalPaidReceivable": <nonnegative integer>
+    "statsOpt": <optional {  
+        "totalUnpaidAndPendingPayableGwei": <nonnegative integer>
+        "totalPaidPayableGwei": <nonnegative integer>
+        "totalUnpaidReceivableGwei": <integer>
+        "totalPaidReceivableGwei": <nonnegative integer>
+    }>,
+    "queryResultsOpt":<optional {
+        "payableOpt": [
+            {
+              "wallet": <string>,
+              "ageS": <integer>,
+              "balanceGwei": <integer>, 
+              "pendingPayableHashOpt": <optional string> 
+            },
+            [...]
+        ],
+        "receivableOpt": [
+            {
+              "wallet": <string>,
+              "ageS": <integer>,
+              "balanceGwei": <integer>
+            },
+            [...]
+        ]
+    }>
 }
 ```
 ##### Description:
-Contains the requested financial statistics.
+Contains the requested financial statistics or subsets (views) of the database tables and their records.
+
+`statsOpt` provides a collection of metrics on services consumed and provided. The current span of the tracked data
+is since the start of the still running Node. Later on, we'd like to change it to all-time values.  
 
-`totalUnpaidAndPendingPayable` is the number of Gwei we believe we owe to other Nodes and that those other Nodes have
-not yet received, as far as we know. This includes both bills we haven't yet paid and bills we have paid, but whose
+`totalUnpaidAndPendingPayableGwei` is the number of gwei we believe we owe to other Nodes and that those other Nodes
+have not yet received, as far as we know. This includes both bills we haven't yet paid and bills we have paid, but whose
 transactions we have not yet seen confirmed on the blockchain.
 
-`totalPaidPayable` is the number of Gwei we have successfully paid to our creditors and seen confirmed during the time
-the current instance of the Node has been running. In the future, this number may become cumulative over more time than
-just the current Node run.
+`totalPaidPayableGwei` is the number of gwei we have successfully paid to our creditors and seen confirmed.
 
-`totalUnpaidReceivable` is the number of Gwei we believe other Nodes owe to us, but have not yet been included in
+`totalUnpaidReceivableGwei` is the number of gwei we believe other Nodes owe to us, but have not yet been included in
 payments we have seen confirmed on the blockchain. This includes both payments that have never been made and also
 payments that have been made but not yet confirmed.
 
-`totalPaidReceivable` is the number of Gwei we have successfully received in confirmed payments from our debtors during
-the time the current instance of the Node has been running. In the future, this number may become cumulative over more
-time than just the current Node run.
+`totalPaidReceivableGwei` is the number of gwei we have successfully received in confirmed payments from our debtors.
+
+`queryResultsOpt` with no respect to which mode of record retrieval was requested, this is always the field that will
+hold the records found. If there are no records matching the query, the response will bring an empty array. 
+
+If the `topRecords` parameter is used, the results will be sorted in descending order by either balance or age,
+depending on the value of the orderedBy parameter. The number of results returned will be no greater than the value
+of the `topRecords` parameter.
+
+With `customQueryOpt`, the limiting age and balance ranges depend on the user's choices and constrain the subset of
+records being returned. The results are always ordered by balance in this mode, and it is the case here too, that
+an empty array is handed back if no records can be retrieved. 
+
+This query mode is just optional, and it is also a valid option to request just a single table view. Therefore, null
+should be anticipated at various places, either at the position of individual tables (`payableOpt`, `receivableOpt`)
+or in place of the whole thing (`customQueryOpt`), which implies that a command with these arguments was not used. 
+
+`payableOpt` is the part referring to payable records if any exist, null or an empty array are also possible.
+
+`wallet` is the wallet of the Node that we owe to.
+
+`ageS` is a number of seconds that elapsed since our payment to this particular Node was sent out last time, and the
+payment was later also confirmed on the blockchain.
+
+`balanceGwei` is a number of gwei we owe to this particular Node.
+
+`pendingPayableHashOpt` is present only sporadically. When it is, it denotes that we've recently sent a payment to the
+blockchain, but our confirmation detector has not yet determined that the payment has been confirmed. The value is
+either null or stores a transaction hash of the pending transaction. 
+
+`receivable` is the field devoted to receivable records if any exist.
+
+`wallet` is the wallet of the Node that owes money to us for the services we provided to this Node in the past.
+
+`age` is a number of seconds that elapsed since this particular debtor made the last payment to our account in order to 
+redeem his liabilities.
+
+`balanceGwei` is a number of gwei that this debtor owes to us.
+
 
 #### `generateWallets`
 ##### Direction: Request
 
@@ -1,6 +1,6 @@
 [package]
 name = "automap"
-version = "0.6.2"
+version = "0.7.0"
 authors = ["Dan Wiebe <[email protected]>", "MASQ"]
 license = "GPL-3.0-only"
 copyright = "Copyright (c) 2019-2021, MASQ (https://masq.ai) and/or its affiliates. All rights reserved."
 
@@ -1,6 +1,6 @@
 [package]
 name = "dns_utility"
-version = "0.6.3"
+version = "0.7.0"
 license = "GPL-3.0-only"
 authors = ["Dan Wiebe <[email protected]>", "MASQ"]
 copyright = "Copyright (c) 2019, MASQ (https://masq.ai) and/or its affiliates. All rights reserved."
 
@@ -1,6 +1,6 @@
 [package]
 name = "masq"
-version = "0.6.3"
+version = "0.7.0"
 authors = ["Dan Wiebe <[email protected]>", "MASQ"]
 license = "GPL-3.0-only"
 copyright = "Copyright (c) 2019, MASQ (https://masq.ai) and/or its affiliates. All rights reserved."
@@ -18,13 +18,18 @@ itertools = "0.8.0"
 lazy_static = "1.4.0"
 linefeed = "0.6.0"
 masq_lib = { path = "../masq_lib" }
+num = "0.4.0"
 regex = "1.5.4"
+thousands = "0.2.0"
 websocket = {version = "0.26.2", default-features = false, features = ["sync"]}
 ctrlc = "3.2.1"
 
 [target.'cfg(not(target_os = "windows"))'.dependencies]
 nix = "0.23.0"
 
+[dev-dependencies]
+atty = "0.2.14"
+
 [lib]
 name = "masq_cli_lib"
 path = "src/lib.rs"
 
@@ -52,7 +52,10 @@ impl CommandFactory for CommandFactoryReal {
                 Err(msg) => return Err(CommandSyntax(msg)),
             },
             "descriptor" => Box::new(DescriptorCommand::new()),
-            "financials" => Box::new(FinancialsCommand::new()),
+            "financials" => match FinancialsCommand::new(pieces) {
+                Ok(command) => Box::new(command),
+                Err(msg) => return Err(CommandSyntax(msg)),
+            },
             "generate-wallets" => match GenerateWalletsCommand::new(pieces) {
                 Ok(command) => Box::new(command),
                 Err(msg) => return Err(CommandSyntax(msg)),
@@ -367,6 +370,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn complains_about_financials_command_with_bad_syntax() {
+        let subject = CommandFactoryReal::new();
+
+        let result = subject
+            .make(&[
+                "financials".to_string(),
+                "--make-me-rich".to_string(),
+                "slowly".to_string(),
+            ])
+            .err()
+            .unwrap();
+
+        let msg = match result {
+            CommandSyntax(msg) => msg,
+            x => panic!("Expected syntax error, got {:?}", x),
+        };
+        assert_eq!(msg.contains("Found argument"), true, "{}", msg);
+        assert_eq!(msg.contains("--make-me-rich"), true, "{}", msg);
+        assert_eq!(
+            msg.contains("which wasn't expected, or isn't valid in this context"),
+            true,
+            "{}",
+            msg
+        );
+    }
+
     #[test]
     fn testing_command_factory_with_good_command() {
         let subject = CommandFactoryReal::new();