> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocklight.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Rule Structure

> YAML rule format and required fields

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:

```yaml theme={null}
# 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
```

<Warning>
  **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](/rules/macros) for details.
</Warning>

## 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:

1. `rule` - Rule identifier
2. `desc` - Description
3. `references` - Threat intelligence links (optional)
4. `tags` - Categorization tags (optional)
5. `condition` - Detection logic
6. `output` - Alert message
7. `priority` - Severity level
8. `chain` - Target networks (optional)
9. `enabled` - Activation status

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

## 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

```yaml theme={null}
- 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

<CardGroup cols={2}>
  <Card title="Fields" icon="file-lines" href="/rules/fields">
    Learn about available transaction fields
  </Card>

  <Card title="Lists & Macros" icon="brackets-curly" href="/rules/macros">
    Create reusable components
  </Card>

  <Card title="Operators" icon="code" href="/rules/operators">
    Build conditions with operators
  </Card>

  <Card title="Examples" icon="book" href="/rules/examples">
    See complete rule examples
  </Card>
</CardGroup>