Struct Contract 

pub struct Contract(pub AccountId);

Contract-related interactions with the NEAR Protocol

The Contract struct provides methods to interact with NEAR contracts, including calling functions, querying storage, and deploying contracts.

Examples

use near_api::*;

let abi = Contract("some_contract.testnet".parse()?).abi().fetch_from_testnet().await?;
println!("ABI: {:?}", abi);

Tuple Fields

0: AccountId

Implementations

impl Contract

pub const fn account_id(&self) -> &AccountId

Returns the underlying account ID for this contract.

Example

use near_api::*;

let contract = Contract("contract.testnet".parse()?);
let account_id = contract.account_id();
println!("Contract account ID: {}", account_id);

pub fn as_account(&self) -> Account

Converts this contract to an Account for account-related operations.

Example

use near_api::*;

let contract = Contract("contract.testnet".parse()?);
let account = contract.as_account();
let account_info = account.view().fetch_from_testnet().await?;
println!("Account balance: {}", account_info.data.amount);

pub fn storage_deposit(&self) -> StorageDeposit

Creates a StorageDeposit wrapper for storage management operations on this contract.

This is useful for contracts that implement the NEP-145 storage management standard.

Example

use near_api::*;

let contract = Contract("usdt.tether-token.near".parse()?);
let storage = contract.storage_deposit();

// Check storage balance for an account
let balance = storage.view_account_storage("alice.near".parse()?)?.fetch_from_mainnet().await?;
println!("Storage balance: {:?}", balance);

pub fn call_function<Args>( &self, method_name: &str, args: Args, ) -> Result<CallFunctionBuilder, BuilderError>

where Args: Serialize,

Prepares a call to a contract function with JSON-serialized arguments.

This is the default and most common way to call contract functions, using JSON serialization for the input arguments. This will return a builder that can be used to prepare a query or a transaction.

For alternative serialization formats, see:

• call_function_borsh for Borsh serialization
• call_function_raw for pre-serialized raw bytes

Calling view function get_number

use near_api::*;

let number: Data<u64> = Contract("some_contract.testnet".parse()?)
    .call_function("get_number", ())?
    .read_only()
    .fetch_from_testnet()
    .await?;
println!("Number: {:?}", number);

Calling a state changing function set_number

use near_api::*;
use serde_json::json;

let signer = Signer::new(Signer::from_ledger())?;
let result = Contract("some_contract.testnet".parse()?)
    .call_function("set_number", json!({ "number": 100 }))?
    .transaction()
     // Optional
    .gas(NearGas::from_tgas(200))
    .with_signer("alice.testnet".parse()?, signer)
    .send_to_testnet()
    .await?;

pub fn call_function_borsh<Args>( &self, method_name: &str, args: Args, ) -> Result<CallFunctionBuilder, Error>

where Args: BorshSerialize,

Prepares a call to a contract function with Borsh-serialized arguments.

This method is useful when the contract expects Borsh-encoded input arguments instead of JSON. This is less common but can be more efficient for certain use cases.

Example

use near_api::*;
use borsh::BorshSerialize;

#[derive(BorshSerialize)]
struct MyArgs {
    value: u64,
}

let signer = Signer::new(Signer::from_ledger())?;
let args = MyArgs { value: 42 };
let result = Contract("some_contract.testnet".parse()?)
    .call_function_borsh("set_value", args)?
    .transaction()
    .with_signer("alice.testnet".parse()?, signer)
    .send_to_testnet()
    .await?;

pub fn call_function_raw( &self, method_name: &str, args: Vec<u8>, ) -> CallFunctionBuilder

Prepares a call to a contract function with pre-serialized raw bytes.

This method is useful when you already have serialized arguments or need complete control over the serialization format. The bytes are passed directly to the contract without any additional processing.

Example

use near_api::*;

let signer = Signer::new(Signer::from_ledger())?;
// Pre-serialized or custom-encoded data
let raw_args = vec![1, 2, 3, 4];
let result = Contract("some_contract.testnet".parse()?)
    .call_function_raw("custom_method", raw_args)
    .transaction()
    .with_signer("alice.testnet".parse()?, signer)
    .send_to_testnet()
    .await?;

pub const fn deploy(contract: AccountId) -> DeployBuilder

Prepares a transaction to deploy a contract to the provided account.

The code is the wasm bytecode of the contract. For more information on how to compile your contract, please refer to the NEAR documentation.

Deploying the contract

use near_api::*;

let code = std::fs::read("path/to/your/contract.wasm")?;
let signer = Signer::new(Signer::from_ledger())?;
let result = Contract::deploy("contract.testnet".parse()?)
    .use_code(code)
    .without_init_call()
    .with_signer(signer)
    .send_to_testnet()
    .await?;

Deploying the contract with an init call

use near_api::*;
use serde_json::json;

let code = std::fs::read("path/to/your/contract.wasm")?;
let signer = Signer::new(Signer::from_ledger())?;
let result = Contract::deploy("contract.testnet".parse()?)
    .use_code(code)
    .with_init_call("init", json!({ "number": 100 }))?
    // Optional
    .gas(NearGas::from_tgas(200))
    .with_signer(signer)
    .send_to_testnet()
    .await?;

pub const fn deploy_global_contract_code(code: Vec<u8>) -> GlobalDeployBuilder

Prepares a transaction to deploy a code to the global contract code storage.

This will allow other users to reference given code as hash or account-id and reduce the gas cost for deployment.

Please be aware that the deploy costs 10x more compared to the regular costs and the tokens are burnt with no way to get it back.

Example deploying a contract to the global contract code storage as hash

use near_api::*;

let code = std::fs::read("path/to/your/contract.wasm")?;
let signer = Signer::new(Signer::from_ledger())?;
let result = Contract::deploy_global_contract_code(code)
    .as_hash()
    .with_signer("some-account.testnet".parse()?, signer)
    .send_to_testnet()
    .await?;

