https://github.com/deluXtreme/circles-rs
Rust SDK for Circles protocol
https://github.com/deluXtreme/circles-rs
Last synced: about 1 month ago
JSON representation
Rust SDK for Circles protocol
- Host: GitHub
- URL: https://github.com/deluXtreme/circles-rs
- Owner: deluXtreme
- Created: 2025-06-09T12:41:34.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-06-07T18:25:55.000Z (about 2 months ago)
- Last Synced: 2026-06-07T20:14:25.231Z (about 2 months ago)
- Language: Rust
- Homepage: https://circles-rs-book.vercel.app/
- Size: 492 KB
- Stars: 5
- Watchers: 0
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- awesome-circles - circles-rs - Rust workspace mirroring the TS SDK: RPC client, pathfinder, flow-matrix, transfer planning, and a higher-level `circles-sdk` crate. (SDKs & Libraries / Developer Demos)
README
# 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`](crates/rpc/) — HTTP/WS JSON-RPC client with pagination helpers and event subscriptions.
- [`circles-pathfinder`](crates/pathfinder/) — pathfinding + flow matrix utilities (wrapped token handling, netted-flow checks) ready for contract calls.
- [`circles-transfers`](crates/transfers/) — builds ordered tx lists (approval → unwraps → operateFlowMatrix → inflationary re-wraps).
- [`circles-utils`](crates/utils/) — demurrage/inflation converters and day-index helpers.
- [`circles-types`](crates/types/) — shared types for RPC responses, events, pathfinding, contracts, and config.
- [`circles-sdk`](crates/sdk/) — thin orchestrator wiring RPC, profiles, pathfinding, transfers, and optional contract runners; WS helpers with retry/catch-up.
- [`crates/abis`](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, 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)
```rust
use circles_sdk::{config, Sdk};
use alloy_primitives::address;
#[tokio::main]
async fn main() -> Result<(), Box> {
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.