Skip to content

classify-rules.md

Latest commit

 

History

History
86 lines (55 loc) · 2.65 KB

classify-rules.md

File metadata and controls

86 lines (55 loc) · 2.65 KB
Raw

Address Classification Rules

hyena analyze classify runs a set of heuristic rules against the indexed activity for an address and returns zero or more labels. Each label includes a machine-readable reason string.

How It Works

Rules are evaluated against a ClassificationContext that contains:

  • the address's AddressProfile (tx count, native in/out, top counterparties)
  • derived ClassificationMetrics (dex swap count, unique counterparties)
  • all indexed StoredTransaction records for the address
  • the active ClassifyConfig thresholds

Multiple labels can apply simultaneously.

Labels

whale

Trigger: max(native_in_wei, native_out_wei) >= whale_native_threshold_wei

The address has moved at least the threshold amount of native currency (ETH / ETH-on-Base) in a single direction within the indexed block range.

Default threshold: 10_000_000_000_000_000_000 wei (10 ETH)

Config key:

[classify]
whale_native_threshold_wei = "10000000000000000000"

high_frequency

Trigger: transaction_count >= high_frequency_tx_count
OR: unique_counterparties >= high_frequency_tx_count / 2

The address has a large number of indexed transactions or interacts with many unique counterparties, suggesting automated or high-volume activity.

Default threshold: 25 transactions (or ≥ 12 unique counterparties)

Config key:

[classify]
high_frequency_tx_count = 25

dex_bot_candidate

Trigger: dex_swap_count >= dex_bot_swap_count
OR: the address's event overview contains a swap entry

dex_swap_count counts transactions whose input selector matches known Uniswap v2/v3 router function signatures (swapExactTokensForTokens, swapExactETHForTokens, exactInputSingle, exactInput).

Default threshold: 3 DEX swap transactions

Config key:

[classify]
dex_bot_swap_count = 3

Example Output

address   0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
chain     ethereum
labels    whale, high_frequency
reasons   whale: native flow 246820000000000000000 wei exceeds threshold 10000000000000000000 wei
          high_frequency: transaction_count=3841 unique_counterparties=512 threshold=25

Customising Thresholds

All thresholds are configurable in hyena.toml under [classify]. Lower them to classify smaller wallets, raise them to filter only the top-activity addresses. See hyena.toml.example for the full key list.

Adding Custom Rules

Implement the ClassifierRule trait in crates/analyze/src/lib.rs and register it in RulePack::default_rules(). See CONTRIBUTING.md for details.