A user-friendly interface for explaining contracts and transactions on EVM chains using a LLM.
TinyExplorer provides intuitive, human-readable explanations of smart contracts, including their functions and events, and breaks down transactions into a similar format.
- Contract Analysis: Fetch and analyze smart contract source code and ABIs
- AI Explanations: Generate human-readable explanations of contract functionality and interactions using LLMs
- Multi-Chain Support: Configurable support for different EVM-compatible blockchains
- Caching: Efficient caching to reduce API calls and improve performance
- User Interface: Clean, intuitive React UI for interacting with the system
- Node.js (tested with v23.8.0)
- pnpm (tested with v9.15.6)
- Docker and Docker Compose (for containerized deployment); or you can use OrbStack on Mac
- Foundry (for smart contract development)
- Clone the repository:
git clone https://github.com/0xpolarzero/tiny-explorer.git
cd tiny-explorer- Install dependencies:
pnpm install- Set up environment variables:
cp .env.example .env
# Edit .env with your configurationTo run the entire system in development mode:
pnpm devThis will start:
- Redis cache (Dragonfly)
- tRPC server
- React frontend
Key configuration options:
- LLM Provider: Currently uses OpenRouter, configurable to other providers
- Blockchain Networks: Add RPC URLs and explorer API keys in the environment file
- Caching: Adjust cache TTL and other parameters in environment variables
The project is organized as a monorepo with the following packages:
- core: Shared configuration, constants, types, and utilities
- server: tRPC server providing API endpoints for contract analysis
- web: React frontend for interacting with the system
- contracts: Example smart contracts for testing
- User Input: User provides a contract address and selects a blockchain network
- Contract Fetching: System fetches contract ABI and source code using WhatsAbi
- AI Analysis: LLM analyzes the contract and generates explanations
- Event Monitoring: System listens for contract events in real-time
- Explanation: Events are explained to the user as they occur
Future development plans:
- Use whatsabi to get the contract code and abi (especially code)
- ass multiple api keys for various chains
- create server for both llm & backend stuff
- use caching for contract code & abi
- add lm studio running in docker instead of deep infra https://gitlab.com/logliwo/lm-studio-docker-compose/-/tree/main?ref_type=heads (??)
- update server to use serverless
- the cache is not a database; a lot of stuff needs to be saved into a database instead (e.g. transaction details, transaction explanations)
- figure out a good model + some ai slop: sometimes it loops over the functions, forgets some, doesn't detect modifiers, etc. Most important is tx simulation tho, so we really need this one right.
- simulate tx with tevm then explain it
- simulate multiple txs (actually executed with tevm for accurate state) and get the payload for batch executing
- better ux after tx/chain of txs was explained and "verified", something to copy/paste or a link and run the tx from your wallet?
- for unverified contracts, better interpretation where the LLM is provided all state/storage changes and figures out if anything weird happened
- train LLM for this specific purpose (on transactions that might not be understandable -> understandable output)
- provide just API for external use, maybe it can be self-hosted as well
- port to krome, enter api keys first time, then run whenever you want and eveything is stored locally
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.