Skip to main content
Get the most out of Blocklight with these recommendations:

​
Start Simple

Begin with basic rules. Keep rules simple and focused on what you need to detect.

​
Always Validate & Test

Use validate and dry-run before deploying rules.

​
Use Testing Directory for Development

Create new rules in rules/testing/ first, then test them with dry-run before moving to production:
  1. Create rule in testing directory: 
    # Create your rule
vim rules/testing/my_new_rule.yaml
  2. Test it safely: 
    # Test without affecting production (dry-run automatically includes testing rules)
blocklight dry-run --tx 0xabc123...
  3. Move to production when ready: 
    # Once validated, move to custom
mv rules/testing/my_new_rule.yaml rules/custom/
Important: Rules in rules/testing/ are NEVER loaded in production (when running blocklight start). The dry-run command automatically includes them for testing purposes, ensuring you can test rules safely without generating alerts or affecting your monitoring system.

​
Caching

Caching is always enabled in Blocklight for optimal performance. Configure appropriate TTL values in analysis config based on your use case.

​
Use Aggregation

Enable aggregation to reduce alert fatigue in high-volume scenarios.

​
Reuse Components

Use lists and macros to keep rules maintainable. Important: lists and macros are defined at the file level (not inside rules), allowing you to create reusable building blocks that multiple rules in the same file can share.

​
Secure Your Secrets

Use ${ENV_VARS} in alert configuration. Never commit secrets.