Crate circles_pathfinder 

Circles Pathfinder

Pathfinding and flow matrix calculation for the Circles protocol.

This crate provides efficient pathfinding algorithms and flow matrix generation for the Circles universal basic income protocol, with ready-to-use types for smart contract interactions.

Quick Start

High-level API (Recommended)

use circles_pathfinder::{FindPathParams, prepare_flow_for_contract};
use alloy_primitives::{Address, aliases::U192, U256};

let params = FindPathParams {
    from: "0x123...".parse()?,
    to: "0x456...".parse()?,
    target_flow: U256::from(1_000_000_000_000_000_000u64), // 1 CRC
    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: None,
};

// One function call gets contract-ready data
let path_data = prepare_flow_for_contract("https://rpc.circles.com", params).await?;

// Ready for smart contract calls
let (vertices, edges, streams, coords) = path_data.to_contract_params();
// contract.some_function(vertices, edges, streams, coords)

Low-level API (Advanced)

use circles_pathfinder::{find_path, create_flow_matrix};
use alloy_primitives::{Address, aliases::U192};

// Step 1: Find path
let transfers = find_path(
    "https://rpc.circles.com",
    "0x123...".parse()?,
    "0x456...".parse()?,
    U192::from(1000u64),
    true
).await?;

// Step 2: Create flow matrix
let matrix = create_flow_matrix(
    "0x123...".parse()?,
    "0x456...".parse()?,
    U192::from(1000u64),
    &transfers
)?;

Modules

• hub - Circles Hub contract types and conversions
• rpc - RPC communication and pathfinding
• flow - Flow matrix calculation
• packing - Coordinate packing utilities
• convenience - High-level convenience functions

Features

• Fast pathfinding using Circles RPC endpoints
• Hub contract integration with ready-to-use types
• Type safety with alloy-primitives
• Efficient packing for on-chain storage
• Comprehensive testing with real-world scenarios

Re-exports

pub use hub::PathData;

pub use path::assert_no_netted_flow_mismatch;

pub use path::compute_netted_flow;

pub use path::expected_unwrapped_totals;

pub use path::expected_unwrapped_totals_at;

pub use path::get_wrapped_tokens_from_path;

pub use path::replace_wrapped_tokens;

pub use path::replace_wrapped_tokens_with_avatars;

pub use path::shrink_path_values;

pub use path::token_info_map_from_path;

pub use path::token_info_map_from_path_via_rpc;

pub use path::token_info_map_from_path_with_url;

pub use path::wrapped_totals_from_path;

Modules

hub

Circles Hub Contract Integration

path

Structs

FindPathParams

Path finding parameters for circlesV2_findPath.

FlowEdge

Standard Circles Hub FlowEdge struct matching the contract ABI

FlowMatrix

Stream

Standard Circles Hub Stream struct matching the contract ABI

redeemCall

Function with signature redeem(bytes32,bytes) and selector 0xf7ff7207.

redeemReturn

Container type for the return parameters of the redeem(bytes32,bytes) function.

Enums

PathfinderError

Errors that can occur during pathfinding and flow matrix operations.

Functions

create_flow_matrix

Create a flow matrix from a sequence of transfer steps.

encode_redeem_flow_matrix

encode_redeem_trusted_data

find_path

Find an optimal path between two addresses using an existing CirclesRpc client.

find_path_via_rpc

Find an optimal path between two addresses in the Circles network.

find_path_with_params

Find a path using structured parameters.

find_path_with_params_via_rpc

Find a path using structured parameters and an existing CirclesRpc client.

get_available_flow

Get the maximum available flow between two addresses from an RPC URL.

get_available_flow_via_rpc

Get the maximum available flow between two addresses

pack_coordinates

Pack coordinate values into a compact byte representation.

prepare_flow_for_contract

High-level helper that performs pathfinding and flow-matrix preparation from an RPC URL.

prepare_flow_for_contract_simple

Prepare flow for contract using individual parameters (legacy compatibility)

prepare_flow_for_contract_via_rpc

High-level function that combines pathfinding and matrix creation

prepare_flow_matrix_streams

Clone flow-matrix streams and optionally attach transaction data to the first stream.

transform_to_flow_vertices

Transform transfer steps into sorted vertices and coordinate mapping.