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