circles_types/
pathfinding.rs

1use alloy_primitives::{aliases::U192, Address, Bytes, U256};
2use serde::{Deserialize, Serialize};
3
4/// Simulated balance for path finding.
5#[derive(Debug, Clone, Serialize, Deserialize)]
6pub struct SimulatedBalance {
7    pub holder: Address,
8    pub token: Address,
9    pub amount: U256,
10    pub is_wrapped: bool,
11    pub is_static: bool,
12}
13
14/// Path finding parameters for `circlesV2_findPath`.
15#[derive(Debug, Clone, Serialize, Deserialize)]
16pub struct FindPathParams {
17    #[serde(rename = "Source")]
18    pub from: Address,
19    #[serde(rename = "Sink")]
20    pub to: Address,
21    #[serde(rename = "TargetFlow")]
22    pub target_flow: U256,
23    #[serde(rename = "UseWrappedBalances")]
24    pub use_wrapped_balances: Option<bool>,
25    #[serde(rename = "FromTokens")]
26    pub from_tokens: Option<Vec<Address>>,
27    #[serde(rename = "ToTokens")]
28    pub to_tokens: Option<Vec<Address>>,
29    #[serde(rename = "ExcludeFromTokens")]
30    pub exclude_from_tokens: Option<Vec<Address>>,
31    #[serde(rename = "ExcludeToTokens")]
32    pub exclude_to_tokens: Option<Vec<Address>>,
33    #[serde(rename = "SimulatedBalances")]
34    pub simulated_balances: Option<Vec<SimulatedBalance>>,
35    #[serde(rename = "MaxTransfers")]
36    pub max_transfers: Option<u32>,
37}
38
39/// A single transfer step in a pathfinding result.
40/// This is the pathfinding version; different from the contract-facing `TransferStep`.
41#[derive(Debug, Clone, Serialize, Deserialize)]
42#[serde(rename_all = "camelCase")]
43pub struct PathfindingTransferStep {
44    pub from: Address,
45    pub to: Address,
46    pub token_owner: String, // TypeScript uses string, keeping it for API compatibility
47    pub value: U256,
48}
49
50/// Result of pathfinding computation.
51#[derive(Debug, Clone, Serialize, Deserialize)]
52#[serde(rename_all = "camelCase")]
53pub struct PathfindingResult {
54    pub max_flow: U256,
55    pub transfers: Vec<PathfindingTransferStep>,
56}
57
58/// Flow edge structure for `operateFlowMatrix`.
59/// Corresponds to `TypeDefinitions.FlowEdge` in Hub V2.
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct FlowEdgeStruct {
62    #[serde(rename = "streamSinkId")]
63    pub stream_sink_id: u16,
64    pub amount: U192, // uint192 in Solidity
65}
66
67/// Stream structure for `operateFlowMatrix`.
68/// Corresponds to `TypeDefinitions.Stream` in Hub V2.
69#[derive(Debug, Clone, Serialize, Deserialize)]
70pub struct StreamStruct {
71    #[serde(rename = "sourceCoordinate")]
72    pub source_coordinate: u16,
73    #[serde(rename = "flowEdgeIds")]
74    pub flow_edge_ids: Vec<u16>,
75    pub data: Bytes, // Handles both Uint8Array and Hex from TypeScript
76}
77
78/// Flow matrix for ABI encoding, used with Hub V2 `operateFlowMatrix`.
79/// This is the pathfinding version; different from the contract-facing `FlowMatrix`.
80#[derive(Debug, Clone, Serialize, Deserialize)]
81pub struct PathfindingFlowMatrix {
82    #[serde(rename = "flowVertices")]
83    pub flow_vertices: Vec<String>, // Keep as strings for API compatibility
84    #[serde(rename = "flowEdges")]
85    pub flow_edges: Vec<FlowEdgeStruct>,
86    pub streams: Vec<StreamStruct>,
87    #[serde(rename = "packedCoordinates")]
88    pub packed_coordinates: String, // Hex string
89    #[serde(rename = "sourceCoordinate")]
90    pub source_coordinate: u16, // Convenience field, not part of ABI
91}
92
93/// Advanced transfer options.
94/// Extends `FindPathParams` to add transfer-specific options.
95#[derive(Debug, Clone, Serialize, Deserialize)]
96pub struct AdvancedTransferOptions {
97    // All fields from FindPathParams except from, to, targetFlow
98    pub use_wrapped_balances: Option<bool>,
99    pub from_tokens: Option<Vec<Address>>,
100    pub to_tokens: Option<Vec<Address>>,
101    pub exclude_from_tokens: Option<Vec<Address>>,
102    pub exclude_to_tokens: Option<Vec<Address>>,
103    pub simulated_balances: Option<Vec<SimulatedBalance>>,
104    pub max_transfers: Option<u32>,
105
106    /// Custom data to attach to the transfer (optional)
107    pub tx_data: Option<Bytes>,
108}
109
110impl AdvancedTransferOptions {
111    /// Convert to `FindPathParams` with the required from/to/targetFlow fields.
112    pub fn to_find_path_params(
113        self,
114        from: Address,
115        to: Address,
116        target_flow: U256,
117    ) -> FindPathParams {
118        FindPathParams {
119            from,
120            to,
121            target_flow,
122            use_wrapped_balances: self.use_wrapped_balances,
123            from_tokens: self.from_tokens,
124            to_tokens: self.to_tokens,
125            exclude_from_tokens: self.exclude_from_tokens,
126            exclude_to_tokens: self.exclude_to_tokens,
127            simulated_balances: self.simulated_balances,
128            max_transfers: self.max_transfers,
129        }
130    }
131}
132
133// ============================================================================
134// Original Flow Types (moved from lib.rs)
135// ============================================================================
136
137/// Edge in the flow graph (sinkId 1 == final hop).
138/// This is the original version from lib.rs.
139#[derive(Clone, Debug, Serialize, Deserialize)]
140pub struct FlowEdge {
141    pub stream_sink_id: u16,
142    pub amount: U192,
143}
144
145/// Stream with byte data.
146/// This is the original version from lib.rs.
147#[derive(Clone, Debug, Serialize, Deserialize)]
148pub struct Stream {
149    pub source_coordinate: u16,
150    pub flow_edge_ids: Vec<u16>,
151    pub data: Vec<u8>,
152}
153
154/// Transfer step for internal flow calculations.
155/// This is the original version from lib.rs—different from `PathfindingTransferStep`.
156#[derive(Clone, Debug, Serialize, Deserialize)]
157pub struct TransferStep {
158    pub from_address: Address,
159    pub to_address: Address,
160    pub token_owner: Address,
161    pub value: U192,
162}
163
164/// ABI-ready matrix returned by `create_flow_matrix`.
165/// This is the original version from lib.rs—different from `PathfindingFlowMatrix`.
166#[derive(Clone, Debug)]
167pub struct FlowMatrix {
168    pub flow_vertices: Vec<Address>,
169    pub flow_edges: Vec<FlowEdge>,
170    pub streams: Vec<Stream>,
171    pub packed_coordinates: Vec<u8>,
172    pub source_coordinate: u16,
173}
circles_types/pathfinding.rs

circles_types/
pathfinding.rs
