use std::{collections::BTreeMap, time::Duration};
use async_stream::stream;
use futures::{Stream, StreamExt};
use serde::{
de::{DeserializeOwned, IgnoredAny},
Deserialize, Deserializer,
};
use serde_json::value::RawValue;
use tokio::time::{sleep, timeout, timeout_at, Instant};
use tokio_tungstenite::{connect_async, tungstenite::Message};
use tracing::{info, warn};
use tycho_common::Bytes;
use super::{
overrides::{AccountOverride, PammSimulationOverrides},
telemetry::{self, ReconnectReason, RejectReason},
SLOT,
};
pub(super) const TITAN_PRICE_LEVEL_URL: &str =
"wss://eu.data.titanbuilder.xyz/ws/pamm_price_levels_v2";
pub(super) const TITAN_PRICE_LEVEL_URL_ENV: &str = "TITAN_PAMM_PRICE_LEVEL_URL";
pub(super) const TITAN_QUOTE_STREAM_URL: &str =
"wss://eu.data.titanbuilder.xyz/ws/pamm_quote_stream_v2";
pub(super) const TITAN_QUOTE_STREAM_URL_ENV: &str = "TITAN_PAMM_QUOTE_STREAM_URL";
const BEACON_GENESIS: u64 = 1_606_824_023;
const ADDRESS_BYTES: usize = 20;
const WORD_BYTES: usize = 32;
const MAX_ACCOUNTS: usize = 32;
const MAX_SLOTS: usize = 512;
#[derive(Clone, Copy, Debug)]
pub(super) struct ConnectionSettings {
pub connect_timeout: Duration,
pub read_idle_timeout: Duration,
pub max_backoff: Duration,
}
impl Default for ConnectionSettings {
fn default() -> Self {
Self {
connect_timeout: Duration::from_secs(10),
read_idle_timeout: Duration::from_secs(10),
max_backoff: Duration::from_secs(32),
}
}
}
fn backoff(attempt: u32, max_backoff: Duration) -> Duration {
2u64.checked_pow(attempt)
.map_or(Duration::MAX, Duration::from_secs)
.min(max_backoff)
}
fn deadline_after(idle_timeout: Duration) -> Instant {
Instant::now() + idle_timeout.min(Duration::from_secs(u32::MAX.into()))
}
pub(super) trait TitanMessage: DeserializeOwned + Send {
const SOCKET: &'static str;
}
#[derive(Debug, Deserialize)]
pub(super) struct TitanPriceLevelMessage {
pub block: u64,
pub slot: Option<u64>,
pub ts: u64,
pub books: Vec<TitanBook>,
}
impl TitanMessage for TitanPriceLevelMessage {
const SOCKET: &'static str = "price_levels";
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub(super) enum QuoteSequence {
#[default]
Absent,
Valid(u128),
Unreadable,
}
fn lenient_sequence<'de, D>(deserializer: D) -> Result<QuoteSequence, D::Error>
where
D: Deserializer<'de>,
{
let raw = Box::<RawValue>::deserialize(deserializer)?;
let text = raw.get();
if text.trim() == "null" {
return Ok(QuoteSequence::Absent);
}
Ok(serde_json::from_str::<u128>(text).map_or(QuoteSequence::Unreadable, QuoteSequence::Valid))
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(super) struct TitanBook {
#[cfg_attr(
not(test),
expect(
dead_code,
reason = "a display label, deliberately not part of any identity the stream records"
)
)]
pub maker: Option<String>,
pub quote_address: Bytes,
pub token1: String,
pub token2: String,
pub token1_address: Bytes,
pub token2_address: Bytes,
#[serde(rename = "calculated_from", default, deserialize_with = "lenient_sequence")]
pub calculated_from: QuoteSequence,
pub asks: Vec<TitanLevel>,
pub bids: Vec<TitanLevel>,
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(super) struct TitanLevel {
pub price: f64,
pub cum_volume: f64,
}
#[derive(Debug, Deserialize)]
pub(super) struct TitanQuoteStreamMessage {
pub venues: Vec<Box<RawValue>>,
}
impl TitanMessage for TitanQuoteStreamMessage {
const SOCKET: &'static str = "quote_stream";
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(super) struct TitanVenueOverride {
pub quote_address: Bytes,
#[serde(default)]
pub priced_addresses: Vec<Bytes>,
pub block_number: Option<u64>,
pub slot: Option<u64>,
pub timestamp: Option<u64>,
#[serde(default)]
pub asset_pairs: Vec<TitanAssetPair>,
#[serde(default)]
pub pair_sequences: Vec<u128>,
#[serde(default)]
pub state_override: BTreeMap<Bytes, TitanAccountOverride>,
}
#[derive(Debug, Deserialize)]
pub(super) struct TitanAssetPair {
pub token_1: Bytes,
pub token_2: Bytes,
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(super) struct TitanAccountOverride {
pub balance: Option<String>,
pub nonce: Option<String>,
#[serde(default)]
pub state_diff: BTreeMap<Bytes, Bytes>,
pub code: Option<IgnoredAny>,
pub state: Option<IgnoredAny>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct VenueOverrides {
pub quote_address: Bytes,
pub priced_addresses: Vec<Bytes>,
pub pairs: Vec<PairSequence>,
pub slot: Option<u64>,
pub overrides: PammSimulationOverrides,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct PairSequence {
pub token_1: Bytes,
pub token_2: Bytes,
pub sequence: u128,
}
#[derive(
Debug, Clone, Copy, PartialEq, Eq, strum_macros::IntoStaticStr, strum_macros::EnumIter,
)]
#[strum(serialize_all = "snake_case")]
pub(super) enum EntryRejection {
Undecodable,
NotAVenue,
NotAnAccount,
MalformedPair,
MalformedStorage,
MalformedQuantity,
NoTimestamp,
PairsAndSequencesDiffer,
Empty,
UnsupportedOverride,
OverCap,
}
pub(super) fn validate(
message: TitanQuoteStreamMessage,
) -> Vec<Result<VenueOverrides, EntryRejection>> {
message
.venues
.into_iter()
.map(|raw| {
serde_json::from_str::<TitanVenueOverride>(raw.get())
.map_err(|e| {
warn!(error = %e, "Titan venue entry does not decode");
EntryRejection::Undecodable
})
.and_then(validated)
})
.collect()
}
fn validated(entry: TitanVenueOverride) -> Result<VenueOverrides, EntryRejection> {
if entry.quote_address.len() != ADDRESS_BYTES ||
entry
.priced_addresses
.iter()
.any(|address| address.len() != ADDRESS_BYTES)
{
return Err(EntryRejection::NotAVenue);
}
let Some(built_at_ns) = entry.timestamp else {
return Err(EntryRejection::NoTimestamp);
};
if entry.asset_pairs.len() != entry.pair_sequences.len() {
return Err(EntryRejection::PairsAndSequencesDiffer);
}
if entry.asset_pairs.is_empty() || entry.state_override.is_empty() {
return Err(EntryRejection::Empty);
}
ensure_within_caps(&entry.state_override)?;
Ok(VenueOverrides {
quote_address: entry.quote_address,
priced_addresses: entry.priced_addresses,
pairs: pair_sequences(entry.asset_pairs, &entry.pair_sequences)?,
slot: entry.slot,
overrides: PammSimulationOverrides {
accounts: validated_accounts(entry.state_override)?,
block_number: entry.block_number,
block_timestamp: block_timestamp(entry.slot),
built_at_ns,
},
})
}
fn ensure_within_caps(
accounts: &BTreeMap<Bytes, TitanAccountOverride>,
) -> Result<(), EntryRejection> {
if accounts.len() > MAX_ACCOUNTS {
return Err(EntryRejection::OverCap);
}
let mut slots: usize = 0;
for account in accounts.values() {
slots = slots.saturating_add(account.state_diff.len());
}
if slots > MAX_SLOTS {
return Err(EntryRejection::OverCap);
}
Ok(())
}
fn pair_sequences(
pairs: Vec<TitanAssetPair>,
sequences: &[u128],
) -> Result<Vec<PairSequence>, EntryRejection> {
let mut paired = Vec::with_capacity(pairs.len());
for (pair, sequence) in pairs.into_iter().zip(sequences) {
if pair.token_1.len() != ADDRESS_BYTES || pair.token_2.len() != ADDRESS_BYTES {
return Err(EntryRejection::MalformedPair);
}
paired.push(PairSequence {
token_1: pair.token_1,
token_2: pair.token_2,
sequence: *sequence,
});
}
Ok(paired)
}
fn validated_accounts(
streamed: BTreeMap<Bytes, TitanAccountOverride>,
) -> Result<BTreeMap<Bytes, AccountOverride>, EntryRejection> {
let mut accounts = BTreeMap::new();
for (address, account) in streamed {
if address.len() != ADDRESS_BYTES {
return Err(EntryRejection::NotAnAccount);
}
accounts.insert(address, account_override(account)?);
}
Ok(accounts)
}
fn account_override(account: TitanAccountOverride) -> Result<AccountOverride, EntryRejection> {
if account.code.is_some() || account.state.is_some() {
return Err(EntryRejection::UnsupportedOverride);
}
let balance = match account.balance.as_deref() {
Some(quantity) => Some(quantity_bytes(quantity).ok_or(EntryRejection::MalformedQuantity)?),
None => None,
};
let nonce = match account.nonce.as_deref() {
Some(quantity) => Some(quantity_u64(quantity).ok_or(EntryRejection::MalformedQuantity)?),
None => None,
};
for (slot, word) in &account.state_diff {
if slot.len() != WORD_BYTES || word.len() != WORD_BYTES {
return Err(EntryRejection::MalformedStorage);
}
}
Ok(AccountOverride { balance, nonce, state_diff: account.state_diff })
}
fn quantity_digits(quantity: &str) -> Option<&str> {
let digits = quantity.strip_prefix("0x")?;
let readable = !digits.is_empty() &&
digits
.bytes()
.all(|digit| digit.is_ascii_hexdigit());
readable.then_some(digits)
}
fn quantity_bytes(quantity: &str) -> Option<Bytes> {
let digits = quantity_digits(quantity)?;
if digits.len() > 2 * WORD_BYTES {
return None;
}
let bytes =
if digits.len() % 2 == 0 { hex::decode(digits) } else { hex::decode(format!("0{digits}")) };
bytes.ok().map(Bytes::from)
}
fn quantity_u64(quantity: &str) -> Option<u64> {
u64::from_str_radix(quantity_digits(quantity)?, 16).ok()
}
fn block_timestamp(slot: Option<u64>) -> Option<u64> {
slot?
.checked_mul(SLOT.as_secs())?
.checked_add(BEACON_GENESIS)
}
pub(super) fn messages<T: TitanMessage>(
url: String,
settings: ConnectionSettings,
) -> impl Stream<Item = T> + Send {
stream! {
let mut attempt: u32 = 0;
loop {
match timeout(settings.connect_timeout, connect_async(url.as_str())).await {
Ok(Ok((mut ws_stream, _))) => {
info!(%url, socket = T::SOCKET, "Connected to Titan pAMM stream");
let mut idle_deadline = deadline_after(settings.read_idle_timeout);
loop {
let message = match timeout_at(idle_deadline, ws_stream.next()).await {
Ok(Some(message)) => message,
Ok(None) => {
warn!(socket = T::SOCKET, "Titan stream ended; reconnecting");
telemetry::record_reconnect(T::SOCKET, ReconnectReason::Ended);
break;
}
Err(_elapsed) => {
warn!(
socket = T::SOCKET,
idle_secs = settings.read_idle_timeout.as_secs(),
"No parsed Titan message within idle timeout; reconnecting"
);
let reason = ReconnectReason::IdleTimeout;
telemetry::record_reconnect(T::SOCKET, reason);
break;
}
};
match message {
Ok(Message::Text(text)) => {
match serde_json::from_str::<T>(text.as_str())
{
Ok(message) => {
attempt = 0;
yield message;
idle_deadline = deadline_after(settings.read_idle_timeout);
}
Err(e) => {
warn!(
socket = T::SOCKET,
error = %e,
"Failed to parse Titan message"
);
telemetry::record_frame_rejected(
T::SOCKET,
RejectReason::ParseError,
);
}
}
}
Ok(Message::Binary(bytes)) => {
warn!(
socket = T::SOCKET,
len = bytes.len(),
"Ignoring unexpected binary Titan message"
);
}
Ok(Message::Ping(_)) | Ok(Message::Pong(_)) => {}
Ok(Message::Frame(_)) => {}
Ok(Message::Close(frame)) => {
warn!(
socket = T::SOCKET,
?frame,
"Titan stream closed by server; reconnecting"
);
telemetry::record_reconnect(T::SOCKET, ReconnectReason::Closed);
break;
}
Err(e) => {
warn!(
socket = T::SOCKET,
error = %e,
"Titan stream read error; reconnecting"
);
telemetry::record_reconnect(T::SOCKET, ReconnectReason::ReadError);
break;
}
}
}
}
Ok(Err(e)) => {
warn!(
socket = T::SOCKET,
error = %e,
"Failed to connect to Titan stream; retrying"
);
telemetry::record_reconnect(T::SOCKET, ReconnectReason::ConnectFailed);
}
Err(_elapsed) => {
warn!(
socket = T::SOCKET,
timeout_secs = settings.connect_timeout.as_secs(),
"Titan connect timed out; retrying"
);
telemetry::record_reconnect(T::SOCKET, ReconnectReason::ConnectTimeout);
}
}
attempt = attempt.saturating_add(1);
let backoff = backoff(attempt, settings.max_backoff);
warn!(
socket = T::SOCKET,
seconds = backoff.as_secs(),
attempt,
"Backing off before reconnecting to Titan"
);
sleep(backoff).await;
}
}
}
#[cfg(test)]
mod tests {
use std::{collections::HashSet, str::FromStr, sync::atomic::Ordering};
use futures::SinkExt;
use rstest::rstest;
use super::{
super::{
telemetry::{
recorded::{counter_value, record_async},
FRAMES_REJECTED, RECONNECTS,
},
test_support::{
address, captured_quote_stream_message, captured_quote_stream_text,
captured_venue_overrides, message_text, message_then_repeat, test_overrides,
wall_nanos_now, FakeTitan, PAMM, USDC, WBTC, WETH,
},
},
*,
};
const CAPTURED_MESSAGE: &str =
include_str!("test_responses/pamm_price_levels_v2_1792115918290990905.json");
const EARLIER_QUOTE_STREAM_MESSAGE: &str =
include_str!("test_responses/pamm_quote_stream_v2_1792115920051017671.json");
const METRIC: &str = "0xe844701934d9c6085b292e428f41b911cc0b3872";
const GOLIATH: &str = "0x4367985a63063fc970b009c6e599e9225181f551";
const METRIC_ACCOUNT: &str = "0x629ef4396ec73973b5ea25c3f0cd1c45cd73948e";
const LINK: &str = "0x514910771af9ca656af840dff83e8264ecf986ca";
const METRIC_BLOCK_SECOND: u64 = 1_792_115_927;
const NANOS_LOWER_BOUND: u64 = 1_700_000_000_000_000_000;
const NANOS_UPPER_BOUND: u64 = 2_000_000_000_000_000_000;
#[test]
fn parses_captured_live_message() {
let message: TitanPriceLevelMessage =
serde_json::from_str(CAPTURED_MESSAGE).expect("valid JSON");
assert_eq!(message.block, 26_201_953);
assert_eq!(message.slot, Some(15_440_991));
assert!(
(NANOS_LOWER_BOUND..NANOS_UPPER_BOUND).contains(&message.ts),
"ts is not nanosecond-scale: {}",
message.ts
);
let venues: HashSet<&Bytes> = message
.books
.iter()
.map(|book| &book.quote_address)
.collect();
assert!(venues.len() >= 2, "expected several venues, got {}", venues.len());
let fermi = message
.books
.iter()
.find(|book| {
book.quote_address == Bytes::from_str(PAMM).unwrap() &&
book.token1 == "WBTC" &&
book.token2 == "USDC"
})
.expect("Fermi WBTC/USDC book");
assert_eq!(fermi.maker.as_deref(), Some("Fermi"));
assert!(!fermi.asks.is_empty());
assert!(!fermi.bids.is_empty());
for book in &message.books {
for level in book.asks.iter().chain(&book.bids) {
assert!(level.cum_volume > 0.0, "non-positive cumVolume: {level:?}");
assert!(level.price > 0.0, "non-positive price: {level:?}");
}
}
}
#[test]
fn requires_ts_but_not_slot() {
let without_ts = r#"{"slot": 1, "block": 2, "books": []}"#;
assert!(serde_json::from_str::<TitanPriceLevelMessage>(without_ts).is_err());
let without_slot = r#"{"block": 2, "ts": 3, "books": []}"#;
let message: TitanPriceLevelMessage =
serde_json::from_str(without_slot).expect("valid JSON");
assert_eq!(message.slot, None);
}
#[rstest]
#[case::named_maker(r#""maker": "Fermi","#, Some("Fermi"))]
#[case::empty_maker(r#""maker": "","#, Some(""))]
#[case::null_maker(r#""maker": null,"#, None)]
#[case::absent_maker("", None)]
fn tolerates_internal_fields_and_unlabelled_makers(
#[case] maker: &str,
#[case] expected: Option<&str>,
) {
let json = format!(
r#"{{
{maker}
"quoteAddress": "{PAMM}",
"token1": "WBTC",
"token2": "USDC",
"token1Address": "{WBTC}",
"token2Address": "{USDC}",
"calculated_from": 283851543383726791766048878,
"asks": [{{"price": 80997.89405475458, "cumVolume": 0.00012346}}],
"bids": []
}}"#
);
let book: TitanBook = serde_json::from_str(&json).expect("valid book");
assert_eq!(book.maker.as_deref(), expected);
assert_eq!(book.quote_address, Bytes::from_str(PAMM).unwrap());
assert_eq!(book.calculated_from, QuoteSequence::Valid(283_851_543_383_726_791_766_048_878));
assert_eq!(book.asks.len(), 1);
assert_eq!(book.asks[0].price, 80997.89405475458);
assert_eq!(book.asks[0].cum_volume, 0.00012346);
assert!(book.bids.is_empty());
}
#[test]
fn backoff_grows_exponentially_up_to_the_cap() {
let max_backoff = ConnectionSettings::default().max_backoff;
assert_eq!(backoff(1, max_backoff), Duration::from_secs(2));
assert_eq!(backoff(4, max_backoff), Duration::from_secs(16));
assert_eq!(backoff(5, max_backoff), max_backoff);
assert_eq!(backoff(100, max_backoff), max_backoff);
assert_eq!(backoff(u32::MAX, max_backoff), max_backoff);
}
fn fast_settings() -> ConnectionSettings {
ConnectionSettings {
connect_timeout: Duration::from_secs(1),
read_idle_timeout: Duration::from_millis(100),
max_backoff: Duration::from_millis(10),
}
}
fn price_level_message() -> Message {
Message::Text(message_text(100, wall_nanos_now()).into())
}
async fn next_message(stream: &mut (impl Stream<Item = TitanPriceLevelMessage> + Unpin)) {
tokio::time::timeout(Duration::from_secs(2), stream.next())
.await
.expect("a message within two seconds")
.expect("the stream never ends");
}
#[rstest]
#[case::ping_only(Message::Ping(Vec::new().into()), false)]
#[case::malformed_text(Message::Text("nonsense".into()), true)]
fn traffic_that_is_not_a_message_does_not_count_as_liveness(
#[case] filler: Message,
#[case] rejected_as_parse_error: bool,
) {
let (connections, snapshot) = record_async(async {
let fake = FakeTitan::spawn(message_then_repeat(
price_level_message(),
filler,
Duration::from_millis(10),
))
.await;
let stream = messages(fake.url(), fast_settings());
tokio::pin!(stream);
next_message(&mut stream).await;
next_message(&mut stream).await;
fake.connections.load(Ordering::SeqCst)
});
assert!(connections >= 2, "no reconnect on non-message traffic");
assert!(
counter_value(
&snapshot,
RECONNECTS,
&[("reason", "idle_timeout"), ("socket", "price_levels")]
) >= 1
);
let parse_errors = counter_value(
&snapshot,
FRAMES_REJECTED,
&[("reason", "parse_error"), ("socket", "price_levels")],
);
assert_eq!(parse_errors > 0, rejected_as_parse_error);
}
#[test]
fn server_close_frame_reconnects() {
let (connections, snapshot) = record_async(async {
let fake = FakeTitan::spawn(|_, mut socket| async move {
if socket
.send(price_level_message())
.await
.is_err()
{
return;
}
#[expect(
clippy::let_underscore_must_use,
reason = "the fake peer may already be gone; that is not a test failure"
)]
let _ = socket.send(Message::Close(None)).await;
})
.await;
let stream = messages(fake.url(), fast_settings());
tokio::pin!(stream);
next_message(&mut stream).await;
next_message(&mut stream).await;
fake.connections.load(Ordering::SeqCst)
});
assert_eq!(connections, 2);
assert_eq!(
counter_value(
&snapshot,
RECONNECTS,
&[("reason", "closed"), ("socket", "price_levels")]
),
1
);
}
#[test]
fn a_reconnect_names_the_socket_it_happened_on() {
let ((), snapshot) = record_async(async {
let fake = FakeTitan::spawn(|_, mut socket| async move {
#[expect(
clippy::let_underscore_must_use,
reason = "the fake peer may already be gone; that is not a test failure"
)]
let _ = socket.send(Message::Close(None)).await;
})
.await;
let stream = messages::<TitanQuoteStreamMessage>(fake.url(), fast_settings());
tokio::pin!(stream);
#[expect(
clippy::let_underscore_must_use,
reason = "the fake peer may already be gone; that is not a test failure"
)]
let _ = tokio::time::timeout(Duration::from_millis(100), stream.next()).await;
});
assert!(
counter_value(
&snapshot,
RECONNECTS,
&[("reason", "closed"), ("socket", "quote_stream")]
) >= 1,
"the quote stream socket's reconnects are not counted under its own socket"
);
assert_eq!(
counter_value(
&snapshot,
RECONNECTS,
&[("reason", "closed"), ("socket", "price_levels")]
),
0,
"the quote stream socket's reconnects were attributed to the price level socket"
);
}
#[test]
fn slow_consumer_does_not_trigger_the_idle_timeout() {
let (connections, snapshot) = record_async(async {
let fake = FakeTitan::spawn(message_then_repeat(
price_level_message(),
price_level_message(),
Duration::from_millis(20),
))
.await;
let stream = messages(fake.url(), fast_settings());
tokio::pin!(stream);
next_message(&mut stream).await;
tokio::time::sleep(Duration::from_millis(300)).await;
next_message(&mut stream).await;
fake.connections.load(Ordering::SeqCst)
});
assert_eq!(connections, 1, "reconnected while the consumer was not polling");
assert_eq!(
counter_value(
&snapshot,
RECONNECTS,
&[("reason", "idle_timeout"), ("socket", "price_levels")]
),
0
);
}
#[tokio::test]
async fn parsed_messages_keep_the_connection_alive() {
let fake = FakeTitan::spawn(message_then_repeat(
price_level_message(),
price_level_message(),
Duration::from_millis(30),
))
.await;
let settings =
ConnectionSettings { read_idle_timeout: Duration::from_millis(150), ..fast_settings() };
let stream = messages(fake.url(), settings);
tokio::pin!(stream);
for _ in 0..10 {
next_message(&mut stream).await;
}
assert_eq!(fake.connections.load(Ordering::SeqCst), 1);
}
#[test]
fn the_quote_stream_endpoint_is_pinned() {
assert_eq!(
TITAN_QUOTE_STREAM_URL,
"wss://eu.data.titanbuilder.xyz/ws/pamm_quote_stream_v2"
);
assert_eq!(TITAN_QUOTE_STREAM_URL_ENV, "TITAN_PAMM_QUOTE_STREAM_URL");
}
#[tokio::test]
async fn the_reader_serves_the_quote_stream_socket() {
let fake = FakeTitan::spawn(message_then_repeat(
Message::Text(captured_quote_stream_text().into()),
Message::Ping(Vec::new().into()),
Duration::from_millis(50),
))
.await;
let stream = messages::<TitanQuoteStreamMessage>(fake.url(), fast_settings());
tokio::pin!(stream);
let message = tokio::time::timeout(Duration::from_secs(2), stream.next())
.await
.expect("a message within two seconds")
.expect("the stream never ends");
assert_eq!(message.venues.len(), 9);
}
fn parsed(message: &str) -> TitanQuoteStreamMessage {
serde_json::from_str(message).expect("a valid quote stream message")
}
fn decoded(message: &str) -> Vec<TitanVenueOverride> {
parsed(message)
.venues
.iter()
.map(|raw| serde_json::from_str(raw.get()).expect("a decodable venue entry"))
.collect()
}
#[test]
fn parses_the_captured_quote_stream_messages() {
let venues = decoded(captured_quote_stream_text());
let earlier = decoded(EARLIER_QUOTE_STREAM_MESSAGE);
assert_eq!(venues.len(), 9);
assert_eq!(earlier.len(), 9);
let metric = venues
.iter()
.find(|venue| venue.quote_address == address(METRIC))
.expect("the Metric entry");
assert!(metric
.priced_addresses
.contains(&address("0x99ab7c1c5eab47801f7937075998527a550fba8a")));
assert_eq!(metric.block_number, Some(26_201_954));
assert_eq!(metric.slot, Some(15_440_992));
assert_eq!(metric.timestamp, Some(1_792_115_920_126_438_314));
assert_eq!(metric.pair_sequences, vec![284_836_027_668_196_596_826_243_146; 8]);
assert!(metric
.pair_sequences
.iter()
.all(|sequence| *sequence > u128::from(u64::MAX)));
assert_eq!(metric.asset_pairs.len(), 8);
assert_eq!(metric.asset_pairs[0].token_1, address(WETH));
assert_eq!(metric.asset_pairs[0].token_2, address(USDC));
assert_eq!(metric.asset_pairs[4].token_1, address(LINK));
assert_eq!(metric.state_override.len(), 2);
}
#[test]
fn a_captured_entry_validates_into_the_transcribed_overrides() {
let entries = captured_venue_overrides(captured_quote_stream_message());
let goliath = entries
.into_iter()
.find(|entry| entry.quote_address == address(GOLIATH))
.expect("the Goliath entry");
assert_eq!(goliath.overrides, test_overrides());
}
#[rstest]
#[case::later(captured_quote_stream_text(), 8)]
#[case::earlier(EARLIER_QUOTE_STREAM_MESSAGE, 9)]
fn every_captured_entry_carrying_data_validates(
#[case] message: &str,
#[case] accepted_entries: usize,
) {
let entries = captured_venue_overrides(parsed(message));
assert_eq!(entries.len(), accepted_entries);
for entry in entries {
assert_eq!(entry.overrides.block_number, Some(26_201_954));
assert_eq!(entry.overrides.block_timestamp, Some(METRIC_BLOCK_SECOND));
assert_eq!(entry.slot, Some(15_440_992));
}
}
#[test]
fn each_pair_keeps_the_quote_sequence_at_its_position() {
let entry = Entry {
asset_pairs: format!(
r#"[{{"token_1": "{LINK}", "token_2": "{USDC}"}},
{{"token_1": "{WETH}", "token_2": "{USDC}"}}]"#
),
pair_sequences: "[284836027668196596826243146, 284836027668196596826243150]"
.to_string(),
..Entry::default()
};
let pairs = entry.validated().pairs;
assert_eq!(pairs[0].token_1, address(LINK));
assert_eq!(pairs[0].sequence, 284_836_027_668_196_596_826_243_146);
assert_eq!(pairs[1].token_1, address(WETH));
assert_eq!(pairs[1].sequence, 284_836_027_668_196_596_826_243_150);
}
struct Entry {
quote_address: String,
block_number: String,
slot: String,
timestamp: String,
asset_pairs: String,
pair_sequences: String,
state_override: String,
}
impl Default for Entry {
fn default() -> Self {
Self {
quote_address: format!(r#""{METRIC}""#),
block_number: "26148760".to_string(),
slot: "15440992".to_string(),
timestamp: "1792115920126438314".to_string(),
asset_pairs: format!(r#"[{{"token_1": "{LINK}", "token_2": "{USDC}"}}]"#),
pair_sequences: "[284836027668196596826243146]".to_string(),
state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{"balance": "0x2a60f7239c6aedc", "nonce": "0x1"}}}}"#
),
}
}
}
impl Entry {
fn message(&self) -> String {
let Self {
quote_address,
block_number,
slot,
timestamp,
asset_pairs,
pair_sequences,
state_override,
} = self;
format!(
r#"{{"venues": [{{
"maker": "Metric",
"quoteAddress": {quote_address},
"pricedAddresses": ["{METRIC}"],
"blockNumber": {block_number},
"slot": {slot},
"timestamp": {timestamp},
"assetPairs": {asset_pairs},
"pairSequences": {pair_sequences},
"stateOverride": {state_override}
}}]}}"#
)
}
fn outcome(&self) -> [Result<VenueOverrides, EntryRejection>; 1] {
validate(parsed(&self.message()))
.try_into()
.expect("expected exactly one venue entry")
}
fn rejection(&self) -> EntryRejection {
let [outcome] = self.outcome();
outcome.expect_err("the entry was accepted")
}
fn validated(&self) -> VenueOverrides {
let [outcome] = self.outcome();
outcome.expect("the entry was refused")
}
}
#[test]
fn the_synthetic_entry_is_accepted_unmutated() {
let entry = Entry::default().validated();
assert_eq!(entry.quote_address, address(METRIC));
assert_eq!(entry.pairs.len(), 1);
assert_eq!(entry.pairs[0].sequence, 284_836_027_668_196_596_826_243_146);
assert_eq!(entry.overrides.accounts.len(), 1);
assert_eq!(entry.overrides.built_at_ns, 1_792_115_920_126_438_314);
}
#[rstest]
#[case::no_block_number(
Entry { block_number: "null".to_string(), ..Entry::default() },
None,
Some(1_792_115_927)
)]
#[case::no_slot(
Entry { slot: "null".to_string(), ..Entry::default() },
Some(26_148_760),
None
)]
fn an_entry_without_a_block_number_or_slot_is_accepted(
#[case] entry: Entry,
#[case] block_number: Option<u64>,
#[case] block_timestamp: Option<u64>,
) {
let entry = entry.validated();
assert_eq!(entry.overrides.block_number, block_number);
assert_eq!(entry.overrides.block_timestamp, block_timestamp);
}
#[rstest]
#[case::fewer_sequences("[283851543383726791766048793]")]
#[case::more_sequences(
"[283851543383726791766048793, 283851543383726791766048835, 283851543383726791766048836]"
)]
#[case::no_sequences("[]")]
fn a_sequence_length_mismatch_rejects_the_entry(#[case] pair_sequences: &str) {
let entry = Entry {
asset_pairs: format!(
r#"[{{"token_1": "{LINK}", "token_2": "{USDC}"}},
{{"token_1": "{WETH}", "token_2": "{USDC}"}}]"#
),
pair_sequences: pair_sequences.to_string(),
..Entry::default()
};
assert_eq!(entry.rejection(), EntryRejection::PairsAndSequencesDiffer);
}
#[rstest]
#[case::code(r#""code": "0x6080604052","#)]
#[case::full_state(
r#""state": {"0x8dc4adfc36586ffb9fe5c2dba18756239463dda9032bbfa7fd13f3bb3b16358f":
"0x6ac7bf2b01000000000001a11c42ae030000007600000076000000000003969f"},"#
)]
fn code_or_a_full_state_rejects_the_entry(#[case] unsupported: &str) {
let entry = Entry {
state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{"balance": "0xb0618b2431873a", "nonce": "0x1"}},
"0x27df873222a07fa78d0e52797380dbbfa0e98d43": {{{unsupported}
"balance": "0x9ae4c04827bc33", "nonce": "0x2b2d"}}}}"#
),
..Entry::default()
};
assert_eq!(entry.rejection(), EntryRejection::UnsupportedOverride);
}
#[rstest]
#[case::null_code(r#""code": null,"#)]
#[case::null_state(r#""state": null,"#)]
fn a_null_code_or_state_is_not_an_override(#[case] null_field: &str) {
let entry = Entry {
state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{{null_field} "balance": "0xb0618b2431873a",
"nonce": "0x1"}}}}"#
),
..Entry::default()
};
assert_eq!(
entry
.validated()
.overrides
.accounts
.len(),
1
);
}
fn synthetic_state_override(accounts: usize, slots: usize, word_bytes: usize) -> String {
let word = format!("0x{}", "ab".repeat(word_bytes));
let accounts: Vec<String> = (0..accounts)
.map(|account| {
let diff: Vec<String> = (0..slots)
.map(|slot| format!(r#""0x{:064x}": "{word}""#, account * slots + slot))
.collect();
format!(r#""0x{:040x}": {{"stateDiff": {{{}}}}}"#, account + 1, diff.join(", "))
})
.collect();
format!("{{{}}}", accounts.join(", "))
}
#[rstest]
#[case::too_many_accounts(33, 0)]
#[case::too_many_slots(2, 257)]
fn an_over_cap_entry_is_rejected(#[case] accounts: usize, #[case] slots: usize) {
let entry = Entry {
state_override: synthetic_state_override(accounts, slots, WORD_BYTES),
..Entry::default()
};
assert_eq!(entry.rejection(), EntryRejection::OverCap);
}
#[test]
fn an_entry_at_the_caps_is_accepted() {
let entry =
Entry { state_override: synthetic_state_override(32, 16, 32), ..Entry::default() }
.validated();
assert_eq!(entry.overrides.accounts.len(), 32);
let slots: usize = entry
.overrides
.accounts
.values()
.map(|account| account.state_diff.len())
.sum();
assert_eq!(slots, 512);
}
#[rstest]
#[case::odd_digits("0x31a98d578d71685db", "0x031a98d578d71685db")]
#[case::zero("0x0", "0x00")]
#[case::even_digits("0xb0618b2431873a", "0xb0618b2431873a")]
#[case::one_odd_digit("0xf", "0x0f")]
fn a_balance_quantity_decodes_to_its_minimal_bytes(
#[case] quantity: &str,
#[case] expected: &str,
) {
let entry = Entry {
state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{"balance": "{quantity}", "nonce": "0x2b2d"}}}}"#
),
..Entry::default()
};
let account = entry
.validated()
.overrides
.accounts
.remove(&address(METRIC_ACCOUNT))
.expect("the overridden account");
assert_eq!(account.balance, Some(Bytes::from_str(expected).expect("hex literal")));
assert_eq!(account.nonce, Some(0x2b2d));
}
#[rstest]
#[case::not_hex(r#""balance": "0xzz""#)]
#[case::unprefixed(r#""balance": "b0618b2431873a""#)]
#[case::empty(r#""balance": "0x""#)]
#[case::decimal(r#""balance": "12345""#)]
#[case::wider_than_a_u256(
r#""balance":
"0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff""#
)]
#[case::nonce_overflow(r#""nonce": "0x10000000000000000""#)]
#[case::nonce_not_hex(r#""nonce": "0x1g""#)]
#[case::nonce_signed(r#""nonce": "0x+1""#)]
fn a_malformed_quantity_rejects_the_entry(#[case] quantity: &str) {
let entry = Entry {
state_override: format!(r#"{{"{METRIC_ACCOUNT}": {{{quantity}}}}}"#),
..Entry::default()
};
assert_eq!(entry.rejection(), EntryRejection::MalformedQuantity);
}
#[test]
fn a_nonce_at_the_width_of_its_field_is_accepted() {
let entry = Entry {
state_override: format!(r#"{{"{METRIC_ACCOUNT}": {{"nonce": "0xffffffffffffffff"}}}}"#),
..Entry::default()
};
let account = entry
.validated()
.overrides
.accounts
.remove(&address(METRIC_ACCOUNT))
.expect("the overridden account");
assert_eq!(account.nonce, Some(u64::MAX));
assert_eq!(account.balance, None);
}
#[rstest]
#[case::short_venue(
Entry { quote_address: r#""0x3ce2672aa806138585920421406bf0decb81""#.to_string(),
..Entry::default() },
EntryRejection::NotAVenue
)]
#[case::long_venue(
Entry { quote_address: r#""0x3ce2672aa806138585920421406bf0decb8130cbcb""#.to_string(),
..Entry::default() },
EntryRejection::NotAVenue
)]
#[case::pair_token(
Entry { asset_pairs: r#"[{"token_1": "0xc845b2894dbddd03858fd2d643b4ef725fe0849d0a0a",
"token_2": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}]"#
.to_string(),
..Entry::default() },
EntryRejection::MalformedPair
)]
#[case::account_address(
Entry { state_override:
r#"{"0xba443ecec71dc7123bd68c2082d13e3299cd": {"nonce": "0x1"}}"#.to_string(),
..Entry::default() },
EntryRejection::NotAnAccount
)]
#[case::storage_slot(
Entry { state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{"stateDiff": {{"0x8dc4adfc": "0x{}"}}}}}}"#,
"ab".repeat(32)),
..Entry::default() },
EntryRejection::MalformedStorage
)]
#[case::stored_word(
Entry { state_override: format!(
r#"{{"{METRIC_ACCOUNT}": {{"stateDiff": {{"0x{}": "0xabab"}}}}}}"#,
"ab".repeat(32)),
..Entry::default() },
EntryRejection::MalformedStorage
)]
fn a_malformed_address_or_word_rejects_the_entry(
#[case] entry: Entry,
#[case] expected: EntryRejection,
) {
assert_eq!(entry.rejection(), expected);
}
#[rstest]
#[case::no_pairs(
"[]",
"[]",
r#"{"0xba443ecec71dc7123bd68c2082d13e3299cde896": {"nonce": "0x1"}}"#
)]
#[case::no_accounts(
r#"[{"token_1": "0xc845b2894dbddd03858fd2d643b4ef725fe0849d",
"token_2": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}]"#,
"[283851543383726791766048793]",
"{}"
)]
fn an_entry_without_data_is_rejected(
#[case] asset_pairs: &str,
#[case] pair_sequences: &str,
#[case] state_override: &str,
) {
let entry = Entry {
asset_pairs: asset_pairs.to_string(),
pair_sequences: pair_sequences.to_string(),
state_override: state_override.to_string(),
..Entry::default()
};
assert_eq!(entry.rejection(), EntryRejection::Empty);
}
#[rstest]
#[case::block_number_as_text(r#""blockNumber": "26148760","#)]
#[case::sequence_as_text(r#""pairSequences": ["283851543383726791766048793"],"#)]
#[case::balance_as_number(
r#""stateOverride": {"0xba443ecec71dc7123bd68c2082d13e3299cde896": {"balance": 1}},"#
)]
fn an_undecodable_entry_costs_only_itself(#[case] wrong_field: &str) {
let undecodable = format!(
r#"{{"quoteAddress": "{METRIC}", {wrong_field} "timestamp": 1791475494775213874}}"#
);
let good = Entry::default().message();
let good_entry = good
.trim_start_matches(r#"{"venues": ["#)
.trim_end_matches("]}");
let message = format!(r#"{{"venues": [{undecodable}, {good_entry}]}}"#);
let outcomes = validate(parsed(&message));
assert_eq!(outcomes.len(), 2);
assert_eq!(outcomes[0], Err(EntryRejection::Undecodable));
assert!(outcomes[1].is_ok(), "{:?}", outcomes[1]);
}
#[test]
fn a_malformed_priced_address_rejects_the_entry() {
let message = Entry::default().message().replace(
&format!(r#""pricedAddresses": ["{METRIC}"]"#),
r#""pricedAddresses": ["0x99ab7c1c"]"#,
);
assert_eq!(validate(parsed(&message)), vec![Err(EntryRejection::NotAVenue)]);
}
#[test]
fn a_message_without_venues_yields_no_result() {
assert!(validate(parsed(r#"{"venues": []}"#)).is_empty());
}
#[rstest]
#[case::null(Entry { timestamp: "null".to_string(), ..Entry::default() }.message())]
#[case::absent(format!(
r#"{{"venues": [{{
"quoteAddress": "{METRIC}",
"blockNumber": 26148760,
"slot": 15387623,
"assetPairs": [{{"token_1": "{LINK}", "token_2": "{USDC}"}}],
"pairSequences": [283851543383726791766048793],
"stateOverride": {{"{METRIC_ACCOUNT}": {{"nonce": "0x1"}}}}
}}]}}"#
))]
fn an_entry_without_a_timestamp_is_rejected(#[case] message: String) {
assert_eq!(validate(parsed(&message)), vec![Err(EntryRejection::NoTimestamp)]);
}
#[test]
fn unread_and_unknown_fields_are_tolerated() {
let message = format!(
r#"{{"venues": [{{
"quoteAddress": "{METRIC}",
"pricedAddresses": ["{METRIC}", "{USDC}"],
"somethingNew": {{"nested": [1, 2, 3]}},
"blockNumber": 26148760,
"slot": 15387623,
"timestamp": 1791475494775213874,
"assetPairs": [{{"token_1": "{LINK}", "token_2": "{USDC}", "extra": true}}],
"pairSequences": [283851543383726791766048793],
"stateOverride": {{"{METRIC_ACCOUNT}": {{"nonce": "0x1", "extra": null}}}}
}}]}}"#
);
let mut outcomes = validate(parsed(&message));
assert_eq!(outcomes.len(), 1);
assert_eq!(
outcomes
.remove(0)
.expect("the entry was refused")
.pairs
.len(),
1
);
}
#[test]
fn decodes_the_captured_quote_sequences() {
let message: TitanPriceLevelMessage =
serde_json::from_str(CAPTURED_MESSAGE).expect("valid JSON");
assert_eq!(
message.books[0].calculated_from,
QuoteSequence::Valid(284_836_009_221_452_523_116_691_695)
);
for book in &message.books {
match book.calculated_from {
QuoteSequence::Valid(sequence) => {
assert!(sequence > u128::from(u64::MAX), "{sequence} fits a u64");
}
QuoteSequence::Absent | QuoteSequence::Unreadable => {
panic!("a captured book carried no readable quote sequence: {book:?}")
}
}
}
}
#[test]
fn a_book_without_a_quote_sequence_decodes_as_absent() {
let json = format!(
r#"{{"quoteAddress": "{PAMM}", "token1": "WBTC", "token2": "USDC",
"token1Address": "{WBTC}", "token2Address": "{USDC}",
"asks": [], "bids": []}}"#
);
let book: TitanBook = serde_json::from_str(&json).expect("valid book");
assert_eq!(book.calculated_from, QuoteSequence::Absent);
}
fn message_with_mutated_quote_sequence(index: usize, literal: &str) -> String {
const KEY: &str = r#""calculated_from""#;
let keys: Vec<usize> = CAPTURED_MESSAGE
.match_indices(KEY)
.map(|(at, _)| at)
.collect();
let key_at = keys[index];
let value_at = key_at +
CAPTURED_MESSAGE[key_at..]
.find(':')
.expect("the quote sequence has a value") +
1;
let value_end = value_at +
CAPTURED_MESSAGE[value_at..]
.find(',')
.expect("a field follows the quote sequence");
format!("{}{literal}{}", &CAPTURED_MESSAGE[..value_at], &CAPTURED_MESSAGE[value_end..])
}
#[rstest]
#[case::null("null", QuoteSequence::Absent)]
#[case::string(r#""283851543383726791766048878""#, QuoteSequence::Unreadable)]
#[case::negative("-1", QuoteSequence::Unreadable)]
#[case::fraction("1.5", QuoteSequence::Unreadable)]
#[case::boolean("true", QuoteSequence::Unreadable)]
#[case::object("{}", QuoteSequence::Unreadable)]
#[case::above_u128("3402823669209384634633746074317682114560", QuoteSequence::Unreadable)]
fn an_unreadable_quote_sequence_costs_only_itself(
#[case] literal: &str,
#[case] expected: QuoteSequence,
) {
const MUTATED: usize = 3;
let captured: TitanPriceLevelMessage =
serde_json::from_str(CAPTURED_MESSAGE).expect("valid JSON");
let text = message_with_mutated_quote_sequence(MUTATED, literal);
let message: TitanPriceLevelMessage =
serde_json::from_str(&text).expect("the message still parses");
assert_eq!(message.books.len(), captured.books.len());
assert_eq!(message.ts, captured.ts);
for (index, (book, original)) in message
.books
.iter()
.zip(&captured.books)
.enumerate()
{
assert_eq!(book.quote_address, original.quote_address);
assert_eq!(book.token1, original.token1);
assert_eq!(book.asks.len(), original.asks.len());
assert_eq!(book.bids.len(), original.bids.len());
let expected = if index == MUTATED { expected } else { original.calculated_from };
assert_eq!(book.calculated_from, expected, "book {index}");
}
}
#[rstest]
#[case::truncated(r#"{"block": 1, "ts": 2, "books": ["#)]
#[case::not_json("nonsense")]
#[case::unreadable_price_levels(
r#"{"block": 1, "ts": 2, "books": [{"quoteAddress": "0x01", "token1": "A",
"token2": "B", "token1Address": "0x01", "token2Address": "0x02",
"asks": "nope", "bids": []}]}"#
)]
#[case::price_beyond_f64(
r#"{"block": 1, "ts": 2, "books": [{"quoteAddress": "0x01", "token1": "A",
"token2": "B", "token1Address": "0x01", "token2Address": "0x02",
"asks": [{"price": 1e400, "cumVolume": 1.0}], "bids": []}]}"#
)]
fn invalid_json_still_rejects_the_message(#[case] text: &str) {
assert!(serde_json::from_str::<TitanPriceLevelMessage>(text).is_err());
}
}