config.hpp

Go to the documentation of this file.

#pragma once
// Typed configuration (8.7). TOML parsing lives in src/core/config.cpp (toml++ is a
// private dependency of fastmm_core); this header exposes only plain structs.
//
// Sections: [engine] [venues.<x>] [venues.<x>.fees] [[instruments]] [strategy]
//           [strategy.params] [risk] [gateway] [accounting] [accounting.fx] [logging] [sim]
//           [backtest] [storage]
// A [venues.<x>] key the generic parser does not read is kept verbatim in VenueSection::extra:
// the connector `kind` names owns it (include/fastmm/venues/registry.hpp).
// Rules: ${VAR} is substituted only inside [venues.*] strings; a value that looks like an
// inline secret (> 32 chars, no ${) is rejected unless allow_inline_secrets; redacted()
// prints the config with secrets masked; validation errors carry line:col.
#include "fastmm/core/account_pool.hpp"
#include "fastmm/core/balance_book.hpp"
#include "fastmm/core/enums.hpp"
#include "fastmm/core/fees.hpp"
#include "fastmm/core/fx.hpp"
#include "fastmm/core/instrument.hpp"
#include "fastmm/core/perp_book.hpp"
#include "fastmm/core/quote_manager.hpp"
#include "fastmm/core/risk.hpp"
#include "fastmm/core/thread_utils.hpp"
#include "fastmm/core/treasury.hpp"
#include "fastmm/core/underlying.hpp"
#include "fastmm/strategies/params.hpp"
 
#include <cstdint>
#include <map>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace fastmm {
 
inline constexpr std::size_t kMaxVenuesConfig = 8;  // == kMaxVenues (transport.hpp)
// The shortest [venues.<name>] fill_audit_interval_s: an audit reads every subscribed symbol.
inline constexpr int kMinFillAuditIntervalS = 10;
 
class ConfigError : public std::runtime_error {
 public:
  ConfigError(const std::string& msg, int line = 0, int col = 0)
      : std::runtime_error(line > 0 ? msg + " (line " + std::to_string(line) + ":" +
                                          std::to_string(col) + ")"
                                    : msg),
        line_(line),
        col_(col) {}
  [[nodiscard]] int line() const noexcept { return line_; }
  [[nodiscard]] int col() const noexcept { return col_; }
 
 private:
  int line_;
  int col_;
};
 
struct EngineSection {
  std::string name = "fastmm";
  int cpu = -1;
  std::vector<int> net_cpus;
  std::string spin_mode = "adaptive";
  // Carry the previous session's positions over from the store (venues that replay executions).
  bool restore_position = true;
  std::string net_backend = "epoll";  // net::Reactor backend: "epoll" | "io_uring"
  // fastmm-live: "split" runs the engine and each venue's network loop on their own threads;
  // "single" runs the one venue's network loop, the engine and order sending on the engine thread.
  std::string threading = "split";
  bool journal = true;
  std::string journal_dir = "runs";
  std::string journal_sync = "async";  // "async" | "fdatasync" (core/journal.hpp)
  std::size_t journal_max_bytes = 0;   // roll over to the next part at this size (0: never)
  int journal_retention_days = 0;      // delete .fmj files older than this at start (0: keep)
  std::string epoch_file = "runs/session_epoch";
  // Latched kill switch and cumulative PnL; empty = "<journal_dir>/<name>.kill".
  std::string kill_file;
  // fastmm-live: an exclusive flock(2) on lock_file (empty = "<journal_dir>/<name>.lock") taken
  // before the session touches the account, so one process of this engine name trades at a time
  // (live/instance_lock.hpp). --standby and --takeover take it whatever this says.
  bool instance_lock = false;
  std::string lock_file;
  // --takeover: how long the new process waits for the running one to release the lock after it
  // accepted `handoff`, ms.
  int handoff_timeout_ms = 75'000;
  std::uint64_t rng_seed = 1;
  std::size_t md_ring_bytes = 4U << 20;
  std::size_t order_ring_bytes = 1U << 20;
  std::size_t journal_ring_bytes = 16U << 20;
  std::uint32_t max_events_per_step = 64;
  std::uint32_t feed_budget_per_ring = 64;  // RingFeed: events per ring before the next one's turn
  // Adaptive: a network thread alone on its pinned core never blocks (net_never_blocks).
  bool net_spin_dedicated = false;
  int crossed_grace_ms = 100;
  int ack_timeout_ms = 0;  // force-cancel an order without an ack after this long; 0 = off
  // Operator flatten (fastmm-ctl flatten): the sweep period, how long the engine keeps working the
  // position off (0 = until it is flat or an operator stops it) and the default slippage.
  int flatten_interval_ms = 500;
  int flatten_timeout_ms = 60000;
  int flatten_slippage_bps = 25;
  double queue_conservatism = 1.0;  // queue position estimate (ctx.queue_ahead), 0..1
  int latency_publish_ms = 1000;
  int tsc_recalibrate_s = 10;       // fastmm-live: TSC recalibration period, 0 = never
  std::int64_t timer_slack_ns = 0;  // fastmm-live: PR_SET_TIMERSLACK of its threads, 0 = kernel's
  bool lock_memory = false;         // fastmm-live: mlockall(MCL_CURRENT | MCL_FUTURE)
  // fastmm-live: PM QoS CPU latency request (/dev/cpu_dma_latency) held for the session, us;
  // -1 = none.
  int cpu_dma_latency_us = -1;
  // fastmm-live: SCHED_FIFO priority of the engine thread and of the network threads, 0 = off.
  int rt_priority = 0;
  int net_rt_priority = 0;
  // fastmm-live: log the NICs' interrupt CPUs against the pinned ones.
  bool log_irq_affinity = false;
  int min_requote_ticks = 1;
  int min_requote_interval_ms = 50;
  int min_qty_bps = 8000;
  bool post_only = true;
  bool supports_replace = true;
  int reject_backoff_ms = 1000;       // QuoteManager: pause a side after a venue reject (0 = off)
  int reject_backoff_max_ms = 60000;  // doubling cap
  int quote_token_reserve = 0;        // [risk] order tokens quotes that add risk leave to others
  // fastmm-live after a kill switch it did not ask for (risk limit, internal failure, every venue
  // killed): "exit" shuts down like SIGTERM and exits with code 6; "stay" keeps running with
  // quoting off and logs an ERROR line every 10 s.
  std::string on_kill = "exit";
};
 
