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}