Example deploying a contract to the global contract code storage as account-id

The difference between the hash and account-id version is that the account-id version upgradable and can be changed.

use near_api::*;

let code = std::fs::read("path/to/your/contract.wasm")?;
let signer = Signer::new(Signer::from_ledger())?;
let result = Contract::deploy_global_contract_code(code)
    .as_account_id("nft-contract.testnet".parse()?)
    .with_signer(signer)
    .send_to_testnet()
    .await?;

pub fn abi( &self, ) -> RequestBuilder<PostprocessHandler<Option<AbiRoot>, CallResultHandler<Vec<u8>>>>

Prepares a query to fetch the ABI of the contract using the following standard.

Please be aware that not all the contracts provide the ABI.

Example

use near_api::*;

let abi = Contract("some_contract.testnet".parse()?).abi().fetch_from_testnet().await?;
println!("ABI: {:?}", abi);

pub fn wasm(&self) -> RequestBuilder<ViewCodeHandler>

Prepares a query to fetch the wasm code (Data<ContractCodeView>) of the contract.

Example

use near_api::*;

let wasm = Contract("some_contract.testnet".parse()?).wasm().fetch_from_testnet().await?;
println!("WASM: {}", wasm.data.code_base64);

pub const fn global_wasm() -> GlobalWasmBuilder

Creates a builder to query contract code from the global contract code storage.

The global contract code storage allows contracts to be deployed once and referenced by multiple accounts, reducing deployment costs. This feature is defined in NEP-591. Contracts can be referenced either by a contract hash (immutable) or by an account ID (mutable).

Example querying by account ID

use near_api::*;

let code = Contract::global_wasm()
    .by_account_id("nft-contract.testnet".parse()?)
    .fetch_from_testnet()
    .await?;
println!("Global contract code: {}", code.data.code_base64);

Example querying by hash

use near_api::*;

let code = Contract::global_wasm()
    .by_hash("DxfRbrjT3QPmoANMDYTR6iXPGJr7xRUyDnQhcAWjcoFF".parse()?)
    .fetch_from_testnet()
    .await?;
println!("Global contract code: {}", code.data.code_base64);

pub fn view_storage_with_prefix( &self, prefix: &[u8], ) -> RequestBuilder<ViewStateHandler>

Prepares a query to fetch the storage of the contract (Data<ViewStateResult>) using the given prefix as a filter.

It helpful if you are aware of the storage that you are looking for.

Example

use near_api::*;

let storage = Contract("some_contract.testnet".parse()?)
    .view_storage_with_prefix(b"se")
    .fetch_from_testnet()
    .await?;
println!("Storage: {:?}", storage);

pub fn view_storage(&self) -> RequestBuilder<ViewStateHandler>

Prepares a query to fetch the storage of the contract (Data<ViewStateResult>).

Please be aware that large storage queries might fail.

Example

use near_api::*;

let storage = Contract("some_contract.testnet".parse()?)
    .view_storage()
    .fetch_from_testnet()
    .await?;
println!("Storage: {:?}", storage);

pub fn contract_source_metadata( &self, ) -> RequestBuilder<CallResultHandler<ContractSourceMetadata>>

Prepares a query to fetch the contract source metadata(Data<ContractSourceMetadata>) using NEP-330 standard.

The contract source metadata is a standard interface that allows auditing and viewing source code for a deployed smart contract. Implementation of this standard is purely optional but is recommended for developers whose contracts are open source.

Examples

use near_api::*;

let source_metadata = Contract("some_contract.testnet".parse()?)
    .contract_source_metadata()
    .fetch_from_testnet()
    .await?;
println!("Source metadata: {:?}", source_metadata);

A more verbose runnable example is present in examples/contract_source_metadata.rs:

use std::str::FromStr;

use near_api::{types::AccountId, Contract};

#[tokio::main]
async fn main() {
    for (account_name, expected_json_metadata) in [
        ("desolate-toad.testnet", FIRST_METADATA),
        ("fat-fabulous-toad.testnet", SECOND_METADATA),
    ] {
        let source_metadata = Contract(AccountId::from_str(account_name).expect("no err"))
            .contract_source_metadata()
            .fetch_from_testnet()
            .await
            .expect("no network or rpc err");

        assert_eq!(
            expected_json_metadata,
            serde_json::to_string_pretty(&source_metadata.data).expect("no ser err")
        );
    }
}

const FIRST_METADATA: &str = r#"{
  "version": "0.1.0",
  "link": "https://github.com/dj8yfo/quiet_glen",
  "standards": [
    {
      "standard": "nep330",
      "version": "1.2.0"
    }
  ],
  "build_info": null
}"#;

const SECOND_METADATA: &str = r#"{
  "version": "0.1.0",
  "link": "https://github.com/dj8yfo/quiet_glen/tree/8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b",
  "standards": [
    {
      "standard": "nep330",
      "version": "1.2.0"
    }
  ],
  "build_info": {
    "build_environment": "sourcescan/cargo-near:0.13.3-rust-1.84.0@sha256:722198ddb92d1b82cbfcd3a4a9f7fba6fd8715f4d0b5fb236d8725c4883f97de",
    "build_command": [
      "cargo",
      "near",
      "build",
      "non-reproducible-wasm",
      "--locked"
    ],
    "contract_path": "",
    "source_code_snapshot": "git+https://github.com/dj8yfo/quiet_glen?rev=8d8a8a0fe86a1d8eb3bce45f04ab1a65fecf5a1b",
    "output_wasm_path": null
  }
}"#;

Trait Implementations

impl Clone for Contract

fn clone(&self) -> Contract

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Contract

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.