Quickstart Guide for Circles SDK (Rust)

The Rust SDK is currently read-only. You can query data, run pathfinding, and decode events, but write flows (invites, minting, transfers, wrapping) are runner-dependent and will be added later.

Install crates

Add the core crates to your Cargo.toml:

[dependencies]
circles-types = "0.3"
circles-pathfinder = "0.4"
circles-rpc = "0.1"
circles-profiles = "0.1"
alloy-primitives = "0.7"
tokio = { version = "1", features = ["full"] }
reqwest = "0.12" # for RpcClient::http URL parsing

Minimal pathfinding example

Uses circles-pathfinder to prepare a flow matrix for contract calls (read-only preparation; sending the transaction will come once runner support exists).

use circles_pathfinder::{prepare_flow_for_contract, FindPathParams};
use alloy_primitives::{Address, U256};
 
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let params = FindPathParams {
        from: "0x1234567890123456789012345678901234567890".parse()?,
        to: "0x0987654321098765432109876543210987654321".parse()?,
        target_flow: U256::from(1_000_000_000_000_000_000u64), // 1 token
        use_wrapped_balances: Some(true),
        from_tokens: None,
        to_tokens: None,
        exclude_from_tokens: None,
        exclude_to_tokens: None,
    };
 
    let flow_matrix = prepare_flow_for_contract(
        "https://rpc.aboutcircles.com/",
        params,
    )
    .await?;
 
    println!(
        "Flow matrix ready with {} vertices",
        flow_matrix.flow_vertices.len()
    );
 
    // Send on-chain once runner integration is available:
    // let (vertices, edges, streams, coordinates) = flow_matrix.into_contract_params();
    // runner.transfer_flow(vertices, edges, streams, coordinates).await?;
 
    Ok(())
}

Fetching balances (read-only placeholder)

Balance queries use circles-rpc + circles-types.

use circles_rpc::{BalanceMethods, RpcClient};
use circles_types::Address;
use reqwest::Url;
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = RpcClient::http(Url::parse("https://rpc.aboutcircles.com/")?);
    let balances = BalanceMethods::new(client);
 
    let avatar: Address = "0x1234567890123456789012345678901234567890".parse()?;
    let total = balances
        .get_total_balance(avatar, /* as_time_circles */ false, /* use_v2 */ true)
        .await?;
 
    println!("Total balance: {total:?}");
    Ok(())
}