Auto-Generated State Machine Diagram from Contract

WHAT IT DOES

This tool auto-generates state machine diagrams from smart contracts by analyzing state variables, transition functions, and on-chain events. It extracts state definitions from contract storage and event logs, identifying discrete states and the transitions between them based on historical transaction patterns. The tool visualizes these states and transitions as a structured state machine diagram showing states, transition arrows, event triggers, and terminal states. Results are presented as a detailed state machine diagram with state descriptions, transition lists, event mappings, and flow visualization. This is essential for developers documenting contract behavior, auditors understanding state management, and teams analyzing contract state lifecycle.

HOW TO USE

Connect your wallet (read-only, no transaction required) and select the target network. Enter the contract name and address, and set the lookback blocks for state analysis. Click "generate state machine diagram" and the tool will verify the contract, analyze state variables and transition patterns, and generate a structured state machine diagram. Results display a summary with contract details and state count, a text-based state machine diagram showing states and transitions, detailed state cards showing each state with its description, transitions, and associated events, and a table of all states with their transitions. Use the report to understand contract state lifecycle, document behavior, and identify state management patterns.

TECHNICAL MECHANISM

The generator uses ethers.js v5.7.2 to perform a multi-stage state machine analysis. First, it calls eth_getCode to verify the contract is deployed and uses block explorer APIs to fetch verification status, source code, and ABI. The tool then scans historical logs using eth_getLogs across the specified block range to identify state transition events (e.g., StateChanged, Transitioned, events with state-related parameters). It queries the contract state via eth_call to retrieve current state variable values and identify possible state values from the contract's storage layout. The tool analyzes the ABI to identify functions that cause state transitions, mapping function calls to state changes based on observed patterns. It constructs a state machine model with states (nodes), transitions (edges), and event triggers. States are identified from state variables, event parameters, and observed value ranges. Transitions are inferred from the order of events and state changes in transaction logs. The diagram is represented both as a text-based visualization and a structured data model. Results are compiled into a structured report with detailed state information, transition mappings, and event correlations.

WHAT IT CANNOT SEE

This tool cannot generate diagrams for contracts that are not verified or have opaque state management where state definitions cannot be resolved. It is limited by the RPC provider's rate limits and block range availability for historical log queries. It cannot detect state machines that do not emit state transition events or have implicit state encoding (e.g., bit-packed flags, state derived from multiple variables). The analysis relies on the accuracy and completeness of contract verification and event data; incomplete logs or unverified contracts may produce incomplete diagrams. It cannot analyze contracts that use complex state management patterns (e.g., external state oracles, cross-contract state dependencies) without additional heuristics. The tool is limited to the specific contract instances and state transitions that are accessible via RPC. It cannot guarantee that generated diagrams capture all possible states without exhaustive transaction analysis across a large number of transactions. The diagram is a representation of observed state patterns and may not reflect all possible contract states.

PLEASE NOTE

This is a read‑only analytics tool—it never submits transactions or modifies contract state. It is designed for EVM‑compatible chains and works best with verified contracts that emit state transition events. The generated state machine diagrams are for informational and documentation purposes only and should not be considered a comprehensive behavioral analysis. Always verify state machine behavior against actual contract logic and test edge cases. The tool's state inference is heuristic and based on observed patterns—customize or refine the diagram as needed for your specific documentation requirements.