use std::sync::Arc;
use async_trait::async_trait;
use color_eyre::Result;
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use serde::Deserialize;
use crate::{
indicators::{Bands, BollingerBands},
ports::{MarketDataSource, TradingGateway},
strategies::{
CommonParams, Strategy, cancel_all_orders, closes_of, fetch_candles, limit_order,
params_from_table,
},
};
#[derive(Debug, Clone, Deserialize)]
pub struct BollGridConfig {
#[serde(flatten)]
pub common: CommonParams,
#[serde(default = "default_window")]
pub boll_window: usize,
#[serde(default = "default_mult")]
pub boll_mult: Decimal,
#[serde(default = "default_levels")]
pub grid_num: u32,
#[serde(default = "default_qty")]
pub qty: Decimal,
#[serde(default = "default_spread")]
pub profit_spread_pct: Decimal,
}
const fn default_window() -> usize {
21
}
fn default_mult() -> Decimal {
Decimal::new(2, 0)
}
const fn default_levels() -> u32 {
3
}
fn default_qty() -> Decimal {
Decimal::new(1, 3)
}
fn default_spread() -> Decimal {
Decimal::new(5, 4)
}
const fn max_grid_num() -> u32 {
200
}
impl BollGridConfig {
pub fn from_params(table: &toml::Table) -> Result<Self> {
let config: Self = params_from_table(table)?;
if config.grid_num > max_grid_num() {
return Err(color_eyre::eyre::eyre!(
"grid_num must be at most {}, got {}",
max_grid_num(),
config.grid_num
));
}
Ok(config)
}
}
#[must_use]
pub fn plan_ladder(close: Decimal, bands: &Bands, grid_num: u32) -> Vec<(Decimal, bool)> {
let width = bands.upper - bands.lower;
if width <= Decimal::ZERO || close > bands.upper || close < bands.lower {
return Vec::new();
}
let step = width / Decimal::from(grid_num.saturating_add(1));
let mut plan = Vec::with_capacity(usize::try_from(grid_num).unwrap_or(0) * 2);
for level in 1..=grid_num {
let offset = step * Decimal::from(level);
let bid = close - offset;
let ask = close + offset;
if bid > dec!(0) && bid >= bands.lower {
plan.push((bid, true));
}
if ask <= bands.upper {
plan.push((ask, false));
}
}
plan
}
pub struct BollGrid {
config: BollGridConfig,
gateway: Arc<dyn TradingGateway>,
market: Arc<dyn MarketDataSource>,
}
impl BollGrid {
pub fn new(
config: BollGridConfig,
gateway: Arc<dyn TradingGateway>,
market: Arc<dyn MarketDataSource>,
) -> Self {
Self { config, gateway, market }
}
pub async fn tick(&self) -> Result<()> {
let exchange = self.config.common.proto_exchange_id();
let candles = fetch_candles(
self.market.as_ref(),
&exchange,
&self.config.common.symbol,
&self.config.common.timeframe,
u32::try_from(self.config.boll_window).unwrap_or(200),
)
.await?;
let closes = closes_of(&candles);
let Some(bands) = BollingerBands::compute(&closes, self.config.boll_mult) else {
tracing::debug!("boll-grid warmup incomplete");
return Ok(());
};
let Some(close) = closes.last().copied() else {
return Ok(());
};
cancel_all_orders(self.gateway.as_ref(), &exchange.clone(), &self.config.common.symbol)
.await?;
for (price, is_buy) in plan_ladder(close, &bands, self.config.grid_num) {
let coid = format!("bollgrid-{}", ulid::Ulid::generate());
let request = limit_order(
&exchange,
&self.config.common.symbol,
coid,
is_buy,
price,
self.config.qty,
);
self.gateway.create_order(request).await?;
}
Ok(())
}
}
#[async_trait]
impl Strategy for BollGrid {
async fn run(&self) -> Result<()> {
let poll = std::time::Duration::from_secs(self.config.common.poll_secs.max(1));
loop {
if let Err(err) = self.tick().await {
tracing::error!(error = %err, "boll-grid tick failed");
}
tokio::time::sleep(poll).await;
}
}
}
#[cfg(test)]
mod tests {
use async_trait::async_trait;
use proptest::prelude::*;
use super::*;
use crate::{
adapters::MockAdapter,
ports::{MarketEventStream, OverflowPolicy, PortError},
proto::{market, trading},
};
#[test]
fn ladder_plans_both_sides_inside_bands() {
let bands = Bands { middle: dec!(100), upper: dec!(120), lower: dec!(80) };
let plan = plan_ladder(dec!(100), &bands, 3);
assert_eq!(
plan,
vec![(dec!(90), true), (dec!(110), false), (dec!(80), true), (dec!(120), false),]
);
}
#[test]
fn ladder_drops_levels_outside_bands() {
let bands = Bands { middle: dec!(100), upper: dec!(105), lower: dec!(95) };
let plan = plan_ladder(dec!(100), &bands, 2);
assert_eq!(plan.len(), 2);
assert_eq!(plan[0].1, true);
assert_eq!(plan[1].1, false);
}
#[test]
fn ladder_skips_when_close_outside_bands() {
let bands = Bands { middle: dec!(100), upper: dec!(110), lower: dec!(90) };
assert!(plan_ladder(dec!(120), &bands, 3).is_empty());
assert!(plan_ladder(dec!(80), &bands, 3).is_empty());
}
#[test]
fn config_parses_from_params_table() {
let table: toml::Table =
toml::from_str("symbol = \"BTCUSDT\"\ngrid_num = 4\nqty = \"0.01\"")
.expect("valid toml");
let cfg = BollGridConfig::from_params(&table).expect("parse");
assert_eq!(cfg.grid_num, 4);
assert_eq!(cfg.qty.to_string(), "0.01");
}
#[test]
fn an_absurd_grid_num_is_refused_naming_the_ceiling() {
let table: toml::Table =
toml::from_str("symbol = \"BTCUSDT\"\ngrid_num = 4294967295").expect("valid toml");
let err = BollGridConfig::from_params(&table).expect_err("u32::MAX levels is not a ladder");
let message = err.to_string();
assert!(message.contains("200"), "the error must name the ceiling: {message}");
assert!(message.contains("4294967295"), "the error must echo the value: {message}");
}
#[test]
fn a_grid_num_at_the_ceiling_is_accepted() {
let table: toml::Table =
toml::from_str("symbol = \"BTCUSDT\"\ngrid_num = 200").expect("valid toml");
assert_eq!(BollGridConfig::from_params(&table).expect("parse").grid_num, 200);
}
#[test]
fn a_zero_grid_num_plans_nothing() {
let bands = Bands { middle: dec!(100), upper: dec!(120), lower: dec!(80) };
assert!(plan_ladder(dec!(100), &bands, 0).is_empty());
}
#[test]
fn a_non_positive_band_width_plans_nothing() {
let collapsed = Bands { middle: dec!(100), upper: dec!(100), lower: dec!(100) };
assert!(plan_ladder(dec!(100), &collapsed, 4).is_empty());
let inverted = Bands { middle: dec!(100), upper: dec!(80), lower: dec!(120) };
assert!(plan_ladder(dec!(100), &inverted, 4).is_empty());
}
#[test]
fn the_band_edges_are_inclusive_on_both_sides() {
let bands = Bands { middle: dec!(100), upper: dec!(120), lower: dec!(80) };
assert_eq!(
plan_ladder(dec!(120), &bands, 3),
vec![(dec!(110), true), (dec!(100), true), (dec!(90), true)]
);
assert_eq!(
plan_ladder(dec!(80), &bands, 3),
vec![(dec!(90), false), (dec!(100), false), (dec!(110), false)]
);
}
#[test]
fn non_positive_bids_are_dropped() {
let bands = Bands { middle: dec!(5), upper: dec!(15), lower: dec!(-5) };
assert_eq!(plan_ladder(dec!(5), &bands, 3), vec![(dec!(10), false), (dec!(15), false)]);
}
#[test]
fn the_level_count_never_exceeds_two_entries_per_grid_level() {
let bands = Bands { middle: dec!(1000), upper: dec!(1999), lower: dec!(1) };
for grid_num in 0..=6u32 {
let plan = plan_ladder(dec!(1000), &bands, grid_num);
let per_side = usize::try_from(grid_num).expect("u32 fits usize");
let buys = plan.iter().filter(|(_, is_buy)| *is_buy).count();
assert!(buys <= per_side, "grid_num {grid_num} produced {buys} bids");
assert!(plan.len() - buys <= per_side, "grid_num {grid_num} produced too many asks");
}
}
#[test]
fn each_level_contributes_a_bid_below_and_an_ask_above_the_close() {
let bands = Bands { middle: dec!(100), upper: dec!(120), lower: dec!(80) };
let plan = plan_ladder(dec!(100), &bands, 3);
assert!(!plan.is_empty(), "a ladder inside the bands must plan something");
for (price, is_buy) in &plan {
if *is_buy {
assert!(*price < dec!(100), "a bid must be below the close: {price}");
} else {
assert!(*price > dec!(100), "an ask must be above the close: {price}");
}
}
assert!(
plan.iter().any(|(price, is_buy)| *is_buy && *price > dec!(80)),
"the ladder must reach the bid band: {plan:?}"
);
assert!(
plan.iter().any(|(price, is_buy)| !*is_buy && *price < dec!(120)),
"the ladder must reach the ask band: {plan:?}"
);
}
fn grid_config() -> BollGridConfig {
let table: toml::Table = toml::from_str(
"symbol = \"BTC/USDT\"\nboll_window = 20\nboll_mult = \"2\"\n\
grid_num = 3\nqty = \"0.01\"\n",
)
.expect("valid toml");
BollGridConfig::from_params(&table).expect("parse")
}
fn grid_over_closes(closes: &[Decimal]) -> (Arc<MockAdapter>, BollGrid) {
let adapter = Arc::new(MockAdapter::new(dec!(100)));
let gateway: Arc<dyn TradingGateway> = adapter.clone();
let market: Arc<dyn MarketDataSource> = Arc::new(ScriptedCandles(closes.to_vec()));
(adapter, BollGrid::new(grid_config(), gateway, market))
}
async fn resting_orders(adapter: &MockAdapter) -> Vec<trading::Order> {
adapter
.fetch_open_orders(trading::FetchOpenOrdersRequest::default())
.await
.expect("test setup")
}
#[tokio::test]
async fn a_band_with_width_quotes_the_planned_ladder() {
let (adapter, grid) = grid_over_closes(&[dec!(90), dec!(100), dec!(110)]);
grid.tick().await.expect("quoted");
assert!(
!resting_orders(&adapter).await.is_empty(),
"a band with width must produce quotes for this assertion to mean anything"
);
}
#[tokio::test]
async fn a_refused_ladder_leg_propagates_out_of_the_tick() {
let (adapter, grid) = grid_over_closes(&[dec!(90), dec!(100), dec!(110)]);
adapter.fail_next_creates(1).await;
let err = grid.tick().await.expect_err("a refused leg must not read as a full ladder");
assert!(err.to_string().contains("scripted failure"), "{err}");
assert!(resting_orders(&adapter).await.is_empty(), "the refused leg must not rest");
}
struct ScriptedCandles(Vec<Decimal>);
#[async_trait]
impl MarketDataSource for ScriptedCandles {
async fn get_candles(
&self,
_req: market::GetCandlesRequest,
) -> Result<market::GetCandlesResponse, PortError> {
Ok(market::GetCandlesResponse {
candles: self
.0
.iter()
.map(|close| market::Candle {
close: buffa::MessageField::some(
longtrader_contract::ext::decimal_to_common(*close),
),
..Default::default()
})
.collect(),
..Default::default()
})
}
async fn fetch_ticker(
&self,
_req: market::FetchTickerRequest,
) -> Result<market::Ticker, PortError> {
Err(PortError::Unsupported("fetch_ticker".into()))
}
async fn fetch_order_book(
&self,
_req: market::FetchOrderBookRequest,
) -> Result<market::OrderBook, PortError> {
Err(PortError::Unsupported("fetch_order_book".into()))
}
async fn list_symbols(
&self,
_req: market::ListSymbolsRequest,
) -> Result<market::ListSymbolsResponse, PortError> {
Err(PortError::Unsupported("list_symbols".into()))
}
async fn search_symbols(
&self,
_req: market::SearchSymbolsRequest,
) -> Result<market::SearchSymbolsResponse, PortError> {
Err(PortError::Unsupported("search_symbols".into()))
}
async fn list_tickers(
&self,
_req: market::ListTickersRequest,
) -> Result<market::ListTickersResponse, PortError> {
Err(PortError::Unsupported("list_tickers".into()))
}
async fn subscribe_market_data(
&self,
_req: market::StreamMarketDataRequest,
_policy: OverflowPolicy,
) -> Result<MarketEventStream, PortError> {
Err(PortError::Unsupported("subscribe_market_data".into()))
}
}
#[tokio::test]
async fn a_flat_close_series_collapses_the_bands_and_quotes_nothing() {
let (adapter, grid) = grid_over_closes(&[dec!(100); 5]);
grid.tick().await.expect("a collapsed ladder is not a failure");
assert!(resting_orders(&adapter).await.is_empty(), "a zero-width band must not quote");
}
#[tokio::test]
async fn a_candle_feed_failure_propagates_out_of_the_tick() {
let adapter = Arc::new(MockAdapter::new(dec!(100)));
let gateway: Arc<dyn TradingGateway> = adapter.clone();
let market: Arc<dyn MarketDataSource> = Arc::new(FailingCandles);
let grid = BollGrid::new(grid_config(), gateway, market);
let err = grid.tick().await.expect_err("a broken feed must not read as a quiet tick");
assert!(err.to_string().contains("candle feed down"), "{err}");
}
struct FailingCandles;
#[async_trait]
impl MarketDataSource for FailingCandles {
async fn fetch_ticker(
&self,
_req: market::FetchTickerRequest,
) -> Result<market::Ticker, PortError> {
Err(PortError::Transport("ticker feed down".into()))
}
async fn fetch_order_book(
&self,
_req: market::FetchOrderBookRequest,
) -> Result<market::OrderBook, PortError> {
Err(PortError::Transport("book feed down".into()))
}
async fn get_candles(
&self,
_req: market::GetCandlesRequest,
) -> Result<market::GetCandlesResponse, PortError> {
Err(PortError::Transport("candle feed down".into()))
}
async fn list_symbols(
&self,
_req: market::ListSymbolsRequest,
) -> Result<market::ListSymbolsResponse, PortError> {
Err(PortError::Transport("symbol feed down".into()))
}
async fn search_symbols(
&self,
_req: market::SearchSymbolsRequest,
) -> Result<market::SearchSymbolsResponse, PortError> {
Err(PortError::Transport("symbol feed down".into()))
}
async fn list_tickers(
&self,
_req: market::ListTickersRequest,
) -> Result<market::ListTickersResponse, PortError> {
Err(PortError::Transport("ticker feed down".into()))
}
async fn subscribe_market_data(
&self,
_req: market::StreamMarketDataRequest,
_policy: OverflowPolicy,
) -> Result<MarketEventStream, PortError> {
Err(PortError::Unsupported("no stream".into()))
}
}
proptest! {
#![proptest_config(ProptestConfig::with_cases(256))]
#[test]
fn every_level_is_positive_in_band_and_on_its_side_of_the_close(
lower_milli in 1i64..100_000,
width_milli in 1i64..100_000,
offset_micro in 0i64..1_000_001,
grid_num in 0u32..8,
) {
let lower = Decimal::new(lower_milli, 3);
let upper = lower + Decimal::new(width_milli, 3);
let middle = (lower + upper) / dec!(2);
let bands = Bands { middle, upper, lower };
let span = upper - lower;
let close = lower + span * Decimal::new(offset_micro, 6);
if close > upper || close < lower {
return Ok(());
}
let plan = plan_ladder(close, &bands, grid_num);
let bound = usize::try_from(grid_num).expect("u32 fits usize") * 2;
prop_assert!(plan.len() <= bound, "grid_num {grid_num} produced {} levels", plan.len());
for (price, is_buy) in &plan {
prop_assert!(*price > Decimal::ZERO, "{price} is not a tradable price");
prop_assert!(
*price >= lower && *price <= upper,
"{price} escaped [{lower}, {upper}]"
);
prop_assert_eq!(*is_buy, *price < close, "side must follow the side of {}", close );
}
}
#[test]
fn bids_descend_and_asks_ascend(
lower_milli in 1i64..50_000,
width_milli in 1i64..50_000,
offset_micro in 0i64..1_000_001,
grid_num in 1u32..8,
) {
let lower = Decimal::new(lower_milli, 3);
let upper = lower + Decimal::new(width_milli, 3);
let middle = (lower + upper) / dec!(2);
let bands = Bands { middle, upper, lower };
let span = upper - lower;
let close = lower + span * Decimal::new(offset_micro, 6);
if close > upper || close < lower {
return Ok(());
}
let plan = plan_ladder(close, &bands, grid_num);
let bids: Vec<Decimal> =
plan.iter().filter(|(_, buy)| *buy).map(|(p, _)| *p).collect();
let asks: Vec<Decimal> =
plan.iter().filter(|(_, buy)| !*buy).map(|(p, _)| *p).collect();
prop_assert!(
bids.windows(2).all(|w| w[0] > w[1]),
"bids must descend: {bids:?}"
);
prop_assert!(
asks.windows(2).all(|w| w[0] < w[1]),
"asks must ascend: {asks:?}"
);
prop_assert!(
bids.iter().all(|p| *p < close),
"a bid at or above {close} would cross the close"
);
prop_assert!(asks.iter().all(|p| *p > close), "an ask at or below {close} would cross");
}
#[test]
fn a_non_positive_width_always_plans_nothing(
lower_milli in 1i64..10_000,
width_delta in -10_000i64..10_000,
grid_num in 0u32..6,
) {
let lower = Decimal::new(lower_milli, 3);
let upper = lower + Decimal::new(width_delta, 3);
if upper > lower {
return Ok(());
}
let bands = Bands { middle: lower, upper, lower };
prop_assert!(
plan_ladder(lower, &bands, grid_num).is_empty(),
"width {} must not be laddered", upper - lower
);
}
}
}