feat: Add async builders for view_* functions

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+### Added
+
+- [`view_*` asynchronous builders have been added which provides being able to query from a specific block hash or block height](https://github.com/near/workspaces-rs/pull/218)
+
+### Changed
+
+- [Apart of the changes from adding `view_*` async builders, we can have a couple breaking changes to the `view_*` functions](https://github.com/near/workspaces-rs/pull/218):
+  - `{Account, Contract, Worker}::view_state` moved `prefix` parameter into builder. i.e.
+    ```
+    worker.view_state("account_id", Some(prefix)).await?;
+    // is now
+    worker.view_state("account_id")
+        .prefix(prefix)
+        .await?;
+    // if prefix was `None`, then simply delete the None argument.
+    ```
+  - `view` function changed to be a builder, and no longer take in `args` as a parameter. It instead has been moved to the builder side.
+  - Changed `Worker::view_latest_block` to `Worker::view_block` as the default behavior is equivalent.
+
 ## [0.6.0]
 
 ### Added

examples/src/fast_forward.rs

@@ -18,7 +18,7 @@ async fn main() -> anyhow::Result<()> {
         contract.call("current_env_data").view().await?.json()?;
     println!("timestamp = {}, epoch_height = {}", timestamp, epoch_height);
 
-    let block_info = worker.view_latest_block().await?;
+    let block_info = worker.view_block().await?;
     println!("BlockInfo pre-fast_forward {:?}", block_info);
 
     // Call into fast_forward. This will take a bit of time to invoke, but is
@@ -29,7 +29,7 @@ async fn main() -> anyhow::Result<()> {
         contract.call("current_env_data").view().await?.json()?;
     println!("timestamp = {}, epoch_height = {}", timestamp, epoch_height);
 
-    let block_info = worker.view_latest_block().await?;
+    let block_info = worker.view_block().await?;
     println!("BlockInfo post-fast_forward {:?}", block_info);
 
     Ok(())

examples/src/nft.rs

@@ -37,12 +37,11 @@ async fn main() -> anyhow::Result<()> {
     println!("nft_mint outcome: {:#?}", outcome);
 
     let result: serde_json::Value = worker
-        .view(contract.id(), "nft_metadata", Vec::new())
+        .view(contract.id(), "nft_metadata")
         .await?
         .json()?;
 
     println!("--------------\n{}", result);
-
     println!("Dev Account ID: {}", contract.id());
 
     Ok(())

examples/src/ref_finance.rs

@@ -258,32 +258,22 @@ async fn main() -> anyhow::Result<()> {
     ///////////////////////////////////////////////////////////////////////////
 
     let ft_deposit: String = worker
-        .view(
-            ref_finance.id(),
-            "get_deposit",
-            serde_json::json!({
-                "account_id": owner.id(),
-                "token_id": ft.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view(ref_finance.id(), "get_deposit")
+        .args_json(serde_json::json!({
+            "account_id": owner.id(),
+            "token_id": ft.id(),
+        }))
         .await?
         .json()?;
     println!("Current FT deposit: {}", ft_deposit);
     assert_eq!(ft_deposit, parse_near!("100 N").to_string());
 
     let wnear_deposit: String = worker
-        .view(
-            ref_finance.id(),
-            "get_deposit",
-            serde_json::json!({
-                "account_id": owner.id(),
-                "token_id": wnear.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view(ref_finance.id(), "get_deposit")
+        .args_json(serde_json::json!({
+            "account_id": owner.id(),
+            "token_id": wnear.id(),
+        }))
         .await?
         .json()?;
 
@@ -295,18 +285,13 @@ async fn main() -> anyhow::Result<()> {
     ///////////////////////////////////////////////////////////////////////////
 
     let expected_return: String = worker
-        .view(
-            ref_finance.id(),
-            "get_return",
-            serde_json::json!({
-                "pool_id": pool_id,
-                "token_in": ft.id(),
-                "token_out": wnear.id(),
-                "amount_in": parse_near!("1 N").to_string(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view(ref_finance.id(), "get_return")
+        .args_json(serde_json::json!({
+            "pool_id": pool_id,
+            "token_in": ft.id(),
+            "token_out": wnear.id(),
+            "amount_in": parse_near!("1 N").to_string(),
+        }))
         .await?
         .json()?;
 
@@ -345,31 +330,22 @@ async fn main() -> anyhow::Result<()> {
     ///////////////////////////////////////////////////////////////////////////
 
     let ft_deposit: String = worker
-        .view(
-            ref_finance.id(),
-            "get_deposit",
-            serde_json::json!({
-                "account_id": owner.id(),
-                "token_id": ft.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view(ref_finance.id(), "get_deposit")
+        .args_json(serde_json::json!({
+            "account_id": owner.id(),
+            "token_id": ft.id(),
+        }))
         .await?
         .json()?;
     println!("New FT deposit after swap: {}", ft_deposit);
     assert_eq!(ft_deposit, parse_near!("99 N").to_string());
 
     let wnear_deposit: String = ref_finance
-        .view(
-            "get_deposit",
-            serde_json::json!({
-                "account_id": owner.id(),
-                "token_id": wnear.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view("get_deposit")
+        .args_json(serde_json::json!({
+            "account_id": owner.id(),
+            "token_id": wnear.id(),
+        }))
         .await?
         .json()?;
     println!("New WNear deposit after swap: {}", wnear_deposit);

examples/src/spooning.rs

@@ -79,7 +79,7 @@ async fn main() -> anyhow::Result<()> {
             .parse()
             .map_err(anyhow::Error::msg)?;
 
-        let mut state_items = worker.view_state(&contract_id, None).await?;
+        let mut state_items = worker.view_state(&contract_id).await?;
 
         let state = state_items.remove(b"STATE".as_slice()).unwrap();
         let status_msg = StatusMessage::try_from_slice(&state)?;
@@ -106,14 +106,10 @@ async fn main() -> anyhow::Result<()> {
 
     // Now grab the state to see that it has indeed been patched:
     let status: String = sandbox_contract
-        .view(
-            "get_status",
-            serde_json::json!({
-                "account_id": testnet_contract_id,
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view("get_status")
+        .args_json(serde_json::json!({
+            "account_id": testnet_contract_id,
+        }))
         .await?
         .json()?;
 
@@ -122,14 +118,10 @@ async fn main() -> anyhow::Result<()> {
 
     // See that sandbox state was overriden. Grabbing get_status(sandbox_contract_id) should yield Null
     let result: Option<String> = sandbox_contract
-        .view(
-            "get_status",
-            serde_json::json!({
-                "account_id": sandbox_contract.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view("get_status")
+        .args_json(serde_json::json!({
+            "account_id": sandbox_contract.id(),
+        }))
         .await?
         .json()?;
     assert_eq!(result, None);

examples/src/status_message.rs

@@ -18,14 +18,10 @@ async fn main() -> anyhow::Result<()> {
     println!("set_status: {:?}", outcome);
 
     let result: String = contract
-        .view(
-            "get_status",
-            json!({
-                "account_id": contract.id(),
-            })
-            .to_string()
-            .into_bytes(),
-        )
+        .view("get_status")
+        .args_json(json!({
+            "account_id": contract.id(),
+        }))
         .await?
         .json()?;
 

workspaces/Cargo.toml

@@ -18,6 +18,7 @@ bs58 = "0.4"
 cargo_metadata = { version = "0.14.2", optional = true }
 chrono = "0.4.19"
 dirs = "3.0.2"
+futures = "0.3"
 hex = "0.4.2"
 portpicker = "0.1.1"
 rand = "0.8.4"

workspaces/src/operations.rs

@@ -24,17 +24,21 @@ const MAX_GAS: Gas = 300_000_000_000_000;
 /// A set of arguments we can provide to a transaction, containing
 /// the function name, arguments, the amount of gas to use and deposit.
 #[derive(Debug)]
-pub struct Function<'a> {
-    name: &'a str,
-    args: Result<Vec<u8>>,
-    deposit: Balance,
-    gas: Gas,
+pub struct FunctionArgs<T> {
+    pub(crate) name: T,
+    pub(crate) args: Result<Vec<u8>>,
+    pub(crate) deposit: Balance,
+    pub(crate) gas: Gas,
 }
 
-impl<'a> Function<'a> {
+pub type Function<'a> = FunctionArgs<&'a str>;
+/// Owned version of [`Function`], whereby a lifetime is not attached.
+pub type FunctionOwned = FunctionArgs<String>;
+
+impl<T> FunctionArgs<T> {
     /// Initialize a new instance of [`Function`], tied to a specific function on a
     /// contract that lives directly on a contract we've specified in [`Transaction`].
-    pub fn new(name: &'a str) -> Self {
+    pub fn new(name: T) -> Self {
         Self {
             name,
             args: Ok(vec![]),
@@ -321,12 +325,8 @@ impl<'a, 'b> CallTransaction<'a, 'b> {
     /// Instead of transacting the transaction, call into the specified view function.
     pub async fn view(self) -> Result<ViewResultDetails> {
         self.worker
-            .client()
-            .view(
-                self.contract_id,
-                self.function.name.to_string(),
-                self.function.args?,
-            )
+            .view(&self.contract_id, self.function.name)
+            .args(self.function.args?)
             .await
     }
 }