Invariant Test Scenario Builder

WHAT IT DOES

Invariant Test Scenario Builder is a read-only developer tool that builds test scenarios for invariant testing of smart contracts. It reads the contract ABI, invariant definitions (user-provided), contract state variables, current on-chain state (via the provider), function signatures, parameter types, and scenario configuration (sequence length and iteration count). The tool then generates a set of test scenarios—each consisting of a sequence of function calls—that can be used to test whether the contract's invariants hold under various sequences of operations. This helps developers identify potential invariant violations before deploying contracts to production.

HOW TO USE

Connect your wallet via the built-in connector. Select the network where the contract is deployed. Enter the contract ABI as a JSON array. Provide invariant definitions (one per line, e.g., "totalSupply == sum(balances)"). Optionally, enter the contract address to read current on-chain state for more realistic scenarios. Configure the sequence length (number of calls per scenario) and the number of iterations (scenarios to generate). The tool will parse the ABI, extract functions, read contract state if an address is provided, and generate test scenarios. The results display: functions detected, invariants defined, scenarios generated, sequence length, and the scenarios themselves—each showing a sequence of function calls with arguments. The tool also shows previous scenario records (simulated, as this is read-only).

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to parse the ABI and read contract state. It extracts all function names from the ABI and, if a contract address is provided, attempts to read view/pure functions to get current state values. For scenario generation, the tool creates sequences of function calls by randomly selecting functions and generating random arguments based on the parameter types. It supports common parameter types: address, uint256, int256, bool, and string. The tool uses the specified sequence length and iteration count to generate a diverse set of scenarios. Each scenario is paired with the invariant definitions provided by the user, allowing testers to manually verify the invariants after running the scenario. The tool does not execute any transactions or perform any on-chain modifications—it only reads state and generates scenarios locally. No data is sent to any server.

WHAT IT CANNOT SEE

This tool cannot verify that invariant definitions are correct—it only uses them as labels for scenarios. It cannot detect if scenarios will actually break invariants—this requires running the scenarios against the contract. It cannot guarantee that scenarios cover all possible states. It cannot ensure that scenarios are reproducible across different contract versions. It cannot predict if scenarios will trigger invariant violations. It cannot validate that the contract state is consistent across reads. It cannot detect if scenarios are too similar to each other. It cannot verify that scenarios are appropriate for the contract's current state.

PLEASE NOTE

This tool is EVM-only and works across all supported chains (Ethereum, Polygon, BNB Chain, Arbitrum, Optimism, Avalanche). The scenario generation is local—no data is transmitted. The generated scenarios are a starting point for testing; you should combine them with a proper invariant testing framework like Foundry or Echidna. The tool does not execute any tests—it only generates scenarios. Always validate the generated scenarios before using them in a testing campaign.