circles_types/
lib.rs

1//! # Circles Types
2//!
3//! Core type definitions for the Circles protocol ecosystem.
4//!
5//! This crate provides fundamental data structures used throughout the Circles
6//! protocol implementation, including flow matrices, transfer steps, and address
7//! handling with full `serde` serialization support.
8//!
9//! ## Usage
10//!
11//! ```rust,ignore
12//! use circles_types::{TransferStep, FlowEdge, Stream};
13//! use alloy_primitives::U256;
14//!
15//! // Create a transfer step
16//! let transfer = TransferStep {
17//!     from_address: "0x123...".parse()?,
18//!     to_address: "0x456...".parse()?,
19//!     token_owner: "0x789...".parse()?,
20//!     value: U256::from(1000u64),
21//! };
22//!
23//! // Serialize to JSON
24//! let json = serde_json::to_string(&transfer)?;
25//! # Ok::<(), Box<dyn std::error::Error>>(())
26//! ```
27//!
28//! ## Core Types
29//!
30//! - [`TransferStep`] - Single transfer operation in a multi-hop path
31//! - [`FlowEdge`] - Directed edge in flow graph with routing info
32//! - [`Stream`] - Collection of edges representing a transfer route
33//! - [`FlowMatrix`] - Complete flow representation for contracts
34//! - [`Address`] - Ethereum address (re-exported from alloy-primitives)
35
36use alloy_primitives::U256;
37use serde::{Deserialize, Serialize};
38
39pub type Address = alloy_primitives::Address;
40
41/// Edge in the flow graph (sinkId 1 == final hop)
42#[derive(Clone, Debug, Serialize, Deserialize)]
43pub struct FlowEdge {
44    pub stream_sink_id: u16,
45    pub amount: U256,
46}
47
48#[derive(Clone, Debug, Serialize, Deserialize)]
49pub struct Stream {
50    pub source_coordinate: u16,
51    pub flow_edge_ids: Vec<u16>,
52    pub data: Vec<u8>,
53}
54
55#[derive(Clone, Debug, Serialize, Deserialize)]
56pub struct TransferStep {
57    pub from_address: Address,
58    pub to_address: Address,
59    pub token_owner: Address,
60    pub value: U256,
61}
62
63/// ABI-ready matrix returned by `create_flow_matrix`
64#[derive(Clone, Debug)]
65pub struct FlowMatrix {
66    pub flow_vertices: Vec<Address>,
67    pub flow_edges: Vec<FlowEdge>,
68    pub streams: Vec<Stream>,
69    pub packed_coordinates: Vec<u8>,
70    pub source_coordinate: u16,
71}
circles_types/lib.rs

circles_types/
lib.rs
