state-mate

name

state-mate

description

Use this skill when writing, debugging, or reviewing state-mate YAML configs that verify on-chain EVM contract state — proxy patterns and their storage, multisig wallets, role-based access control, ABI resolution, and discovering unknown on-chain values. Also applies when verifying or auditing a deployment against a config: pre-vote state review, role audit, checking that implementations are neutered and constants aren't forged. Applies even when the user just says a check is failing or asks to add a contract to an existing config, without naming state-mate explicitly.

State-Mate Skill

Validate EVM smart-contract state against YAML configs. state-mate calls view functions and diffs returns against the expected values you declare.

Pick a section

Task	Go to
New config from scratch	Top-level structure, Workflow
Contract with a proxy	Proxy patterns
Multisig checks	Gnosis Safe
Role/ACL checks	Access control
Unknown return values	REPLACEME discovery
Overloaded function (two ABI fragments with same name)	Function overloads
ABI not found / rate-limit / revert reading	Troubleshooting
Deployment verification / audit (pre-vote state, roles)	Read references/verification-playbook.md

Top-level structure

parameters: # optional — arbitrary constants used across the file
  - &someConstant "0x..."

deployed: # address book, grouped by chain
  l1:
    - &contractAddress "0x..."
    - &implAddress "0x..."
  l2: # for multi-chain configs (e.g. L1↔L2 bridges)
    - &l2ContractAddress "0x..."

misc: # numeric/bytes32 constants, EIP slots, zeros
  - &ZERO_ADDRESS "0x0000000000000000000000000000000000000000"
  - &ZERO_BYTES32 "0x0000000000000000000000000000000000000000000000000000000000000000"
  - &EIP1967_ADMIN_SLOT "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103"
  - &EIP1967_IMPLEMENTATION_SLOT "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc"

roles: # bytes32 role hashes, often many (one per domain)
  - &DEFAULT_ADMIN_ROLE "0x00..."
  - &SOME_ROLE "0x..."

eoa: # named EOAs (deployer, signer addresses); useful for "deployer renounced" checks
  - &deployer "0x..."

l1: # per-chain section — literal key name, not the chain's own name
  rpcUrl: ETH_RPC_URL # env-var name, or inline URL
  explorerHostname: api.etherscan.io
  explorerTokenEnv: ETHERSCAN_TOKEN
  chainId: 1 # number or string
  contracts:
    contractName:
      # ...

l2: # present when deployed.l2 exists
  rpcUrl: OPTIMISM_RPC_URL
  # ...

parameters, deployed, misc, roles, eoa are anchor-only sections — they define YAML anchors (&name) that later sections reference via *name. deployed-aux, tvl, delays, signers, selectors, validators are optional anchor-only sections too, same shape as misc. Only <chain-key> sections with contracts: produce on-chain calls.

deployed and the per-chain sections accept exactly two keys: l1 (required) and l2 (optional) — fixed schema literals, not placeholders for the actual network's name. A config for a single L2 chain still uses l1:, never the chain's own name.

Contract patterns

Simple (no proxy)

contractName:
  name: ContractName # must match the name stored in abis.json.gz for this chain and address
  address: *contractAddress
  checks:
    functionName: expectedValue
    anotherFunction: *someVariable

Proxy patterns

Transparent Upgradeable Proxy. proxyChecks: {} because the admin/impl live in EIP-1967 slots. The implementation slot is verified for every entry automatically. proxyAdmin: pins the contract the admin slot holds, proxyAdminOwner: pins the address that controls it one hop further, and neither needs a separate ProxyAdmin entry or its ABI. Declare both: an unexpected ProxyAdmin owned by the expected owner passes the owner check alone.

contractName:
  name: ContractName
  address: *contractAddress
  proxyName: TransparentUpgradeableProxy
  implementation: *implementationAddress
  proxyAdmin: "0x0000000000000000000000000000000000000000" # the ProxyAdmin in the EIP-1967 admin slot
  proxyAdminOwner: *ownerOfTheProxyAdmin
  proxyChecks: {}
  checks:
    # against the proxy (implementation logic, proxy state)
    someFunction: expectedValue
  implementationChecks:
    # against the impl directly (uninitialized state — zeros/empties)
    someFunction: *ZERO_ADDRESS

