From 863e2a81463bb1d3297310a75f33c2b4a9f34d06 Mon Sep 17 00:00:00 2001 From: matta Date: Fri, 3 Apr 2026 14:38:54 -0300 Subject: [PATCH 1/8] Updated translations, and added agent documentation and tracking for future work --- AGENTS.md | 130 +++++++++++++ README.md | 125 +++++++++---- app/[locale]/page.tsx | 2 +- app/[locale]/security/51-percent/page.tsx | 2 +- app/[locale]/security/double-signing/page.tsx | 2 +- app/[locale]/security/eclipse-attack/page.tsx | 2 +- app/[locale]/security/front-running/page.tsx | 2 +- .../security/oracle-manipulation/page.tsx | 2 +- app/[locale]/security/page.tsx | 2 +- app/[locale]/security/reentrancy/page.tsx | 2 +- app/[locale]/security/rogue-proposer/page.tsx | 2 +- messages/en.json | 7 +- messages/es.json | 7 +- next-env.d.ts | 2 +- skills/mastering-ethereum.md | 171 ++++++++++++++++++ 15 files changed, 411 insertions(+), 49 deletions(-) create mode 100644 AGENTS.md create mode 100644 skills/mastering-ethereum.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..27f206d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,130 @@ +# AGENTS.md — InteractivETH + +## What This Project Is + +**InteractivETH** is an interactive educational platform for learning Ethereum protocol concepts. It uses hands-on simulations (transaction lifecycle, block building, gas auctions, security attacks) to teach concepts from the book [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook). + +**Branding**: The name is InteractivETH (capital ETH). Favicon is a lotus flower 🪷 (The Red Guild). + +## Critical Rules + +### 1. ALWAYS USE `pnpm` +Never use `npm` or `yarn`. All commands use `pnpm`: +```bash +pnpm install +pnpm dev +pnpm build +``` + +### 2. ALWAYS EXTRACT STRINGS TO TRANSLATIONS +Never hardcode user-facing text. Always use `useTranslations()`: + +```typescript +import { useTranslations } from 'next-intl'; + +const t = useTranslations('namespace'); // or useTranslations() for root +``` + +**Translation workflow:** +1. Add the key to `messages/en.json` first +2. Add the Spanish equivalent to `messages/es.json` +3. Keep both files in sync — same keys, translated values +4. Use the component with `t('key')` or `t('nested.key')` + +**Example:** +```json +// messages/en.json +{ "sandwich": { "title": "Sandwich Attack Simulator" } } + +// messages/es.json +{ "sandwich": { "title": "Simulador de Ataque Sandwich" } } +``` + +```tsx +const t = useTranslations('sandwich'); +

{t('title')}

