{"id":29248507,"url":"https://github.com/polareth/tiny-explorer","last_synced_at":"2026-02-12T21:03:06.740Z","repository":{"id":281525192,"uuid":"945538179","full_name":"polareth/tiny-explorer","owner":"polareth","description":"A user-friendly interface for explaining contracts and events in real time on EVM chains using AI.","archived":false,"fork":false,"pushed_at":"2025-03-17T15:38:35.000Z","size":1257,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-04T14:40:40.696Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polareth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-09T16:57:30.000Z","updated_at":"2025-03-21T17:13:06.000Z","dependencies_parsed_at":"2025-07-04T00:03:50.704Z","dependency_job_id":"b0cfb3a5-d3fe-40a1-a1a4-a60a6e283d8b","html_url":"https://github.com/polareth/tiny-explorer","commit_stats":null,"previous_names":["0xpolarzero/evm-ai-indexer","0xpolarzero/tiny-explorer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/polareth/tiny-explorer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polareth%2Ftiny-explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polareth%2Ftiny-explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polareth%2Ftiny-explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polareth%2Ftiny-explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polareth","download_url":"https://codeload.github.com/polareth/tiny-explorer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polareth%2Ftiny-explorer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29381043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T20:34:40.886Z","status":"ssl_error","status_checked_at":"2026-02-12T20:23:00.490Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-04T00:07:59.298Z","updated_at":"2026-02-12T21:03:06.724Z","avatar_url":"https://github.com/polareth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TinyExplorer\n\n**A user-friendly interface for explaining contracts and transactions on EVM chains using a LLM.**\n\n## Table of contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Development](#development)\n  - [Docker](#docker)\n  - [Configuration](#configuration)\n- [Architecture](#architecture)\n  - [Packages](#packages)\n  - [Flow](#flow)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nTinyExplorer provides intuitive, human-readable explanations of smart contracts, including their functions and events, and breaks down transactions into a similar format.\n\n- **Contract Analysis**: Fetch and analyze smart contract source code and ABIs\n- **AI Explanations**: Generate human-readable explanations of contract functionality and interactions using LLMs\n- **Multi-Chain Support**: Configurable support for different EVM-compatible blockchains\n- **Caching**: Efficient caching to reduce API calls and improve performance\n- **User Interface**: Clean, intuitive React UI for interacting with the system\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) (tested with v23.8.0)\n- [pnpm](https://pnpm.io/) (tested with v9.15.6)\n- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) (for containerized deployment); or you can use [OrbStack](https://www.orbstack.dev/) on Mac\n- [Foundry](https://getfoundry.sh/) (for smart contract development)\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/0xpolarzero/tiny-explorer.git\ncd tiny-explorer\n```\n\n2. Install dependencies:\n\n```bash\npnpm install\n```\n\n3. Set up environment variables:\n\n```bash\ncp .env.example .env\n# Edit .env with your configuration\n```\n\n## Usage\n\n### Development\n\nTo run the entire system in development mode:\n\n```bash\npnpm dev\n```\n\nThis will start:\n\n- Redis cache (Dragonfly)\n- tRPC server\n- React frontend\n\n### Configuration\n\nKey configuration options:\n\n- **LLM Provider**: Currently uses OpenRouter, configurable to other providers\n- **Blockchain Networks**: Add RPC URLs and explorer API keys in the environment file\n- **Caching**: Adjust cache TTL and other parameters in environment variables\n\n## Architecture\n\n### Packages\n\nThe project is organized as a monorepo with the following packages:\n\n- [**core**](./packages/core/README.md): Shared configuration, constants, types, and utilities\n- [**server**](./packages/server/README.md): tRPC server providing API endpoints for contract analysis\n- [**web**](./packages/web/README.md): React frontend for interacting with the system\n- [**contracts**](./packages/contracts/README.md): Example smart contracts for testing\n\n### Flow\n\n1. **User Input**: User provides a contract address and selects a blockchain network\n2. **Contract Fetching**: System fetches contract ABI and source code using WhatsAbi\n3. **AI Analysis**: LLM analyzes the contract and generates explanations\n4. **Event Monitoring**: System listens for contract events in real-time\n5. **Explanation**: Events are explained to the user as they occur\n\n## TODO\n\nFuture development plans:\n\n- [x] Use whatsabi to get the contract code and abi (especially code)\n- [ ] ass multiple api keys for various chains\n- [x] create server for both llm \u0026 backend stuff\n  - [x] use caching for contract code \u0026 abi\n- [ ] add lm studio running in docker instead of deep infra https://gitlab.com/logliwo/lm-studio-docker-compose/-/tree/main?ref_type=heads (??)\n- [ ] update server to use serverless\n- [ ] the cache is not a database; a lot of stuff needs to be saved into a database instead (e.g. transaction details, transaction explanations)\n- [ ] 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.\n- [ ] simulate tx with tevm then explain it\n- [ ] simulate multiple txs (actually executed with tevm for accurate state) and get the payload for batch executing\n- [ ] 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?\n- [ ] for unverified contracts, better interpretation where the LLM is provided all state/storage changes and figures out if anything weird happened\n- [ ] train LLM for this specific purpose (on transactions that might not be understandable -\u003e understandable output)\n- [ ] provide just API for external use, maybe it can be self-hosted as well\n- [ ] port to krome, enter api keys first time, then run whenever you want and eveything is stored locally\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolareth%2Ftiny-explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolareth%2Ftiny-explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolareth%2Ftiny-explorer/lists"}