Skip to main content

tycho_simulation/
serde_helpers.rs

1/// serde functions for handling bytes as hex strings, such as `bytes::Bytes`
2pub mod hex_bytes {
3    use serde::{Deserialize, Deserializer, Serializer};
4
5    /// Serialize a byte vec as a hex string with 0x prefix
6    pub fn serialize<S, T>(x: T, s: S) -> Result<S::Ok, S::Error>
7    where
8        S: Serializer,
9        T: AsRef<[u8]>,
10    {
11        s.serialize_str(&format!("0x{encoded}", encoded = hex::encode(x.as_ref())))
12    }
13
14    /// Deserialize a hex string into a byte vec
15    /// Accepts a hex string with optional 0x prefix
16    pub fn deserialize<'de, T, D>(d: D) -> Result<T, D::Error>
17    where
18        D: Deserializer<'de>,
19        T: From<Vec<u8>>,
20    {
21        let value = String::deserialize(d)?;
22        if let Some(value) = value.strip_prefix("0x") {
23            hex::decode(value)
24        } else {
25            hex::decode(&value)
26        }
27        .map(Into::into)
28        .map_err(|e| serde::de::Error::custom(e.to_string()))
29    }
30}
31
32/// serde functions for handling Option of bytes
33pub mod hex_bytes_option {
34    use serde::{Deserialize, Deserializer, Serializer};
35
36    /// Serialize a byte vec as a Some hex string with 0x prefix
37    #[expect(clippy::ref_option, reason = "serde's serialize_with passes the field by reference")]
38    pub fn serialize<S, T>(x: &Option<T>, s: S) -> Result<S::Ok, S::Error>
39    where
40        S: Serializer,
41        T: AsRef<[u8]>,
42    {
43        if let Some(x) = x {
44            s.serialize_str(&format!("0x{encoded}", encoded = hex::encode(x.as_ref())))
45        } else {
46            s.serialize_none()
47        }
48    }
49
50    /// Deserialize a hex string into a byte vec or None
51    /// Accepts a hex string with optional 0x prefix
52    pub fn deserialize<'de, T, D>(d: D) -> Result<Option<T>, D::Error>
53    where
54        D: Deserializer<'de>,
55        T: From<Vec<u8>>,
56    {
57        let value: Option<String> = Option::deserialize(d)?;
58
59        match value {
60            Some(val) => {
61                let val = if let Some(stripped) = val.strip_prefix("0x") { stripped } else { &val };
62                hex::decode(val)
63                    .map(Into::into)
64                    .map(Some)
65                    .map_err(|e| serde::de::Error::custom(e.to_string()))
66            }
67            None => Ok(None),
68        }
69    }
70}
71
72/// Deserializes a hex string that must be a 20-byte EVM address into its bytes; any letter case
73/// is accepted, any other length rejected.
74#[cfg(feature = "book-feeds")]
75pub(crate) mod evm_address {
76    use alloy::primitives::Address;
77    use serde::{Deserialize, Deserializer};
78    use tycho_common::Bytes;
79
80    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Bytes, D::Error> {
81        Ok(Bytes::from(Address::deserialize(d)?.into_array()))
82    }
83}
84
85/// Serde helpers for `HashMap<String, Box<dyn ProtocolSim>>`.
86///
87/// Some `ProtocolSim` implementations (VM-backed states) return errors from
88/// their `Serialize` impl. This module provides a custom serializer that
89/// gracefully skips those entries instead of failing the entire map.
90pub mod protocol_states {
91    use std::collections::HashMap;
92
93    use serde::{ser::SerializeMap, Deserialize, Deserializer, Serializer};
94    use tracing::{debug, warn};
95    use tycho_common::simulation::protocol_sim::ProtocolSim;
96
97    /// Serializes a map of `ProtocolSim` trait objects, skipping entries
98    /// whose `Serialize` impl returns an error (e.g., VM-backed states).
99    pub fn serialize<S>(
100        states: &HashMap<String, Box<dyn ProtocolSim>>,
101        serializer: S,
102    ) -> Result<S::Ok, S::Error>
103    where
104        S: Serializer,
105    {
106        let mut map = serializer.serialize_map(None)?;
107        let mut skipped = 0u32;
108        for (key, value) in states {
109            match serde_json::to_value(value.as_ref()) {
110                Ok(json_val) => map.serialize_entry(key, &json_val)?,
111                Err(err) => {
112                    debug!(key, %err, "skipping non-serializable ProtocolSim entry");
113                    skipped += 1;
114                }
115            }
116        }
117        if skipped > 0 {
118            warn!(skipped, total = states.len(), "skipped non-serializable ProtocolSim entries");
119        }
120        map.end()
121    }
122
123    /// Deserializes back into the map. Non-serializable states are simply
124    /// absent from the data, so default deserialization works.
125    pub fn deserialize<'de, D>(
126        deserializer: D,
127    ) -> Result<HashMap<String, Box<dyn ProtocolSim>>, D::Error>
128    where
129        D: Deserializer<'de>,
130    {
131        HashMap::<String, Box<dyn ProtocolSim>>::deserialize(deserializer)
132    }
133}
134
135/// Macro to implement error-returning Serialize/Deserialize for protocols
136/// that cannot be serialized (e.g., due to VM state or external SDK dependencies).
137///
138/// # Examples
139/// ```ignore
140/// impl_non_serializable_protocol!(MyProtocolState, "error message");
141/// ```
142#[macro_export]
143macro_rules! impl_non_serializable_protocol {
144    ($type:ty, $msg:expr) => {
145        impl serde::Serialize for $type {
146            fn serialize<S>(&self, _serializer: S) -> Result<S::Ok, S::Error>
147            where
148                S: serde::Serializer,
149            {
150                Err(serde::ser::Error::custom($msg))
151            }
152        }
153
154        impl<'de> serde::Deserialize<'de> for $type {
155            fn deserialize<D>(_deserializer: D) -> Result<Self, D::Error>
156            where
157                D: serde::Deserializer<'de>,
158            {
159                Err(serde::de::Error::custom($msg))
160            }
161        }
162    };
163}
164
165#[cfg(test)]
166mod tests {
167    use std::{collections::HashMap, str::FromStr};
168
169    use serde::{Deserialize, Serialize};
170    use serde_json;
171    use tycho_common::{simulation::protocol_sim::ProtocolSim, Bytes};
172
173    use super::*;
174    use crate::protocol::models::Update;
175
176    #[derive(Debug, Serialize, Deserialize)]
177    struct TestStruct {
178        #[serde(with = "hex_bytes")]
179        bytes: Vec<u8>,
180
181        #[serde(with = "hex_bytes_option")]
182        bytes_option: Option<Vec<u8>>,
183    }
184
185    #[test]
186    fn hex_bytes_serialize_deserialize() {
187        let test_struct = TestStruct { bytes: vec![0u8; 10], bytes_option: Some(vec![0u8; 10]) };
188
189        // Serialize to JSON
190        let serialized = serde_json::to_string(&test_struct).unwrap();
191        assert_eq!(
192            serialized,
193            "{\"bytes\":\"0x00000000000000000000\",\"bytes_option\":\"0x00000000000000000000\"}"
194        );
195
196        // Deserialize from JSON
197        let deserialized: TestStruct = serde_json::from_str(&serialized).unwrap();
198        assert_eq!(deserialized.bytes, vec![0u8; 10]);
199        assert_eq!(deserialized.bytes_option, Some(vec![0u8; 10]));
200    }
201
202    #[test]
203    fn evm_address_accepts_any_case_and_rejects_other_lengths() {
204        #[derive(Deserialize)]
205        struct Holder(#[serde(deserialize_with = "evm_address::deserialize")] Bytes);
206
207        let lower = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
208        let mixed = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
209        let from_lower: Holder = serde_json::from_str(&format!("\"{lower}\"")).unwrap();
210        let from_mixed: Holder = serde_json::from_str(&format!("\"{mixed}\"")).unwrap();
211        assert_eq!(from_lower.0, from_mixed.0);
212        assert_eq!(from_lower.0, Bytes::from_str(lower).unwrap());
213
214        for not_an_address in ["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb", "0x", "a0b8"] {
215            assert!(serde_json::from_str::<Holder>(&format!("\"{not_an_address}\"")).is_err());
216        }
217    }
218
219    #[test]
220    fn hex_bytes_option_none() {
221        let test_struct = TestStruct { bytes: vec![0u8; 10], bytes_option: None };
222
223        // Serialize to JSON
224        let serialized = serde_json::to_string(&test_struct).unwrap();
225        assert_eq!(serialized, "{\"bytes\":\"0x00000000000000000000\",\"bytes_option\":null}");
226
227        // Deserialize from JSON
228        let deserialized: TestStruct = serde_json::from_str(&serialized).unwrap();
229        assert_eq!(deserialized.bytes, vec![0u8; 10]);
230        assert_eq!(deserialized.bytes_option, None);
231    }
232
233    #[cfg(feature = "evm")]
234    #[test]
235    fn update_roundtrip_with_serializable_state() {
236        use alloy::primitives::U256;
237
238        use crate::evm::protocol::uniswap_v2::state::UniswapV2State;
239
240        let mut states: HashMap<String, Box<dyn ProtocolSim>> = HashMap::new();
241        states.insert(
242            "pool_a".to_string(),
243            Box::new(UniswapV2State::new(U256::from(1000), U256::from(2000))),
244        );
245
246        let update = Update::new(12345, states, HashMap::new());
247        let json = serde_json::to_string(&update).unwrap();
248
249        assert!(json.contains("pool_a"));
250
251        let roundtripped: Update = serde_json::from_str(&json).unwrap();
252        assert_eq!(roundtripped.block_number, 12345);
253        assert_eq!(roundtripped.states.len(), 1);
254        assert!(roundtripped
255            .states
256            .contains_key("pool_a"));
257    }
258
259    #[cfg(feature = "evm")]
260    #[test]
261    fn protocol_states_skips_non_serializable_entries() {
262        use alloy::primitives::U256;
263
264        use crate::evm::{decoder::MockProtocolSim, protocol::uniswap_v2::state::UniswapV2State};
265
266        let mut states: HashMap<String, Box<dyn ProtocolSim>> = HashMap::new();
267        states.insert(
268            "serializable".to_string(),
269            Box::new(UniswapV2State::new(U256::from(1000), U256::from(2000))),
270        );
271        states.insert("non_serializable".to_string(), Box::new(MockProtocolSim::new()));
272
273        let update = Update::new(42, states, HashMap::new());
274        let json = serde_json::to_string(&update).expect("serialization should succeed");
275        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
276
277        let states_map = parsed["states"]
278            .as_object()
279            .expect("states is a map");
280        assert_eq!(states_map.len(), 1, "only the serializable entry should survive");
281        assert!(states_map.contains_key("serializable"));
282        assert!(!states_map.contains_key("non_serializable"));
283    }
284
285    #[cfg(feature = "evm")]
286    #[test]
287    fn protocol_states_serialize_produces_valid_json() {
288        use alloy::primitives::U256;
289
290        use crate::evm::protocol::uniswap_v2::state::UniswapV2State;
291
292        let mut states: HashMap<String, Box<dyn ProtocolSim>> = HashMap::new();
293        states.insert(
294            "pool_x".to_string(),
295            Box::new(UniswapV2State::new(U256::from(100), U256::from(200))),
296        );
297        states.insert(
298            "pool_y".to_string(),
299            Box::new(UniswapV2State::new(U256::from(300), U256::from(400))),
300        );
301
302        #[derive(Serialize)]
303        struct Wrapper {
304            #[serde(with = "protocol_states")]
305            states: HashMap<String, Box<dyn ProtocolSim>>,
306        }
307
308        let wrapper = Wrapper { states };
309        let json = serde_json::to_value(&wrapper).unwrap();
310        let map = json["states"].as_object().unwrap();
311        assert_eq!(map.len(), 2);
312        assert!(map.contains_key("pool_x"));
313        assert!(map.contains_key("pool_y"));
314    }
315
316    #[test]
317    fn update_roundtrip_empty() {
318        let update = Update::new(99999, HashMap::new(), HashMap::new());
319        let json = serde_json::to_string(&update).unwrap();
320        let roundtripped: Update = serde_json::from_str(&json).unwrap();
321        assert_eq!(roundtripped.block_number, 99999);
322        assert!(roundtripped.states.is_empty());
323        assert!(roundtripped.new_pairs.is_empty());
324    }
325}