use std::sync::Arc;
use async_trait::async_trait;
use serde::Deserialize;
use crate::book::l3::{OrderAction, OrderEvent, OrderId};
use crate::book::{BookDelta, BookSnapshot, L2Book, LevelChange};
use crate::clock::{Clock, Timestamps};
use crate::error::{Error, Result};
use crate::fixed::Fixed;
use crate::gap::DetectionLimit;
use crate::limits::VenueBudget;
use crate::sequence::{SeqState, SeqVerdict, Unverifiable};
use crate::symbols::{SymbolMapper, mappers};
use crate::types::{BookLevel, Side, Symbol, VenueId, VenueSymbol};
use crate::venue::{
ControlEvent, ControlKind, DecimalEncoding, FeedDepth, FeedEvent, FeedTransport, HttpFetch,
Keepalive, OrderSnapshot, RawFrame, RedundantDeletes, SequenceScope, SnapshotSource,
ValidationScheme, ValidationTiming, Venue, VenueCapabilities, VenueTimestamps,
};
const WS_URL: &str = "wss://ws.bitstamp.net";
const REST_BOOK: &str = "https://www.bitstamp.net/api/v2/order_book";
pub struct Bitstamp {
caps: VenueCapabilities,
http: Arc<dyn HttpFetch>,
clock: Arc<dyn Clock>,
ws_url: String,
symbols: SymbolMapper,
book_level: BookLevel,
seed_from_rest: bool,
}
impl Bitstamp {
pub fn new(http: Arc<dyn HttpFetch>, clock: Arc<dyn Clock>) -> Self {
Bitstamp {
caps: Self::capabilities(),
http,
clock,
ws_url: WS_URL.to_string(),
symbols: mappers::bitstamp(),
book_level: BookLevel::L2,
seed_from_rest: false,
}
}
pub fn with_book_level(mut self, level: BookLevel) -> Self {
self.book_level = level;
self.caps = Self::capabilities_for(level);
self
}
pub fn book_level(&self) -> BookLevel {
self.book_level
}
pub fn with_order_seed(mut self, seed: bool) -> Self {
self.seed_from_rest = seed;
self
}
fn live_orders_channel(&self, symbol: &Symbol) -> String {
format!("live_orders_{}", self.venue_symbol(symbol))
}
fn parse_event_token(raw: &str) -> Option<u128> {
let hex: String = raw.chars().filter(|c| c.is_ascii_hexdigit()).collect();
(hex.len() == 32).then(|| u128::from_str_radix(&hex, 16).ok())?
}
fn classify(event: &str, order: &LiveOrder) -> Option<OrderAction> {
match event {
"order_created" => Some(OrderAction::Add),
"order_changed" => Some(OrderAction::Modify),
"order_deleted" => {
let fully_traded = order.amount_at_create.is_positive()
&& order.amount_traded >= order.amount_at_create;
Some(if fully_traded {
OrderAction::Execute
} else {
OrderAction::Cancel
})
}
_ => None,
}
}
pub fn with_symbols(mut self, symbols: &[Symbol]) -> Self {
self.symbols.register_all(symbols);
self
}
pub fn with_ws_url(mut self, url: impl Into<String>) -> Self {
self.ws_url = url.into();
self
}
fn channel(&self, symbol: &Symbol) -> String {
format!("diff_order_book_{}", self.venue_symbol(symbol))
}
fn symbol_from_channel(&self, channel: &str) -> Result<Symbol> {
let raw = channel
.strip_prefix("diff_order_book_")
.or_else(|| channel.strip_prefix("live_orders_"))
.or_else(|| channel.strip_prefix("order_book_"))
.ok_or_else(|| Error::UnknownSymbol {
venue: VenueId::Bitstamp,
symbol: channel.to_string(),
})?;
self.canonical_symbol(raw)
}
fn capabilities() -> VenueCapabilities {
Self::capabilities_for(BookLevel::L2)
}
fn capabilities_for(level: BookLevel) -> VenueCapabilities {
if level == BookLevel::L3 {
return Self::l3_capabilities();
}
VenueCapabilities {
id: VenueId::Bitstamp,
book_level: BookLevel::L2,
validation: ValidationScheme::MonotonicTimestamp,
scope: SequenceScope::PerSymbol,
timing: ValidationTiming::BeforeApply,
snapshot_source: SnapshotSource::Rest,
feed_depth: FeedDepth::Full,
decimals: DecimalEncoding::Strings,
redundant_deletes: RedundantDeletes::Expected,
timestamps: VenueTimestamps::PerMessage,
keepalive: Keepalive::ProtocolPings,
budget: VenueBudget {
subscriptions_per_connection: 20,
max_connections: 4,
connect_interval: std::time::Duration::from_secs(1),
connect_burst: 2,
rest_interval: std::time::Duration::from_millis(500),
rest_burst: 2,
},
requires_auth: false,
detection_limits: vec![
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "always".to_string(),
consequence:
"the feed carries no sequence number, update id, or checksum, so a lost \
message is undetectable by any means; every book message is reported \
unverifiable and no Bitstamp window is ever claimed as validated"
.to_string(),
},
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "a book built from one REST snapshot".to_string(),
consequence:
"the REST book contains levels the diff stream never retracts. Measured: \
starting from one snapshot and applying its own diffs, the book crosses \
by the fifteenth message and never heals. The crossed-book check \
catches it and rebuilds, which is why this venue re-snapshots a couple \
of times a minute; a consumer that trusted a single snapshot would hold \
a crossed book all day without noticing"
.to_string(),
},
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "deletes for levels we never held".to_string(),
consequence:
"counted and published as this venue's only weak health signal, but not \
acted on: rebuilding the book on each one measurably degraded the \
capture, because the REST snapshot runs about a second behind the \
stream and every splice is another chance to go wrong"
.to_string(),
},
],
}
}
fn l3_capabilities() -> VenueCapabilities {
VenueCapabilities {
id: VenueId::Bitstamp,
book_level: BookLevel::L3,
validation: ValidationScheme::Chained,
scope: SequenceScope::PerSymbol,
timing: ValidationTiming::BeforeApply,
snapshot_source: SnapshotSource::None,
feed_depth: FeedDepth::Full,
decimals: DecimalEncoding::Strings,
redundant_deletes: RedundantDeletes::Expected,
timestamps: VenueTimestamps::PerMessage,
keepalive: Keepalive::ProtocolPings,
budget: VenueBudget {
subscriptions_per_connection: 10,
max_connections: 4,
connect_interval: std::time::Duration::from_secs(1),
connect_burst: 2,
rest_interval: std::time::Duration::from_millis(500),
rest_burst: 2,
},
requires_auth: false,
detection_limits: vec![
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "every gap".to_string(),
consequence:
"the event token chains exactly, so a break proves loss occurred, but \
the token is an identifier rather than a counter and can never say how \
many events it swallowed"
.to_string(),
},
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "orders that predate the recording".to_string(),
consequence:
"the feed carries no snapshot and the REST book holds orders the stream \
never retracts, so the book starts empty and fills in as orders churn. \
Levels known to hold an order we never watched arrive are marked, and \
no queue position on one of them is reported as observed"
.to_string(),
},
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "queue position for orders seeded from a snapshot".to_string(),
consequence:
"orders seeded from the REST book inherit the venue's listing order as \
their queue order. Measured: across 591 price levels holding more than \
one order, every one was listed in ascending order id, and order ids \
increase with time. Well evidenced is still not observed, so those \
positions are marked seeded rather than counted as known"
.to_string(),
},
DetectionLimit {
venue: VenueId::Bitstamp,
scope: "execution versus cancellation".to_string(),
consequence:
"the feed reports created, changed, and deleted, so which of the last \
two a deletion was has to be inferred from amount_traded. On 19 of \
3,999 measured events the resting quantity moved by more than the \
reported trade explains, and those are flagged rather than guessed"
.to_string(),
},
],
}
}
fn levels(entries: &[Level], side: Side) -> Vec<LevelChange> {
entries
.iter()
.map(|l| LevelChange::new(side, l.0, l.1))
.collect()
}
fn micros_to_nanos(raw: Option<&String>) -> Option<i64> {
raw?.parse::<i64>().ok()?.checked_mul(1_000)
}
}
#[derive(Debug, Deserialize)]
struct Level(Fixed, Fixed);
#[derive(Debug, Deserialize)]
struct Frame {
event: Option<String>,
channel: Option<String>,
data: Option<serde_json::Value>,
event_id: Option<String>,
pre_event_id: Option<String>,
}
#[derive(Debug, Deserialize)]
struct LiveOrder {
id_str: String,
order_type: u8,
microtimestamp: Option<String>,
amount_str: Fixed,
#[serde(default)]
amount_traded: Fixed,
#[serde(default)]
amount_at_create: Fixed,
price_str: Fixed,
}
impl LiveOrder {
fn side(&self) -> Side {
if self.order_type == 0 {
Side::Bid
} else {
Side::Ask
}
}
fn size_change_explained(&self) -> bool {
match self.amount_at_create.checked_sub(self.amount_traded) {
Some(expected) => expected == self.amount_str,
None => false,
}
}
}
#[derive(Debug, Deserialize)]
struct SnapshotOrder(Fixed, Fixed, String);
#[derive(Debug, Deserialize)]
struct OrderBookL3 {
microtimestamp: Option<String>,
#[serde(default)]
bids: Vec<SnapshotOrder>,
#[serde(default)]
asks: Vec<SnapshotOrder>,
}
#[derive(Debug, Deserialize)]
struct BookData {
#[allow(dead_code)]
timestamp: Option<String>,
microtimestamp: Option<String>,
#[serde(default)]
bids: Vec<Level>,
#[serde(default)]
asks: Vec<Level>,
}
#[async_trait]
impl Venue for Bitstamp {
fn capabilities(&self) -> &VenueCapabilities {
&self.caps
}
fn venue_symbol(&self, symbol: &Symbol) -> VenueSymbol {
self.symbols.to_venue(symbol)
}
fn canonical_symbol(&self, raw: &str) -> Result<Symbol> {
self.symbols
.to_canonical(raw)
.map_err(|e| Error::Other(e.to_string()))
}
async fn connect(&self) -> Result<Box<dyn FeedTransport>> {
Ok(Box::new(
crate::transport::WsTransport::connect(
VenueId::Bitstamp,
&self.ws_url,
Arc::clone(&self.clock),
)
.await?,
))
}
fn subscribe(&self, symbols: &[Symbol]) -> Result<Vec<String>> {
if symbols.is_empty() {
return Err(Error::Subscription {
venue: VenueId::Bitstamp,
reason: "no symbols requested".to_string(),
});
}
Ok(symbols
.iter()
.map(|s| {
let channel = match self.book_level {
BookLevel::L3 => self.live_orders_channel(s),
BookLevel::L2 => self.channel(s),
};
serde_json::json!({
"event": "bts:subscribe",
"data": {"channel": channel},
})
.to_string()
})
.collect())
}
async fn snapshot(&self, symbol: &Symbol) -> Result<BookSnapshot> {
let url = format!("{REST_BOOK}/{}/", self.venue_symbol(symbol));
let body = self.http.get(&url).await?;
let parsed: BookData = serde_json::from_slice(&body)
.map_err(|e| Error::protocol(VenueId::Bitstamp, format!("order_book: {e}"), &body))?;
let micros = Bitstamp::micros_to_nanos(parsed.microtimestamp.as_ref());
Ok(BookSnapshot {
symbol: symbol.clone(),
bids: parsed.bids.iter().map(|l| (l.0, l.1)).collect(),
asks: parsed.asks.iter().map(|l| (l.0, l.1)).collect(),
seq: None,
checksum: None,
stamps: Timestamps::new(self.clock.stamp(), micros),
})
}
async fn order_snapshot(&self, symbol: &Symbol) -> Result<Option<OrderSnapshot>> {
if self.book_level != BookLevel::L3 || !self.seed_from_rest {
return Ok(None);
}
let url = format!("{REST_BOOK}/{}/?group=2", self.venue_symbol(symbol));
let body = self.http.get(&url).await?;
let parsed: OrderBookL3 = serde_json::from_slice(&body).map_err(|e| {
Error::protocol(VenueId::Bitstamp, format!("order_book group=2: {e}"), &body)
})?;
let mut orders = Vec::with_capacity(parsed.bids.len() + parsed.asks.len());
for (side, entries) in [(Side::Bid, &parsed.bids), (Side::Ask, &parsed.asks)] {
for entry in entries {
orders.push((OrderId::new(entry.2.clone()), side, entry.0, entry.1));
}
}
Ok(Some(OrderSnapshot {
symbol: symbol.clone(),
orders,
stamps: Timestamps::new(
self.clock.stamp(),
Bitstamp::micros_to_nanos(parsed.microtimestamp.as_ref()),
),
}))
}
fn parse_delta(&self, frame: &RawFrame) -> Result<Vec<FeedEvent>> {
let parsed: Frame = serde_json::from_slice(&frame.payload)
.map_err(|e| Error::protocol(VenueId::Bitstamp, e.to_string(), &frame.payload))?;
let event = parsed.event.as_deref().unwrap_or("");
if let Some(action) = ["order_created", "order_changed", "order_deleted"]
.contains(&event)
.then_some(event)
{
let channel = parsed.channel.as_deref().unwrap_or_default();
let symbol = self.symbol_from_channel(channel)?;
let value = parsed.data.ok_or_else(|| {
Error::protocol(
VenueId::Bitstamp,
"order event without data",
&frame.payload,
)
})?;
let order: LiveOrder = serde_json::from_value(value).map_err(|e| {
Error::protocol(
VenueId::Bitstamp,
format!("live order: {e}"),
&frame.payload,
)
})?;
let Some(kind) = Bitstamp::classify(action, &order) else {
return Err(Error::protocol(
VenueId::Bitstamp,
format!("unknown order event {action:?}"),
&frame.payload,
));
};
let micros = Bitstamp::micros_to_nanos(order.microtimestamp.as_ref());
return Ok(vec![FeedEvent::Order(Box::new(OrderEvent {
symbol,
order_id: OrderId::new(order.id_str.clone()),
action: kind,
side: order.side(),
price: order.price_str,
qty: if kind.removes() {
Fixed::ZERO
} else {
order.amount_str
},
original_qty: Some(order.amount_at_create),
executed_qty: Some(order.amount_traded),
stamps: Timestamps::new(frame.stamp, micros),
event_token: parsed
.event_id
.as_deref()
.and_then(Bitstamp::parse_event_token),
prev_event_token: parsed
.pre_event_id
.as_deref()
.and_then(Bitstamp::parse_event_token),
size_change_explained: order.size_change_explained(),
}))]);
}
if event != "data" {
let kind = match event {
"bts:subscription_succeeded" => ControlKind::SubscriptionAck,
"bts:error" => ControlKind::SubscriptionError,
"bts:request_reconnect" => ControlKind::ReconnectRequested,
_ => ControlKind::Status,
};
return Ok(vec![FeedEvent::Control(ControlEvent {
kind,
detail: event.to_string(),
stamp: frame.stamp,
seq: None,
})]);
}
let Some(channel) = parsed.channel.as_deref() else {
return Err(Error::protocol(
VenueId::Bitstamp,
"data frame without a channel",
&frame.payload,
));
};
let symbol = self.symbol_from_channel(channel)?;
let value = parsed.data.ok_or_else(|| {
Error::protocol(VenueId::Bitstamp, "data frame without data", &frame.payload)
})?;
let data: BookData = serde_json::from_value(value).map_err(|e| {
Error::protocol(VenueId::Bitstamp, format!("book data: {e}"), &frame.payload)
})?;
let micros = Bitstamp::micros_to_nanos(data.microtimestamp.as_ref());
let mut changes = Bitstamp::levels(&data.bids, Side::Bid);
changes.extend(Bitstamp::levels(&data.asks, Side::Ask));
Ok(vec![FeedEvent::Delta(BookDelta {
symbol,
changes,
seq: None,
checksum: None,
stamps: Timestamps::new(frame.stamp, micros),
prev_seq: None,
first_seq: None,
})])
}
fn validate_sequence(
&self,
state: &mut SeqState,
event: &FeedEvent,
_book: &L2Book,
) -> SeqVerdict {
if let SeqState::Chain(chain) = state {
return match event {
FeedEvent::Order(order) => match order.event_token {
Some(token) => chain.observe(token, order.prev_event_token),
None => SeqVerdict::Unverifiable(Unverifiable::MessageCarriedNoCheck),
},
_ => SeqVerdict::Unverifiable(Unverifiable::MessageCarriedNoCheck),
};
}
let SeqState::Timestamp(timestamps) = state else {
return SeqVerdict::Unverifiable(Unverifiable::VenuePublishesNoSequence);
};
match event {
FeedEvent::Snapshot(s) => match s.stamps.venue_nanos {
Some(nanos) => {
timestamps.anchor_snapshot(nanos);
SeqVerdict::Unverifiable(Unverifiable::VenuePublishesNoSequence)
}
None => SeqVerdict::Unverifiable(Unverifiable::MessageCarriedNoCheck),
},
FeedEvent::Delta(d) => match d.stamps.venue_nanos {
Some(nanos) => timestamps.observe(nanos),
None => SeqVerdict::Unverifiable(Unverifiable::MessageCarriedNoCheck),
},
FeedEvent::Order(_) | FeedEvent::Control(_) => {
SeqVerdict::Unverifiable(Unverifiable::MessageCarriedNoCheck)
}
}
}
}