feat(json_rpc): improve queryStakes optional params: distinct, limit, offset, since, order

Author: guidiaz

node/src/actors/chain_manager/handlers.rs

@@ -46,7 +46,7 @@ use crate::{
             GetMemoryTransaction, GetMempool, GetMempoolResult, GetNodeStats, GetProtocolInfo,
             GetReputation, GetReputationResult, GetSignalingInfo, GetState, GetSuperBlockVotes,
             GetSupplyInfo, GetSupplyInfo2, GetUtxoInfo, IsConfirmedBlock, PeersBeacons,
-            QueryStakePowers, QueryStakes, QueryStakesFilter, ReputationStats, Rewind,
+            QueryStakePowers, QueryStakes, QueryStakesOrderByOptions, ReputationStats, Rewind,
             SendLastBeacon, SessionUnitResult, SetLastBeacon, SetPeersLimits, SignalingInfo,
             SnapshotExport, SnapshotImport, TryMineBlock,
         },
@@ -1543,39 +1543,112 @@ impl Handler<QueryStakes> for ChainManager {
     type Result = <QueryStakes as Message>::Result;
 
     fn handle(&mut self, msg: QueryStakes, _ctx: &mut Self::Context) -> Self::Result {
-        // query stakes from current chain state
+        let filter = msg.filter.unwrap_or_default();
+        let params = msg.params.unwrap_or_default();
+        let since = params.since.unwrap_or_default();
+        let order = params.order.unwrap_or_default();
+        let order_desc = order.reverse.unwrap_or_default();
+        let distinct = params.distinct.unwrap_or_default();
+        let offset = params.offset.unwrap_or_default();
+        let limit = params.limit.unwrap_or(u16::MAX) as usize;
+
+        // fetch filtered stake entries from current chain state:
         let mut stakes = self
             .chain_state
             .stakes
-            .query_stakes(msg.filter)
+            .query_stakes(filter.clone())
             .map_err(StakesError::from)?;
-        // filter out stake entries whose last mining and witnessing epochs are previous to `epoch`
-        let epoch: u32 = if msg.limits.since >= 0 {
-            msg.limits.since.try_into().inspect_err(|&e| {
+
+        // filter out stake entries having a nonce, last mining or witnessing epochs (depending
+        // on actual ordering field) older than calculated `since_epoch`:
+        let since_epoch: u64 = if since >= 0 {
+            since.try_into().inspect_err(|&e| {
                 log::warn!("Invalid 'since' limit on QueryStakes: {}", e);
             })?
         } else {
-            (self.current_epoch.unwrap() as i64 + msg.limits.since)
+            (self.current_epoch.unwrap() as i64 + since)
                 .try_into()
                 .unwrap_or_default()
         };
-        stakes.retain(|stake| {
-            let nonce: u32 = stake.value.nonce.try_into().unwrap_or_default();
-            stake.value.epochs.mining >= epoch && stake.value.epochs.mining != nonce
-                || (stake.value.epochs.witnessing >= epoch
-                    && stake.value.epochs.witnessing != nonce)
-        });
-        if msg.limits.distinct {
-            // if only distinct validators are required, retain only first appearence in the stakes array:
-            let stakes = stakes
+        if since_epoch > 0 {
+            match order.by {
+                QueryStakesOrderByOptions::Coins | QueryStakesOrderByOptions::Nonce => {
+                    stakes.retain(|stake| stake.value.nonce >= since_epoch);
+                }
+                QueryStakesOrderByOptions::Mining => {
+                    stakes.retain(|stake| {
+                        stake.value.epochs.mining as u64 >= since_epoch
+                            && stake.value.epochs.mining as u64 >= stake.value.nonce
+                    });
+                }
+                QueryStakesOrderByOptions::Witnessing => {
+                    stakes.retain(|stake| {
+                        stake.value.epochs.witnessing as u64 >= since_epoch
+                            && stake.value.epochs.witnessing as u64 >= stake.value.nonce
+                    });
+                }
+            }
+        }
+
+        // sort stake entries by specified field, worst case costing n * log (n) ...
+        match order.by {
+            QueryStakesOrderByOptions::Coins => {
+                stakes.sort_by(|a, b| {
+                    if order_desc {
+                        b.value.coins.cmp(&a.value.coins)
+                    } else {
+                        a.value.coins.cmp(&b.value.coins)
+                    }
+                });
+            }
+            QueryStakesOrderByOptions::Nonce => {
+                stakes.sort_by(|a, b| {
+                    if order_desc {
+                        b.value.nonce.cmp(&a.value.nonce)
+                    } else {
+                        a.value.nonce.cmp(&b.value.nonce)
+                    }
+                });
+            }
+            QueryStakesOrderByOptions::Mining => {
+                stakes.sort_by(|a, b| {
+                    if order_desc {
+                        b.value.epochs.mining.cmp(&a.value.epochs.mining)
+                    } else {
+                        a.value.epochs.mining.cmp(&b.value.epochs.mining)
+                    }
+                });
+            }
+            QueryStakesOrderByOptions::Witnessing => {
+                stakes.sort_by(|a, b| {
+                    if order_desc {
+                        b.value.epochs.witnessing.cmp(&a.value.epochs.witnessing)
+                    } else {
+                        a.value.epochs.witnessing.cmp(&b.value.epochs.witnessing)
+                    }
+                });
+            }
+        }
+
+        // if `distinct` is required, retain first appearence per validator:
+        let stakes = if distinct {
+            stakes
                 .into_iter()
                 .unique_by(|stake| stake.key.validator)
-                .collect();
-
-            Ok(stakes)
+                .collect()
         } else {
-            Ok(stakes)
-        }
+            stakes
+        };
+
+        log::info!(
+            "queryStakes => found {} entries after filter {:?} w/ params {:?}",
+            stakes.len(),
+            filter,
+            params,
+        );
+
+        // applies `offset`, if any, and limits number of returned records to `limit``
+        Ok(stakes.into_iter().skip(offset).take(limit).collect())
     }
 }
 

node/src/actors/json_rpc/api.rs

@@ -1471,7 +1471,9 @@ pub async fn get_balance(params: Params) -> JsonRpcResult {
     };
 
     if target == GetBalanceTarget::Own {
-        return Err(Error::invalid_params("Providing server's balance is not allowed"));
+        return Err(Error::invalid_params(
+            "Providing server's balance is not allowed",
+        ));
     };
 
     let chain_manager_addr = ChainManager::from_registry();

node/src/actors/messages.rs

@@ -357,35 +357,83 @@ impl Message for QueryStakePowers {
 }
 
 /// Stake key for quering stakes
-#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
-#[derive(Default)]
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize, Default)]
 pub struct QueryStakesFilter {
     /// To search by the validator public key hash
     pub validator: Option<MagicEither<String, PublicKeyHash>>,
     /// To search by the withdrawer public key hash
     pub withdrawer: Option<MagicEither<String, PublicKeyHash>>,
 }
 
-
 /// Limits when querying stake entries
-#[derive(Clone, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
-#[derive(Default)]
-pub struct QueryStakesLimits {
-    /// Retrieve only first appearence for every distinct validator
-    pub distinct: bool,
-    /// Either absolute or relative epoch (negative values) when stake entries were last modified
-    pub since: i64,
+pub struct QueryStakesParams {
+    /// Retrieve only first appearence for every distinct validator (default: false)
+    pub distinct: Option<bool>,
+    /// Limits max number of entries to return (default: 0 == u16::MAX)
+    pub limit: Option<u16>,
+    /// Skips first found entries (default: 0)
+    pub offset: Option<usize>,
+    /// Order by specified stake entry field (default: reverse order by coins)
+    pub order: Option<QueryStakesOrderBy>,
+    /// Select entries having either the nonce, last mining or last witnessing epoch,
+    /// greater than specified absolute epoch, or relative epoch if negative (default: 0)
+    pub since: Option<i64>,
+}
+
+impl Default for QueryStakesParams {
+    fn default() -> Self {
+        QueryStakesParams {
+            distinct: Some(false),
+            limit: Some(u16::MAX),
+            offset: Some(0),
+            order: Some(QueryStakesOrderBy::default()),
+            since: Some(0),
+        }
+    }
+}
+
+/// Order by parameter for QueryStakes
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub struct QueryStakesOrderBy {
+    /// Data field to order by
+    pub by: QueryStakesOrderByOptions,
+    /// Reverse order (default: false)
+    pub reverse: Option<bool>,
+}
+
+impl Default for QueryStakesOrderBy {
+    fn default() -> Self {
+        QueryStakesOrderBy {
+            by: QueryStakesOrderByOptions::Coins,
+            reverse: Some(true),
+        }
+    }
 }
 
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+/// Ordering options for QueryStakes
+pub enum QueryStakesOrderByOptions {
+    /// Order by stake entry coins
+    Coins = 0,
+    /// Order by stake entry nonce
+    Nonce = 1,
+    /// Order by last validation epoch
+    Mining = 2,
+    /// Order by last witnessing epoch
+    Witnessing = 3,
+}
 
 /// Message for querying stakes
 #[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
 pub struct QueryStakes {
     /// query's where clause
-    pub filter: QueryStakesFilter,
+    pub filter: Option<QueryStakesFilter>,
     /// query's limit params
-    pub limits: QueryStakesLimits,
+    pub params: Option<QueryStakesParams>,
 }
 
 impl Message for QueryStakes {
@@ -403,21 +451,17 @@ where
 
     fn try_from(filter: QueryStakesFilter) -> Result<Self, Self::Error> {
         Ok(match (filter.validator, filter.withdrawer) {
-            (Some(validator), Some(withdrawer)) => {
-                QueryStakesKey::Key(StakeKey {
-                    validator: try_do_magic_into_pkh(validator)?.into(),
-                    withdrawer: try_do_magic_into_pkh(withdrawer)?.into(),
-                })
-            }, 
+            (Some(validator), Some(withdrawer)) => QueryStakesKey::Key(StakeKey {
+                validator: try_do_magic_into_pkh(validator)?.into(),
+                withdrawer: try_do_magic_into_pkh(withdrawer)?.into(),
+            }),
             (Some(validator), None) => {
                 QueryStakesKey::Validator(try_do_magic_into_pkh(validator)?.into())
-            },
+            }
             (None, Some(withdrawer)) => {
                 QueryStakesKey::Withdrawer(try_do_magic_into_pkh(withdrawer)?.into())
-            },
-            (None, None) => {
-                QueryStakesKey::All
-            },
+            }
+            (None, None) => QueryStakesKey::All,
         })
     }
 }