struct FeesSection {
  double maker_bps = 0.0;
  double taker_bps = 0.0;
};
 
// [venues.<primary>.treasury]: the pool treasury of an account pool's primary
// (core/treasury.hpp). Decimals keep their text; Config::treasury_config() makes it typed.
struct TreasurySection {
  bool configured = false;  // the table is present
  bool enabled = false;
  bool dry_run = false;
  std::string asset;
  std::map<std::string, double> weights;        // pool account -> weight (absent: 1)
  std::map<std::string, std::string> min_free;  // pool account -> decimal (absent: 0)
  double threshold = 0.2;
  std::string min_amount = "0";
  std::string max_amount = "0";
  std::string step = "0.01";
  std::int64_t interval_s = 10;
  std::int64_t min_interval_s = 60;
  std::int64_t max_per_hour = 12;
  std::int64_t cooldown_s = 300;
  std::int64_t timeout_s = 60;
  std::int64_t settle_s = 30;
  std::string state_file;  // empty: <journal_dir>/<engine name>.<primary>.treasury
};
 
struct VenueSection {
  std::string name;
  std::string kind;
  std::string ws_url;
  std::string ws_api_url;
  std::string rest_url;
  std::string api_key;
  std::string api_secret;
  std::string api_passphrase;  // OKX: the passphrase chosen with the API key
  bool testnet = true;
  bool supports_replace = false;
  // Market data only: no keys needed, no private sessions, no orders, not awaited at start, not
  // cancelled at stop. For a venue that is only a price leader for a strategy on another venue.
  bool public_only = false;
  // Another account of the venue named: this one takes orders for that venue's instruments with
  // its own keys, balances and order-count windows, and has no instruments or market data of its
  // own (core/account_pool.hpp). Empty: a venue of its own.
  std::string pool_of;
  bool insecure_tls = false;
  std::string ca_file;
  int recv_window_ms = 3000;
  // Where this venue's connections leave the host from: one of its addresses, or the address of a
  // network interface (net/source_address.hpp). Empty: the kernel chooses.
  std::string source_ip;
  std::string source_interface;
  // Fill audit (live/fill_auditor.hpp): every fill_audit_interval_s seconds fastmm-live compares
  // the venue's trade history with the fills the store holds for this venue, up to
  // fill_audit_lag_s ago. 0: off. "report" only reports a difference; "book" also books the
  // executions the engine missed, through the execution replay.
  int fill_audit_interval_s = 0;
  int fill_audit_lag_s = 180;
  std::string fill_audit_mode = "report";
  FeesSection fees;
  TreasurySection treasury;
  // Every key the generic parser does not interpret, stringified. The venue `kind` names owns
  // them: it declares them, validates them and reports an unknown one
  // (fastmm::venues::validate_venues, include/fastmm/venues/registry.hpp), which is why the
  // central schema knows none of them. `extra_lines` is the line each key came from, absent for a
  // key set in code, so the owner can report with a position the way the schema does.
  std::map<std::string, std::string> extra;
  std::map<std::string, int> extra_lines;
};
 