OssifiableProxy exposes proxy__getAdmin / proxy__getImplementation, so proxyChecks is usually non-empty and storage: isn't needed:

contractName:
  name: ContractName
  address: *contractAddress
  proxyName: OssifiableProxy
  implementation: *implAddress
  proxyChecks:
    proxy__getAdmin: *proxyAdminAddress
    proxy__getImplementation: *implAddress
    proxy__getIsOssified: false
  checks:
    someFunction: expectedValue
  implementationChecks:
    someFunction: *ZERO_ADDRESS

AppProxyUpgradeable has its own shape:

contractName:
  name: ContractName
  address: *contractAddress
  proxyName: AppProxyUpgradeable
  implementation: *implAddress
  proxyChecks:
    proxyType: *PROXY_TYPE_APP_PROXY_UPGRADEABLE
    isDepositable: false
    implementation: *implAddress
    appId: *APP_ID
    kernel: *kernelAddress

ProxyAdmin

proxyAdminName:
  name: ProxyAdmin
  address: *proxyAdminAddress
  checks:
    UPGRADE_INTERFACE_VERSION: "5.0.0"
    owner: *ownerAddress

Gnosis Safe

Safes use storage slot 0 for the singleton (not EIP-1967). Detect via VERSION()(string):

cast call $ADDRESS "VERSION()(string)" --rpc-url $RPC
# Safe → returns "1.4.1"; EOA or non-Safe → reverts

A Safe is a SafeProxy delegating to a singleton — model it as a proxy. name: is the singleton contract (its ABI carries all view functions); SafeProxy exposes no view functions (masterCopy() is a fallback trick absent from the ABI), so proxyChecks: {} and the linkage is verified via slot 0:

multisigName:
  name: Safe # GnosisSafe for pre-1.3.0 deployments
  address: *multisigAddress
  proxyName: SafeProxy
  implementation: *safeSingleton # canonical singleton for that version
  proxyChecks: {}
  storage:
    - slot: "0x0000000000000000000000000000000000000000000000000000000000000000"
      expected: *safeSingleton
      label: singleton
  checks:
    VERSION: "1.4.1"
    getThreshold: *THRESHOLD_VALUE
    getOwners:
      - *signer1
      - *signer2
    isOwner:
      - args: [*signer1]
        result: true

Transient values (Safe nonce, queue canBeRemoved, getResumeSinceTimestamp after a transient pause) drift over time — either leave the key null to skip, or accept that each state change needs a config update.

Contract with indexed collections

checks:
  getItemCount: 2
  hasItem:
    - args: [*item1]
      result: true
  itemAt:
    - args: [0]
      result: *item1
    - args: [1]
      result: *item2
    - args: [2]
      mustRevert: true # out of bounds

Multi-arg indexed getter:

checks:
  itemAt:
    - args: [true, 0]
      result: *depositItem
    - args: [false, 0]
      result: *withdrawItem

Function check patterns

Simple value

checks:
  decimals: 18
  name: "Token Name"

Skipped (requires args or too complex)

checks:
  functionWithArgs: # null value → skipped
  anotherComplexFunction:

With arguments

checks:
  balanceOf:
    - args: [*userAddress]
      result: "1000000000000000000"
  hasRole:
    - args: [*SOME_ROLE, *holderAddress]
      result: true

Must revert

checks:
  itemAt:
    - args: [1]
      mustRevert: true

Tuple / array returns

Document field names with comments — tuple positions aren't obvious from YAML alone:

checks:
  # [fieldA, fieldB, fieldC]
  params: [1000, 86400, 3600]

  simpleParams: [200, 86400] # [penaltyRate, maxAge]

  flags: [false, false, false, 0]

Function overloads

When the ABI has two fragments with the same name, state-mate needs disambiguation. Add signature: inside the arg entry:

checks:
  domainSeparatorV4:
    - args: [*contractAddress]
      signature: "domainSeparatorV4(address)"
      result: *DOMAIN_SEPARATOR

