ic_agent/
lib.rs

1//! The `ic-agent` is a simple-to-use library that enables you to
2//! build applications and interact with the [Internet Computer](https://internetcomputer.org)
3//! in Rust. It serves as a Rust-based low-level backend for the
4//! DFINITY Canister Software Development Kit (SDK) and the command-line execution environment
5//! [`dfx`](https://internetcomputer.org/docs/current/developer-docs/setup/install).
6//!
7//! ## Overview
8//! The `ic-agent` is a Rust crate that can connect directly to the Internet
9//! Computer through the Internet Computer protocol (ICP).
10//! The key software components of the ICP are broadly referred to as the
11//! [replica](https://internetcomputer.org/docs/current/concepts/nodes-subnets).
12//!
13//! The agent is designed to be compatible with multiple versions of the
14//! replica API, and to expose both low-level APIs for communicating with
15//! Internet Computer protocol components like the replica and to provide
16//! higher-level APIs for communicating with software applications deployed
17//! as [canisters](https://internetcomputer.org/docs/current/concepts/canisters-code).
18//!
19//! ## Example
20//! The following example illustrates how to use the Agent interface to send
21//! a call to an Internet Computer's Ledger Canister to check the total ICP tokens supply.
22//!
23//! ```rust
24//!use anyhow::{Context, Result};
25//!use candid::{Decode, Nat};
26//!use ic_agent::{export::Principal, Agent};
27//!use url::Url;
28//!
29//!pub async fn create_agent(url: Url, use_mainnet: bool) -> Result<Agent> {
30//!    let agent = Agent::builder().with_url(url).build()?;
31//!    if !use_mainnet {
32//!        agent.fetch_root_key().await?;
33//!    }
34//!    Ok(agent)
35//!}
36//!
37//!#[tokio::main]
38//!async fn main() -> Result<()> {
39//!    // IC HTTP Gateway URL
40//!    let url = Url::parse("https://ic0.app").unwrap();
41//!    let agent = create_agent(url, true).await?;
42//!
43//!    // ICP Ledger Canister ID
44//!    let canister_id = Principal::from_text("ryjl3-tyaaa-aaaaa-aaaba-cai")?;
45//!
46//!    // Method: icrc1_total_supply (takes no arguments, returns nat)
47//!    let method_name = "icrc1_total_supply";
48//!
49//!    // Encode empty Candid arguments
50//!    let args = candid::encode_args(())?;
51//!
52//!    // Dispatch query call
53//!    let response = agent
54//!        .query(&canister_id, method_name)
55//!        .with_arg(args)
56//!        .call()
57//!        .await
58//!        .context("Failed to query icrc1_total_supply method.")?;
59//!
60//!    // Decode the response as nat
61//!    let total_supply_nat =
62//!        Decode!(&response, Nat).context("Failed to decode total supply as nat.")?;
63//!
64//!    println!("Total ICP Supply: {} ICP", total_supply_nat);
65//!
66//!    Ok(())
67//!}
68//! ```
69//! For more information about the Agent interface used in this example, see the
70//! [Agent] documentation.
71//!
72//! ## References
73//! For an introduction to the Internet Computer and the DFINITY Canister SDK,
74//! see the following resources:
75//!
76//! - [How the IC Works](https://internetcomputer.org/docs/current/concepts/)
77//! - [DFINITY Canister SDK](https://internetcomputer.org/docs/current/references/cli-reference/)
78//!
79//! The Internet Computer protocol and interface specifications are not
80//! publicly available yet. When these specifications are made public and
81//! generally available, additional details about the versions supported will
82//! be available here.
83
84#![warn(
85    missing_docs,
86    rustdoc::broken_intra_doc_links,
87    rustdoc::private_intra_doc_links
88)]
89#![cfg_attr(not(target_family = "wasm"), warn(clippy::future_not_send))]
90#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
91
92#[macro_use]
93mod util;
94
95pub mod agent;
96pub mod export;
97pub mod identity;
98
99use agent::response_authentication::LookupPath;
100#[doc(inline)]
101pub use agent::{agent_error, agent_error::AgentError, Agent, NonceFactory, NonceGenerator};
102#[doc(inline)]
103pub use ic_transport_types::{to_request_id, RequestId, RequestIdError, TransportCallResponse};
104#[doc(inline)]
105pub use identity::{Identity, Signature};
106
107// Re-export from ic_certification for backward compatibility.
108pub use ic_certification::{hash_tree, Certificate};
109
110/// Looks up a value in the certificate's tree at the specified hash.
111///
112/// Returns the value if it was found; otherwise, errors with `LookupPathAbsent`, `LookupPathUnknown`, or `LookupPathError`.
113pub fn lookup_value<P: LookupPath, Storage: AsRef<[u8]>>(
114    tree: &ic_certification::certificate::Certificate<Storage>,
115    path: P,
116) -> Result<&[u8], AgentError> {
117    agent::response_authentication::lookup_value(&tree.tree, path)
118}
ic_agent/lib.rs

ic_agent/
lib.rs
