hjnormey/siloqy
Public Access
1
0
Fork 0
Code Issues 7 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

PINK: kernel fee prediction + calibration loop

Browse Source 
ExchangeFeeConfig in AccountState:
  taker_rate, maker_rate, lot_step, tick_size, funding_interval_secs
  calibration_ratio: EMA of actual/expected, updated on every fill

Kernel now predicts fees at fill time (PREDICTED_FILL event):
  k_capital updated immediately without waiting for WS FILL_SETTLED
  When actual fee arrives, prediction is replaced and ratio recalibrated
  Reconcile delta: 0.000000 (was ~0.9 USDT in canary without prediction)

Calibration loop on connect():
  Fetches recent fill history, validates model vs exchange actuals
  deviation < 1pct -> OK; < 5pct -> WARN; >= 5pct -> ERROR (pre-trade gate)

New FFI: dita_kernel_set_exchange_config_json, dita_kernel_calibrate_fee_json
New ExecutionKernel methods: set_exchange_config(), calibrate_fee()
pink_direct.py: loads BingX fee config on connect, calibrates before stream

131/131 offline pass.
This commit is contained in:
Codex
2026-06-01 23:45:50 +02:00
parent 7d13df35db
commit b3b28bb44a
3 changed files with 331 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
prod/clean_arch/dita_v2/_rust_kernel/src/lib.rs
View File

