near-jsonrpc-client

Lower-level API for interfacing with the NEAR Protocol via JSONRPC.

Usage

Each one of the valid JSON RPC methods are defined in the methods module. For instance, to make a tx request, you start with the tx module and construct a request using the methods::tx::RpcTransactionStatusRequest struct.

use near_jsonrpc_client::{methods, JsonRpcClient};
use near_jsonrpc_primitives::types::transactions::TransactionInfo;

let mainnet_client = JsonRpcClient::connect("https://archival-rpc.mainnet.near.org");

let tx_status_request = methods::tx::RpcTransactionStatusRequest {
    transaction_info: TransactionInfo::TransactionId {
        hash: "9FtHUFBQsZ2MG77K3x3MJ9wjX3UT8zE1TczCrhZEcG8U".parse()?,
        account_id: "miraclx.near".parse()?,
    },
};

// call a method on the server via the connected client
let tx_status = mainnet_client.call(tx_status_request).await?;

println!("{:?}", tx_status);

Check out the examples folder for a comprehensive list of helpful demos. You can run the examples with cargo. For example: cargo run --example view_account.

For all intents and purposes, the predefined structures in methods should suffice, if you find that they don't or you crave extra flexibility, well, you can opt in to use the generic constructor methods::any() with the any feature flag.

In this example, we retrieve only the parts from the genesis config response that we care about.

# in Cargo.toml
near-jsonrpc-client = { ..., features = ["any"] }

use serde::Deserialize;
use serde_json::json;

use near_jsonrpc_client::{methods, JsonRpcClient};
use near_primitives::serialize::dec_format;
use near_primitives::types::*;

#[derive(Debug, Deserialize)]
struct PartialGenesisConfig {
    protocol_version: ProtocolVersion,
    chain_id: String,
    genesis_height: BlockHeight,
    epoch_length: BlockHeightDelta,
    #[serde(with = "dec_format")]
    min_gas_price: Balance,
    #[serde(with = "dec_format")]
    max_gas_price: Balance,
    #[serde(with = "dec_format")]
    total_supply: Balance,
    validators: Vec<AccountInfo>,
}

impl methods::RpcHandlerResponse for PartialGenesisConfig {}

let mainnet_client = JsonRpcClient::connect("https://rpc.mainnet.near.org");

let genesis_config_request = methods::any::<Result<PartialGenesisConfig, ()>>(
    "EXPERIMENTAL_genesis_config",
    json!(null),
);

let partial_genesis = mainnet_client.call(genesis_config_request).await?;

println!("{:#?}", partial_genesis);

By default, near-jsonrpc-client uses native-tls. On Linux, this introduces a dependency on the system openssl library. In some situations, for example when cross-compiling, it can be problematic to depend on non-Rust libraries.

If you wish to switch to an all-Rust TLS implementation, you may do so using the rustls-tls feature flag. Note that the native-tls feature is enabled by default. Therefore, to disable it and use rustls-tls instead, you must also use default-features = false. The default auth feature must then be declared explicitly.

# in Cargo.toml
near-jsonrpc-client = { ..., default-features = false, features = ["auth","rustls-tls"] }

Releasing

Versioning and releasing of this crate is automated and managed by custom fork of cargo-workspaces. To publish a new version of this crate, you can do so by bumping the version under the [workspace.metadata.workspaces] section in the package manifest and submit a PR.

We have CI Infrastructure put in place to automate the process of publishing all crates once a version change has merged into master.

However, before you release, make sure the CHANGELOG is up to date and that the [Unreleased] section is present but empty.

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.