Tesser RFC-001: Native Multi-Exchange Architecture & Symbol Reification

[EwigMidori]

Tesser RFC-001: Native Multi-Exchange Architecture & Symbol Reification

Metadata	Detail
Status	Done in #79 v0.9.1
Type	Breaking Architectural Change
Objective	Enable cross-exchange arbitrage, hedging, and global liquidity aggregation.

---

1. Summary

This RFC proposes a foundational refactoring of Tesser's type system and runtime architecture. We will transition from a string-based, single-venue model to a strongly-typed, multi-venue federated architecture.

Currently, Symbol is an alias for String. This prevents the type system from distinguishing between BTCUSDT on Binance and BTCUSDT on Bybit. By reifying Symbol, ExchangeId, and AssetId into distinct types, and introducing a Routing Layer, we will enable institutional-grade strategies (e.g., triangular arbitrage, basis trading) while eliminating entire classes of runtime errors.

Note: As Tesser is pre-production, this refactor will not prioritize backward compatibility. We will prioritize correctness and type safety.

---

2. Core Type System Overhaul (tesser-core)

The primitive String types currently used for identifiers must be replaced with structured types that carry context.

2.1 ExchangeId

A lightweight, Copy-able identifier for physical execution venues.

• Implementation: Newtype wrapper around u8 or u16.
• Mapping: A static registry maps string identifiers (e.g., "binance_perp") to IDs at runtime startup.
• Motivation: Enables O(1) routing decisions and hash map lookups without heap allocations.

2.2 AssetId

Assets must be scoped to their custody location (the exchange) or chain, not treated as global platonic ideals.

• Definition: struct AssetId { exchange: ExchangeId, inner: u32 } (where inner maps to an interned string like "USDT").
• Rule: AssetId(Binance, USDT) != AssetId(Bybit, USDT).
• Impact: Prevents logic errors where a strategy attempts to use Binance collateral to fund a Bybit order.

2.3 Symbol (The Breaking Change)

The Symbol type alias becomes a struct.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Symbol {
    pub exchange: ExchangeId,
    /// Internal unique ID for O(1) lookup in MarketRegistry
    pub market_id: u32, 
}

// Display implementation should return "EXCHANGE:INSTRUMENT" (e.g., "BINANCE:BTCUSDT")
impl std::fmt::Display for Symbol { ... }

---

3. The Virtualized Broker Layer (tesser-broker)

We will implement the Composite Pattern. The strategy interaction layer remains unchanged (ExecutionClient trait), but the implementation changes from a direct connector to a Router.

3.1 The Router (RouterExecutionClient)

This component holds a map of ExchangeId -> Arc<dyn ExecutionClient>.

• Order Routing:
  1. Receive place_order(request).
  2. Inspect request.symbol.exchange.
  3. Dispatch to the specific connector.
• ID Namespacing (Critical Corner Case):
  • Problem: Two exchanges might generate colliding Order IDs, or accept the same Client ID causing confusion in the internal state map.
  • Solution: The Router must perform ID Translation.
    • Internal ID: UUID (Globally unique).
    • External ID: The router prefixes IDs sent to exchanges (e.g., TESSER_{InternalUUID}).
    • Inbound Mapping: When a fill comes back, the Router strips the prefix/maps it back to the Internal ID before passing it to the Strategy.

3.2 Unified Market Stream (RouterMarketStream)

• Architecture: Spawns N WebSocket tasks (one per exchange).
• Aggregation: Uses a MPSC channel to fan-in Tick, Candle, and OrderBook events.
• No Time Sorting: Events are processed in arrival order. Do not attempt to sort by exchange_timestamp across venues, as clock drift and network jitter will introduce unacceptable latency or stalled streams.

---

4. Portfolio Isolation (tesser-portfolio)

The Portfolio struct must transition from a "Global Wallet" to a "Federation of Wallets".

4.1 Hierarchical Accounting

Currently, Tesser assumes a single pool of USDT. This is dangerous for cross-exchange trading.

