feat: Re-exported near-abi-client (#303)

.gitignore

@@ -9,4 +9,4 @@ target
 .vscode
 
 # generated files
-.near-credentials
+.near-credentials

examples/Cargo.toml

@@ -22,6 +22,10 @@ near-workspaces = { path = "../workspaces", features = [
     "unstable",
 ] }
 
+[build-dependencies]
+anyhow = "1.0"
+near-workspaces = { path = "../workspaces" }
+
 [[example]]
 name = "async_transaction"
 path = "src/async_transaction.rs"
@@ -89,3 +93,11 @@ path = "src/noop.rs"
 [[example]]
 name = "custom_network"
 path = "src/custom_network.rs"
+
+[[example]]
+name = "build_gen_abi"
+path = "src/build_gen_abi.rs"
+
+[[example]]
+name = "macro_gen_abi"
+path = "src/macro_gen_abi.rs"

examples/build.rs

@@ -0,0 +1,6 @@
+fn main() -> anyhow::Result<()> {
+    near_workspaces::near_abi_client::Generator::new("src/gen".into())
+        .file("res/adder.json")
+        .generate()?;
+    Ok(())
+}

examples/res/adder.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": "0.4.0",
+  "metadata": {
+    "name": "abi",
+    "version": "0.1.0",
+    "authors": [
+      "Near Inc <[email protected]>"
+    ]
+  },
+  "body": {
+    "functions": [
+      {
+        "name": "add",
+        "doc": " Adds two pairs point-wise.",
+        "kind": "view",
+        "params": {
+          "serialization_type": "json",
+          "args": [
+            {
+              "name": "a",
+              "type_schema": {
+                "$ref": "#/definitions/Pair"
+              }
+            },
+            {
+              "name": "b",
+              "type_schema": {
+                "$ref": "#/definitions/Pair"
+              }
+            }
+          ]
+        },
+        "result": {
+          "serialization_type": "json",
+          "type_schema": {
+            "$ref": "#/definitions/Pair"
+          }
+        }
+      }
+    ],
+    "root_schema": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "String",
+      "type": "string",
+      "definitions": {
+        "Pair": {
+          "type": "array",
+          "items": [
+            {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            }
+          ],
+          "maxItems": 2,
+          "minItems": 2
+        }
+      }
+    }
+  }
+}

examples/src/build_gen_abi.rs

@@ -0,0 +1,28 @@
+// This example shows how to use the `near_abi_client` Generation Based API.
+// We are generating client code using the schema for the ABI and and `workspaces-rs` to call into the contract.
+// More information about usage can be found here: <https://github.com/near/near-abi-client-rs/blob/main/README.md>
+//
+// A good scenario for usage might be when you are interacting with a contract or multiple contracts at an automated level
+// and you want to have a type-safe way of interacting with them.
+
+/// The generated api requires setup in the `build.rs` file to generate the client code.
+#[path = "gen/adder.rs"]
+mod generation_adder;
+
+const ADDER_WASM_FILEPATH: &str = "./examples/res/adder.wasm";
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let worker = near_workspaces::sandbox().await?;
+    let wasm = std::fs::read(ADDER_WASM_FILEPATH)?;
+    let contract = worker.dev_deploy(&wasm).await?;
+
+    // The client is initialized with the contract.
+    let abi_client = generation_adder::AbiClient { contract };
+
+    // Here we can call the method, now typed with arguments and return types.
+    let res = abi_client.add(vec![1, 2], vec![3, 4]).await?;
+
+    assert_eq!(res, [4, 6]);
+    Ok(())
+}

examples/src/gen/adder.rs

@@ -0,0 +1 @@
+// No content here, it's to be generated on build. Here to allow cargofmt to work.

examples/src/macro_gen_abi.rs

@@ -0,0 +1,26 @@
+// This example shows how to use the `near_abi_client` Macro Based API.
+// We are generating client code using the schema for the ABI and and `workspaces-rs` to call into the contract.
+// More information about usage can be found here: <https://github.com/near/near-abi-client-rs/blob/main/README.md>
+//
+// A good scenario for usage might be when you are interacting with a contract or multiple contracts at an automated level
+// and you want to have a type-safe way of interacting with them.
+
+const ADDER_WASM_FILEPATH: &str = "./examples/res/adder.wasm";
+
+near_workspaces::near_abi_client::generate!(AbiClient for "res/adder.json");
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let worker = near_workspaces::sandbox().await?;
+    let wasm = std::fs::read(ADDER_WASM_FILEPATH)?;
+    let contract = worker.dev_deploy(&wasm).await?;
+
+    // The client is initialized with the contract.
+    let abi_client = AbiClient { contract };
+
+    // Here we can call the method, now typed with arguments and return types.
+    let res = abi_client.add(vec![1, 2], vec![3, 4]).await?;
+
+    assert_eq!(res, [4, 6]);
+    Ok(())
+}

workspaces/Cargo.toml

@@ -30,6 +30,7 @@ tokio-retry = "0.3"
 tracing = "0.1"
 url = { version = "2.2.2", features = ["serde"] }
 
+near-abi-client = "0.1.1"
 near-gas = { version = "0.2.5", features = ["serde", "borsh", "schemars"] }
 near-token = { version = "0.2.0", features = ["serde"] }
 near-sdk = { version = "5.0.0-alpha.2", optional = true }

workspaces/src/lib.rs

@@ -21,6 +21,10 @@ pub mod result;
 pub mod rpc;
 pub mod types;
 
+/// The near_abi_client implementation is currently in flux and we offer a re-export
+/// of it and example code. No public near_abi APIs are baked into workspace-rs yet.
+pub use near_abi_client;
+
 pub use network::pick_unused_port;
 pub use network::variants::{DevNetwork, Network};
 pub use result::Result;