+``` + +### 3. UPDATE TODOS AND STATUS +After completing work: +- Update `TODO.md` with current status +- Update `SECURITY_TODO.md` for security modules +- Keep this file current if project structure changes + +## Project Structure + +``` +app/[locale]/ → Pages (i18n routing: /en, /es) +components/ + layout/ → Sidebar, breadcrumbs, tutorial layout, page nav + navigation/ → Search modal, locale switcher + ethereum/ → Shared simulator components + tutorials/ → Per-tutorial components (validator/, gas-auction/, etc.) + ui/ → Reusable primitives (CodeBlock, etc.) +messages/ → en.json, es.json (keep keys in sync!) +book/ → Mastering Ethereum git submodule (17 chapters) +public/ → Static assets (lotus favicon) +``` + +## Code Patterns + +### New tutorial page +```tsx +'use client'; +import { useTranslations } from 'next-intl'; +import { TutorialLayout } from '@/components/layout/tutorial-layout'; + +export default function MyTutorialPage() { + const t = useTranslations('myTutorial'); + // ... +} +``` + +### New Coming Soon page +All use the shared pattern in `security/*/page.tsx` with `useTranslations('common')`. + +### File naming +- Components: `kebab-case.tsx` +- Hooks: `use-kebab-case.ts` +- Pages: `page.tsx` in route directories + +## Adding Content + +1. **New tutorial**: Create page in `app/[locale]/slug/`, components in `components/tutorials/slug/`, translations in both JSON files +2. **New translation key**: Add to `en.json` AND `es.json` simultaneously +3. **New route**: Register in `breadcrumbs.tsx` PAGE_HIERARCHY and `sidebar.tsx` +4. **Difficulty badges**: Use `useTranslations('difficulty')` → `td('beginner')`, `td('intermediate')`, `td('advanced')` + +## Book Reference + +The `book/` directory contains Mastering Ethereum as a git submodule with all 17 chapters in Markdown. Use it as the technical reference when building new tutorials. Key mappings: + +| Tutorial | Chapter | +|----------|---------| +| Transactions | 6 (Transactions) | +| Block Builder | 15 (Consensus) | +| Gas & Fees | 6 (Gas) | +| Block Internals | 14 (EVM) + 15 (Consensus) | +| Smart Contracts | 7 (Solidity) + 8 (Vyper) | +| EVM | 14 (EVM) | +| Security modules | 9 (Smart Contract Security) | +| MEV | 16 (Scaling) | + +## Verification + +Before marking work complete: +```bash +pnpm build # Must compile with zero errors +``` + +Check translation parity: +```bash +node -e "const en=require('./messages/en.json');const es=require('./messages/es.json');const ek=Object.keys(en);const sk=Object.keys(es);console.log('en:',ek.length,'es:',sk.length);" +``` + +## Current Status (as of 2026-04-03) + +**Completed:** Transactions, Block Builder, Gas & Fees, Block Internals, Protocol Visualizer, Sandwich Attack simulator +**In progress:** Security section (7/8 modules are "Coming Soon" placeholders) +**Planned:** Smart Contracts, EVM, MEV tutorials +**i18n:** English + Spanish fully wired, all translation keys synced (510+ keys) diff --git a/README.md b/README.md index 12dc017..9c30f42 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,125 @@ -# InteractiveETH +# InteractivETH Interactive educational visualizations for understanding Ethereum protocol concepts, based on [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook). ## Features -- Interactive transaction lifecycle visualization -- Block creation and consensus simulation -- Multi-language support (English, Spanish) -- Modular tutorial architecture for adding new content +- **Interactive Simulators** — Hands-on exploration of Ethereum concepts (transactions, block building, gas markets, consensus) +- **Security Section** — Learn about attack vectors (sandwich attacks, front-running, reentrancy, etc.) with both attack and defense perspectives +- **Bilingual** — Full English/Spanish support via `next-intl` with locale-based routing (`/en/...`, `/es/...`) +- **Difficulty Levels** — Beginner and Advanced modes per tutorial +- **Modular Architecture** — Easy to add new tutorials following established patterns +- **Responsive Design** — Works on desktop and mobile with collapsible sidebar +- **Lotus Flower Favicon** — Branded with The Red Guild identity 🪷 ## Getting Started ```bash -# Install dependencies pnpm install - -# Run development server pnpm dev - -# Build for production -pnpm build ``` -Open [http://localhost:3000](http://localhost:3000) in your browser. +Open [http://localhost:3000](http://localhost:3000). ## Available Tutorials -| Tutorial | Status | -|----------|--------| -| Transactions | Available | -| Blocks | Available | -| Smart Contracts | Coming Soon | -| Gas & Fees | Coming Soon | -| EVM | Coming Soon | -| MEV | Coming Soon | +### Core Concepts + +| Tutorial | Route | Status | +|----------|-------|--------| +| Transactions | `/transactions` | ✅ Available | +| Block Builder | `/validator` | ✅ Available | +| Gas & Fees | `/gas` | ✅ Available | +| Block Internals | `/block-internals` | ✅ Available | +| Protocol Visualizer | `/protocol-visualizer` | ✅ Available | + +### Security + +| Tutorial | Route | Status | +|----------|-------|--------| +| Sandwich Attack | `/security/sandwich-attack` | ✅ Available | +| Front-Running | `/security/front-running` | 🚧 Coming Soon | +| Reentrancy | `/security/reentrancy` | 🚧 Coming Soon | +| Oracle Manipulation | `/security/oracle-manipulation` | 🚧 Coming Soon | +| Rogue Proposer | `/security/rogue-proposer` | 🚧 Coming Soon | +| Double-Signing | `/security/double-signing` | 🚧 Coming Soon | +| Eclipse Attack | `/security/eclipse-attack` | 🚧 Coming Soon | +| 51% Attack | `/security/51-percent` | 🚧 Coming Soon | + +### Planned + +| Tutorial | Book Chapter | +|----------|-------------| +| Smart Contracts | Chapter 7 (Solidity) / Chapter 8 (Vyper) | +| EVM Deep Dive | Chapter 14 | +| MEV & PBS | Chapter 16 | ## Project Structure ``` -├── app/ # Next.js app router pages -│ ├── [locale]/ # i18n routing -│ └── [locale]/transactions/ # First tutorial -├── components/ # React components -│ ├── ethereum/ # Simulator components -│ └── ui/ # UI primitives -├── book/ # Mastering Ethereum source (git submodule) -├── hooks/ # Custom React hooks -├── i18n/ # Internationalization config -├── lib/ # Utilities and types -└── messages/ # Translation files +├── app/ +│ ├── [locale]/ # i18n routing (en, es) +│ │ ├── page.tsx # Landing page +│ │ ├── transactions/ # Core concept tutorials +│ │ ├── validator/ +│ │ ├── gas/ +│ │ ├── block-internals/ +│ │ ├── protocol-visualizer/ +│ │ └── security/ # Security section +│ │ ├── page.tsx # Security overview +│ │ ├── sandwich-attack/ +│ │ └── ... # Coming soon modules +│ └── layout.tsx # Root layout with metadata +├── components/ +│ ├── layout/ # Sidebar, breadcrumbs, navigation +│ ├── navigation/ # Search modal, locale switcher +│ ├── ethereum/ # Shared simulator components +│ ├── tutorials/ # Per-tutorial components +│ │ ├── validator/ +│ │ ├── gas-auction/ +│ │ └── block-internals/ +│ └── ui/ # Reusable UI primitives +├── hooks/ # Custom React hooks +├── i18n/ # next-intl config & routing +├── lib/ # Utilities and types +├── messages/ # Translation files (en.json, es.json) +├── public/ # Static assets (lotus favicon, etc.) +└── book/ # Mastering Ethereum (git submodule) ``` ## Adding a New Tutorial -1. Create a new page: `app/[locale]/[tutorial]/page.tsx` -2. Add tutorial metadata to the landing page -3. Create translations in `messages/en.json` and `messages/es.json` +1. **Create the page**: `app/[locale]/[tutorial-slug]/page.tsx` +2. **Build components**: `components/tutorials/[tutorial-slug]/` +3. **Add translations**: Keys in both `messages/en.json` and `messages/es.json` +4. **Register on landing page**: Add to `LEARNING_CARDS` or `COMING_SOON_CARDS` +5. **Add to sidebar**: Update `sidebar.tsx` navigation config +6. **Add breadcrumbs**: Register in `components/navigation/breadcrumbs.tsx` + +See `AGENTS.md` for detailed development guidelines. + +## i18n + +- **Default locale**: English (`en`) +- **Supported locales**: English, Spanish +- **Routing**: Prefix-based (`/en/...`, `/es/...`) +- **Translation files**: `messages/en.json`, `messages/es.json` +- **Usage**: Always use `useTranslations()` — never hardcode user-facing strings ## Tech Stack -- Next.js 16 +- Next.js 16 (App Router) - React 19 - TypeScript - Tailwind CSS - Framer Motion - next-intl (i18n) +- Lucide React (icons) +- Vercel Analytics + +## Book Reference + +Content is based on [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook) by Andreas M. Antonopoulos and Gavin Wood. The book is included as a git submodule in `book/` with all 17 chapters in Markdown format. ## License diff --git a/app/[locale]/page.tsx b/app/[locale]/page.tsx index 8a7e027..c1926cf 100644 --- a/app/[locale]/page.tsx +++ b/app/[locale]/page.tsx @@ -363,7 +363,7 @@ export default function LandingPage() {