Access control

OpenZeppelin AccessControlEnumerable → ozAcl:

Use when getRoleMemberCount(bytes32) succeeds:

ozAcl:
  *DEFAULT_ADMIN_ROLE : [*adminAddress]
  *SOME_ROLE : [*holder1, *holder2]
  *UNUSED_ROLE : [] # explicit: 0 members

Non-enumerable AccessControl → ozNonEnumerableAcl:

Same shape as ozAcl, but state-mate verifies via per-address hasRole instead of iterating role members. Use for AccessControl without the Enumerable extension:

ozNonEnumerableAcl:
  *DEFAULT_ADMIN_ROLE : [*agent]
  *DEPOSITS_ENABLER_ROLE : [*agent]
  *WITHDRAWALS_DISABLER_ROLE : [*agent, *emergencyMultisig]

Raw hasRole checks

When a contract doesn't expose role management in a standard way, or you only care about specific (role, address) pairs:

checks:
  hasRole:
    - args: [*DEFAULT_ADMIN_ROLE, *adminAddress]
      result: true
    - args: [*SOME_ROLE, *holderAddress]
      result: true

Picking between them

# Enumerable present?
cast call $CONTRACT "getRoleMemberCount(bytes32)(uint256)" $ROLE --rpc-url $RPC
# succeeds → ozAcl; reverts → ozNonEnumerableAcl or raw hasRole

REPLACEME discovery

For unknown function return values:

checks:
  unknownValue: "REPLACEME"

Run yarn start config.yml — the error surfaces the actual on-chain value:

✗ .unknownValue: expected REPLACEME, got 0xb13b0c93...

Do not use REPLACEME in deployed: — invalid-address errors block the whole file from loading. For unknown addresses, read EIP-1967 slots first:

cast admin $PROXY --rpc-url $RPC           # EIP-1967 admin
cast implementation $PROXY --rpc-url $RPC  # EIP-1967 implementation
cast storage $CONTRACT <slot> --rpc-url $RPC

Role discovery

# Enumerable
cast call $CONTRACT "getRoleMemberCount(bytes32)(uint256)" $ROLE --rpc-url $RPC
cast call $CONTRACT "getRoleMember(bytes32,uint256)(address)" $ROLE 0 --rpc-url $RPC

# Non-enumerable
cast call $CONTRACT "hasRole(bytes32,address)(bool)" $ROLE $ADDRESS --rpc-url $RPC

Workflow

Adding a new contract to an existing config:

1. Resolve addresses — cast admin / cast implementation for proxies; EIP-1967 slots for anything non-standard.
2. Define anchors in deployed: (and implementation: addresses in the same section with a matching name).
3. Write the contract stanza — pick the proxy pattern, seed checks: with function names, leave unknowns as REPLACEME.
4. ABIs — a run downloads whatever is missing, no flag needed. They live in abis.json.gz next to the config, keyed by EVM chain ID and lowercase address: { "1:0x…": { name, abi } }. checks resolve the ABI at implementation: (or address: for non-proxies), proxyChecks at address:; the YAML name:/proxyName: must equal the stored contract name.
5. Run, read actuals, replace — iterate yarn start config.yml -o l1/contractName until green.
6. Access control — probe with cast call getRoleMemberCount; choose ozAcl / ozNonEnumerableAcl / hasRole. List every role constant, including empty ones ([]).

Implementation checks

For implementationChecks, use uninitialized defaults — implementations store no state:

Type	Default
Address	*ZERO_ADDRESS
Bytes32	*ZERO_BYTES32
Number	0 (or *MAX_UINT256 for pause-until values)
String	""
Boolean	false
Tuple	All zeros: [0, 0, 0, …]

Running checks

yarn start config.yml                                     # full config
yarn start config.yml -o l1                               # specific section
yarn start config.yml -o l1/contractName                  # specific contract (great for rate-limited RPC)
yarn start config.yml -o l1/contractName/checks/funcName  # single function
yarn start <directory> --update-abi                       # rebuild the store: re-download all, drop unreferenced
yarn start config.yml --quiet                             # failures and totals only (CI uses this)

