Declarative state checks for EVM smart contracts.

Quick Start · How-To Guides · Configuration Reference · CLI Reference · Environment Reference · JSON Output · Observed Values · ABI & Proxies

state-mate compares live EVM contract state with an expected state declared in YAML. It verifies function results, storage slots, access control, proxy implementations, and proxy admin ownership. Failed checks produce a non-zero exit code for local and CI use.

Quick start

Requirements: Node.js 24 or newer, Corepack with Yarn 4, and an RPC endpoint for each target network.

corepack enable
yarn install
cp .env.sample .env

Set the environment variables required by your config, then run it:

yarn start path/to/config.yaml

What it checks

• view-function results and expected reverts
• raw storage slots
• enumerable and non-enumerable OpenZeppelin access control; non-enumerable checks automatically discover candidate holders from RoleGranted events and let the chain decide who still holds
• the full Aragon DAO permission map — grants, parameterized grants, and permission managers — discovered from the ACL's event history and reconciled against its raw storage
• proxy implementations and ProxyAdmin ownership
• coverage of every view and pure function in the selected ABI

Development

yarn test
yarn lint
yarn format
yarn typecheck

Pull requests, bug reports, and feature requests are welcome.

License

MIT