This commit is contained in:
2026-04-29 17:18:35 +02:00
parent f8a2309173
commit 0b36caf77d
17 changed files with 1593 additions and 11 deletions

View File

@@ -0,0 +1,693 @@
// file: kb_lib/src/trade_aggregation.rs
//! Cross-DEX trade aggregation service.
/// One trade-aggregation result.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KbTradeAggregationResult {
/// Persisted trade-event id.
pub trade_event_id: i64,
/// Persisted pair-metric id.
pub pair_metric_id: i64,
/// Related pair id.
pub pair_id: i64,
/// Related pool id.
pub pool_id: i64,
/// Whether the trade-event row was newly created.
pub created_trade_event: bool,
}
/// Trade-aggregation service.
#[derive(Debug, Clone)]
pub struct KbTradeAggregationService {
database: std::sync::Arc<crate::KbDatabase>,
persistence: crate::KbDetectionPersistenceService,
}
impl KbTradeAggregationService {
/// Creates a new trade-aggregation service.
pub fn new(database: std::sync::Arc<crate::KbDatabase>) -> Self {
let persistence = crate::KbDetectionPersistenceService::new(database.clone());
Self {
database,
persistence,
}
}
/// Records normalized trade events and updates pair metrics for one transaction signature.
pub async fn record_transaction_by_signature(
&self,
signature: &str,
) -> Result<std::vec::Vec<crate::KbTradeAggregationResult>, crate::KbError> {
let transaction_result =
crate::get_chain_transaction_by_signature(self.database.as_ref(), signature).await;
let transaction_option = match transaction_result {
Ok(transaction_option) => transaction_option,
Err(error) => return Err(error),
};
let transaction = match transaction_option {
Some(transaction) => transaction,
None => {
return Err(crate::KbError::InvalidState(format!(
"cannot aggregate trades for unknown transaction '{}'",
signature
)));
}
};
let transaction_id = match transaction.id {
Some(transaction_id) => transaction_id,
None => {
return Err(crate::KbError::InvalidState(format!(
"transaction '{}' has no internal id",
signature
)));
}
};
let decoded_events_result = crate::list_dex_decoded_events_by_transaction_id(
self.database.as_ref(),
transaction_id,
)
.await;
let decoded_events = match decoded_events_result {
Ok(decoded_events) => decoded_events,
Err(error) => return Err(error),
};
let mut results = std::vec::Vec::new();
for decoded_event in &decoded_events {
if !decoded_event.event_kind.ends_with(".swap") {
continue;
}
let decoded_event_id = match decoded_event.id {
Some(decoded_event_id) => decoded_event_id,
None => {
return Err(crate::KbError::InvalidState(
"decoded event has no internal id".to_string(),
));
}
};
let existing_trade_result = crate::get_trade_event_by_decoded_event_id(
self.database.as_ref(),
decoded_event_id,
)
.await;
let existing_trade_option = match existing_trade_result {
Ok(existing_trade_option) => existing_trade_option,
Err(error) => return Err(error),
};
let pool_address = match decoded_event.pool_account.clone() {
Some(pool_address) => pool_address,
None => continue,
};
let pool_result =
crate::get_pool_by_address(self.database.as_ref(), pool_address.as_str()).await;
let pool_option = match pool_result {
Ok(pool_option) => pool_option,
Err(error) => return Err(error),
};
let pool = match pool_option {
Some(pool) => pool,
None => continue,
};
let pool_id = match pool.id {
Some(pool_id) => pool_id,
None => {
return Err(crate::KbError::InvalidState(format!(
"pool '{}' has no internal id",
pool.address
)));
}
};
let pair_result = crate::get_pair_by_pool_id(self.database.as_ref(), pool_id).await;
let pair_option = match pair_result {
Ok(pair_option) => pair_option,
Err(error) => return Err(error),
};
let pair = match pair_option {
Some(pair) => pair,
None => continue,
};
let pair_id = match pair.id {
Some(pair_id) => pair_id,
None => {
return Err(crate::KbError::InvalidState(format!(
"pair for pool '{}' has no internal id",
pool_id
)));
}
};
let payload_result =
serde_json::from_str::<serde_json::Value>(decoded_event.payload_json.as_str());
let payload = match payload_result {
Ok(payload) => payload,
Err(error) => {
return Err(crate::KbError::Json(format!(
"cannot parse decoded_event payload_json '{}': {}",
decoded_event.payload_json, error
)));
}
};
let trade_side = kb_extract_trade_side(&payload);
let base_amount_raw = kb_extract_amount_string(
&payload,
&[
"baseAmountRaw",
"base_amount_raw",
"baseAmount",
"amountBase",
"amountInBase",
],
);
let quote_amount_raw = kb_extract_amount_string(
&payload,
&[
"quoteAmountRaw",
"quote_amount_raw",
"quoteAmount",
"amountQuote",
"amountOutQuote",
],
);
let price_quote_per_base =
kb_compute_price_quote_per_base(base_amount_raw.clone(), quote_amount_raw.clone());
let slot_i64 = kb_convert_slot_to_i64(transaction.slot);
let created_trade_event = existing_trade_option.is_none();
let trade_event_id = if let Some(existing_trade) = existing_trade_option {
match existing_trade.id {
Some(trade_event_id) => trade_event_id,
None => {
return Err(crate::KbError::InvalidState(
"trade event has no internal id".to_string(),
));
}
}
} else {
let trade_event_dto = crate::KbTradeEventDto::new(
pool.dex_id,
pool_id,
pair_id,
transaction_id,
decoded_event_id,
transaction.signature.clone(),
slot_i64,
trade_side,
pair.base_token_id,
pair.quote_token_id,
base_amount_raw.clone(),
quote_amount_raw.clone(),
price_quote_per_base,
crate::KbObservationSourceKind::Dex,
transaction.source_endpoint_name.clone(),
decoded_event.payload_json.clone(),
);
let upsert_result =
crate::upsert_trade_event(self.database.as_ref(), &trade_event_dto).await;
match upsert_result {
Ok(trade_event_id) => trade_event_id,
Err(error) => return Err(error),
}
};
let pair_metric_result =
crate::get_pair_metric_by_pair_id(self.database.as_ref(), pair_id).await;
let pair_metric_option = match pair_metric_result {
Ok(pair_metric_option) => pair_metric_option,
Err(error) => return Err(error),
};
let pair_metric_id = if let Some(existing_metric) = pair_metric_option {
let existing_metric_id = match existing_metric.id {
Some(existing_metric_id) => existing_metric_id,
None => {
return Err(crate::KbError::InvalidState(
"pair metric has no internal id".to_string(),
));
}
};
if created_trade_event {
let mut updated_metric = existing_metric.clone();
kb_apply_trade_to_pair_metric(
&mut updated_metric,
slot_i64,
transaction.signature.clone(),
trade_side,
base_amount_raw.clone(),
quote_amount_raw.clone(),
price_quote_per_base,
);
let upsert_result =
crate::upsert_pair_metric(self.database.as_ref(), &updated_metric).await;
if let Err(error) = upsert_result {
return Err(error);
}
}
existing_metric_id
} else {
let mut new_metric = crate::KbPairMetricDto::new(pair_id);
kb_apply_trade_to_pair_metric(
&mut new_metric,
slot_i64,
transaction.signature.clone(),
trade_side,
base_amount_raw.clone(),
quote_amount_raw.clone(),
price_quote_per_base,
);
let upsert_result =
crate::upsert_pair_metric(self.database.as_ref(), &new_metric).await;
match upsert_result {
Ok(pair_metric_id) => pair_metric_id,
Err(error) => return Err(error),
}
};
if created_trade_event {
let payload = serde_json::json!({
"pairId": pair_id,
"poolId": pool_id,
"tradeEventId": trade_event_id,
"tradeSide": format!("{:?}", trade_side),
"baseAmountRaw": base_amount_raw,
"quoteAmountRaw": quote_amount_raw,
"priceQuotePerBase": price_quote_per_base,
"transactionSignature": transaction.signature
});
let observation_result = self
.persistence
.record_observation(&crate::KbDetectionObservationInput::new(
"dex.trade_aggregation".to_string(),
crate::KbObservationSourceKind::Dex,
transaction.source_endpoint_name.clone(),
transaction.signature.clone(),
transaction.slot,
payload.clone(),
))
.await;
let observation_id = match observation_result {
Ok(observation_id) => observation_id,
Err(error) => return Err(error),
};
let signal_result = self
.persistence
.record_signal(&crate::KbDetectionSignalInput::new(
"signal.dex.trade_aggregation.recorded".to_string(),
crate::KbAnalysisSignalSeverity::Low,
transaction.signature.clone(),
Some(observation_id),
None,
payload,
))
.await;
if let Err(error) = signal_result {
return Err(error);
}
}
results.push(crate::KbTradeAggregationResult {
trade_event_id,
pair_metric_id,
pair_id,
pool_id,
created_trade_event,
});
}
Ok(results)
}
}
fn kb_convert_slot_to_i64(slot: std::option::Option<u64>) -> std::option::Option<i64> {
match slot {
Some(slot) => match i64::try_from(slot) {
Ok(slot) => Some(slot),
Err(_) => None,
},
None => None,
}
}
fn kb_extract_trade_side(payload: &serde_json::Value) -> crate::KbSwapTradeSide {
let trade_side_option = kb_extract_string_by_candidate_keys(payload, &["tradeSide"]);
match trade_side_option.as_deref() {
Some("BuyBase") => crate::KbSwapTradeSide::BuyBase,
Some("SellBase") => crate::KbSwapTradeSide::SellBase,
_ => crate::KbSwapTradeSide::Unknown,
}
}
fn kb_extract_amount_string(
payload: &serde_json::Value,
candidate_keys: &[&str],
) -> std::option::Option<std::string::String> {
kb_extract_scalar_as_string_by_candidate_keys(payload, candidate_keys)
}
fn kb_compute_price_quote_per_base(
base_amount_raw: std::option::Option<std::string::String>,
quote_amount_raw: std::option::Option<std::string::String>,
) -> std::option::Option<f64> {
let base_amount_text = match base_amount_raw {
Some(base_amount_text) => base_amount_text,
None => return None,
};
let quote_amount_text = match quote_amount_raw {
Some(quote_amount_text) => quote_amount_text,
None => return None,
};
let base_amount_result = base_amount_text.parse::<f64>();
let base_amount = match base_amount_result {
Ok(base_amount) => base_amount,
Err(_) => return None,
};
if base_amount <= 0.0 {
return None;
}
let quote_amount_result = quote_amount_text.parse::<f64>();
let quote_amount = match quote_amount_result {
Ok(quote_amount) => quote_amount,
Err(_) => return None,
};
Some(quote_amount / base_amount)
}
fn kb_apply_trade_to_pair_metric(
metric: &mut crate::KbPairMetricDto,
slot: std::option::Option<i64>,
signature: std::string::String,
trade_side: crate::KbSwapTradeSide,
base_amount_raw: std::option::Option<std::string::String>,
quote_amount_raw: std::option::Option<std::string::String>,
price_quote_per_base: std::option::Option<f64>,
) {
metric.trade_count += 1;
if trade_side == crate::KbSwapTradeSide::BuyBase {
metric.buy_count += 1;
}
if trade_side == crate::KbSwapTradeSide::SellBase {
metric.sell_count += 1;
}
if metric.first_slot.is_none() {
metric.first_slot = slot;
}
if metric.first_signature.is_none() {
metric.first_signature = Some(signature.clone());
}
metric.last_slot = slot;
metric.last_signature = Some(signature);
metric.cumulative_base_amount_raw =
kb_add_raw_amounts(metric.cumulative_base_amount_raw.clone(), base_amount_raw);
metric.cumulative_quote_amount_raw =
kb_add_raw_amounts(metric.cumulative_quote_amount_raw.clone(), quote_amount_raw);
if price_quote_per_base.is_some() {
metric.last_price_quote_per_base = price_quote_per_base;
}
metric.updated_at = chrono::Utc::now();
}
fn kb_add_raw_amounts(
left: std::option::Option<std::string::String>,
right: std::option::Option<std::string::String>,
) -> std::option::Option<std::string::String> {
match (left, right) {
(None, None) => None,
(Some(left), None) => Some(left),
(None, Some(right)) => Some(right),
(Some(left), Some(right)) => {
let left_value_result = left.parse::<i128>();
let left_value = match left_value_result {
Ok(left_value) => left_value,
Err(_) => return Some(left),
};
let right_value_result = right.parse::<i128>();
let right_value = match right_value_result {
Ok(right_value) => right_value,
Err(_) => return Some(left),
};
Some((left_value + right_value).to_string())
}
}
}
fn kb_extract_string_by_candidate_keys(
value: &serde_json::Value,
candidate_keys: &[&str],
) -> std::option::Option<std::string::String> {
if let Some(object) = value.as_object() {
for candidate_key in candidate_keys {
let direct_option = object.get(*candidate_key);
if let Some(direct) = direct_option {
let direct_text_option = direct.as_str();
if let Some(direct_text) = direct_text_option {
return Some(direct_text.to_string());
}
}
}
for nested_value in object.values() {
let nested_result = kb_extract_string_by_candidate_keys(nested_value, candidate_keys);
if nested_result.is_some() {
return nested_result;
}
}
return None;
}
if let Some(array) = value.as_array() {
for nested_value in array {
let nested_result = kb_extract_string_by_candidate_keys(nested_value, candidate_keys);
if nested_result.is_some() {
return nested_result;
}
}
}
None
}
fn kb_extract_scalar_as_string_by_candidate_keys(
value: &serde_json::Value,
candidate_keys: &[&str],
) -> std::option::Option<std::string::String> {
if let Some(object) = value.as_object() {
for candidate_key in candidate_keys {
let direct_option = object.get(*candidate_key);
if let Some(direct) = direct_option {
if let Some(text) = direct.as_str() {
return Some(text.to_string());
}
if let Some(number) = direct.as_i64() {
return Some(number.to_string());
}
if let Some(number) = direct.as_u64() {
return Some(number.to_string());
}
if let Some(number) = direct.as_f64() {
return Some(number.to_string());
}
}
}
for nested_value in object.values() {
let nested_result =
kb_extract_scalar_as_string_by_candidate_keys(nested_value, candidate_keys);
if nested_result.is_some() {
return nested_result;
}
}
return None;
}
if let Some(array) = value.as_array() {
for nested_value in array {
let nested_result =
kb_extract_scalar_as_string_by_candidate_keys(nested_value, candidate_keys);
if nested_result.is_some() {
return nested_result;
}
}
}
None
}
#[cfg(test)]
mod tests {
async fn make_database() -> std::sync::Arc<crate::KbDatabase> {
let tempdir_result = tempfile::tempdir();
let tempdir = match tempdir_result {
Ok(tempdir) => tempdir,
Err(error) => panic!("tempdir must succeed: {}", error),
};
let database_path = tempdir.path().join("trade_aggregation.sqlite3");
let config = crate::KbDatabaseConfig {
enabled: true,
backend: crate::KbDatabaseBackend::Sqlite,
sqlite: crate::KbSqliteDatabaseConfig {
path: database_path.to_string_lossy().to_string(),
create_if_missing: true,
busy_timeout_ms: 5000,
max_connections: 1,
auto_initialize_schema: true,
use_wal: true,
},
};
let database_result = crate::KbDatabase::connect_and_initialize(&config).await;
let database = match database_result {
Ok(database) => database,
Err(error) => panic!("database init must succeed: {}", error),
};
std::sync::Arc::new(database)
}
async fn seed_fluxbeam_swap_transaction(
database: std::sync::Arc<crate::KbDatabase>,
signature: &str,
base_amount_raw: &str,
quote_amount_raw: &str,
) {
let transaction_model = crate::KbTransactionModelService::new(database.clone());
let dex_decode = crate::KbDexDecodeService::new(database.clone());
let dex_detect = crate::KbDexDetectService::new(database);
let resolved_transaction = serde_json::json!({
"slot": 940001,
"blockTime": 1779400001,
"version": 0,
"transaction": {
"message": {
"instructions": [
{
"programId": crate::KB_FLUXBEAM_PROGRAM_ID,
"program": "fluxbeam",
"stackHeight": 1,
"accounts": [
"TradeAggPool111",
"TradeAggLpMint111",
"TradeAggTokenA111",
"So11111111111111111111111111111111111111112"
],
"parsed": {
"info": {
"instruction": "swap",
"pool": "TradeAggPool111",
"tokenA": "TradeAggTokenA111",
"tokenB": "So11111111111111111111111111111111111111112",
"baseAmountRaw": base_amount_raw,
"quoteAmountRaw": quote_amount_raw
}
},
"data": "opaque"
}
]
}
},
"meta": {
"err": null,
"logMessages": [
"Program log: Instruction: Swap",
"Program log: buy"
]
}
});
let project_result = transaction_model
.persist_resolved_transaction(
signature,
Some("helius_primary_http".to_string()),
&resolved_transaction,
)
.await;
if let Err(error) = project_result {
panic!("projection must succeed: {}", error);
}
let decode_result = dex_decode.decode_transaction_by_signature(signature).await;
if let Err(error) = decode_result {
panic!("dex decode must succeed: {}", error);
}
let detect_result = dex_detect.detect_transaction_by_signature(signature).await;
if let Err(error) = detect_result {
panic!("dex detect must succeed: {}", error);
}
}
#[tokio::test]
async fn record_transaction_by_signature_creates_trade_event_and_pair_metric() {
let database = make_database().await;
seed_fluxbeam_swap_transaction(database.clone(), "sig-trade-aggregation-1", "1000", "2500")
.await;
let service = crate::KbTradeAggregationService::new(database.clone());
let record_result = service
.record_transaction_by_signature("sig-trade-aggregation-1")
.await;
let results = match record_result {
Ok(results) => results,
Err(error) => panic!("trade aggregation must succeed: {}", error),
};
assert_eq!(results.len(), 1);
assert!(results[0].created_trade_event);
let trade_events_result =
crate::list_trade_events_by_pair_id(database.as_ref(), results[0].pair_id).await;
let trade_events = match trade_events_result {
Ok(trade_events) => trade_events,
Err(error) => panic!("trade event list must succeed: {}", error),
};
assert_eq!(trade_events.len(), 1);
assert_eq!(trade_events[0].trade_side, crate::KbSwapTradeSide::BuyBase);
assert_eq!(trade_events[0].base_amount_raw, Some("1000".to_string()));
assert_eq!(trade_events[0].quote_amount_raw, Some("2500".to_string()));
assert_eq!(trade_events[0].price_quote_per_base, Some(2.5));
let pair_metric_result =
crate::get_pair_metric_by_pair_id(database.as_ref(), results[0].pair_id).await;
let pair_metric_option = match pair_metric_result {
Ok(pair_metric_option) => pair_metric_option,
Err(error) => panic!("pair metric fetch must succeed: {}", error),
};
let pair_metric = match pair_metric_option {
Some(pair_metric) => pair_metric,
None => panic!("pair metric must exist"),
};
assert_eq!(pair_metric.trade_count, 1);
assert_eq!(pair_metric.buy_count, 1);
assert_eq!(pair_metric.sell_count, 0);
assert_eq!(
pair_metric.cumulative_base_amount_raw,
Some("1000".to_string())
);
assert_eq!(
pair_metric.cumulative_quote_amount_raw,
Some("2500".to_string())
);
assert_eq!(pair_metric.last_price_quote_per_base, Some(2.5));
}
#[tokio::test]
async fn record_transaction_by_signature_is_idempotent() {
let database = make_database().await;
seed_fluxbeam_swap_transaction(database.clone(), "sig-trade-aggregation-2", "1000", "2500")
.await;
let service = crate::KbTradeAggregationService::new(database.clone());
let first_result = service
.record_transaction_by_signature("sig-trade-aggregation-2")
.await;
let first_results = match first_result {
Ok(first_results) => first_results,
Err(error) => panic!("first trade aggregation must succeed: {}", error),
};
assert_eq!(first_results.len(), 1);
assert!(first_results[0].created_trade_event);
let second_result = service
.record_transaction_by_signature("sig-trade-aggregation-2")
.await;
let second_results = match second_result {
Ok(second_results) => second_results,
Err(error) => panic!("second trade aggregation must succeed: {}", error),
};
assert_eq!(second_results.len(), 1);
assert!(!second_results[0].created_trade_event);
let trade_events_result =
crate::list_trade_events_by_pair_id(database.as_ref(), first_results[0].pair_id).await;
let trade_events = match trade_events_result {
Ok(trade_events) => trade_events,
Err(error) => panic!("trade event list must succeed: {}", error),
};
assert_eq!(trade_events.len(), 1);
let pair_metric_result =
crate::get_pair_metric_by_pair_id(database.as_ref(), first_results[0].pair_id).await;
let pair_metric_option = match pair_metric_result {
Ok(pair_metric_option) => pair_metric_option,
Err(error) => panic!("pair metric fetch must succeed: {}", error),
};
let pair_metric = match pair_metric_option {
Some(pair_metric) => pair_metric,
None => panic!("pair metric must exist"),
};
assert_eq!(pair_metric.trade_count, 1);
}
}