feat(stitch): add configurable repost lead time for order overlap

- Add `repost_lead_secs` configuration option to control when sides repost before expiry, ensuring replacement orders overlap with live orders instead of leaving gaps
- Introduce `DEFAULT_REPOST_LEAD_SECS` constant set to 60 seconds, sized to clear the indexer's deadline margin plus web poll time
- Update `requote_age_secs()` to accept repost lead parameter and cap it at half the TTL to prevent misconfiguration from causing excessive re-signing
- Refactor `should_requote_now()` to use the new repost lead logic instead of fixed two-thirds TTL calculation
- Add comprehensive test coverage for repost timing with various lead and TTL configurations
- Update example configuration with documentation on repost lead semantics and the relationship between TTL and lead time
- Bump version to 0.1.27

Author: bnolens

.textile-monorepo-source

@@ -1 +1 @@
-70c55cb34fd82fcc9137fb6a693141001ba5309b
+33e93aff140e6a7964f4532446bb31871c98231f

.textile-stitch-release-version

@@ -1 +1 @@
-0.1.26
+0.1.27

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "stitch-bot"
-version = "0.1.26"
+version = "0.1.27"
 edition = "2021"
 description = "Stitch — Textile filler-network operator bot; signs UniswapX limit orders and closes settlement auctions."
 license = "AGPL-3.0-or-later"

Cargo.toml

@@ -12,6 +12,14 @@ use crate::quote::Spread;
 pub const MAX_SUPPORTED_LADDER_ORDERS: u32 = 40;
 pub const DEFAULT_MAX_LADDER_ORDERS: u32 = MAX_SUPPORTED_LADDER_ORDERS;
 
+/// Default seconds before a live order's deadline at which the bot reposts its
+/// side, so the replacement overlaps the old order instead of leaving a gap.
+/// Sized to clear the indexer's order-deadline margin (30s) plus the ~15s web
+/// poll with headroom, so the live order book never blanks between reposts.
+/// Effective overlap is capped at half the TTL (see `requote_age_secs`), so
+/// keep `ttl_secs ≥ 2 × repost_lead_secs` to get the full lead.
+pub const DEFAULT_REPOST_LEAD_SECS: u64 = 60;
+
 #[derive(Debug, Clone, Deserialize)]
 pub struct Config {
     pub chain_id: u64,
@@ -109,6 +117,11 @@ pub struct PoolConfig {
 
     /// Order lifetime.
     pub ttl_secs: u64,
+    /// Repost a side this many seconds before its live order expires, so the
+    /// replacement overlaps the old order rather than leaving a book gap.
+    /// Capped at half the TTL. Defaults to `DEFAULT_REPOST_LEAD_SECS`.
+    #[serde(default)]
+    pub repost_lead_secs: Option<u64>,
     /// Re-sign a side when its price moves more than this since its last order.
     pub refresh_threshold_bps: u32,
 
@@ -151,6 +164,10 @@ fn spread_from(bps: Option<u32>, abs: Option<f64>) -> Option<Spread> {
 }
 
 impl PoolConfig {
+    /// Seconds before expiry at which this side reposts, with the default applied.
+    pub fn repost_lead_secs(&self) -> u64 {
+        self.repost_lead_secs.unwrap_or(DEFAULT_REPOST_LEAD_SECS)
+    }
     /// The bid spread for this pool, however the operator expressed it.
     pub fn buy_spread(&self) -> Option<Spread> {
         spread_from(self.buy_offset_bps, self.buy_offset_abs)

src/config.rs

@@ -537,6 +537,7 @@ async fn run(config_path: String, dry_run: bool) -> anyhow::Result<()> {
                     pool.refresh_threshold_bps,
                     now,
                     pool.ttl_secs,
+                    pool.repost_lead_secs(),
                 ) {
                     let sizes = if pool.buy_ladder_enabled() {
                         match (
@@ -605,6 +606,7 @@ async fn run(config_path: String, dry_run: bool) -> anyhow::Result<()> {
                     pool.refresh_threshold_bps,
                     now,
                     pool.ttl_secs,
+                    pool.repost_lead_secs(),
                 ) {
                     let sizes = if pool.sell_ladder_enabled() {
                         match (

src/main.rs

@@ -22,30 +22,43 @@ pub fn should_requote(last_bid: Option<f64>, new_bid: f64, threshold_bps: u32) -
 }
 
 /// True when a side's order should be re-signed: no prior order, the price
-/// moved at least `threshold_bps`, or the last post is late enough in its TTL so a
-/// replacement lands before the live order expires. The age gate keeps a stable
-/// market from going dark when the price-move gate alone would never fire before
-/// the TTL lapses, but waits until two-thirds of the TTL to limit how long old
-/// signed orders overlap with their replacements. `last` is
+/// moved at least `threshold_bps`, or the last post is old enough that a
+/// replacement should land while the live order still has `repost_lead_secs` of
+/// life. The age gate keeps a stable market from going dark when the price-move
+/// gate alone would never fire before the TTL lapses. `last` is
 /// `(price, posted_at_unix)`.
 pub fn should_requote_now(
     last: Option<(f64, u64)>,
     new_bid: f64,
     threshold_bps: u32,
     now: u64,
     ttl_secs: u64,
+    repost_lead_secs: u64,
 ) -> bool {
     match last {
         None => true,
         Some((prev, posted_at)) => {
-            let aged = now.saturating_sub(posted_at) >= requote_age_secs(ttl_secs);
+            let aged =
+                now.saturating_sub(posted_at) >= requote_age_secs(ttl_secs, repost_lead_secs);
             aged || should_requote(Some(prev), new_bid, threshold_bps)
         }
     }
 }
 
-fn requote_age_secs(ttl_secs: u64) -> u64 {
-    ttl_secs.saturating_mul(2) / 3
+/// The order age at which a side reposts: `ttl_secs - repost_lead_secs`, so the
+/// replacement is signed while the live order still has `repost_lead_secs` of
+/// life and the two overlap instead of leaving a gap.
+///
+/// The lead is capped at half the TTL. That cap is a safety floor against a
+/// large or misconfigured lead driving the repost age to zero (which would
+/// re-sign the whole ladder every tick), but it has a cost: below `ttl ≈ 2 ×
+/// lead` the effective overlap is `ttl/2`, not the configured lead. So as the
+/// TTL drops the gap-free margin shrinks back toward the indexer's deadline
+/// margin. Keep `ttl_secs ≥ 2 × repost_lead_secs` to actually get the lead you
+/// asked for.
+fn requote_age_secs(ttl_secs: u64, repost_lead_secs: u64) -> u64 {
+    let lead = repost_lead_secs.min(ttl_secs / 2);
+    ttl_secs.saturating_sub(lead)
 }
 
 #[cfg(test)]
@@ -70,15 +83,38 @@ mod tests {
 
     #[test]
     fn requotes_near_expiry_even_when_price_is_flat() {
+        // 30s TTL, 10s lead → repost at age 20 (30 - 10).
         // First quote always.
-        assert!(should_requote_now(None, 1.0, 10, 0, 30));
-        // 5s into a 30s TTL, flat price → not yet.
-        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 5, 30));
-        // 15s in, flat price → wait to reduce old/new signed-order overlap.
-        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 15, 30));
-        // 20s in (two-thirds of TTL), flat price → re-quote to avoid a gap.
-        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 20, 30));
+        assert!(should_requote_now(None, 1.0, 10, 0, 30, 10));
+        // 5s into the TTL, flat price → not yet.
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 5, 30, 10));
+        // 15s in, flat price → still before the repost age.
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 15, 30, 10));
+        // 20s in (lead before expiry), flat price → re-quote to avoid a gap.
+        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 20, 30, 10));
         // A big move still re-quotes before the age gate.
