use std::sync::Arc;
use starknet::core::types::Felt;
use tracing::{debug, warn};
use crate::data::pathfinder::PathfinderClient;
use crate::data::types::SnEvent;
use crate::data::{DataSource, FilterKind};
use crate::error::Result;
use crate::network::address::{
AddressActivityPage, EventQueryKind, fetch_address_activity, fetch_events_routed,
};
fn filter_kind_for(kind: EventQueryKind) -> FilterKind {
match kind {
EventQueryKind::Account => FilterKind::Keyed,
EventQueryKind::Contract => FilterKind::Unkeyed,
}
}
pub const EVENT_FIRST_PAINT_TARGET: u32 = 200;
pub const EVENT_LARGE_GAP_THRESHOLD_BLOCKS: u64 = 100_000;
pub const TIP_ONLY_WINDOW_BLOCKS: u64 = 5_000;
pub const EVENT_PAGE_LIMIT: u32 = 200;
pub const EXTEND_DOWN_INITIAL_WINDOW: u64 = 5_000;
pub const EXTEND_DOWN_MIN_WINDOW: u64 = 5_000;
pub const EXTEND_DOWN_MAX_WINDOW: u64 = 500_000;
#[derive(Debug, Clone, Copy)]
pub enum EventWindowPolicy {
TopDelta,
ExtendDown { window_size: u64 },
FillGap { from_block: u64, to_block: u64 },
}
#[derive(Debug, Clone)]
pub(crate) struct EventWindowOutcome {
pub merged: Vec<SnEvent>,
pub fetched: usize,
pub next_token: Option<u64>,
pub deferred_gap: Option<(u64, u64)>,
pub max_searched: u64,
pub min_searched: u64,
pub suggested_next_window: Option<u64>,
pub page: crate::network::address::AddressActivityPage,
}
pub(crate) async fn ensure_address_events_window(
address: Felt,
kind: EventQueryKind,
policy: EventWindowPolicy,
pf: Option<&Arc<PathfinderClient>>,
ds: &Arc<dyn DataSource>,
latest_block: u64,
floor_block: u64,
) -> Result<EventWindowOutcome> {
let filter_kind = filter_kind_for(kind);
let progress = ds.load_search_progress(&address, filter_kind);
let (from_block, deferred_gap) = match policy {
EventWindowPolicy::TopDelta => resolve_top_delta(progress, latest_block),
EventWindowPolicy::ExtendDown { window_size } => {
match progress {
Some((min, _)) if min > floor_block => {
let from = min.saturating_sub(window_size).max(floor_block);
(from, None)
}
Some(_) => {
let (min, max) = progress.unwrap_or((0, 0));
return Ok(EventWindowOutcome {
merged: ds.load_address_events(&address),
fetched: 0,
next_token: None,
deferred_gap: None,
max_searched: max,
min_searched: min,
suggested_next_window: None,
page: empty_page(),
});
}
None => {
resolve_top_delta(progress, latest_block)
}
}
}
EventWindowPolicy::FillGap { from_block, .. } => (from_block, None),
};
let to_block = match policy {
EventWindowPolicy::FillGap { to_block, .. } => Some(to_block),
EventWindowPolicy::ExtendDown { .. } => progress.and_then(|(min, _)| min.checked_sub(1)),
EventWindowPolicy::TopDelta => None,
};
debug!(
address = %format!("{:#x}", address),
?policy,
from_block,
?to_block,
?deferred_gap,
pf_available = pf.is_some(),
"event_window: fetching"
);
let page = match pf {
Some(pf_client) => {
fetch_address_activity(
address,
kind,
from_block,
to_block,
None,
EVENT_PAGE_LIMIT,
pf_client,
)
.await
.inspect_err(|e| {
warn!(
address = %format!("{:#x}", address),
error = %e,
"event_window: fetch_address_activity failed"
);
})?
}
None => {
let events = fetch_events_routed(
kind,
None,
ds,
address,
Some(from_block),
to_block,
EVENT_PAGE_LIMIT as usize,
)
.await
.inspect_err(|e| {
warn!(
address = %format!("{:#x}", address),
error = %e,
"event_window: RPC event scan failed"
);
})?;
page_from_events(events)
}
};
let fetched = page.events.len();
let merged = ds.merge_address_events(&address, &page.events);
let scanned_min = match policy {
EventWindowPolicy::TopDelta => from_block,
EventWindowPolicy::ExtendDown { .. } => from_block,
EventWindowPolicy::FillGap { from_block, .. } => from_block,
};
let scanned_max = to_block.unwrap_or(latest_block);
if scanned_max >= scanned_min {
ds.save_search_progress(&address, filter_kind, scanned_min, scanned_max);
}
let (min_searched, max_searched) = ds
.load_search_progress(&address, filter_kind)
.unwrap_or((scanned_min, scanned_max));
let suggested_next_window = match policy {
EventWindowPolicy::ExtendDown { window_size } => {
Some(suggest_next_window(window_size, fetched))
}
_ => None,
};
Ok(EventWindowOutcome {
merged,
fetched,
next_token: page.next_token,
deferred_gap,
max_searched,
min_searched,
suggested_next_window,
page,
})
}
fn suggest_next_window(current: u64, fetched: usize) -> u64 {
let next = if fetched == 0 {
current.saturating_mul(2)
} else if fetched >= EVENT_PAGE_LIMIT as usize {
current / 2
} else {
current
};
next.clamp(EXTEND_DOWN_MIN_WINDOW, EXTEND_DOWN_MAX_WINDOW)
}
fn empty_page() -> AddressActivityPage {
AddressActivityPage {
events: Vec::new(),
tx_rows: Vec::new(),
unique_hashes: Vec::new(),
tx_block_map: std::collections::HashMap::new(),
next_token: None,
}
}
fn page_from_events(events: Vec<SnEvent>) -> AddressActivityPage {
let mut unique_hashes: Vec<Felt> = Vec::with_capacity(events.len());
let mut seen: std::collections::HashSet<Felt> = std::collections::HashSet::new();
let mut tx_block_map: std::collections::HashMap<Felt, u64> = std::collections::HashMap::new();
for e in &events {
if e.transaction_hash != Felt::ZERO && seen.insert(e.transaction_hash) {
unique_hashes.push(e.transaction_hash);
}
tx_block_map
.entry(e.transaction_hash)
.or_insert(e.block_number);
}
AddressActivityPage {
events,
tx_rows: Vec::new(),
unique_hashes,
tx_block_map,
next_token: None,
}
}
fn resolve_top_delta(progress: Option<(u64, u64)>, latest_block: u64) -> (u64, Option<(u64, u64)>) {
let Some((_min, max_searched)) = progress else {
let from = latest_block.saturating_sub(TIP_ONLY_WINDOW_BLOCKS);
return (from, None);
};
if latest_block <= max_searched {
return (max_searched.saturating_add(1), None);
}
let delta = latest_block - max_searched;
if delta <= EVENT_LARGE_GAP_THRESHOLD_BLOCKS {
(max_searched.saturating_add(1), None)
} else {
let tip_start = latest_block.saturating_sub(TIP_ONLY_WINDOW_BLOCKS);
let gap = (max_searched.saturating_add(1), tip_start.saturating_sub(1));
(tip_start, Some(gap))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn top_delta_cold_cache_fetches_tip_only() {
let (from, gap) = resolve_top_delta(None, 9_000_000);
assert_eq!(from, 9_000_000 - TIP_ONLY_WINDOW_BLOCKS);
assert_eq!(gap, None);
}
#[test]
fn top_delta_small_gap_fetches_contiguous() {
let (from, gap) = resolve_top_delta(Some((3_000_000, 8_900_000)), 8_950_000);
assert_eq!(from, 8_900_001);
assert_eq!(gap, None);
}
#[test]
fn top_delta_large_gap_defers_backfill() {
let (from, gap) = resolve_top_delta(Some((3_000_000, 5_000_000)), 9_000_000);
let tip_start = 9_000_000 - TIP_ONLY_WINDOW_BLOCKS;
assert_eq!(from, tip_start);
assert_eq!(gap, Some((5_000_001, tip_start - 1)));
}
#[test]
fn top_delta_no_new_blocks_is_noop() {
let (from, gap) = resolve_top_delta(Some((0, 9_000_000)), 9_000_000);
assert_eq!(from, 9_000_001); assert_eq!(gap, None);
}
#[test]
fn suggest_next_window_doubles_on_empty_page() {
assert_eq!(suggest_next_window(5_000, 0), 10_000);
assert_eq!(suggest_next_window(50_000, 0), 100_000);
}
#[test]
fn suggest_next_window_caps_at_max() {
assert_eq!(
suggest_next_window(EXTEND_DOWN_MAX_WINDOW, 0),
EXTEND_DOWN_MAX_WINDOW
);
assert_eq!(
suggest_next_window(EXTEND_DOWN_MAX_WINDOW / 2 + 1, 0),
EXTEND_DOWN_MAX_WINDOW
);
}
#[test]
fn suggest_next_window_halves_on_full_page() {
assert_eq!(
suggest_next_window(100_000, EVENT_PAGE_LIMIT as usize),
50_000
);
}
#[test]
fn suggest_next_window_floors_at_min() {
assert_eq!(
suggest_next_window(EXTEND_DOWN_MIN_WINDOW, EVENT_PAGE_LIMIT as usize),
EXTEND_DOWN_MIN_WINDOW
);
}
#[test]
fn suggest_next_window_keeps_on_partial_page() {
assert_eq!(suggest_next_window(20_000, 37), 20_000);
}
}