Skip to content

feat: Detect High-Frequency Contract Calls#210

Merged
mijinummi merged 1 commit into
MD-Creative-Production:mainfrom
bellabuks:feat/high-frequency-contract-call-detection
Jul 21, 2026
Merged

feat: Detect High-Frequency Contract Calls#210
mijinummi merged 1 commit into
MD-Creative-Production:mainfrom
bellabuks:feat/high-frequency-contract-call-detection

Conversation

@bellabuks

Copy link
Copy Markdown
Contributor

What

Implements high-frequency contract call detection requested in #150, under src/modules/detection/contracts/.

Why

Exploits often generate abnormal transaction volume against a contract before or during an attack. This gives Sentinel a way to flag that volume in near real time.

Implementation

HighFrequencyContractCallsService runs two independent detection rules on every recorded call:

  • Frequency monitoringrecordCall() tracks calls per contract in a sliding, tumbling window (getCallCount() / getWindowHistory() expose the current and recently-closed window counts).
  • Baseline comparison — a rolling average is kept across the last baselineWindowCount closed windows (getBaselineAverage()). If the current window's count exceeds that average by baselineSpikeMultiplierx, a baseline_spike alert fires — this catches sustained-but-abnormal activity even when it stays under the absolute cap.
  • Alert generationonAlert() lets subscribers observe FrequencyAlerts (with an unsubscribe function), each carrying the triggering reason, call count, threshold, and (for baseline alerts) the baseline average.
  • Configurable thresholds — a default FrequencyThresholdConfig (window size, absolute cap, baseline window count, spike multiplier) can be set via the constructor, and overridden per contract with setThreshold()/getThreshold(). clearContract() resets all tracked state for a contract.

Follows the same plain-class-plus-interfaces style already used by src/modules/detection/malicious-addresses.

Testing

15 new unit tests in high-frequency-calls.service.spec.ts, using explicit event timestamps (no real-time waiting or fake timers needed) covering: per-contract threshold configuration and overrides, window rolling/history capping, absolute-threshold alerts, baseline-spike alerts, no-alert-on-normal-activity, subscriber notification/unsubscription, and state reset via clearContract.

Verified locally:

  • npm run lint — clean
  • npm run format:check — clean for these files
  • npm run build — passes
  • npx jest --config jest.backend.config.js src/modules/detection/contracts — 15/15 passing
  • Full src/modules suite — 70/70 passing (no regressions)

Acceptance Criteria

  • Activity spikes detected
  • Alerts generated
  • Thresholds configurable

Closes #150

Adds src/modules/detection/contracts/ with
HighFrequencyContractCallsService, which flags abnormal per-contract
call volume via two independent rules: a configurable absolute cap per
sliding window, and a rolling-baseline comparison (current window vs.
a multiple of the average of recent closed windows). Thresholds are
configurable globally (constructor default) and per contract
(setThreshold/getThreshold).

Closes MD-Creative-Production#150
@mijinummi

Copy link
Copy Markdown
Collaborator

LGTM

@mijinummi
mijinummi merged commit 4474f17 into MD-Creative-Production:main Jul 21, 2026
12 checks passed
@grantfox-oss grantfox-oss Bot mentioned this pull request Jul 21, 2026
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Detect High-Frequency Contract Calls

2 participants