Rule Structure

Every detection rule is a YAML document. This page covers the rule structure, required fields, and how to organize your rules.

File Structure

A rule file contains reusable components (lists and macros) followed by rules. Components are defined first, then rules reference them:

# 1. Reusable components (defined at file level, before rules)
- list: monitored_addresses
  items:
    - "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

- macro: is_high_value
  condition: tx.value > 100 ether

# 2. Rules (reference components defined above)
- rule: High Value Transfer to Monitored Address
  desc: Detects large transfers to monitored addresses
  tags: ["security", "high-value"]
  condition: >
    is_high_value and tx.to in (monitored_addresses)
  output: >
    High value transfer detected: %tx.value_eth ETH to %tx.to
  priority: WARNING
  chain: ["ethereum"]
  enabled: true

Important: lists and macros are NOT fields within a rule. They are separate components defined at the file level (before rules) that can be reused by multiple rules in the same file. See Lists & Macros for details.

Organizing Rules in Files

Best Practice: When grouping multiple rules in the same file, ensure they are related to each other (e.g., same category, same threat type, or same protocol). This makes maintenance easier and keeps your rule base organized. While lists and macros can be shared across rules in the same file, mixing unrelated rules in a single file can make maintenance complex. Consider organizing rules by:

Category: All DEX-related rules together, all mixer-related rules together, etc.
Threat Type: All flash loan attack rules, all phishing rules, etc.
Protocol: All rules monitoring a specific protocol or contract
Chain: Rules specific to a particular blockchain

Example: A file rules/custom/dex-monitoring.yaml might contain:

Lists of known DEX routers
Macros for DEX interaction patterns
Multiple rules detecting different DEX-related threats

This organization makes it easier to:

Find and update related rules
Maintain shared lists and macros
Understand the purpose of each file
Avoid conflicts when multiple team members work on rules

Required Fields

Every rule must include these fields:

Field	Type	Description	Example
`rule`	string	Unique rule name	`High Value Transfer`
`desc`	string	Human-readable description	`Detects transfers over 100 ETH`
`condition`	string	Detection condition expression	`tx.value > 100 ether`
`output`	string	Alert message with placeholders	`Large transfer: %tx.value_eth ETH`
`priority`	string	Alert priority: `NOTICE`, `WARNING`, or `CRITICAL`	`WARNING`
`enabled`	boolean	Whether rule is active	`true`

Optional Fields

Field	Type	Description	Example
`tags`	array	Tags for categorization	`["security", "high-value"]`
`chain`	array	Target blockchain(s). If not specified, applies to all enabled chains	`["ethereum", "polygon"]`
`references`	array	URLs to threat intelligence, blog posts, or documentation	`["https://rekt.news/..."]`

Recommended Field Order

For consistency, follow this field order within each rule:

rule - Rule identifier
desc - Description
references - Threat intelligence links (optional)
tags - Categorization tags (optional)
condition - Detection logic
output - Alert message
priority - Severity level
chain - Target networks (optional)
enabled - Activation status

The validator will warn if fields are out of order, but won’t block validation. This helps maintain consistency across your rule base.

References Field

The references field allows you to document threat intelligence sources, blog posts, exploit analyses, or any relevant context for your detection rule.

Example

- rule: Euler Finance Exploit Pattern
  desc: Detects donation attack pattern similar to Euler Finance hack (March 2023)
  references:
    - "https://rekt.news/euler-finance-rekt/"
    - "https://twitter.com/BlockSecTeam/status/1635527807996932096"
  tags: ["defi", "flash-loan", "exploit"]
  condition: >
    tx.logs.any(event_name == "Donate") and
    tx.value > 10 ether
  output: >
    Potential donation attack detected - Value: %tx.value_eth ETH
  priority: CRITICAL
  chain: ["ethereum"]
  enabled: true

When this rule triggers in dry-run, the references will be displayed in the output.

Next Steps

Fields

Learn about available transaction fields

Lists & Macros

Create reusable components

Operators

Build conditions with operators

Examples

See complete rule examples

Welcome

Rules

Deployment

CLI Tools

Features

Production

File Structure

Organizing Rules in Files

Required Fields

Optional Fields

Recommended Field Order

References Field

Example

Next Steps

Fields

Lists & Macros

Operators

Examples

​File Structure

​Organizing Rules in Files

​Required Fields

​Optional Fields

​Recommended Field Order

​References Field

​Example

​Next Steps

Fields

Lists & Macros

Operators

Examples

File Structure

Organizing Rules in Files

Required Fields

Optional Fields

Recommended Field Order

References Field

Example

Next Steps