CHANGELOG.md
Cargo.toml
README.md
examples
    access_keys.rs
    auth.rs
    contract_change_method.rs
    contract_change_method_commit.rs
    contract_view_code.rs
    contract_view_method.rs
    create_account.rs
    query_block.rs
    query_tx.rs
    utils.rs
    view_account.rs
src
    auth.rs
    errors.rs
    header.rs
    lib.rs
    methods
        adversarial
            check_store.rs
            disable_doomslug.rs
            disable_header_sync.rs
            get_saved_blocks.rs
            mod.rs
            produce_blocks.rs
            set_weight.rs
            switch_to_height.rs
        any
            mod.rs
        block.rs
        broadcast_tx_async.rs
        broadcast_tx_commit.rs
        chunk.rs
        experimental
            changes.rs
            changes_in_block.rs
            check_tx.rs
            genesis_config.rs
            mod.rs
            protocol_config.rs
            receipt.rs
            tx_status.rs
            validators_ordered.rs
        gas_price.rs
        health.rs
        light_client_proof.rs
        mod.rs
        network_info.rs
        next_light_client_block.rs
        query.rs
        sandbox
            fast_forward.rs
            mod.rs
            patch_state.rs
        status.rs
        tx.rs
        validators.rs

# near-jsonrpc-client

## WARNING

This crate is based on the tag v0.4.0 of the official near-jsonrpc-client crate.
It will be used by the Post-Quantum-Near-CLI-RS.

## Introduction

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

[![Crates.io](https://img.shields.io/crates/v/near-jsonrpc-client?label=latest)](https://crates.io/crates/near-jsonrpc-client)
[![Documentation](https://docs.rs/near-jsonrpc-client/badge.svg)](https://docs.rs/near-jsonrpc-client)
[![MIT or Apache 2.0 Licensed](https://img.shields.io/crates/l/near-jsonrpc-client.svg)](#license)
[![Dependency Status](https://deps.rs/crate/near-jsonrpc-client/0.4.0/status.svg)](https://deps.rs/crate/near-jsonrpc-client/0.4.0)

## 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.

```rust
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`](https://github.com/near/near-jsonrpc-client-rs/tree/master/examples) 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.

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

```rust
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.

```toml
# 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](https://github.com/miraclx/cargo-workspaces/tree/grouping-versioning-and-exclusion) of [`cargo-workspaces`](https://github.com/pksunkara/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](https://github.com/near/near-jsonrpc-client-rs/blob/master/Cargo.toml) 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](https://github.com/near/near-jsonrpc-client-rs/blob/master/CHANGELOG.md) 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](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license
   ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.
