tycho_simulation/book/mod.rs
1//! Book feeds: a provider's complete set of priced pairs, republished whenever it changes.
2
3use std::{
4 collections::{hash_map::Entry, HashMap},
5 sync::Arc,
6};
7
8use chrono::{DateTime, Utc};
9use tracing::{debug, warn};
10use tycho_common::{
11 models::{token::Token, Chain},
12 simulation::protocol_sim::ProtocolSim,
13 Bytes,
14};
15
16use crate::{
17 protocol::models::ProtocolComponent,
18 snapshot_feed::{
19 errors::FeedError, SnapshotFeedEvent, SnapshotFeedOutcome, SnapshotFeedStream,
20 SnapshotFeedStreams, SnapshotFeedWatch,
21 },
22};
23
24pub mod all_pairs;
25pub(crate) mod component;
26pub use component::{decode_swap_directions, SWAP_DIRECTIONS_ATTRIBUTE};
27pub(crate) mod levels;
28pub use levels::{Levels, PriceLevel};
29pub mod quote_tokens;
30pub(crate) mod sim;
31pub(crate) mod tvl;
32pub(crate) mod wire;
33
34/// One pair's book: the component that identifies the pair and the ready-to-simulate state
35/// holding the provider's price levels for it.
36///
37/// The state is shared, so keeping one past the snapshot it came from costs a reference count;
38/// cloning a whole book copies the component.
39#[derive(Clone, Debug)]
40pub struct Book {
41 pub component: ProtocolComponent,
42 pub state: Arc<dyn ProtocolSim>,
43 /// When the provider last updated this book, on the provider's clock; `None` when the
44 /// provider reports none. The snapshot's [`ReceivedAt`] anchor is the feed's own.
45 pub updated_at: Option<DateTime<Utc>>,
46}
47
48/// The books a source has decoded out of one answer from its venue, each under the id of the
49/// component it carries.
50#[derive(Debug, Default, derive_more::Deref)]
51pub(crate) struct Books(HashMap<String, Book>);
52
53impl Books {
54 pub fn new() -> Self {
55 Books::default()
56 }
57
58 /// Keeps `book` under its own component's id.
59 ///
60 /// Two books claiming one component leaves the one added last, and says so: they price the
61 /// same pair differently, and which of them a consumer quotes is the order they arrived in.
62 pub fn insert(&mut self, book: Book) {
63 match self
64 .0
65 .entry(book.component.id.to_string())
66 {
67 Entry::Occupied(mut taken) => {
68 warn!(
69 component = %taken.key(),
70 "two books price one component, keeping the last"
71 );
72 taken.insert(book);
73 }
74 Entry::Vacant(free) => {
75 free.insert(book);
76 }
77 }
78 }
79
80 /// Returns the books as the map stored in a snapshot.
81 pub fn into_map(self) -> HashMap<String, Book> {
82 self.0
83 }
84}
85
86impl Extend<Book> for Books {
87 fn extend<I: IntoIterator<Item = Book>>(&mut self, books: I) {
88 for book in books {
89 self.insert(book);
90 }
91 }
92}
93
94/// One provider's complete set of books at one instant, so a pair absent from a snapshot is one
95/// the provider has stopped serving. The books are `Arc`'d so cloning the snapshot (e.g. out of a
96/// watch channel) never copies states.
97///
98/// This is the [`SnapshotFeed::Snapshot`](crate::snapshot_feed::SnapshotFeed) payload of every
99/// feed in this module, wrapped in an `Option` whose `None` means there is no servable snapshot:
100/// none received yet, or the last one withdrawn as stale (see `max_snapshot_age` on both feed
101/// configs).
102///
103/// `A` is what the snapshot is anchored to. Every feed in this module publishes
104/// `BookSnapshot<ReceivedAt>`; a feed whose snapshots belong to a block rather than to a moment
105/// publishes a block anchor instead, and the anchor type tells its consumers which.
106#[derive(Clone, Debug)]
107pub struct BookSnapshot<A> {
108 pub anchor: A,
109 pub books: Arc<HashMap<String, Book>>,
110}
111
112impl BookSnapshot<ReceivedAt> {
113 /// `books` as the complete set a feed received just now.
114 pub(crate) fn received_now(books: Books) -> Self {
115 BookSnapshot { anchor: ReceivedAt(Utc::now()), books: Arc::new(books.0) }
116 }
117}
118
119/// When the feed received a snapshot, on the feed's clock.
120#[derive(Clone, Copy, Debug, PartialEq, Eq)]
121pub struct ReceivedAt(pub DateTime<Utc>);
122
123/// What every book feed needs, whatever transport it runs on: the chain, the tokens it may serve
124/// pairs of, and the liquidity floor below which a book is not worth publishing. Every feed
125/// builder takes it by value as its first argument and stores it whole; build a second config to
126/// give one provider a different universe or floor. The token map is reference-counted, so
127/// cloning the config for several feeds shares one map.
128///
129/// The transport's own tuning is separate:
130/// [`snapshot_feed::ws::WsFeedConfig`](crate::snapshot_feed::ws::WsFeedConfig)
131/// and [`snapshot_feed::http::HttpFeedConfig`](crate::snapshot_feed::http::HttpFeedConfig).
132#[derive(Clone, derive_more::Debug)]
133pub struct BookFeedConfig {
134 pub chain: Chain,
135 /// The universe of tradable tokens with their metadata; pairs involving tokens missing here
136 /// are not served.
137 #[debug("{} tokens", tokens.len())]
138 pub tokens: Arc<HashMap<Bytes, Token>>,
139 /// Minimum book TVL in USD; 100 USD is a sensible floor for the supported providers.
140 pub min_tvl_usd: f64,
141}
142
143impl BookFeedConfig {
144 /// The two tokens of a pair, or `None` when either is outside the universe and the pair is
145 /// therefore not served.
146 pub(crate) fn pair_tokens(&self, a: &Bytes, b: &Bytes) -> Option<(&Token, &Token)> {
147 Some((self.tokens.get(a)?, self.tokens.get(b)?))
148 }
149
150 /// Whether a book with `tvl_usd` clears the floor; names the component it would be
151 /// published under in the log line when it does not.
152 pub(crate) fn clears_min_tvl(&self, tvl_usd: f64, component_id: &Bytes) -> bool {
153 let clears = tvl_usd >= self.min_tvl_usd;
154 if !clears {
155 debug!(
156 book = %component_id,
157 tvl_usd,
158 min_tvl_usd = self.min_tvl_usd,
159 "filtering out book below the TVL floor"
160 );
161 }
162 clears
163 }
164}
165
166/// Returns the numeric id used by venue APIs for `chain`, or a [`FeedError::Fatal`] naming the
167/// chain if it has no numeric id.
168pub(crate) fn chain_id(chain: Chain) -> Result<u64, FeedError> {
169 chain
170 .try_id()
171 .map_err(|error| FeedError::Fatal(format!("no chain id for {chain}: {error}")))
172}
173
174/// Several book feeds, merged — [`SnapshotFeedStreams`] with the types every book feed uses.
175///
176/// [`add`](SnapshotFeedStreams::add) each feed under the label you want its events to carry —
177/// usually as each one is built, since a provider without credentials or without support for the
178/// chain simply never joins the set — then read [`BookFeedEvent`]s until the set runs dry:
179///
180/// ```
181/// # use futures::StreamExt as _;
182/// # use tycho_simulation::book::{BookFeedEvent, BookFeedOutcome, BookFeedStreams};
183/// # async fn consume() {
184/// // Anchored like the snapshots it carries; `add` infers this from the feed.
185/// let mut feeds: BookFeedStreams = BookFeedStreams::new();
186///
187/// while let Some((provider, event)) = feeds.next().await {
188/// match event {
189/// BookFeedEvent::Published(snapshot) => { /* quote from `snapshot.books` */ }
190/// BookFeedEvent::Withdrawn => { /* stop quoting `provider` until it publishes again */ }
191/// // `provider` is out of the set now, whichever of the three ended it.
192/// BookFeedEvent::Ended(BookFeedOutcome::Failed(error)) => { /* it gave up */ }
193/// BookFeedEvent::Ended(outcome) => { /* ran out, or panicked */ }
194/// }
195/// }
196/// # }
197/// ```
198pub type BookFeedStreams<A = ReceivedAt> = SnapshotFeedStreams<BookSnapshot<A>, FeedError>;
199
200/// One book feed, read as a stream of [`BookFeedEvent`]s. See [`SnapshotFeedStream`].
201pub type BookFeedStream<A = ReceivedAt> = SnapshotFeedStream<BookSnapshot<A>, FeedError>;
202
203/// What happened on a book feed. See [`BookFeedStreams`].
204pub type BookFeedEvent<A = ReceivedAt> = SnapshotFeedEvent<BookSnapshot<A>, FeedError>;
205
206/// One book feed, held as the newest book set a consumer can read without awaiting — for one
207/// that prices on demand rather than reacting to every update, with
208/// [`ended`](SnapshotFeedWatch::ended) for why a venue stopped. See [`SnapshotFeedWatch`].
209pub type BookFeedWatch<A = ReceivedAt> = SnapshotFeedWatch<BookSnapshot<A>, FeedError>;
210
211/// How a book feed ended. See [`SnapshotFeedWatch::ended`].
212pub type BookFeedOutcome = SnapshotFeedOutcome<FeedError>;
213
214/// Builds the token map of a test [`BookFeedConfig`] from `(address, symbol, decimals)` entries.
215#[cfg(test)]
216pub(crate) fn test_token_map(entries: &[(&Bytes, &str, u32)]) -> HashMap<Bytes, Token> {
217 entries
218 .iter()
219 .map(|(address, symbol, decimals)| {
220 (
221 (*address).clone(),
222 Token::new(address, symbol, *decimals, 0, &[Some(10_000)], Chain::Ethereum, 100),
223 )
224 })
225 .collect()
226}
227
228/// A chain that resolves to no numeric chain id: a custom chain the registry does not know, which
229/// only deserialization can produce.
230#[cfg(test)]
231pub(crate) fn chain_without_id() -> Chain {
232 serde_json::from_str(r#"{"custom":"unregistered"}"#).unwrap()
233}
234
235/// Asserts that two book sets hold the same components under the same ids, with equal states and
236/// provider times.
237#[cfg(test)]
238pub(crate) fn assert_same_books(actual: &HashMap<String, Book>, expected: &HashMap<String, Book>) {
239 let mut actual_ids: Vec<_> = actual.keys().collect();
240 let mut expected_ids: Vec<_> = expected.keys().collect();
241 actual_ids.sort();
242 expected_ids.sort();
243 assert_eq!(actual_ids, expected_ids);
244 for (id, book) in actual {
245 let other = &expected[id];
246 assert_eq!(book.component, other.component, "{id}");
247 assert_eq!(book.updated_at, other.updated_at, "{id}");
248 assert!(book.state.eq(&*other.state), "{id}: states differ");
249 }
250}
251
252#[cfg(test)]
253mod tests {
254 use tycho_common::models::Chain;
255
256 use super::*;
257 use crate::{book::component::pair_component, evm::decoder::MockProtocolSim};
258
259 fn book(base: &Bytes, quote: &Bytes) -> Book {
260 let token =
261 |address: &Bytes| Token::new(address, "T", 18, 0, &[Some(0)], Chain::Ethereum, 100);
262 Book {
263 component: pair_component(
264 component::pair_component_id("book:venue", base, quote),
265 "book:venue",
266 "venue_pool",
267 Chain::Ethereum,
268 token(base),
269 token(quote),
270 ),
271 state: Arc::new(MockProtocolSim::new()),
272 updated_at: None,
273 }
274 }
275
276 /// Two answers for one pair are one book, whichever way round the venue sent them.
277 #[test]
278 fn a_book_is_kept_under_its_own_component() {
279 let weth = Bytes::from(vec![0x11; 20]);
280 let usdc = Bytes::from(vec![0x22; 20]);
281 let mut books = Books::new();
282
283 books.insert(book(&weth, &usdc));
284 books.insert(book(&usdc, &weth));
285 books.insert(book(&weth, &usdc));
286
287 assert_eq!(books.len(), 2);
288 let ids: Vec<_> = books.keys().cloned().collect();
289 assert!(
290 ids.contains(&component::pair_component_id("book:venue", &weth, &usdc).to_string()),
291 "{ids:?}"
292 );
293 }
294}