Transaction pagination + full query arguments

Addition of new structs in libwallet internal types, RetrieveTxQueryArgs, RetrieveTxQuerySortOrder, RetrieveTxQuerySortField
Update internal retrieve_txs API function to optionally accept a RetrieveTxQueryArgs struct
Implementation of filtering via apply_advanced_tx_list_filtering fn
Modify retrieve_tx implementation to use advanced filfering function if optional query args are supplied
Addition of unit tests to exercise all new query functionality and sorting
Add new JSON API Function query_txs, (note it was necessary to provide a separate function to avoid breaking existing json calls to retrieve_txs
Documentation and Doctesting additions for JSON API
Note that advanced query functionality is API only and not accessible from the command-line

While creating https://github.com/mimblewimble/grin-gui, it's become apparent that we need to implement much more granular transaction querying to better support pagination, sorting, etc. Instead of just implementing basic pagination, I'm taking the opportunity to add a reasonable number of advanced query options via a new query structure.

Details posted here for review and comment, I think this should cover most needs but happy to hear from anyone with suggestions or anything else that should be included in the query arguments:

pub struct RetrieveTxQueryArgs {
    /// Retrieve transactions with an id higher than or equal to the given
    /// If None, consider items from the first transaction and later
    pub min_id: Option<u32>,
    /// Retrieve tranactions with an id less than or equal to the given
    /// If None, consider items from the last transaction and earlier
    pub max_id: Option<u32>,
    /// The maximum number of transactions to return
    /// if both `before_id` and `after_id` are supplied, this will apply
    /// to the before and earlier set
    pub limit: Option<u32>,
    /// whether to exclude cancelled transactions in the returned set
    pub exclude_cancelled: Option<bool>,
    /// whether to only consider outstanding transactions
    pub include_outstanding_only: Option<bool>,
    /// whether to only consider confirmed-only transactions
    pub include_confirmed_only: Option<bool>,
    /// whether to only consider sent transactions
    pub include_sent_only: Option<bool>,
    /// whether to only consider received transactions
    pub include_received_only: Option<bool>,
    /// whether to only consider coinbase transactions
    pub include_coinbase_only: Option<bool>,
    /// whether to only consider reverted transactions
    pub include_reverted_only: Option<bool>,
    /// lower bound on the total amount (amount_credited - amount_debited), inclusive
    #[serde(with = "secp_ser::opt_string_or_u64")]
    #[serde(default)]
    pub min_amount: Option<u64>,
    /// higher bound on the total amount (amount_credited - amount_debited), inclusive
    #[serde(with = "secp_ser::opt_string_or_u64")]
    #[serde(default)]
    pub max_amount: Option<u64>,
    /// lower bound on the creation timestamp, inclusive
    pub min_creation_timestamp: Option<DateTime<Utc>>,
    /// higher bound on on the creation timestamp, inclusive
    pub max_creation_timestamp: Option<DateTime<Utc>>,
    /// lower bound on the confirmation timestamp, inclusive
    pub min_confirmed_timestamp: Option<DateTime<Utc>>,
    /// higher bound on the confirmation timestamp, inclusive
    pub max_confirmed_timestamp: Option<DateTime<Utc>>,
    /// Field within the tranasction list on which to sort
    /// defaults to ID if not present
    pub sort_field: Option<RetrieveTxQuerySortField>,
    /// Sort order, defaults to ASC if not present (earliest is first)
    pub sort_order: Option<RetrieveTxQuerySortOrder>,
}

Sort fields (and sort order) are:

/// Sort tx retrieval order
#[derive(Clone, Serialize, Deserialize)]
pub enum RetrieveTxQuerySortOrder {
    /// Ascending
    Asc,
    /// Descending
    Desc,
}

/// Valid sort fields for a transaction list retrieval query
#[derive(Clone, Serialize, Deserialize)]
pub enum RetrieveTxQuerySortField {
    /// Transaction Id
    Id,
    /// Creation Timestamp
    CreationTimestamp,
    /// Confirmation Timestamp
    ConfirmationTimestamp,
    /// TotalAmount (AmountCredited-AmountDebited)
    TotalAmount,
    /// Amount Credited
    AmountCredited,
    /// Amount Debited
    AmountDebited,
}

mimblewimble / grin-wallet

Transaction pagination + full query arguments #666