EVM Rule Engine

A lightweight and extensible rule engine for evaluating conditions on Ethereum Virtual Machine (EVM) accounts and contracts. Define custom rules to check wallet balances, contract balances, ERC-20 token holdings, transaction counts, NFT ownership, and more.

Compatible with Node and browser environments.

Features

• Wallet Balance: Validate that an account's ETH balance meets specific criteria.
• Contract Balance: Ensure a contract holds a required amount of ETH.
• ERC20 Balance: Check if an account holds a sufficient balance of a given ERC20 token.
• Transaction Count: Verify that an account’s number of transactions (nonce) meets expectations.
• NFT Ownership: Determine if an account owns at least one NFT or a specific NFT token.
• Address Type Verification: Confirm whether an address is a contract or an externally owned account (EOA).
• Contract Call Evaluation: Execute contract functions and evaluate their results against expected outcomes.
• Dynamic Rule Loading: Easily load and export rules from JSON definitions.

Install

npm install evm-rule-engine

Usage

Basic Example

The following example shows how to set up the rule engine, add a rule, and evaluate an EVM address:

import { ethers } from 'ethers'
import { EVMRuleEngine, walletBalance, Networks } from 'evm-rule-engine'

// Configure the network (example using a local Anvil instance)
const networks: Networks = [
  {
    provider: new ethers.JsonRpcProvider('http://127.0.0.1:8545'),
    chainId: '31337'
  }
]

// Create an instance of the rule engine with the network configuration
const engine = new EVMRuleEngine({ networks })

// Add a wallet balance rule: check if the wallet has at least 1 ETH
engine.addRule(
  walletBalance(networks, '31337', {
    value: ethers.parseEther('1'),
    compareType: 'gte'
  })
)

// Evaluate all rules against a given address
const address = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
engine.evaluate(address)
  .then(result => {
    console.log('Evaluation Result:', result)
  })
  .catch(error => {
    console.error('Error evaluating rules:', error)
  })

Loading Rules from JSON

Rules can also be defined in JSON format and loaded dynamically using the createRulesFromDefinitions function:

import { createRulesFromDefinitions } from 'evm-rule-engine'

// Define rule JSON objects
const ruleDefinitions = [
  { type: 'walletBalance', chainId: '31337', params: { value: ethers.parseEther('1'), compareType: 'gte' } }
]

// Create rule instances from the JSON definitions and add them to the engine
const rules = createRulesFromDefinitions(networks, ruleDefinitions)
engine.addRules(rules)

// Export rules as JSON definitions
console.log(engine.exportRulesAsJsonString())

Testing

This project uses Mocha and Chai for testing. Some tests require one or more local Anvil instances.

Start Anvil on port 8545 with chain ID 31337:

anvil --port 8545 --chain-id 31337

Start another instance on port 8546 with chain ID 31338:

anvil --port 8546 --chain-id 31338

Run the tests with:

npm run test

Development

Building Contracts

If your rules interact with Solidity contracts, build them using Forge:

npm run build:contract

Linting and Building the Project

Lint the Code:

npm run lint

Build the Project:

npm run build

Other scripts available in the package.json include test coverage and dependency checks.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the engine, add new features, or fix bugs.

License

This project is dual-licensed under the Apache-2.0 or MIT license.