src/cli/node/json_rpc_client.rs

@@ -56,7 +56,7 @@ use witnet_node::actors::{
     messages::{
         AuthorizeStake, BuildDrt, BuildStakeParams, BuildStakeResponse, BuildUnstakeParams,
         BuildVtt, GetBalanceTarget, GetReputationResult, MagicEither, QueryStakes,
-        QueryStakesFilter, QueryStakesLimits, SignalingInfo, StakeAuthorization,
+        QueryStakesFilter, SignalingInfo, StakeAuthorization,
     },
 };
 use witnet_rad::types::RadonTypes;
@@ -1957,26 +1957,23 @@ pub fn query_stakes(
     let mut stream = start_client(addr)?;
     let params = QueryStakes {
         filter: match (validator, withdrawer) {
-            (Some(validator), Some(withdrawer)) => QueryStakesFilter {
+            (Some(validator), Some(withdrawer)) => Some(QueryStakesFilter {
                 validator: Some(MagicEither::Left(validator)),
                 withdrawer: Some(MagicEither::Left(withdrawer)),
-            },
-            (Some(validator), None) => QueryStakesFilter {
+            }),
+            (Some(validator), None) => Some(QueryStakesFilter {
                 validator: Some(MagicEither::Left(validator)),
                 withdrawer: None,
-            },
-            (None, Some(withdrawer)) => QueryStakesFilter {
+            }),
+            (None, Some(withdrawer)) => Some(QueryStakesFilter {
                 validator: None,
                 withdrawer: Some(MagicEither::Left(withdrawer)),
-            },
-            (None, None) => QueryStakesFilter {
-                validator: None,
-                withdrawer: None,
-            },
+            }),
+            (None, None) => None,
         },
-        limits: QueryStakesLimits::default(),
+        params: None,
     };
-    
+
     let response = send_request(
         &mut stream,
         &format!(