state-mate

state-mate is a simple tool that validates contracts' states against a concise YAML-based description. Run state-mate to verify deploy outcome, current state, access control and more.

state-mate accepts a yaml file that includes contract addresses, view functions and their expected results. It calls each function and compares the output to the expected result.

✨ Features

• state (non-mutable functions result) verification,
• automatically validates that all functions covered,
• supports any EVM network,
• easily configurable checks,
• CI-friendly,
• uses yaml config (env variables, variables, comments).

⚡ Getting started

Requirements

• git
• Node.js >=20,
• yarn

Usage

1. Enable modern yarn support

corepack enable

2. Install dependencies

yarn install

3. Specify RPC endpoints for your target networks, e.g.

# config.seed.yaml

export L1_MAINNET_RPC_URL=%YOUR_RPC_URL%
export L2_MAINNET_RPC_URL=%YOUR_RPC_URL%

4. Prepare a seed config

---
deployed:
  l1:
    - &l1TokenBridge "0xD0DeA0a3bd8E4D55170943129c025d3fe0493F2A"
  l2:
    - &l2TokenBridge "0xb8161F28a5a38cE58f155D9A96bDAc0104985FAc"
    - &l2Wsteth "0x98f96A4B34D03a2E6f225B28b8f8Cb1279562d81"
    - &l2GovExecutor "0x2aCeC6D8ABA90685927b61968D84CfFf6192B32C"

l1:
  rpcUrl: L1_MAINNET_RPC_URL
  explorerHostname: api.etherscan.io
  explorerTokenEnv: ETHERSCAN_TOKEN

l2:
  rpcUrl: L2_MAINNET_RPC_URL
  explorerHostname: explorer.mode.network
  # explorerTokenEnv: ETHERSCAN_MODE_TOKEN

4. Start the program to generate a populated config from the seed one

yarn start path/to/config.seed.yaml --generate

5. Edit the generated config manually

Configuration

Config is a yaml file that contains all the required addresses, parameters, view functions with their expected results for verification. The outline of the config is given below,

# Sample config

parameters:
  # List of parameters
  - &MY_PARAMETER 42

misc:
  # Misc variables
  - &FOO "foo"

deployed:
  # Contract addresses
  - &myContract "0x0000000000000000000000000000000000000001"
  - &adminMultisig "0x0000000000000000000000000000000000000002"

roles:
  # ACL checks
  - &DEFAULT_ADMIN_ROLE "0x0000000000000000000000000000000000000000000000000000000000000000"

l1:
  rpcUrl: L1_MAINNET_RPC_URL # env variable
  contracts:
    myContract:
      name: "myContract"
      address: *myContract
      implementation: "%implementation address%"
      proxyChecks:
        proxy__getAdmin: *adminMultisig
      checks:
        # list of view functions and expected results
        getMyParameter: *MY_PARAMETER
        getFoo: *FOO
      ozAcl:
        *DEFAULT_ADMIN_ROLE : [*adminMultisig]

ABIs

All required ABIs are located in the same directory as the config and placed under abi folder being downloaded upon the first launch. See configs.

state-mate supports two ABI storage formats:

1. Individual files (default): Each contract ABI is stored as a separate JSON file in the abi/ directory
2. Consolidated file: All ABIs are stored in a single abis.json or abis.json.gz file alongside the config

Consolidating ABIs

For large projects with many contracts, you can consolidate all individual ABI files into a single compressed file to reduce repository size and improve performance:

yarn consolidate-abi path/to/config/abi --compress

This command:

• Reads all .json files from the specified ABI directory
• Validates each ABI format
• Consolidates them into a single abis.json.gz file (or abis.json without --compress)
• Places the output file alongside your config file
• Provides compression statistics

Note: You cannot use both consolidated and individual ABI files simultaneously. state-mate will automatically detect which format you're using.

Updating ABIs

Use the --update-abi option to download all ABIs, overwriting existing files:

yarn start path/to/config.yaml --update-abi

🔧 Contributing

Any contributions to this project are welcome. Please fork the repository and submit pull requests with detailed descriptions of your changes. Or you can submit an issue, bug report or feature request.

📃 License

This project is licensed under the MIT License. See the LICENSE file for details.