Best practices

• Named anchors for addresses — define every address in deployed: / eoa:; don't hardcode 0x… inside checks: values. Inline hex is fine for data (bytes32 constants, selectors).
• Anchor naming — addresses are lowerCamelCase (protocolLocator, multisigOwner1; version suffixes keep underscores: safeSingleton_1_3_0). Constants are UPPER_SNAKE: bytes32 roles and slots, numeric parameters (MAX_GROUP_SHARE_LIMIT), hex blobs (MERKLE_TREE_PERMISSIONS), strings. Sentinel addresses count as constants and stay upper: ZERO_ADDRESS, DEAD_ADDRESS, ETH (0xEeee…), DEFAULT_TIER_OPERATOR (0xFFfF…).
• Role hashes live in roles: — every *_ROLE bytes32 goes to the roles: section, not misc:/parameters:; DEFAULT_ADMIN_ROLE first, the rest grouped per contract under a # --- Roles: <contract> --- header.
• Deployer renounced — confirm deployer is not a role holder (not in any ozAcl list; hasRole(…, deployer) = false).
• Empty roles are explicit — list unused roles with [] so a future grant is caught.
• Comment tuples — field names aren't derivable from YAML; look up the ABI.
• Rate-limited RPC? — scope with -o l1/contractName to reduce concurrency.
• Transient values — Safe nonce, getResumeSinceTimestamp, queue operational flags etc. belong as null unless you intentionally want the check to fire on every state change.

Troubleshooting

ABI not found / Cannot find ABI file

• Missing ABIs download on every run, so this means the explorer served none: check that the contract is verified there.
• The store is keyed by chain ID and address, so "not found" means that pair has no entry — download it. A "belongs to X, config expects Y" error means the YAML name:/proxyName: disagrees with the verified contract name at that address — fix the YAML.
• For proxies, checks need the entry at implementation: — make sure the field is present and points at the right address.

delegates to 0x…, while the config expects 0x…

The implementation: in the config is not what the proxy currently delegates to. state-mate checks this for every entry, with or without proxyChecks.

• Read the live address with cast implementation $PROXY, or cast storage $PROXY 0x360894… for the EIP-1967 slot, or cast storage $SAFE 0x0 for a Safe.
• Point implementation: at it and re-run: the new ABI downloads by itself. Set name: to the verified name at the new address.
• One anchor serving two values is a frequent cause. A factory's registryBase is not the implementation its proxies delegate to, so those need separate anchors.
• --skip-implementation-check disables the check when a config pins an implementation on purpose.

delegates to 0x…, but the config describes it as a regular contract

The entry has no implementation:, yet the address holds a non-empty EIP-1967 slot. Every check there runs against the proxy ABI instead of the implementation's.

• Add proxyName: and implementation: and re-run.
• Aragon proxies and Safes never trigger this error: they keep the implementation outside the EIP-1967 slot, so declaring them as proxies is on you.

getRoleMemberCount reverted / no matching function

• The contract is standard AccessControl, not Enumerable — switch to ozNonEnumerableAcl: or raw hasRole checks.
• Or the contract doesn't expose role management at all — skip the role block.

Non-covered functions: ...

• checks: must list every view function of the ABI (unknown ones as null). implementationChecks: doesn't have this requirement: it auto-fills unlisted functions as skipped.

missing revert data with data=null

• Almost always RPC rate limiting or a 502 from the provider, not an on-chain revert.
• Retry with -o l1/contractName scope; or switch RPC provider.
• drpc.org public endpoints are decent for ad-hoc queries.

Invalid address in deployed:

• REPLACEME is invalid in deployed: — resolve the address via cast storage / cast admin first, then add a real anchor.

Ambiguous function overload

Use signature: inside the arg entry (see Function overloads). For cast queries, spell out the full signature:

cast call $CONTRACT "itemAt(bool,uint256)(address)" true 0 --rpc-url $RPC

Unexpected tuple length / field order

The YAML array must match the on-chain struct's field order exactly. Look up the canonical layout in the contract's Solidity source or the ABI's components field — don't rely on field names in the contract UI.