Skip to main content

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