Skip to content

Pathfinder

Pathfinding is available in two forms:

  • low-level flow-matrix preparation via circles-pathfinder
  • high-level transfer planning/execution via circles-sdk

Local pathfinding (crate)

use circles_pathfinder::{prepare_flow_for_contract, FindPathParams};
use alloy_primitives::U256;
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    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,
        simulated_balances: None,
        simulated_trusts: None,
        max_transfers: Some(6),
    };
 
    let flow = prepare_flow_for_contract("https://rpc.aboutcircles.com/", params).await?;
    let (vertices, edges, streams, coordinates) = flow.into_contract_params();
    println!("vertices: {}, edges: {}", vertices.len(), edges.len());
 
    // At this level you own submission of the final contract call.
    // For the higher-level SDK flow, prefer `plan_transfer` / `transfer`.
    Ok(())
}

RPC pathfinding (circles-rpc)

use circles_rpc::{PathfinderMethods, RpcClient};
use circles_types::FindPathParams;
use alloy_primitives::U256;
use reqwest::Url;
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = RpcClient::http(Url::parse("https://rpc.aboutcircles.com/")?);
    let pathfinder = PathfinderMethods::new(client);
 
    let params = FindPathParams {
        from: "0x1234567890123456789012345678901234567890".parse()?,
        to: "0x0987654321098765432109876543210987654321".parse()?,
        target_flow: U256::from(1_000_000_000_000_000_000u64),
        use_wrapped_balances: Some(true),
        from_tokens: None,
        to_tokens: None,
        exclude_from_tokens: None,
        exclude_to_tokens: None,
        simulated_balances: None,
        simulated_trusts: None,
        max_transfers: Some(6),
    };
 
    let result = pathfinder.find_path(params).await?;
    println!("max flow: {}", result.max_flow);
    Ok(())
}

Use find_max_flow to get the ceiling when you don’t know the target amount.

Parameters (FindPathParams)

  • from, to (Address): endpoints.
  • target_flow (U256): required for find_path.
  • use_wrapped_balances (bool): include wrapped tokens in routing (set true if you hold wrappers).
  • from_tokens / to_tokens: pin allowed token owners at ends.
  • exclude_from_tokens / exclude_to_tokens: ban specific token owners.
  • simulated_balances: preview flows with hypothetical balances.
  • simulated_trusts: preview flows with hypothetical trust edges.
  • max_transfers: hop cap; lower = faster but may reduce flow.

From path to execution

  • prepare_flow_for_contract returns contract-ready (vertices, edges, streams, coordinates).
  • HumanAvatar::plan_transfer, OrganisationAvatar::plan_transfer, and BaseGroupAvatar::plan_transfer wrap the same lower-level machinery and return PreparedTransaction values ready for a runner.
  • Use direct_transfer when you already know the token and do not need pathfinding.

Tips

  • If max_flow is 0, check mutual trust or unwrap static/demurraged balances.
  • Always enable use_wrapped_balances when wrappers are involved.
  • Hop limits trade off performance vs. achievable flow.