README.md

near-abi-client-rs

Library to generate Rust client code with workspaces-rs from ABI schemas on NEAR

Release notes

Release notes and unreleased changes can be found in the CHANGELOG

Usage

This crate supports two sets of APIs for users with different needs:

• Macro-driven. Gives you a client in a single macro invocation.
• Generation-based. Gives you more control and is transparent about what code you end up using, but requires more setup.

Macro API

Checkout the delegator-macro example for a standalone project using macro API to get a client and use it.

To generate a struct named ClientName based on ABI located at path/to/abi.json (relative to the current file's directory):

mod mymod {
    near_abi_client::generate!(ClientName for "path/to/abi.json");
}

Placing the macro invocation inside a mod section is optional, but helps reducing unexpected behaviors such as name clashes.

Now, assuming you have a contract: near_workspaces::Contract deployed, you can make a call like this:

let contract = mymod::ClientName { contract };
let res = contract
    .my_method_name(arg1, arg2)
    .await?;

Generation API

Checkout the delegator-generation example for a standalone project using generation API to generate a client and use it.

First, we need our package to have a build.rs file that runs the generation step. The following snippet will generate the client in abi.rs under path/to/out/dir:

fn main() -> anyhow::Result<()> {
    near_abi_client::Generator::new("path/to/out/dir".into())
        .file("path/to/abi.json")
        .generate()?;
    Ok(())
}

The resulting file, however, is not included in your source set by itself. You have to include it manually; the recommended way is to create a mod with a custom path:

#[path = "path/to/out/dir/abi.rs"]
mod mymod;

Now, assuming you have a contract: near_workspaces::Contract deployed, you can make a call like this:

let contract = mymod::AbiClient { contract };
let res = contract
    .my_method_name(arg1, arg2)
    .await?;

Feel free to explore what other methods Generator has to customize the resulting code (e.g. client struct name).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as below, without any additional terms or conditions.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.