ChainStory

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 journey
• An 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+ transactions
• Shareable story pages and JSON exports

ChainStory 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 reputation
• Understanding DeFi participation and protocol usage
• Sharing your blockchain journey on social media
• Analyzing token transfers and trading patterns
• Discovering the story behind any Ethereum address

Try it: "Tell me the story of mattkoch.eth" or "Analyze 0x..." in ChatGPT

ChainStory is built with a two-server architecture optimized for ChatGPT integration:

MCP Server (Node.js + TypeScript):

• Implements Model Context Protocol for ChatGPT communication
• Connects to Blockscout MCP via StreamableHTTP for multi-chain data
• Smart sampling algorithm: fetches oldest transactions (genesis accuracy) + recent activity in parallel
• Ethereum-first strategy with 90s timeout, L2s fetched concurrently with 40s timeouts
• Story generation engine that analyzes patterns and creates character traits
• Share endpoint generates shareable HTML pages with embedded story data

Widget (React + Tailwind + Vite):

• Interactive timeline with Framer Motion animations
• Real-time loading states and error handling
• Chain filtering, block explorer links, and modal dialogs
• Responsive design optimized for ChatGPT's iframe constraints
• Built with esbuild for minimal bundle size (106KB gzipped)

Key Technical Challenges Solved:

1. 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.

2. 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.

3. 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.

4. 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 transfers
• Multi-chain support across 5 networks (Ethereum, Optimism, Arbitrum, Polygon, Base)
• Handles ENS resolution via Blockscout's address endpoint
• Direct block explorer links in the UI

Notable Hacks:

• Custom build script generates version-hashed assets (chainstory-2d2b.*)
• HTML wrapper inlines CSS/JS for single-file deployment
• Clipboard fallback using textarea method for ChatGPT's restricted environment
• Share feature generates unique IDs and stores story data server-side

Tech Stack: Node.js, TypeScript, React 19, Framer Motion, Tailwind CSS 4, Vite, MCP SDK, Zod, Blockscout MCP