struct InstrumentSection {
  std::string venue;
  std::string symbol;
  std::string base;
  std::string quote;
  std::string asset_class = "spot";
  std::string tick;
  std::string lot;
  std::string min_qty;
  std::string max_qty;
  std::string min_notional;
  std::string contract_multiplier = "1";
  bool enabled = true;
  int price_decimals = 8;
  std::string expiry;
  std::string strike;
  std::string option_type;
  // Per-instrument fee schedule; unset means the instrument pays its venue's [venues.<x>.fees].
  // Positive == a fee, negative == a rebate.
  std::optional<double> maker_bps;
  std::optional<double> taker_bps;
  // A derivative's initial margin, fraction of the notional, decimal; empty: none configured.
  std::string initial_margin;
};
 
struct StrategySection {
  std::string name;
  ParamMap params;
  std::int64_t max_param_age_ms = 0;  // 0 = off
  std::string state_file;             // the strategy's state across sessions; empty: none
  std::int64_t state_interval_s = 300;
  std::int64_t state_snapshot_interval_s = 0;  // journal snapshots of state(); 0: none
};
 
struct RiskSection {
  std::string max_order_qty;
  std::string max_order_notional;
  std::string max_position;
  int max_open_orders = 0;
  int price_collar_bps = 0;
  int fat_finger_bps = 0;
  int stale_md_ms = 0;
  std::string max_loss;
  std::string max_gross_notional;
  std::string max_net_notional;
  int orders_per_sec = 0;
  int burst = 0;
  bool stp = true;
  int max_feed_lag_ms = 0;    // 0 = off
  bool check_balance = true;  // refuse what the venue's balance cannot cover
  // [risk.underlying.<BASE>] max_net: net position per base asset over every instrument, base
  // units.
  UnderlyingSpec underlying;
};
 
// fastmm-gateway's account guards: one venue's account, shared by every attached strategy.
struct GatewaySection {
  int orders_per_sec = 0;         // new orders and replaces per venue, 0 = off
  int burst = 0;                  // token-bucket capacity, 0 = orders_per_sec
  std::string max_open_notional;  // notional working at a venue, decimal; empty = off
  // The account over every attached strategy, decimals in the settlement currency; empty = off.
  std::string max_loss;            // net PnL, carried in <journal_dir>/<name>.kill
  std::string max_gross_notional;  // sum of |position| at the marks
  std::string max_net_notional;    // |signed sum| of the positions at the marks
  // [gateway.underlying.<BASE>] max_net: the account's net position per base asset, base units.
  UnderlyingSpec underlying;
  // [gateway.shared."<venue>:<symbol>"]: an instrument several strategies may trade at once, and
  // the [engine] name of its primary strategy (empty: none), which books the events naming no
  // order.
  std::map<std::string, std::string> shared;
  bool check_balance = true;  // the account's balance covers every strategy's orders
 
  [[nodiscard]] bool any() const noexcept {
    return orders_per_sec != 0 || burst != 0 || !max_open_notional.empty() || !max_loss.empty() ||
           !max_gross_notional.empty() || !max_net_notional.empty() || underlying.configured() ||
           !shared.empty() || !check_balance;
  }
};
 
struct LoggingSection {
  std::string level = "info";
  std::string file;
  std::string mirror_level = "warn";
  // Seconds between the per-venue status lines; 0: none. Unset (-1): every second into a log file,
  // every 10 s when the log is stderr.
  std::int64_t status_interval_s = -1;
};
 
// Free-form section used by the sim / backtest libraries: dotted keys -> stringified value.
struct GenericSection {
  std::map<std::string, std::string> values;
  std::map<std::string, int> lines;  // key -> line in the file; absent for keys set in code
  [[nodiscard]] bool has(std::string_view key) const { return values.contains(std::string(key)); }
  [[nodiscard]] std::string get_string(std::string_view key, std::string_view def = "") const;
  [[nodiscard]] std::int64_t get_int(std::string_view key, std::int64_t def = 0) const;
  [[nodiscard]] double get_double(std::string_view key, double def = 0.0) const;
  [[nodiscard]] bool get_bool(std::string_view key, bool def = false) const;
};
 
