Architecture Decision Record Generator for Contracts

WHAT IT DOES

Architecture Decision Record Generator for Contracts is a read-only developer tool that generates structured Architecture Decision Record (ADR) templates based on analysis of deployed EVM smart contracts. It reads contract bytecode to detect architectural patterns including external calls (CALL), storage operations (SLOAD/SSTORE), function selectors, SELFDESTRUCT, REVERT, and the number of public functions. It combines this bytecode analysis with user-provided context, decision descriptions, and contract metadata (address, block number, chain ID) to produce a complete ADR document. The tool helps developers document architectural choices, capture design decisions, and maintain a clear record of why contracts are built the way they are—essential for team collaboration, audits, and long-term maintainability.

HOW TO USE

Connect your EVM-compatible wallet via the BGWallet bridge and select the network where your contract is deployed. Enter the contract address, an ADR title, the context/background describing the architectural situation, and the decision made. Click "Generate ADR" to produce a structured ADR document. Results include a comprehensive ADR with status, date, contract metadata, context, decision, detected architecture patterns, consequences (positive and negative), alternatives considered, and notes. The tool also provides a copy button for the generated ADR. All analysis is read-only—no signatures or transactions are submitted.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to fetch contract bytecode via provider.getCode(address), block number via provider.getBlockNumber(), and chain ID via provider.getNetwork(). It performs static bytecode analysis by scanning the hex string for key opcode patterns: 0x73 for CALL (external calls), 0x54 for SLOAD (storage reads), 0x55 for SSTORE (storage writes), 0x63 for PUSH4 (function selectors), 0xff for SELFDESTRUCT, and 0xfd for REVERT. The tool also counts the number of function selectors to assess contract complexity. These detected patterns are presented as architectural evidence in the ADR. The user-provided context and decision are incorporated into the ADR template, which follows a standard ADR format with status, date, metadata, context, decision, consequences, alternatives, and notes. The generated ADR is displayed in a textarea for review and copying. The tool does not store any data—results are generated on-demand and displayed in the UI.

WHAT IT CANNOT SEE

This tool has fundamental limitations that users must understand. It cannot determine the rationale behind architectural decisions without developer input—the tool provides a template but relies on the user to explain the reasoning. It cannot automatically identify which design patterns were intentionally chosen vs. coincidental—the tool detects patterns but cannot infer intent. It cannot generate context about business requirements or constraints that drove decisions—this must be provided by the user. It cannot produce decision records for decisions that are not reflected in the bytecode—off-chain decisions, process choices, or implementation details that don't appear in the bytecode are not captured. It cannot validate whether the architecture is appropriate for the intended use case—the tool does not assess fitness for purpose. It cannot capture decisions made off-chain or in the development process—the tool only sees the final deployed bytecode. It cannot identify vulnerabilities or security issues in the architecture. It cannot compare architectures across multiple contracts. The generated ADR is a template and requires manual review and enhancement to accurately reflect the actual architectural reasoning.

PLEASE NOTE

This tool only supports EVM-compatible blockchains (Ethereum, Polygon, BSC, Avalanche C-Chain, Optimism, Arbitrum, and their testnets). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. The tool is free, open-source, requires no API keys, and uses the wallet's native provider for all read operations. Architecture Decision Records are an important part of documentation—always review and enhance generated ADRs with actual team knowledge and reasoning.