@@ -527,6 +527,68 @@ struct KernelSnapshot {
account: AccountState,
}
/// Exchange fee schedule + friction model loaded at kernel init.
///
/// All rates are fractions (0.0005 = 0.05%). The kernel uses these to
/// predict fees at fill time so K-capital is updated *immediately* without
/// waiting for the WS `FILL_SETTLED` event. When the actual fee arrives
/// via `FILL_SETTLED`, the prediction is validated and the fee rate is
/// softly recalibrated toward the realised ratio.
#[derive(Debug, Clone, Serialize, Deserialize)]
struct ExchangeFeeConfig {
/// Taker fee rate (market orders). Default: 0.0005 (BingX VST/LIVE).
taker_rate: f64,
/// Maker fee rate (limit orders resting). Default: 0.0002.
maker_rate: f64,
/// Funding payment interval in seconds (8 h = 28800 for BingX perps).
funding_interval_secs: u64,
/// Minimum lot step for quantity rounding.
lot_step: f64,
/// Minimum price tick for price rounding.
tick_size: f64,
/// Running calibration ratio (actual/expected) — updated on every FILL_SETTLED.
/// Starts at 1.0; drifts only if exchange changes fee schedule.
calibration_ratio: f64,
/// Count of fills used to build the calibration ratio.
calibration_samples: u64,
}
impl Default for ExchangeFeeConfig {
fn default() -> Self {
Self {
taker_rate: 0.0005,
maker_rate: 0.0002,
funding_interval_secs: 28_800,
lot_step: 0.001,
tick_size: 0.0001,
calibration_ratio: 1.0,
calibration_samples: 0,
}
}
}
impl ExchangeFeeConfig {
/// Predict the taker fee for a fill.
fn predict_taker_fee(&self, fill_price: f64, fill_qty: f64) -> f64 {
let raw = fill_price.abs() * fill_qty.abs() * self.taker_rate * self.calibration_ratio;
if raw.is_finite() { raw } else { 0.0 }
}
/// Ingest an actual fee observation and softly recalibrate the ratio.
/// Uses exponential moving average with α=0.1 so one outlier doesn't
/// corrupt the model.
fn observe_actual_fee(&mut self, expected: f64, actual: f64) -> f64 {
if expected <= 0.0 || actual <= 0.0 || !actual.is_finite() {
return 1.0;
}
let ratio = actual / expected;
let alpha = if self.calibration_samples == 0 { 1.0 } else { 0.1 };
self.calibration_ratio = self.calibration_ratio * (1.0 - alpha) + ratio * alpha;
self.calibration_samples += 1;
ratio
}
}
/// Per-kernel account ledger — K-values + E-facts + reconcile.
///
/// K-values are computed deterministically from the event stream the kernel
@@ -575,6 +637,12 @@ struct AccountState {
/// Cached available_capital: e_available_margin when E-facts present,
/// k_capital as fallback. E rules.
available_capital: f64,
/// Exchange fee model — loaded at init, recalibrated on every fill.
fee_config: ExchangeFeeConfig,
/// Last predicted fee (for calibration comparison when FILL_SETTLED arrives).
last_predicted_fee: f64,
/// Last calibration ratio observed.
last_calibration_ratio: f64,
}
impl AccountState {
@@ -620,13 +688,35 @@ impl AccountState {
if realized_pnl.is_finite() {
self.k_realized_pnl += realized_pnl;
}
if fee.is_finite() && fee >= 0.0 {
self.k_fees_paid += fee;
// If the WS delivered the actual fee, use it and recalibrate.
// If fee == 0 the fill came from a path that doesn't carry fee info;
// use the model-predicted fee that was folded at fill time (no-op here —
// prediction was already applied in apply_predicted_fill).
if fee.is_finite() && fee > 0.0 {
// We may have already folded the predicted fee; replace with actual.
let predicted = self.last_predicted_fee;
// Undo prediction, apply actual.
self.k_fees_paid = (self.k_fees_paid - predicted + fee).max(0.0);
self.last_calibration_ratio = self.fee_config.observe_actual_fee(predicted.max(fee * 0.001), fee);
self.last_predicted_fee = 0.0;
}
self.event_seq += 1;
self.reconcile();
}
/// Called when a fill event arrives in on_venue_event (before FILL_SETTLED).
/// Predicts and immediately folds the taker fee so K tracks E without delay.
fn apply_predicted_fill(&mut self, fill_price: f64, fill_qty: f64, realized_pnl: f64) {
let predicted_fee = self.fee_config.predict_taker_fee(fill_price, fill_qty);
self.last_predicted_fee = predicted_fee;
if realized_pnl.is_finite() {
self.k_realized_pnl += realized_pnl;
}
self.k_fees_paid += predicted_fee;
self.event_seq += 1;
self.reconcile();
}
fn apply_account_update(
&mut self,
wallet_balance: f64,
@@ -651,6 +741,34 @@ impl AccountState {
self.reconcile();
}
fn set_fee_config(&mut self, taker_rate: f64, maker_rate: f64, lot_step: f64, tick_size: f64, funding_interval_secs: u64) {
self.fee_config.taker_rate = if taker_rate.is_finite() && taker_rate > 0.0 { taker_rate } else { self.fee_config.taker_rate };
self.fee_config.maker_rate = if maker_rate.is_finite() && maker_rate > 0.0 { maker_rate } else { self.fee_config.maker_rate };
self.fee_config.lot_step = if lot_step.is_finite() && lot_step > 0.0 { lot_step } else { self.fee_config.lot_step };
self.fee_config.tick_size = if tick_size.is_finite() && tick_size > 0.0 { tick_size } else { self.fee_config.tick_size };
if funding_interval_secs > 0 { self.fee_config.funding_interval_secs = funding_interval_secs; }
}
/// Validate model against one known fill. Returns calibration report.
fn calibrate_fee(&mut self, fill_price: f64, fill_qty: f64, actual_fee: f64) -> Value {
let expected = self.fee_config.predict_taker_fee(fill_price, fill_qty);
let ratio = self.fee_config.observe_actual_fee(expected, actual_fee);
let deviation_pct = (ratio - 1.0).abs() * 100.0;
let status = if deviation_pct < 1.0 { "OK" } else if deviation_pct < 5.0 { "WARN" } else { "ERROR" };
json!({
"fill_price": fill_price,
"fill_qty": fill_qty,
"expected_fee": expected,
"actual_fee": actual_fee,
"ratio": ratio,
"deviation_pct": deviation_pct,
"calibration_status": status,
"calibrated_taker_rate": self.fee_config.taker_rate,
"calibration_ratio": self.fee_config.calibration_ratio,
"calibration_samples": self.fee_config.calibration_samples,
})
}
fn apply_funding_fee(&mut self, amount: f64) {
if amount.is_finite() {
// amount > 0 = received (increases capital → reduces net funding paid)
@@ -720,6 +838,15 @@ impl KernelCore {
let amount = parsed.get("funding_amount").and_then(|v| v.as_f64()).unwrap_or(0.0);
self.account.apply_funding_fee(amount);
}
"PREDICTED_FILL" => {
// Called from on_venue_event immediately when a fill arrives —
// pre-folds realized PnL + predicted fee so K tracks E without
// waiting for the WS FILL_SETTLED event.
let fill_price = parsed.get("fill_price").and_then(|v| v.as_f64()).unwrap_or(0.0);
let fill_qty = parsed.get("fill_qty").and_then(|v| v.as_f64()).unwrap_or(0.0);
let realized = parsed.get("realized_pnl").and_then(|v| v.as_f64()).unwrap_or(0.0);
self.account.apply_predicted_fill(fill_price, fill_qty, realized);
}
_ => return json!({"error": format!("unknown account event kind: {}", kind)}),
}
serde_json::to_value(&self.account).unwrap_or(json!({"error":"serialize"}))
@@ -1934,6 +2061,68 @@ pub extern "C" fn dita_kernel_snapshot_json(handle: *mut KernelHandle) -> *mut c
}
}
/// Load the exchange fee schedule into the kernel's AccountState.
///
/// JSON: { "taker_rate": 0.0005, "maker_rate": 0.0002,
/// "lot_step": 0.001, "tick_size": 0.0001,
/// "funding_interval_secs": 28800 }
/// Returns 0 on success, -1 on error.
#[no_mangle]
pub extern "C" fn dita_kernel_set_exchange_config_json(
handle: *mut KernelHandle,
payload: *const c_char,
) -> i32 {
let s = match unsafe { CStr::from_ptr(payload) }.to_str() {
Ok(s) => s.to_string(),
Err(_) => return -1,
};
let parsed: Value = match serde_json::from_str(&s) {
Ok(v) => v,
Err(_) => return -1,
};
let taker = parsed.get("taker_rate").and_then(|v| v.as_f64()).unwrap_or(0.0);
let maker = parsed.get("maker_rate").and_then(|v| v.as_f64()).unwrap_or(0.0);
let lot = parsed.get("lot_step").and_then(|v| v.as_f64()).unwrap_or(0.0);
let tick = parsed.get("tick_size").and_then(|v| v.as_f64()).unwrap_or(0.0);
let fi = parsed.get("funding_interval_secs").and_then(|v| v.as_u64()).unwrap_or(0);
match with_handle_mut(handle, |core| {
core.account.set_fee_config(taker, maker, lot, tick, fi);
Ok(())
}) {
Ok(_) => 0,
Err(_) => -1,
}
}
/// Validate the kernel's fee model against one real fill observation.
/// Returns JSON calibration report: expected/actual fee, ratio, deviation_pct, status.
/// Call this once on startup with a recent fill from account history to
/// confirm the fee model is calibrated before live trading begins.
#[no_mangle]
pub extern "C" fn dita_kernel_calibrate_fee_json(
handle: *mut KernelHandle,
payload: *const c_char,
) -> *mut c_char {
let s = match unsafe { CStr::from_ptr(payload) }.to_str() {
Ok(s) => s.to_string(),
Err(_) => return ptr::null_mut(),
};
let parsed: Value = match serde_json::from_str(&s) {
Ok(v) => v,
Err(_) => return ptr::null_mut(),
};
let fill_price = parsed.get("fill_price").and_then(|v| v.as_f64()).unwrap_or(0.0);
let fill_qty = parsed.get("fill_qty").and_then(|v| v.as_f64()).unwrap_or(0.0);
let actual_fee = parsed.get("actual_fee").and_then(|v| v.as_f64()).unwrap_or(0.0);
match with_handle_mut(handle, |core| Ok(core.account.calibrate_fee(fill_price, fill_qty, actual_fee))) {
Ok(result) => {
let s = serde_json::to_string(&result).unwrap_or_else(|_| "{}".to_string());
into_c_string(&s)
}
Err(_) => ptr::null_mut(),
}
}
/// Set the seed capital for the kernel's K-value fold.
/// Must be called once at kernel init (before any account events).
/// Returns 0 on success, -1 on error.

56
prod/clean_arch/dita_v2/rust_backend.py
View File

@@ -121,6 +121,10 @@ class _RustKernelLib:
self.lib.dita_kernel_snapshot_json.restype = ctypes.c_void_p
self.lib.dita_kernel_set_seed_capital.argtypes = [ctypes.c_void_p, ctypes.c_double]
self.lib.dita_kernel_set_seed_capital.restype = ctypes.c_int
self.lib.dita_kernel_set_exchange_config_json.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
self.lib.dita_kernel_set_exchange_config_json.restype = ctypes.c_int
self.lib.dita_kernel_calibrate_fee_json.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
self.lib.dita_kernel_calibrate_fee_json.restype = ctypes.c_void_p
self.lib.dita_kernel_on_account_event_json.argtypes = [
ctypes.c_void_p,
ctypes.c_char_p,
@@ -220,6 +224,18 @@ class _RustKernelLib:
rc = self.lib.dita_kernel_set_seed_capital(handle, ctypes.c_double(seed))
return rc == 0
def set_exchange_config(self, handle: ctypes.c_void_p, config: Dict[str, Any]) -> bool:
encoded = json.dumps(config, separators=(",", ":")).encode("utf-8")
rc = self.lib.dita_kernel_set_exchange_config_json(handle, ctypes.c_char_p(encoded))
return rc == 0
def calibrate_fee(self, handle: ctypes.c_void_p, fill_price: float, fill_qty: float, actual_fee: float) -> Dict[str, Any]:
payload = json.dumps({"fill_price": fill_price, "fill_qty": fill_qty, "actual_fee": actual_fee}).encode("utf-8")
raw = self.lib.dita_kernel_calibrate_fee_json(handle, ctypes.c_char_p(payload))
if not raw:
return {}
return json.loads(self._take_string(raw))
def on_account_event(
self, handle: ctypes.c_void_p, event: Dict[str, Any]
) -> Dict[str, Any]:
@@ -761,6 +777,46 @@ class ExecutionKernel:
"""Set the kernel's seed capital for K-value fold. Call once at init."""
_get_rust().set_seed_capital(self._backend, float(seed))
def set_exchange_config(self, config: Dict[str, Any]) -> None:
"""
Load the exchange fee schedule into the kernel's fee prediction model.
config keys (all optional — unset keys keep defaults):
taker_rate float fraction (0.0005 = 0.05%)
maker_rate float fraction (0.0002 = 0.02%)
lot_step float quantity increment
tick_size float price increment
funding_interval_secs int seconds between funding payments (28800 = 8 h)
After this call the kernel can predict fees at fill time so K-capital
tracks E-wallet without waiting for the WS FILL_SETTLED event.
"""
_get_rust().set_exchange_config(self._backend, config)
def calibrate_fee(
self,
fill_price: float,
fill_qty: float,
actual_fee: float,
) -> Dict[str, Any]:
"""
Validate the fee model against one known fill.
Returns:
expected_fee model prediction before calibration
actual_fee exchange-reported value
ratio actual / expected
deviation_pct |ratio - 1| × 100
calibration_status "OK" (<1%) / "WARN" (<5%) / "ERROR" (≥5%)
calibration_ratio updated EMA of actual/expected ratio
calibration_samples fills seen so far
Call once on startup with a recent fill from account history before
enabling live trading. If status == ERROR, the fee model needs manual
review before K-capital figures can be trusted.
"""
return _get_rust().calibrate_fee(self._backend, float(fill_price), float(fill_qty), float(actual_fee))
def on_account_event(self, event: Dict[str, Any]) -> Dict[str, Any]:
"""
Apply an account-level exchange event atomically to the kernel.