struct ConfigLoadOptions {
  bool allow_inline_secrets = false;
  bool substitute_env = true;
};
 
class Config {
 public:
  using LoadOptions = ConfigLoadOptions;
 
  static Config load(const std::string& path, const LoadOptions& opts = LoadOptions{});
  static Config parse(std::string_view toml,
                      const LoadOptions& opts = LoadOptions{},
                      std::string_view source_name = "<string>");
 
  EngineSection engine;
  std::vector<VenueSection> venues;  // VenueId == index
  std::vector<InstrumentSection> instruments;
  StrategySection strategy;
  RiskSection risk;
  GatewaySection gateway;
  // [accounting]: the reporting currency and the FX source of each other settlement currency,
  // read by fastmm-live, fastmm-gateway, the backtester and replay (build_fx_plan, core/fx.hpp).
  AccountingSpec accounting;
  LoggingSection logging;
  GenericSection sim;
  GenericSection backtest;
  // [storage]: the backend name and whatever keys that backend reads. Free-form, like [sim] and
  // [backtest]: a storage backend parses its own keys and the central schema knows none of them
  // (docs/reference/storage.md).
  GenericSection storage;
  std::vector<std::string> warnings;
  std::string source;      // path or "<string>"
  std::uint64_t hash = 0;  // FNV-1a of the raw text
 
  [[nodiscard]] const VenueSection* venue(std::string_view name) const noexcept;
  [[nodiscard]] VenueId venue_id(std::string_view name) const noexcept;  // invalid if unknown
  // The account pools ([venues.<x>] pool_of), by venue id; inactive without any.
  [[nodiscard]] PoolPlan pool_plan() const noexcept;
  // The treasury of the pool whose primary is `primary` ([venues.<primary>.treasury]), typed; a
  // disabled one when the venue has none.
  [[nodiscard]] TreasuryConfig treasury_config(std::string_view primary) const;
 
  // Typed views used to wire the engine.
  [[nodiscard]] RiskLimits risk_limits() const;
  [[nodiscard]] QuoteParams quote_params() const;
  [[nodiscard]] LogLevel log_level() const;
  [[nodiscard]] LogLevel mirror_level() const;
  // `to_file`: the log goes to a file (--log or [logging] file), where the default is 1 s.
  [[nodiscard]] std::int64_t status_interval_s(bool to_file) const noexcept {
    if (logging.status_interval_s >= 0) return logging.status_interval_s;
    return to_file ? 1 : 10;
  }
  [[nodiscard]] SpinMode spin_mode() const;
  [[nodiscard]] bool single_threaded() const noexcept { return engine.threading == "single"; }
 
  // Dump with api_key/api_secret/api_passphrase masked; safe to log.
  [[nodiscard]] std::string redacted() const;
 
  // The configuration as parsed (after any changes made to this object, e.g. command-line
  // overrides) as complete TOML without api_key / api_secret / api_passphrase. Deterministic:
  // equal configurations give equal text, and parsing the text gives an equal configuration.
  // Journals embed it, and its hash is the journal header's config_hash.
  [[nodiscard]] std::string effective_toml() const;
  [[nodiscard]] std::uint64_t effective_hash() const { return text_hash(effective_toml()); }
  [[nodiscard]] static std::uint64_t text_hash(std::string_view text) noexcept;  // FNV-1a
};
 
// Builds the dense instrument table (src/core/instrument_loader.cpp). Throws ConfigError.
InstrumentTable load_instruments(const Config& cfg);
 
// The fee rates of each instrument: its [[instruments]] maker_bps / taker_bps, else its venue's
// [venues.<x>.fees]; the first venue's are the default for ids outside the configuration. Without
// `table`, instrument k of the configuration is InstrumentId k (load_instruments); with it, each
// instrument of `table` takes the entry with its venue and symbol, `venue_names` naming its venue
// ids (a table from fastmm-gateway, whose order is not the configuration's).
FeeTable fee_table(const Config& cfg,
                   const InstrumentTable* table = nullptr,
                   const std::vector<std::string>* venue_names = nullptr);
 
// [risk] check_balance and each instrument's [[instruments]] initial_margin, the instruments mapped
// as fee_table() maps them.
BalanceConfig balance_config(const Config& cfg,
                             const InstrumentTable* table = nullptr,
                             const std::vector<std::string>* venue_names = nullptr);
 
// [accounting] mark, stale_mark_ms and stale_funding_ms.
PerpConfig perp_config(const Config& cfg);
 
}  // namespace fastmm