DOCSEARCHbyAlgolia
Submit Docs

agent-rs

repository·main·Indexed 40 days ago

https://github.com/dfinity/agent-rs

A suite of Rust tools and libraries for interacting with the Internet Computer (IC) protocol. It includes ic-agent, the core library for communicating with the IC replica and backend for the dfx CLI; ic-utils for higher-level abstractions; ic-identity-hsm for managing identities using Hardware Security Modules; and the icx command-line tool for calling canister functions and debugging.

Tokens
32.3K
Snippets
105
Records
152
Agent score
49%

What's inside agent-rs

  2. Overview of ic-identity-hsm

    main
    ic-identity-hsm is a Rust crate designed to manage identities that utilize a Hardware Security Module (HSM). It enables users to sign Internet Computer messages using their hardware keys. The crate also provides support for SoftHSM, allowing for software-based HSM emulation.

  3. Overview of ic-utils

    main
    ic-utils is a collection of utility crates designed to facilitate communication with the Internet Computer. It provides higher-level abstractions over the lower-level ic-agent library to simplify common tasks when interacting with the network.

  4. Overview of agent-rs packages

    main

    The repository is organized as a Cargo workspace containing several specialized packages:

    Package NameDescription
    ic-agentA library used to talk directly to the Internet Computer Replica.
    ic-utilsA library of utilities for managing calls and canisters.
    icxA command line utility for using the agent. Note: This is intended for testing within this repo and is not meant for publication.
    ref-testsA package specifically for running ic-ref tests using ic-agent as the connection.

  5. Use ic-cert to debug certified HTTP responses

    main
    ic-cert is a command-line tool designed for debugging certified HTTP responses on the Internet Computer. It works by downloading a document from a specified URL and pretty-printing the contents of the IC-Certificate header found in the response.

  6. Understand the Rust toolchain and MSRV

    main

    The repository manages two distinct Rust versions:

    1. Development toolchain: Uses the latest stable release for development, cargo fmt, cargo clippy, and most CI jobs.
    2. MSRV (Minimum Supported Rust Version): The oldest compiler version guaranteed to build the published crates. This is defined by the rust-version field in the workspace Cargo.toml.

    Key implications:

    • The MSRV covers building the libraries, but not necessarily running the full test suite (dev-dependencies may require a newer compiler).
    • Bumping the MSRV requires updating the rust-version in Cargo.toml.
    • New Rust releases may introduce new clippy lints that could cause CI failures even on untouched branches; these should be addressed with lint-cleanup PRs rather than toolchain changes.

  8. Run tests in agent-rs

    main

    There are two types of test suites available:

    1. Regular cargo tests: Standard Rust tests run via cargo test.
    2. ic-ref tests: Specialized tests that require a running local reference server. If no reference server is detected, these tests will be ignored.

  9. Use `icx` to interact with the Internet Computer

    main

    The icx command-line tool allows you to interact with the Internet Computer by calling canister functions directly. Use icx --help to view all available commands and options.

    Identity

    Use the --pem argument to provide a PEM file containing a valid key for Internet Computer signing and validation.

    Root Key

    • For IC Mainnet: The --fetch-root-key argument is not required.
    • For non-IC networks: You must pass --fetch-root-key to fetch the root key. If this argument is omitted, icx uses a hard-coded public key.

  11. Separate signing and sending with `icx`

    main

    For workflows requiring air-gapped signing or manual message handling, use the --serialize flag with icx update or icx query. This serializes the signed canister call message as JSON and prints it to stdout.

    When using icx update with --serialize:

    1. The signed message is printed to stdout.
    2. A corresponding request_status message is printed to stderr.

    Workflow Example

    1. Sign (on an air-gapped machine or locally)

    icx --fetch-root-key update --serialize rwlgt-iiaaa-aaaaa-aaaaa-cai greet '("everyone")' > output.txt
head -n 1 output.txt > update.json
tail -n 1 output.txt > request_status.json

    2. Send the signed message

    cat update.json | icx send

    3. Check request status

    cat request_status.json | icx --fetch-root-key send
    # Sign
icx --fetch-root-key update --serialize rwlgt-iiaaa-aaaaa-aaaaa-cai greet '("everyone")' > output.txt
head -n 1 output.txt > update.json
tail -n 1 output.txt > request_status.json

# Send
cat update.json | icx send

# Request status
cat request_status.json | icx --fetch-root-key send

  12. Install the `icx` CLI

    main

    To install icx, you must build it from source using cargo. Clone the agent-rust repository and run cargo build.

    The resulting executable will be located at target/debug/icx.

    git clone https://github.com/dfinity/agent-rust.git
cd agent-rust
cargo build