Extrema Guard
Composable guard strategy modules built on
extrema_infra. Applications select
built-in or private modules at compile time, register them through EnvBuilder,
and run them in the same typed event runtime.
extrema_guard is not a monolithic trading daemon. It is a reference assembly
and a reusable module library for account protection, order supervision, and
custom exchange policies.
Architecture
flowchart TB
App["Application binary"]
Builder["EnvBuilder"]
subgraph Infra["extrema_infra runtime"]
Contracts["Strategy + EventHandler + CommandEmitter"]
Runtime["Event runtime + scheduler"]
Lob["LobClients"]
end
subgraph Modules["Compile-time strategy modules"]
Static["StaticProtect"]
Profit["ProfitLock"]
Outside["OKX OutsideRangeCancel"]
Custom["Private / downstream module"]
end
Executor["Shared GuardExecutor"]
Exchanges["OKX / Binance / Gate / Hyperliquid"]
Audit["Audit log"]
App --> Builder
Builder --> Runtime
Static -->|"with_strategy_module"| Builder
Profit -->|"with_strategy_module"| Builder
Outside -->|"with_strategy_module"| Builder
Custom -->|"with_strategy_module"| Builder
Static -.-> Contracts
Profit -.-> Contracts
Outside -.-> Contracts
Custom -.-> Contracts
Runtime -->|"scheduled events"| Static
Runtime -->|"scheduled events"| Profit
Runtime -->|"scheduled events"| Outside
Runtime -->|"scheduled events"| Custom
Static --> Executor
Profit --> Executor
Outside --> Executor
Custom --> Executor
Executor --> Lob
Lob --> Exchanges
Executor --> Audit
Design principles
- Compile-time composition: built-in and downstream modules implement the
same
extrema_infratraits and are registered withEnvBuilder::with_strategy_module. - Module-owned configuration: every module owns its config type and loader. Adding a module does not require modifying a shared god-config type.
- One execution boundary: all modules share one
GuardExecutor, preserving per-exchange throttling, dry-run/live behavior, client-order-id rules, and a unified audit trail.
Here, pluggable means ordinary Rust modules composed at compile time. There is no dynamic library ABI or runtime plugin loader.
Using as a library
A strategy repository depends on both crates: extrema_infra supplies the
runtime and exchange contracts, while extrema_guard supplies reusable guard
modules and the shared executor.
[]
= { = "0.6.0", = ["lob_clients"] }
= "0.2.0"
Use compatible extrema_infra versions in both dependency paths so Cargo
resolves one set of runtime traits and exchange types. The application binary
then chooses the schedule tasks and modules that make up one deployment:
use *;
use *;
let executor = connect.await?;
let env = new
.with_task
.with_strategy_module
.with_strategy_module
.build?;
env.execute.await;
A downstream crate can use the public extrema_guard modules, replace the
application binary, or add private modules without changing this repository.
Built-in modules
| Module | Policy | Action |
|---|---|---|
StaticProtect |
Derives stop-loss and take-profit levels from position entry price | Maintains a reduce-only take-profit and closes after a stop breach |
ProfitLock |
Tracks the best observed mark after an activation threshold | Closes after the configured profit floor is crossed |
OkxOutsideRangeCancel |
Tracks zero-fill OKX entries while last price remains outside their TP/SL range | Cancels after a continuous timeout, 37 minutes by default |
These modules are examples of the same extension surface available to private strategies. Order ownership and eligibility remain module-level policy rather than framework-wide restrictions.
Quickstart
The example configuration uses mode = "dry-run". Live mode sends real account
actions and also requires i_understand_live_orders = true.
strategy_config.toml contains one executor section and one section per
selected module. Each loader reads only its own section. See
strategy_config.toml.example for the complete
built-in configuration.
Adding a module
Use examples/guard_custom_template.rs as a
minimal external-assembly example:
- Implement
Strategy,CommandEmitter, and the requiredEventHandlermethods fromextrema_infra. - Keep the module config and loader beside the module, normally in
utils.rs. - Receive a clone of the shared
GuardExecutorinstead of constructing an independent exchange client for mutations. - Add the module schedule and one
with_strategy_modulecall in the binary.
Use GuardExecutor::exchange_reader for exchange-specific reads. Route order
placements and cancellations through GuardExecutor so live arming, action
throttling, and audit behavior remain process-wide.
OKX outside-range policy
The OKX module is deliberately narrower than a generic stale-order canceller:
- It scans live
SWAPandFUTURESlimit or post-only parent entries. - The order must have zero fills,
reduceOnly = false, and one complete fixed TP/SL bracket. - Split attachments, trailing stops, ratio brackets, take-profit limit orders, and partially filled orders are not eligible.
- In net mode, an order opposite the current signed position is not treated as
an entry. In long/short mode, only
buy + longandsell + shortqualify. - It always compares against OKX
last, independent of the bracket's stored trigger-price type. - Price must remain strictly beyond the same TP or SL boundary for the complete configured interval.
- Returning inside, changing breach side, modifying the order, stale price data, clock reversal, or an observation gap resets tracking.
- Before cancellation it reloads account mode, net positions, open orders, and prices. The candidate must still be eligible and must be the only pending order on its instrument. After the cancel ACK, it queries the exact order once; an unconfirmed outcome stays tracked for the next schedule.
The timer is persisted atomically in outside_range_state.toml, so a short
process restart does not silently turn a continuous-observation policy into an
order-age policy.
Operational controls
| Control | Behavior |
|---|---|
| Dry-run | Records intended actions without sending them |
| Live arming | Requires both mode = "live" and explicit acknowledgement |
| Action rate | Enforces one shared minimum interval per exchange |
| Order size | Applies a shared notional cap to modules that place orders |
| Market sanity | Rejects invalid or non-finite prices |
| Audit | Appends requested actions, acknowledgements, and module events to one log |
Modules remain responsible for strict eligibility, preflight revalidation, idempotency, and confirmation of exchange outcomes.
Verification
License
This project is licensed under the Apache 2.0 license.