Crate circles_types

Crate circles_types 

Source
Expand description

§Circles Types

Complete type definitions for the Circles protocol ecosystem in Rust.

This crate provides comprehensive data structures for all aspects of the Circles protocol, including avatar management, trust relations, token operations, pathfinding, event handling, RPC communication, and contract interactions. All types support full serde serialization and are compatible with the TypeScript Circles SDK.

§Features

  • Complete Protocol Coverage: Types for avatars, trust, tokens, groups, events
  • Alloy Integration: Built on alloy-primitives for Ethereum compatibility
  • API Compatible: Matches TypeScript SDK structure exactly
  • Type Safety: Leverages Rust’s type system while maintaining flexibility
  • Async Ready: Traits for contract runners and batch operations
  • Query DSL: Complete query builder for circles_query RPC method

§Usage Examples

ⓘ
use circles_types::{
    // Core types
    Address, U256, TxHash,
    // Avatar and profile types
    AvatarInfo, Profile, AvatarType,
    // Pathfinding
    FindPathParams, PathfindingResult,
    // Trust relations
    TrustRelation, TrustRelationType,
    // Configuration
    CirclesConfig,
};

// Create avatar information
let avatar = AvatarInfo {
    block_number: 12345,
    timestamp: Some(1234567890),
    transaction_index: 1,
    log_index: 0,
    transaction_hash: "0xabc123...".parse()?,
    version: 2,
    avatar_type: AvatarType::CrcV2RegisterHuman,
    avatar: "0x123...".parse()?,
    token_id: Some(U256::from(1)),
    has_v1: false,
    v1_token: None,
    cid_v0_digest: None,
    cid_v0: None,
    v1_stopped: None,
    is_human: true,
    name: None,
    symbol: None,
};

// Create pathfinding parameters
let params = FindPathParams {
    from: "0xabc...".parse()?,
    to: "0xdef...".parse()?,
    target_flow: U256::from(1000u64),
    use_wrapped_balances: Some(true),
    from_tokens: None,
    to_tokens: None,
    exclude_from_tokens: None,
    exclude_to_tokens: None,
    simulated_balances: None,
    max_transfers: Some(10),
};

// Serialize to JSON
let json = serde_json::to_string(&avatar)?;

§Type Categories

§Core Blockchain Types

§Avatar & Profile Management

  • AvatarInfo - Complete avatar information and metadata
  • Profile - User profile with name, description, images
  • GroupProfile - Group profile extending Profile with symbol
  • AvatarType - Registration event types (Human, Group, Organization)

§Trust & Social Graph

§Token Operations

§Group Management

§Pathfinding & Transfers

§Event System

§RPC & Communication

§Query System

§Contract Execution

§Protocol Configuration

§Network State

  • NetworkSnapshot - Complete network state at a block
  • EventRow - Base structure for event pagination
  • Cursor - Pagination cursor for efficient queries

Structs§

