Crate circles_sdk 

Circles SDK orchestrating RPC, profile service access, pathfinding, transfers, and optional contract execution.

This crate mirrors the high-level TypeScript SDK shape while keeping the Rust implementation read-first: most reads work with Sdk::new(config, None), and write paths are gated behind a ContractRunner.

Quick Start

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

let sdk = Sdk::new(config::gnosis_mainnet(), None)?;
let avatar = address!("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
let info = sdk.avatar_info(avatar).await?;
println!("avatar type: {:?}", info.avatar_type);

let typed = sdk.get_avatar(avatar).await?;
match typed {
    circles_sdk::Avatar::Human(human) => {
        let balances = human.balances(false, true).await?;
        println!("balances: {}", balances.len());
    }
    circles_sdk::Avatar::Organisation(_) | circles_sdk::Avatar::Group(_) => {}
}

Usage Model

• Sdk wires together RPC, profile lookups, pathfinding, transfers, and contract bindings.
• Avatar gives you a typed wrapper after runtime avatar detection.
• ContractRunner is only required for write paths such as registrations, trust changes, and transfer submission.
• SafeContractRunner and EoaContractRunner are the built-in execution backends for existing single-owner Safe wallets and direct EOA execution, and now expose buffered batch, gas-estimation, and read-call helper surface on the runner itself.
• SafeExecutionBuilder is the browser/external-signature foundation for Safe-backed flows: it prepares the canonical Safe payload/hash without requiring a local private key.
• The optional ws feature enables WebSocket subscriptions with retry/backoff and HTTP catch-up helpers.

Recommended Entry Points

• config::gnosis_mainnet for the shared mainnet configuration.
• Sdk::avatar_info for a fast read-only probe.
• Sdk::get_avatar when you want a typed avatar wrapper.
• EoaContractRunner::connect and SafeContractRunner::connect when you want built-in execution backends for existing wallets.
• SafeExecutionBuilder::connect when you need the TS-style Safe transaction-preparation seam before an external/browser signer submits the transaction.
• HumanAvatar::plan_transfer, OrganisationAvatar::plan_transfer, and BaseGroupAvatar::plan_transfer for pathfinding-based transaction planning.
• HumanAvatar::plan_direct_transfer, OrganisationAvatar::plan_direct_transfer, and BaseGroupAvatar::plan_direct_transfer for TS-style direct-send planning.
• HumanAvatar::plan_group_token_redeem and OrganisationAvatar::plan_group_token_redeem for automatic group-token redeem planning.
• HumanAvatar::available_invitations, HumanAvatar::invitation_origin, HumanAvatar::proxy_inviters, and HumanAvatar::find_farm_invite_path for the current invitation/referral query surface.
• HumanAvatar::plan_invite and HumanAvatar::invite for TS-style direct invite planning/execution against existing Safe wallets.
• Sdk::referrals and HumanAvatar::list_referrals for the optional referrals backend.
• HumanAvatar::plan_referral_code and HumanAvatar::get_referral_code for the TS-style single-referral planner used by getReferralCode().
• HumanAvatar::plan_generate_referrals and HumanAvatar::generate_referrals for invitation-farm batch referral planning/execution.

Validation

• Unit tests: cargo test -p circles-sdk
• WS helpers: cargo test -p circles-sdk --features ws
• Live checks (ignored by default): RUN_LIVE=1 LIVE_AVATAR=0x... cargo test -p circles-sdk -- --ignored

Modules

config

registration

Registration helpers (human/org/base group).

Structs

BaseGroupAvatar

Top-level avatar enum variant: base group.

EoaContractRunner

EOA-backed contract runner using the same call-builder model as the Safe runner.

HumanAvatar

Top-level avatar enum variant: human.

OrganisationAvatar

Top-level avatar enum variant: organisation.

PreparedSafeExecution

Prepared Safe execution data for browser/external-signature workflows.

PreparedTransaction

Prepared transaction for a runner to submit. This is intentionally simple; we can swap to richer contract-specific types as we wire more flows.

Referral

Full private referral record from the authenticated backend view.

ReferralInfo

Referral info returned from the public retrieve endpoint.

ReferralList

Paginated authenticated referral list.

ReferralListMineOptions

Optional filters for authenticated my-referrals queries.

ReferralPreview

Public masked referral preview.

ReferralPreviewList

Paginated public referral preview list.

ReferralPublicListOptions

Optional filters for public list/{address} queries.

ReferralSession

Distribution-session metadata attached to private referrals.

ReferralStoreInput

One item in the batch store request body.

Referrals

Optional referrals backend client.

RegistrationResult

Generic registration outcome carrying submitted transactions and an optional avatar.

SafeContractRunner

Safe-backed contract runner using safe-rs.

SafeExecutionBuilder

Read-only Safe execution builder for browser/external signing workflows.

Sdk

Top-level SDK orchestrator.

StoreBatchError

Error entry returned from the batch store endpoint.

StoreBatchResult

Batch store result returned by the referrals backend.

SubmittedTx

Result stub for submitted transactions.

Enums

Avatar

Top-level avatar enum (human, organisation, group).

ReferralStatus

Referral status lifecycle exposed by the referrals backend.

ReferralSyncStatus

Cache freshness metadata for public preview queries.

ReferralsError

Errors surfaced by the optional referrals backend client.

RunnerError

Errors surfaced by the runner.

SdkError

High-level SDK errors.

Traits

BatchRun

Buffered batch helper mirroring the TypeScript BatchRun concept.

ContractRunner

Trait that allows the SDK to send transactions (e.g., via a Safe or EOA backend).

Functions

call_to_tx

Helper to turn a SolCall into a prepared transaction.