{"id":50495599,"url":"https://github.com/deluXtreme/circles-rs","last_synced_at":"2026-06-19T00:00:53.215Z","repository":{"id":298113390,"uuid":"998902769","full_name":"deluXtreme/circles-rs","owner":"deluXtreme","description":"Rust SDK for Circles protocol","archived":false,"fork":false,"pushed_at":"2026-06-07T18:25:55.000Z","size":504,"stargazers_count":5,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T20:14:25.231Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://circles-rs-book.vercel.app/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deluXtreme.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-09T12:41:34.000Z","updated_at":"2026-06-07T18:25:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a8d7b17-933b-465f-b1e9-a5153acb3ec3","html_url":"https://github.com/deluXtreme/circles-rs","commit_stats":null,"previous_names":["deluxtreme/circles-rs"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/deluXtreme/circles-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deluXtreme%2Fcircles-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deluXtreme%2Fcircles-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deluXtreme%2Fcircles-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deluXtreme%2Fcircles-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deluXtreme","download_url":"https://codeload.github.com/deluXtreme/circles-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deluXtreme%2Fcircles-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34511617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T07:00:22.844Z","updated_at":"2026-06-19T00:00:53.209Z","avatar_url":"https://github.com/deluXtreme.png","language":"Rust","funding_links":[],"categories":["SDKs \u0026 Libraries"],"sub_categories":["Developer Demos"],"readme":"# Circles Rust Workspace\n\n\u003e **Alpha release:** The API surface is still in flux; expect breaking changes between releases.\n\nRust 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.\n\nThe 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.\n\n## Crates at a glance\n- [`circles-rpc`](crates/rpc/) — HTTP/WS JSON-RPC client with pagination helpers and event subscriptions.\n- [`circles-pathfinder`](crates/pathfinder/) — pathfinding + flow matrix utilities (wrapped token handling, netted-flow checks) ready for contract calls.\n- [`circles-transfers`](crates/transfers/) — builds ordered tx lists (approval → unwraps → operateFlowMatrix → inflationary re-wraps).\n- [`circles-utils`](crates/utils/) — demurrage/inflation converters and day-index helpers.\n- [`circles-types`](crates/types/) — shared types for RPC responses, events, pathfinding, contracts, and config.\n- [`circles-sdk`](crates/sdk/) — thin orchestrator wiring RPC, profiles, pathfinding, transfers, and optional contract runners; WS helpers with retry/catch-up.\n- [`crates/abis`](crates/abis/) — generated contract bindings.\n\n## TypeScript parity snapshot\n\nAs of April 1, 2026, this workspace is closer to the TypeScript SDK, but it is not yet at full feature parity.\n\n| Area | Status | Notes |\n| --- | --- | --- |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n\nThe 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.\n\n## Usage model\n\n- Read-only flows work with `Sdk::new(config, None)`.\n- Typed avatar wrappers are discovered at runtime via `Sdk::get_avatar`.\n- Write paths are delegated to a `ContractRunner` implementation instead of being hard-wired to one wallet transport.\n- Lower-level crates can be used directly when you want narrower control over RPC, pathfinding, or transfer assembly.\n\n## Quick start (read-only SDK)\n```rust\nuse circles_sdk::{config, Sdk};\nuse alloy_primitives::address;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let sdk = Sdk::new(config::gnosis_mainnet(), None)?; // runner None =\u003e read-only\n    let avatar = address!(\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\");\n    let info = sdk.avatar_info(avatar).await?;\n    println!(\"avatar type: {:?}\", info.avatar_type);\n    Ok(())\n}\n```\n\n## Docs\n\n- Generate docs with `cargo doc --workspace --all-features --no-deps`.\n- `crates/sdk/README.md` is the best starting point for application integration.\n- `AGENTS.md` contains contributor/agent guidance for parity work, validation, and safe live-test rules.\n- `docs/plans/` contains repo-local implementation plan indexes, including the current non-web TypeScript SDK parity roadmap.\n- `docs/parity-validation.md` describes the validation policy for TypeScript SDK parity work, golden fixtures, live-test gates, and write-path testing expectations.\n- Per-crate READMEs cover focused examples and feature notes.\n\n## Examples\n- RPC pagination + WS:  \n  `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`\n- Pathfinder contract integration:  \n  `cargo run -p circles-pathfinder --example contract_integration`\n- SDK examples: `cargo run -p circles-sdk --example basic_read` (see `crates/sdk/examples/` for invite generation and WS subscribe demos).\n\n## Validation\n\n- `cargo check`\n- `cargo clippy --workspace --all-targets`\n- `cargo test`\n- `cargo doc --workspace --all-features --no-deps`\n\nLive SDK checks remain opt-in:\n\n- `RUN_LIVE=1 LIVE_AVATAR=0x... cargo test -p circles-sdk -- --ignored`\n- Override endpoints with `CIRCLES_RPC_URL`, `CIRCLES_CHAIN_RPC_URL`, `CIRCLES_PATHFINDER_URL`, and `CIRCLES_PROFILE_URL`\n\n## Development\n- Rust 1.75+ and Cargo are required.\n- Alloy versions aligned at `1.1.2` (`alloy-sol-types` 1.4.1); keep workspace dependencies in sync when bumping.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdeluXtreme%2Fcircles-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FdeluXtreme%2Fcircles-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdeluXtreme%2Fcircles-rs/lists"}