Address
An Ethereum address, 20 bytes in length.
AdvancedTransferOptions
Advanced transfer options. Extends FindPathParams to add transfer-specific options.
AggregatedTrustRelation
Aggregated trust relation
AvatarInfo
Avatar information Contains basic information about a Circles avatar.
AvatarRow
Avatar row data from RPC
Bytes
Wrapper type around bytes::Bytes to support “0x” prefixed hex strings.
CirclesBaseEvent
Base event information shared by all Circles events.
CirclesConfig
Circles protocol configuration for a specific chain.
CirclesEvent
Generic Circles event with dynamic data parsed from HTTP/WS.
CirclesQuery
Circles query result with pagination Note: This is a trait-like interface in TypeScript, but we’ll use a struct with a callback
CirclesQueryResponse
Circles query response format Used for circles_query RPC method results
ColumnInfo
Column information for table metadata.
Conjunction
Conjunction for combining multiple predicates.
DecodedContractError
Decoded contract error information Contains parsed error data from failed contract transactions
EscrowedAmountAndDays
Escrowed Amount and Days Result Returned by InvitationEscrow.getEscrowedAmountAndDays()
EventRow
Defines the minimum columns any event row must have for cursor-based pagination. These values are important for determining cursor position in result sets.
FilterPredicate
Filter predicate for querying.
FindPathParams
Path finding parameters for circlesV2_findPath.
FlowEdge
Edge in the flow graph (sinkId 1 == final hop). This is the original version from lib.rs.
FlowEdgeStruct
Flow edge structure for operateFlowMatrix. Corresponds to TypeDefinitions.FlowEdge in Hub V2.
FlowMatrix
ABI-ready matrix returned by create_flow_matrix. This is the original version from lib.rs—different from PathfindingFlowMatrix.
GeoLocation
Geographic location coordinates
GroupMembershipRow
Group membership row
GroupProfile
Group profile with additional symbol field
GroupQueryParams
Group query parameters
GroupRow
Group row information
JsonRpcError
JSON-RPC error object
JsonRpcRequest
JSON-RPC request structure
JsonRpcResponse
JSON-RPC response structure
NetworkSnapshot
Network snapshot structure
OrderBy
Order by clause.
PagedQueryParams
Parameters for a paginated query
PagedResult
Result of a paginated query
PathfindingFlowMatrix
Flow matrix for ABI encoding, used with Hub V2 operateFlowMatrix. This is the pathfinding version; different from the contract-facing FlowMatrix.
PathfindingResult
Result of pathfinding computation.
PathfindingTransferStep
A single transfer step in a pathfinding result. This is the pathfinding version; different from the contract-facing TransferStep.
Profile
Profile information
QueryParams
Query parameters for circles_query.
QueryResponse
Generic query response wrapper Used for internal query transformations and type-safe responses
RpcSubscriptionEvent
Raw RPC subscription event (eth_subscribe("circles")) before parsing.
RunnerConfig
Configuration for contract runners
SafeQueryResponse
Better version of QueryResponse that’s more idiomatic
SimulatedBalance
Simulated balance for path finding.
Stream
Stream with byte data. This is the original version from lib.rs.
StreamStruct
Stream structure for operateFlowMatrix. Corresponds to TypeDefinitions.Stream in Hub V2.
TableInfo
Table information from circles_tables
TokenBalance
Token balance information
TokenBalanceResponse
Token balance response from circles_getTokenBalances
TokenBalanceRow
Token balance row from RPC
TokenHolder
Token holder information from V_CrcV2_BalancesByAccountAndToken
TokenInfo
Token information
TransactionRequest
Represents all transaction requests to/from RPC.
TransferStep
Transfer step for internal flow calculations. This is the original version from lib.rs—different from PathfindingTransferStep.
TrustRelation
Trust relation information
TrustRelationRow
Trust relation row from RPC
WrappedTokenInfo
Information about a wrapped token found in a transfer path Maps wrapper address to [amount used in path, wrapper type]

Enums§

AvatarType
Avatar type variants
Balance
Balance type that can be either raw U256 or formatted as TimeCircles floating point
CirclesEventType
All possible Circles event types (unknowns map to CrcUnknownEvent).
CirclesType
CirclesType enum Represents the type of Circles ERC20 wrapper
ConjunctionType
Conjunction types for combining predicates.
EventType
Event types for network events
Filter
Filter type (either a predicate or conjunction).
FilterType
Filter types for query predicates.
GroupType
Group type enumeration
SortOrder
Order direction for query results.
TrustRelationType
Trust relation type enumeration

Traits§

BatchRun
Batch transaction runner trait Allows multiple transactions to be batched and executed atomically
ContractRunner
Contract runner trait for executing blockchain operations This is the base trait that all contract runners must implement

Type Aliases§

BlockHash
A block hash.
Cursor
A cursor is a sortable unique identifier for a specific log entry. Used to paginate through query results efficiently.
TransportResult
A transport result is a Result containing a TransportError.
TxHash
A transaction hash is a keccak hash of an RLP encoded signed transaction.
U192
192-bit unsigned integer type, consisting of 3, 64-bit limbs.
U256
256-bit unsigned integer type, consisting of 4, 64-bit limbs.
WrappedTokensRecord
Record of wrapped tokens found in a transfer path Maps wrapper address to wrapped token information