[feature] Allow balance querying at specified block height

.changelog/unreleased/improvements/3530-balance-query-at-height.md

@@ -0,0 +1,2 @@
+- Add optional height parameter to get_token_balance
+  ([\#3530](https://github.com/anoma/namada/pull/3530))

crates/apps_lib/src/cli.rs

@@ -6208,6 +6208,7 @@ pub mod args {
                 owner: chain_ctx.get_cached(&self.owner),
                 token: chain_ctx.get(&self.token),
                 no_conversions: self.no_conversions,
+                height: self.height,
             })
         }
     }
@@ -6218,11 +6219,13 @@ pub mod args {
             let owner = BALANCE_OWNER.parse(matches);
             let token = TOKEN.parse(matches);
             let no_conversions = NO_CONVERSIONS.parse(matches);
+            let height = BLOCK_HEIGHT_OPT.parse(matches);
             Self {
                 query,
                 owner,
                 token,
                 no_conversions,
+                height,
             }
         }
 
@@ -6241,6 +6244,10 @@ pub mod args {
                 .arg(NO_CONVERSIONS.def().help(wrap!(
                     "Whether not to automatically perform conversions."
                 )))
+                .arg(BLOCK_HEIGHT_OPT.def().help(wrap!(
+                    "The block height at which to query the balance. \
+                     (Optional)"
+                )))
         }
     }
 
@@ -7218,6 +7225,7 @@ pub mod args {
         type AddrOrNativeToken = WalletAddrOrNativeToken;
         type Address = WalletAddress;
         type BalanceOwner = WalletBalanceOwner;
+        type BlockHeight = BlockHeight;
         type BpConversionTable = PathBuf;
         type ConfigRpcTendermintAddress = ConfigRpcAddress;
         type Data = PathBuf;

crates/apps_lib/src/client/rpc.rs

@@ -206,6 +206,8 @@ async fn query_transparent_balance(
         owner,
         // The token to query
         token,
+        // Optional block height
+        height,
         ..
     } = args;
 
@@ -214,9 +216,13 @@ async fn query_transparent_balance(
         .expect("Balance owner should have been a transparent address");
 
     let token_alias = lookup_token_alias(context, &token, &owner).await;
-    let token_balance_result =
-        namada_sdk::rpc::get_token_balance(context.client(), &token, &owner)
-            .await;
+    let token_balance_result = namada_sdk::rpc::get_token_balance(
+        context.client(),
+        &token,
+        &owner,
+        height,
+    )
+    .await;
 
     match token_balance_result {
         Ok(balance) => {

crates/apps_lib/src/client/tx.rs

@@ -969,6 +969,7 @@ where
             namada.client(),
             &namada.native_token(),
             &proposal.proposal.author,
+            None,
         )
         .await
         .unwrap();
@@ -999,6 +1000,7 @@ where
             namada.client(),
             &namada.native_token(),
             &proposal.proposal.author,
+            None,
         )
         .await
         .unwrap();

crates/light_sdk/src/reading/asynchronous/account.rs

@@ -1,5 +1,6 @@
 use namada_sdk::account::Account;
 use namada_sdk::key::common;
+use namada_sdk::storage::BlockHeight;
 
 use super::*;
 
@@ -8,13 +9,14 @@ pub async fn get_token_balance(
     tendermint_addr: &str,
     token: &Address,
     owner: &Address,
+    height: Option<BlockHeight>, // Specify block height or None for latest
 ) -> Result<token::Amount, Error> {
     let client = HttpClient::new(
         TendermintAddress::from_str(tendermint_addr)
             .map_err(|e| Error::Other(e.to_string()))?,
     )
     .map_err(|e| Error::Other(e.to_string()))?;
-    rpc::get_token_balance(&client, token, owner).await
+    rpc::get_token_balance(&client, token, owner, height).await
 }
 
 /// Check if the address exists on chain. Established address exists if it

crates/sdk/src/args.rs

@@ -87,6 +87,8 @@ pub trait NamadaTypes: Clone + std::fmt::Debug {
     type BpConversionTable: Clone + std::fmt::Debug;
     /// Address of a `namada-masp-indexer` live instance
     type MaspIndexerAddress: Clone + std::fmt::Debug;
+    /// Represents a block height
+    type BlockHeight: Clone + std::fmt::Debug;
 }
 
 /// The concrete types being used in Namada SDK
@@ -108,6 +110,7 @@ impl NamadaTypes for SdkTypes {
     type AddrOrNativeToken = Address;
     type Address = Address;
     type BalanceOwner = namada_core::masp::BalanceOwner;
+    type BlockHeight = namada_core::chain::BlockHeight;
     type BpConversionTable = HashMap<Address, BpConversionTableEntry>;
     type ConfigRpcTendermintAddress = tendermint_rpc::Url;
     type Data = Vec<u8>;
@@ -718,6 +721,7 @@ impl InitProposal {
                 context.client(),
                 &nam_address,
                 &proposal.proposal.author,
+                None,
             )
             .await?;
             let proposal = proposal
@@ -746,6 +750,7 @@ impl InitProposal {
                 context.client(),
                 &nam_address,
                 &proposal.proposal.author,
+                None,
             )
             .await?;
             let proposal = proposal
@@ -1604,6 +1609,8 @@ pub struct QueryBalance<C: NamadaTypes = SdkTypes> {
     pub token: C::Address,
     /// Whether not to convert balances
     pub no_conversions: bool,
+    /// Optional height to query balances at
+    pub height: Option<C::BlockHeight>,
 }
 
 /// Query historical transfer(s)

crates/sdk/src/queries/vp/token.rs

@@ -54,6 +54,7 @@ where
 pub mod client_only_methods {
     use borsh::BorshDeserialize;
     use namada_core::address::Address;
+    use namada_core::chain::BlockHeight;
     use namada_core::token;
     use namada_io::Client;
     use namada_token::storage_key::{balance_key, masp_total_rewards};
@@ -62,20 +63,22 @@ pub mod client_only_methods {
     use crate::queries::RPC;
 
     impl Token {
-        /// Get the balance of the given `token` belonging to the given `owner`.
+        /// Get the balance of the given `token` belonging to the given `owner`,
+        /// optionally at the given `height`.
         pub async fn balance<CLIENT>(
             &self,
             client: &CLIENT,
             token: &Address,
             owner: &Address,
+            height: Option<BlockHeight>,
         ) -> Result<token::Amount, <CLIENT as Client>::Error>
         where
             CLIENT: Client + Sync,
         {
             let balance_key = balance_key(token, owner);
             let response = RPC
                 .shell()
-                .storage_value(client, None, None, false, &balance_key)
+                .storage_value(client, None, height, false, &balance_key)
                 .await?;
 
             let balance = if response.data.is_empty() {

crates/sdk/src/rpc.rs

@@ -211,9 +211,10 @@ pub async fn get_token_balance<C: namada_io::Client + Sync>(
     client: &C,
     token: &Address,
     owner: &Address,
+    height: Option<namada_storage::BlockHeight>,
 ) -> Result<token::Amount, error::Error> {
     convert_response::<C, _>(
-        RPC.vp().token().balance(client, token, owner).await,
+        RPC.vp().token().balance(client, token, owner, height).await,
     )
 }