chore: update client guide. tests, migrations, log

docs/client_guide.md

@@ -30,9 +30,10 @@ $ file-exchange downloader \
    --indexer-endpoints http://localhost:5678,http://localhost:5677 \
    --free-query-auth-token 'Bearer auth_token' \
    --mnemonic "seed phrase" \
-   --chain-id 421614 \
    --verifier 0xfC24cE7a4428A6B89B52645243662A02BA734ECF \
-   --provider "arbitrum-sepolia-rpc-endpoint"
+   --provider "arbitrum-sepolia-rpc-endpoint" \
+   --network-subgraph https://api.thegraph.com/subgraphs/name/graphprotocol/graph-network-arbitrum-sepolia \
+   --escrow-subgraph https://api.thegraph.com/subgraphs/name/graphprotocol/scalar-tap-arbitrum-sepolia
 ```
 
 ### Requirements
@@ -43,13 +44,14 @@ To use the client effectively, you will need:
 - Local Path: A directory where the downloaded file will be stored. (Later will be a generic storage path, enabling cloud storage access)
 - Wallet: A blockchain wallet containing tokens for escrow payments.
 - Indexer Endpoints: A list of available server addresses.
-- Free Query Auth Token (Optional): For limited access to small files.
+- (Optional) Free Query Auth Token: For limited access to small files.
 
 ### Getting Started
 
 1. Download and install the source code.
-2. Gather configurations: Identify the CID of the desired Bundle, registered indexer endpoints, a local path for storing the downloaded files, private key (or mnemonics) of a wallet valid for Escrow payments, (optional) Obtain a free query auth token for limited access.
+2. Gather configurations: Identify the CID of the desired Bundle, registered indexer endpoints, a local path for storing the downloaded files, private key (or mnemonics) of a wallet valid for Escrow payments, (optional) Obtain a free query auth token for limited access, the preference to concurrent providers for downloading.
 3. Use the CLI commands to download files.
+4. Before downloading, the client will check the status and price of the providers. If the download can be achived by availablility and price at the time of initiation, then download will proceed. If there is no availability, the client will suggest alternative bundles that overlaps with the target bundle and the corresponding providers. If there is not enough balance, the client will suggest Escrow top-up amounts for the Escrow accounts.  
 
 Enjoy seamless access to a vast world of data!
 

file-exchange/src/download_client/mod.rs

@@ -427,13 +427,15 @@ impl Downloader {
         Ok(())
     }
 
+    /// Check escrow balances with cheapest N providers (N is the downloader client configured provider concurrency)
+    /// Make suggestion to individual escrow accounts if balance is low
+    /// Error out if gross buying power is insufficient, otherwise proceed with downloading
     async fn escrow_check(&self) -> Result<(), Error> {
         // check balance availability if payment is enabled
-        tracing::debug!("Escrow account checks");
+        tracing::trace!("Escrow account checks");
         if let PaymentMethod::PaidQuery(on_chain) = &self.payment {
             let mut estimated_buying_power_in_bytes: f64 = 0.0;
             // estimate the cost to download the bundle from each provider
-            let _num_files = self.bundle.file_manifests.len();
             let total_bytes = self
                 .bundle
                 .file_manifests
@@ -443,11 +445,11 @@ impl Downloader {
 
             let endpoints = self.indexer_urls.lock().unwrap().clone();
             for endpoint in endpoints {
-                tracing::debug!(
+                tracing::trace!(
                     endpoint = tracing::field::debug(&endpoint),
                     "Check escrow account for indexer"
                 );
-                let fail_tolerance = 1.5_f64;
+                let fail_tolerance = 1.2_f64;
                 let escrow_requirement = endpoint.price_per_byte * (total_bytes as f64)
                     / (self.provider_concurrency as f64)
                     * fail_tolerance;
@@ -457,16 +459,14 @@ impl Downloader {
                 let account = escrow_balance(&self.http_client, escrow, &sender, &receiver).await?;
 
                 // check for escrow balance
-                // let balance: Option<f32> = account.clone().map(|a| a.balance.parse().unwrap());
                 let _ = match account {
                     None => {
-                        tracing::warn!("Account doesnt exist");
+                        tracing::warn!("Escrow account doesn't exist, make deposits");
                         Err(Error::DataUnavailable(
                             "Escrow account doesn't exist".to_string(),
                         ))
                     }
                     Some(a) if a.lt(&escrow_requirement) => {
-                        // Some(a) if balance.unwrap().lt(&escrow_requirement) => {
                         let msg = format!(
                             "Top-up required to make averaged concurrent requests: {} availble, recommend topping up to {}",
                             a, escrow_requirement
@@ -478,7 +478,7 @@ impl Downloader {
                     }
                     Some(a) => {
                         estimated_buying_power_in_bytes += a / endpoint.price_per_byte;
-                        tracing::debug!("Balance is enough for this account");
+                        tracing::trace!("Balance is enough for this account");
                         Ok(())
                     }
                 };