New Structure:

pub struct Portfolio {
    // Primary storage: Partitioned by Exchange
    sub_accounts: HashMap<ExchangeId, SubAccount>,
    // ...
}

pub struct SubAccount {
    balances: HashMap<AssetId, Balance>,
    positions: HashMap<Symbol, Position>,
}

4.2 Risk Management Implications

PreTradeRiskChecker must be updated to be Venue-Aware.

• Check 1 (Solvency): Does Binance have enough USDT for this buy order? (Hard constraint).
• Check 2 (Global Risk): Does the Total Portfolio Equity support this leverage? (Soft constraint / Policy).
• Corner Case: A strategy might be "Market Neutral" globally (Long A, Short B), but if Exchange B goes down, the portfolio becomes legally naked Long on Exchange A. The Risk engine must track "Gross Exposure per Venue".

---

5. Corner Cases & Safety Mechanisms

5.1 The "Legging" Risk (Atomic Failure)

In cross-exchange arbitrage, if one leg fills and the other fails, the system enters a toxic state.

• Mitigation: The OrderOrchestrator needs a new primitive: ExecutionGroup.
• Logic: If Leg A fills but Leg B is rejected/times out:
  1. Immediate Fail-safe: Fire a Market Order to close Leg A (Panic Close).
  2. Alerting: Trigger Critical alert level (PagerDuty).

5.2 Precision Mismatches

When arbitraging BTCUSDT on Binance vs Bybit:

• Binance Tick Size: 0.1, Lot Size: 0.001
• Bybit Tick Size: 0.5, Lot Size: 0.01
• Logic: The strategy must calculate the Greatest Common Divisor (GCD) of the constraints. The MarketRegistry must expose a normalize_quantity(symbol_a, symbol_b, qty) helper that rounds down to the coarsest granularity of both venues.

5.3 Fee Currency Ambiguity

• Scenario: Binance deducts fees in BNB (if enabled), Bybit deducts in USDT (Linear) or BTC (Inverse).
• Requirement: The Fill event structure must include fee_asset: AssetId. The Portfolio must support negative balances in fee assets temporarily if the exchange allows it, or correctly deduct from the specific asset balance.

---

6. Implementation Plan

Phase 1: Type System & Config

• Goal: Compilation succeeds with new types.
• Tasks:
  1. Create ExchangeId enum/struct in tesser-core.
  2. Convert Symbol type alias to struct.
  3. Update tesser-config to accept [[exchanges]] list instead of single table.
  4. Run global search-and-replace for String-based symbols and fix compilation errors.

Phase 2: Registry & Static Data

• Goal: Application boots and loads metadata from multiple sources.
• Tasks:
  1. Update MarketRegistry to store (ExchangeId, SymbolStr) -> Instrument.
  2. Implement InstrumentInfo merging logic.

Phase 3: The Router & Execution

• Goal: Can place orders on two Mock Exchanges simultaneously.
• Tasks:
  1. Implement RouterExecutionClient.
  2. Implement RouterMarketStream.
  3. Refactor Portfolio to support SubAccount isolation.
  4. Update tesser-test-utils to spin up multiple mock exchange instances.

Phase 4: Strategy Adaptation

• Goal: PairsTrading strategy runs on the new architecture.
• Tasks:
  1. Update Strategy::subscriptions() to return Vec<Symbol> structs.
  2. Update StrategyContext to provide lookup by Symbol struct.
  3. Refactor PairsTradingArbitrage to use explicit exchange targets.

---

7. Future Implications

This architecture paves the way for:

1. Smart Order Routing (SOR): Automatically routing a "Buy BTC" signal to the exchange with the best price/liquidity.
2. HFT Capabilities: Since Symbol is now a struct with an integer ID, we can replace HashMaps with Vec-based direct indexing in the hot path for extreme performance.
3. Unified Book Building: Merging L2 data from multiple exchanges into a single "Global Best Bid/Offer" (GBBO).

[EwigMidori]

#79