-        assert!(should_requote_now(Some((1.0, 0)), 1.002, 10, 1, 30));
+        assert!(should_requote_now(Some((1.0, 0)), 1.002, 10, 1, 30, 10));
+    }
+
+    #[test]
+    fn lead_time_sets_repost_age_and_clamps_at_half_ttl() {
+        // ttl 240, lead 60 → repost at age 180 (240 - 60), 60s overlap.
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 179, 240, 60));
+        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 180, 240, 60));
+
+        // The clamp: an oversized lead is capped at ttl/2, so the repost age
+        // never collapses toward zero. ttl 120, lead 1000 → age 60, not 0.
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 59, 120, 1000));
+        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 60, 120, 1000));
+
+        // The cost of the clamp: at ttl = 2 × lead the overlap is exactly the
+        // lead; below that it silently shrinks to ttl/2. ttl 90, lead 60 → the
+        // lead is capped to 45, so the real overlap is 45s, not 60s.
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 44, 90, 60));
+        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 45, 90, 60));
+
+        // Zero lead → repost only at the deadline (age == ttl).
+        assert!(!should_requote_now(Some((1.0, 0)), 1.0, 10, 239, 240, 0));
+        assert!(should_requote_now(Some((1.0, 0)), 1.0, 10, 240, 240, 0));
     }
 }

src/tick.rs

@@ -46,6 +46,10 @@ sell_min_slice_debt = "10000000"                # 10 USDC-equivalent smallest sl
 sell_max_orders = 40
 
 ttl_secs = 30
+# repost_lead_secs = 60   # repost each side this many secs before its order
+                          # expires, so the new ladder overlaps the old one and
+                          # the book never blanks between reposts. Capped at
+                          # ttl/2, so keep ttl_secs >= 2 x this. Defaults to 60.
 refresh_threshold_bps = 10  # re-quote a side when its price moves >0.10%
 
 # ----- Blue leg (auction closer). Set these to also close this pool's