fix: add block reference support to view calls in NEAR client

Author: Qjawko

README.md

@@ -14,24 +14,28 @@
 
 ## What is Engine?
 
-[Aurora](https://doc.aurora.dev/getting-started/aurora-engine/) is an Ethereum Virtual Machine (EVM)
-project built on the NEAR Protocol, that provides a solution for developers to deploy their apps
-on an Ethereum-compatible, high-throughput, scalable and future-safe platform, with low transaction costs
+[Aurora](https://doc.aurora.dev/getting-started/aurora-engine/) is an Ethereum
+Virtual Machine (EVM) project built on the NEAR Protocol, that provides a
+solution for developers to deploy their apps on an Ethereum-compatible,
+high-throughput, scalable and future-safe platform, with low transaction costs
 for their users. Engine is the Aurora's implementation for it.
 
 ## What is Aurora CLI?
 
-Aurora CLI is a command line interface to bootstrap Aurora Engine with rapid speed built with rust.
+Aurora CLI is a command line interface to bootstrap Aurora Engine with rapid
+speed built with rust.
 
-Aurora CLI comes pre-configuration with opinionated, sensible defaults for standard testing environments.
-If other projects mention testing on Aurora, they are referring to the settings defined in this repo.
+Aurora CLI comes pre-configuration with opinionated, sensible defaults for
+standard testing environments. If other projects mention testing on Aurora, they
+are referring to the settings defined in this repo.
 
 **Aurora CLI has the following advantages over api:**
 
 - :pencil: **Easily modifiable EVM states through terminal**
 - :handshake: **Quick to interact for rapid iterations**
 
-See also prior version [aurora-cli](https://github.com/aurora-is-near/aurora-cli).
+See also prior version
+[aurora-cli](https://github.com/aurora-is-near/aurora-cli).
 
 ## Prerequisites
 
@@ -40,14 +44,17 @@ See also prior version [aurora-cli](https://github.com/aurora-is-near/aurora-cli
 ## Quickstart
 
 - 📦 Install `aurora-cli-rs` and start interacting with it:
-  *`cargo install --git https://github.com/aurora-is-near/aurora-cli-rs.git`*
-- 🔍 Check out what each command is for in the [Commands Reference](#commands-reference) section
-- ✋ Have questions? Ask them at the official Aurora [forum](https://forum.aurora.dev/)
+  _`cargo install --git https://github.com/aurora-is-near/aurora-cli-rs.git`_
+- 🔍 Check out what each command is for in the
+  [Commands Reference](#commands-reference) section
+- ✋ Have questions? Ask them at the official Aurora
+  [forum](https://forum.aurora.dev/)
 
 ## Usage
 
-In the following example, we will see how to deploy Aurora EVM on the `localnet`. Also, we will deploy a simple EVM
-smart contract and will be interacting with it.
+In the following example, we will see how to deploy Aurora EVM on the
+`localnet`. Also, we will deploy a simple EVM smart contract and will be
+interacting with it.
 
 ### **Requirements**
 
@@ -60,10 +67,11 @@ First what we need to do is to install `aurora-cli`:
 
 ```shell
 git clone https://github.com/aurora-engine/aurora-cli-rs
-cd aurora-cli-rs/cli && cargo install --path . 
+cd aurora-cli-rs/cli && cargo install --path .
 ```
 
-Next we need to start a NEAR node locally. We can use the NEAR utility, `nearup`.
+Next we need to start a NEAR node locally. We can use the NEAR utility,
+`nearup`.
 
 ### **Start a NEAR node locally**
 
@@ -79,16 +87,18 @@ Start NEAR node:
 nearup run localnet --home /tmp/localnet
 ```
 
-When running the `nearup run localnet` command on Apple’s M-based hardware, a local build of `neard` is required due to
-compatibility issues with the architecture.
+When running the `nearup run localnet` command on Apple’s M-based hardware, a
+local build of `neard` is required due to compatibility issues with the
+architecture.
 
 Start NEAR node (Apple's M-based hardware):
 
 ```shell
 nearup run localnet --home /tmp/localnet --binary-path /path/to/nearcore/target/release
 ```
 
-Replace `/path/to/nearcore/target/release` with the actual path to the locally built `neard` binary.
+Replace `/path/to/nearcore/target/release` with the actual path to the locally
+built `neard` binary.
 
 ### **Prepare an account and create a private key file for Aurora EVM**
 
@@ -125,8 +135,9 @@ aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/aurora_key.json i
 
 ### **Deploy the EVM smart contract**
 
-And now we can deploy the EVM smart contract. In our example, it will be a simple counter that can return its current
-value and increment and decrement its value.
+And now we can deploy the EVM smart contract. In our example, it will be a
+simple counter that can return its current value and increment and decrement its
+value.
 
 But before that we need to generate a private key for signing transactions:
 
@@ -161,13 +172,14 @@ If everything went well, the response should be like this:
 Contract has been deployed to address: 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf successfully
 ```
 
-So. Now we have deployed the smart contract at address: `0x53a9fed853e02a39bf8d298f751374de8b5a6ddf`.
+So. Now we have deployed the smart contract at address:
+`0x53a9fed853e02a39bf8d298f751374de8b5a6ddf`.
 
 ### **Interact with the smart contract**
 
 First, let's check that the current value is the same as we set in the
-initialization stage. For that, we will use the `view-call` operation, which doesn't demand a private key
-because it is a read-only operation:
+initialization stage. For that, we will use the `view-call` operation, which
+doesn't demand a private key because it is a read-only operation:
 
 ```shell
 aurora-cli --engine aurora.node0 view-call -a 0x53a9fed853e02a39bf8d298f751374de8b5a6ddf -f value \
@@ -186,8 +198,8 @@ aurora-cli --engine aurora.node0 --near-key-path /tmp/localnet/aurora_key.json s
   --aurora-secret-key 3fac6dca1c6fc056b971a4e9090afbbfbdf3bc443e9cda595facb653cb1c01e1
 ```
 
-In the response, we can see if the transaction was successful and the amount of gas used for the execution of this
-transaction.
+In the response, we can see if the transaction was successful and the amount of
+gas used for the execution of this transaction.
 
 Let's make sure that our value was incremented:
 
@@ -200,13 +212,15 @@ So, if we can see `6` in the output then the demo was successful. That's it!
 
 ### **Build aurora-cli with the advanced command line interface (Advanced CLI)**
 
-Advanced CLI provides more options andadvanced features. You can try it by building with the following command:
+Advanced CLI provides more options andadvanced features. You can try it by
+building with the following command:
 
 ```shell
 cargo install --path . --no-default-features -F advanced
 ```
 
-Documentation on how to work with the advanced version of `aurora-cli` can be found [here](docs/localnet.md).
+Documentation on how to work with the advanced version of `aurora-cli` can be
+found [here](docs/localnet.md).
 
 ### **Browse Deployed EVM Metadata**
 
@@ -269,17 +283,19 @@ Disable whitelist status
 aurora-cli --engine aurora.node0 set-whitelist-status --kind <whitelist-kind> --status 0
 ```
 
-Replace `<whitelist-kind>` with the desired whitelist type (admin, evm-admin, account, or address), and `<entry-value>`
-with the address or account to be whitelisted or removed.
+Replace `<whitelist-kind>` with the desired whitelist type (admin, evm-admin,
+account, or address), and `<entry-value>` with the address or account to be
+whitelisted or removed.
 
 Add whitelist batch
 
 ```shell
 aurora-cli --engine aurora.node0 add-entry-to-whitelist-batch path/to/batch_list.json
 ```
 
-The batch should be provided in a JSON format. Each entry in the JSON array should have two properties: `kind` and
-either `account_id` or `address`, depending on the type of whitelist being updated.
+The batch should be provided in a JSON format. Each entry in the JSON array
+should have two properties: `kind` and either `account_id` or `address`,
+depending on the type of whitelist being updated.
 
 Example JSON batch file (`batch_list.json`):
 
@@ -439,6 +455,7 @@ Options:
       --network <NETWORK>              NEAR network ID [default: localnet]
       --engine <ACCOUNT_ID>            Aurora EVM account [default: aurora]
       --near-key-path <NEAR_KEY_PATH>  Path to file with NEAR account id and secret key in JSON format
+      --block-number                   Block number to get data from
   -h, --help                           Print help
   -V, --version                        Print version
 ```
@@ -537,7 +554,6 @@ Arguments:
 
 Options:
   -h, --help  Print help
-
 ```
 
 ### `aurora-cli get-block-hash`
@@ -568,7 +584,6 @@ Arguments:
 
 Options:
   -h, --help  Print help
-
 ```
 
 ### `aurora-cli get-balance`
@@ -867,7 +882,7 @@ Options:
       --value <VALUE>      Attached value in EVM transaction
       --from <FROM>        From account_id
   -h, --help               Print help
- ```
+```
 
 ### `aurora-cli submit`
 
@@ -1202,7 +1217,7 @@ Usage: aurora-cli set-eth-connector-contract-account [OPTIONS] --account-id <ACC
 Options:
       --account-id <ACCOUNT_ID>      Account id of eth connector
       --withdraw-ser <WITHDRAW_SER>  Serialization type in withdraw method
-  -h, --help           
+  -h, --help
 ```
 
 ### `aurora-cli get-eth-connector-contract-account`
@@ -1290,4 +1305,4 @@ Options:
       --full-access-pub-key <FULL_ACCESS_PUB_KEY>      
       --function-call-pub-key <FUNCTION_CALL_PUB_KEY>  
   -h, --help                                           Print help
-```
+```

cli/src/cli/simple/command/mod.rs

@@ -763,7 +763,7 @@ pub async fn get_erc20_metadata(context: Context, identifier: String) -> anyhow:
     let result = context
         .client
         .near()
-        .view_call("get_erc20_metadata", args)
+        .view_call("get_erc20_metadata", args, context.block_ref)
         .await?;
     let output = serde_json::from_slice::<Erc20Metadata>(&result.result)
         .and_then(|metadata| serde_json::to_string_pretty(&metadata))?;
@@ -891,7 +891,7 @@ async fn get_value<T: FromCallResult + Display>(
     let result = context
         .client
         .near()
-        .view_call(method_name, args.unwrap_or_default())
+        .view_call(method_name, args.unwrap_or_default(), context.block_ref)
         .await?;
     let output = T::from_result(result)?;
     println!("{output}");

cli/src/cli/simple/mod.rs

@@ -2,6 +2,7 @@ use aurora_engine_types::account_id::AccountId;
 use aurora_engine_types::public_key::{KeyType, PublicKey};
 use clap::{Parser, Subcommand, ValueEnum};
 use near_primitives::hash::CryptoHash;
+use near_primitives::types::{BlockId, BlockReference};
 use shadow_rs::shadow;
 use std::str::FromStr;
 use std::sync::LazyLock;
@@ -36,6 +37,9 @@ pub struct Cli {
     /// Path to file with NEAR account id and secret key in JSON format
     #[arg(long)]
     pub near_key_path: Option<String>,
+    /// Block number to get data from
+    #[arg(long)]
+    pub block_number: Option<u64>,
     #[clap(subcommand)]
     pub command: Command,
 }
@@ -465,7 +469,12 @@ pub async fn run(args: Cli) -> anyhow::Result<()> {
         Network::Localnet => super::NEAR_LOCAL_ENDPOINT,
     };
     let client = crate::client::Client::new(near_rpc, &args.engine, args.near_key_path);
-    let context = crate::client::Context::new(client, args.output_format);
+    let context = crate::client::Context::new(
+        client,
+        args.output_format,
+        args.block_number
+            .map(|n| BlockReference::BlockId(BlockId::Height(n))),
+    );
 
     match args.command {
         Command::GetChainId => command::get_chain_id(context).await?,

cli/src/client/mod.rs

@@ -4,6 +4,8 @@ use aurora_engine_types::H256;
 use aurora_engine_types::account_id::AccountId;
 #[cfg(feature = "advanced")]
 use aurora_engine_types::parameters::engine::SubmitResult;
+#[cfg(feature = "simple")]
+use near_primitives::types::BlockReference;
 #[cfg(feature = "advanced")]
 use thiserror::Error;
 
@@ -30,14 +32,20 @@ type NearCallError = near_jsonrpc_client::errors::JsonRpcError<
 pub struct Context {
     pub client: Client,
     pub output_format: OutputFormat,
+    pub block_ref: Option<BlockReference>,
 }
 
 #[cfg(feature = "simple")]
 impl Context {
-    pub const fn new(client: Client, output_format: OutputFormat) -> Self {
+    pub const fn new(
+        client: Client,
+        output_format: OutputFormat,
+        block_ref: Option<BlockReference>,
+    ) -> Self {
         Self {
             client,
             output_format,
+            block_ref,
         }
     }
 }

cli/src/client/near.rs

@@ -160,7 +160,7 @@ impl NearClient {
             amount: amount.to_bytes(),
             input,
         };
-        let result = self.view_call("view", borsh::to_vec(&args)?).await?;
+        let result = self.view_call("view", borsh::to_vec(&args)?, None).await?;
         let status = TransactionStatus::try_from_slice(&result.result)?;
         Ok(status)
     }
@@ -169,9 +169,10 @@ impl NearClient {
         &self,
         method_name: &str,
         args: Vec<u8>,
+        block_ref: Option<BlockReference>,
     ) -> anyhow::Result<views::CallResult> {
         let request = methods::query::RpcQueryRequest {
-            block_reference: Finality::Final.into(),
+            block_reference: block_ref.unwrap_or_else(|| Finality::Final.into()),
             request: views::QueryRequest::CallFunction {
                 account_id: self.engine_account_id.clone(),
                 method_name: method_name.to_string(),
@@ -450,7 +451,7 @@ impl NearClient {
         let sender_address = utils::address_from_secret_key(sk)?;
         let nonce = {
             let result = self
-                .view_call("get_nonce", sender_address.as_bytes().to_vec())
+                .view_call("get_nonce", sender_address.as_bytes().to_vec(), None)
                 .await?;
             U256::from_big_endian(&result.result)
         };
@@ -464,7 +465,7 @@ impl NearClient {
         };
         let chain_id = {
             let result = self
-                .view_call("get_chain_id", sender_address.as_bytes().to_vec())
+                .view_call("get_chain_id", sender_address.as_bytes().to_vec(), None)
                 .await?;
             U256::from_big_endian(&result.result).low_u64()
         };