ChainStory

Problem Statement

ChainStory is a ChatGPT app that turns any Ethereum wallet's transaction history into an interactive narrative story. Simply ask "Tell me the story of vitalik.eth" and ChainStory analyzes transactions across Ethereum, Optimism, Arbitrum, Polygon, and Base to generate:An AI-written narrative describing the wallet's blockchain journeyAn interactive timeline of key moments (genesis, milestones, DeFi activity)Character traits based on on-chain behavior (e.g., "DeFi Explorer", "NFT Collector")Smart sampling that accurately identifies wallet genesis dates even for wallets with 1000+ transactionsShareable story pages and JSON exportsChainStory uses the Model Context Protocol (MCP) to integrate with ChatGPT and Blockscout's blockchain data infrastructure. The smart sampling algorithm fetches 30% of oldest transactions (for accurate genesis) and 70% of recent activity (for current behavior), optimized to stay under ChatGPT's timeout limits while maintaining accuracy.Perfect for:Exploring wallet behavior and on-chain reputationUnderstanding DeFi participation and protocol usageSharing your blockchain journey on social mediaAnalyzing token transfers and trading patternsDiscovering the story behind any Ethereum addressTry it: "Tell me the story of mattkoch.eth" or "Analyze 0x..." in ChatGPT

Solution

ChainStory is built with a two-server architecture optimized for ChatGPT integration:MCP Server (Node.js + TypeScript):Implements Model Context Protocol for ChatGPT communicationConnects to Blockscout MCP via StreamableHTTP for multi-chain dataSmart sampling algorithm: fetches oldest transactions (genesis accuracy) + recent activity in parallelEthereum-first strategy with 90s timeout, L2s fetched concurrently with 40s timeoutsStory generation engine that analyzes patterns and creates character traitsShare endpoint generates shareable HTML pages with embedded story dataWidget (React + Tailwind + Vite):Interactive timeline with Framer Motion animationsReal-time loading states and error handlingChain filtering, block explorer links, and modal dialogsResponsive design optimized for ChatGPT's iframe constraintsBuilt with esbuild for minimal bundle size (106KB gzipped)Key Technical Challenges Solved:Genesis Date Accuracy:Large wallets (vitalik.eth with 10,000+ transactions) were showing incorrect genesis dates. Solution: Smart sampling fetches 30% from early blockchain era (2015-2020 for Ethereum) using age_to parameter, ensuring we capture the actual first transaction.ChatGPT Timeout Management:Total execution budget is ~130s. Solution: Fetch Ethereum first (most important for genesis) with 90s timeout, then fetch L2s in parallel with 40s timeouts. Uses Promise.race() to handle timeouts gracefully.Widget Asset Loading:ChatGPT requires external assets. Solution: Separate static file server (port 4444) serves compiled widget files with version-based hashing (2d2b) for cache busting.Token Spam Filtering:Token transfer APIs include spam. Solution: Filter by token value, transaction age, and known spam patterns to surface meaningful activity.Blockscout Integration:Uses Blockscout MCP for transactions, address info, and token transfersMulti-chain support across 5 networks (Ethereum, Optimism, Arbitrum, Polygon, Base)Handles ENS resolution via Blockscout's address endpointDirect block explorer links in the UINotable Hacks:Custom build script generates version-hashed assets (chainstory-2d2b.*)HTML wrapper inlines CSS/JS for single-file deploymentClipboard fallback using textarea method for ChatGPT's restricted environmentShare feature generates unique IDs and stores story data server-sideTech Stack: Node.js, TypeScript, React 19, Framer Motion, Tailwind CSS 4, Vite, MCP SDK, Zod, Blockscout MCP