Circles Rust Workspace

Alpha release: The API surface is still in flux; expect breaking changes between releases.

Rust implementation of the Circles SDK: JSON-RPC client, pathfinding/flow matrix tooling, transfer planning, utilities, and a higher-level circles-sdk orchestrator. The workspace mirrors the TypeScript SDK shape while leaning on Alloy for Ethereum primitives and transports.

The recommended entrypoint for application code is circles-sdk. Lower-level crates remain available when you want direct RPC access, custom pathfinding, or transfer planning without the full orchestrator.

Crates at a glance

• circles-rpc — HTTP/WS JSON-RPC client with pagination helpers and event subscriptions.
• circles-pathfinder — pathfinding + flow matrix utilities (wrapped token handling, netted-flow checks) ready for contract calls.
• circles-transfers — builds ordered tx lists (approval → unwraps → operateFlowMatrix → inflationary re-wraps).
• circles-utils — demurrage/inflation converters and day-index helpers.
• circles-types — shared types for RPC responses, events, pathfinding, contracts, and config.
• circles-sdk — thin orchestrator wiring RPC, profiles, pathfinding, transfers, and optional contract runners; WS helpers with retry/catch-up.
• crates/abis — generated contract bindings.

TypeScript parity snapshot

As of April 1, 2026, this workspace is closer to the TypeScript SDK, but it is not yet at full feature parity.

Area	Status	Notes
circles-rpc	Good coverage	Core HTTP/query/event decoding is in place, including the native cursor-based transaction-history / group-browse / group-membership / token-holder endpoints now used by the TS SDK, the flexible query-backed cursor/order pagination still used for richer group-holder views, invitation-origin / per-source / combined-invitation / inviter-outbound invitation helpers, and the consolidated SDK-facing RPC methods for profile views, trust-network summaries, enriched aggregated trust, valid inviter discovery, enriched transaction history, and address-or-name profile search backed by the current Nethermind RPC surface.
circles-pathfinder	Close	Recent parity work aligned flow-matrix terminal edges, wrapped-token rewriting, token-info helpers, netted-flow helpers, and explicit RPC/client entrypoints.
circles-transfers	Close	Advanced transfer planning, aggregate transfers, the TS-style constructReplenish flow, and the automatic group-token redeem planner are present; remaining work is mostly higher-level parity polish and broader behavioral coverage.
circles-sdk	Partial, improving	Read flows and typed avatars are usable, replenish planning/execution rides the runner abstraction, the crate now ships built-in EOA and single-owner Safe runners for real write execution plus runner-level batch/gas-estimation/read-call helpers, direct create / send_transaction / send_batch_transaction method aliases on the concrete runners, and now also exposes SafeExecutionBuilder for canonical Safe payload/hash preparation ahead of browser or other external signing. The convenience surface covers a dedicated TS-style data facade for basic avatar/trust/balance/invitation reads on top of the existing flat data_* helpers, aggregated trust helpers, consolidated profile-view / trust-summary / enriched trust / valid-inviter / enriched-transaction / unified profile-search reads, native cursor-based transaction-history / group-browse / group-membership / token-holder reads, a dedicated TS-style tokens facade for wrapper lookups and holder pagination on top of the existing flat token helpers, top-level token-holder plus inflationary/demurraged wrapper helpers, derived profile-service URL handling, chain-RPC override support for direct contract calls, direct-transfer planning/execution, plan-first ERC20 wrapper wrap/unwrap helpers, profile metadata / short-name writes, personal minting, max-replenish helpers, base-group read/write helpers, human group-membership detail helpers, top-level group member/collateral/holder reads, group-token mint/redeem/property helpers, a dedicated TS-style register facade that now mirrors sdk.register.asHuman/asOrganization/asGroup with profile-or-CID input on top of the existing Rust registration helpers, invitation origin / per-source / inbound / outbound invitation queries, invitation fee/module/quota helpers, proxy-inviter discovery, invite-path lookup, farm-path lookup, deterministic referral-address computation, plan/execute direct invite, single-referral getReferralCode planning, plan/execute batch referral generation, a dedicated TS-style Invitations facade for inviter-setup/path/referral payload helpers, a dedicated TS-style InviteFarm facade for quota/fee/module reads plus batch referral and existing-account invite planning, and the optional referrals backend client surface including inviter-side public referral listing, SDK-scoped auth-token/provider configuration for TS-style my-referrals access, and distribution-session management/dispense helpers; the remaining invitation work is now follow-up polish rather than missing core planner or service surface.
circles-profiles, circles-utils, circles-types, circles-abis	Supporting / lower risk	These crates are in service for the current SDK flows and are not the main parity bottlenecks right now.

The biggest remaining parity work is no longer the replenish planner, group convenience, invitation-query foundation, the core invitation/referral planners, the consolidated SDK-enablement RPC surface, the latest cursor-native read/config alignment follow-up, the per-source invitation helper follow-up from the latest TS/RPC updates, or the SDK-level data/registration/tokens/invitations/invite-farm facade surface. The open gaps are the remaining service/auth polish around referrals plus the broader wallet/backend surface beyond the current EOA and single-owner Safe runners. Browser-backed Safe preparation is now in place, but actual browser-provider signing/submission is still a follow-up.

Usage model

• Read-only flows work with Sdk::new(config, None).
• Typed avatar wrappers are discovered at runtime via Sdk::get_avatar.
• Write paths are delegated to a ContractRunner implementation instead of being hard-wired to one wallet transport.
• Lower-level crates can be used directly when you want narrower control over RPC, pathfinding, or transfer assembly.

Quick start (read-only SDK)

use circles_sdk::{config, Sdk};
use alloy_primitives::address;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sdk = Sdk::new(config::gnosis_mainnet(), None)?; // runner None => read-only
    let avatar = address!("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
    let info = sdk.avatar_info(avatar).await?;
    println!("avatar type: {:?}", info.avatar_type);
    Ok(())
}

Docs

• Generate docs with cargo doc --workspace --all-features --no-deps.
• crates/sdk/README.md is the best starting point for application integration.
• AGENTS.md contains contributor/agent guidance for parity work, validation, and safe live-test rules.
• docs/plans/ contains repo-local implementation plan indexes, including the current non-web TypeScript SDK parity roadmap.
• docs/parity-validation.md describes the validation policy for TypeScript SDK parity work, golden fixtures, live-test gates, and write-path testing expectations.
• Per-crate READMEs cover focused examples and feature notes.

Examples

• RPC pagination + WS:
  CIRCLES_RPC_URL=https://rpc.aboutcircles.com/ CIRCLES_RPC_WS_URL=wss://rpc.aboutcircles.com/ws cargo run -p circles-rpc --example paged_and_ws --features ws
• Pathfinder contract integration:
  cargo run -p circles-pathfinder --example contract_integration
• SDK examples: cargo run -p circles-sdk --example basic_read (see crates/sdk/examples/ for invite generation and WS subscribe demos).

Validation

• cargo check
• cargo clippy --workspace --all-targets
• cargo test
• cargo doc --workspace --all-features --no-deps

Live SDK checks remain opt-in:

• RUN_LIVE=1 LIVE_AVATAR=0x... cargo test -p circles-sdk -- --ignored
• Override endpoints with CIRCLES_RPC_URL, CIRCLES_CHAIN_RPC_URL, CIRCLES_PATHFINDER_URL, and CIRCLES_PROFILE_URL

Development

• Rust 1.75+ and Cargo are required.
• Alloy versions aligned at 1.1.2 (alloy-sol-types 1.4.1); keep workspace dependencies in sync when bumping.