🌱 DeFi Garden
Calm, honest DeFi yield discovery and goal-based savings planning.
DeFi Garden is a static, zero-backend, zero-build-step web application built on the DefiLlama yields API, designed for cautious savers and DeFi operators who value trust, realistic projections, and mathematical transparency over speculative hype.
🌟 The Two Core Faces of DeFi Garden
DeFi Garden serves two distinct workflows through an inline, zero-flash IA router (window.__APP_MODE in home.html):
1. 🪴 Garden Planner (Default Experience — / and plan.html)
- Goal-First Conversational Savings: Plan savings around real-life goals (subscriptions, gadgets, life milestones) rather than chasing abstract APY numbers.
- Yield-Funded Paradigm: "Buy it outright and the money's gone. Garden it and you keep the money AND get the thing."
- Blended Yield Rates: Calculates honest "forever numbers" — the capital required so ongoing live yield pays recurring bills automatically.
- Degen Honesty: Applies a mandatory ⅓ decay haircut to variable farm/reward emissions, ensuring users plan around realistic long-term carry.
2. 📊 Analytics & Yield Discovery (/?token=, /?chain=, /?pool=, /?app=1)
- Multi-Chain Pool Explorer: Real-time yield monitoring across 50+ blockchains (Ethereum, Arbitrum, Base, Hyperliquid, Solana, etc.) and all major protocol types (Lending, Staking, LP/DEX, Yield Farming).
- Deep Pool Breakdown (
PoolDetail.js): In-depth pool analytics, 30-day mean APY tracking, base vs. reward emission separation, and impermanent loss risk indicators.
- Funding Harvest Module (
/hype-harvest.html / /?module=hype-harvest): Delta-neutral cash-and-carry funding harvest calculator for Hyperliquid perps with live basis spread tracking and dual-oracle divergence tripwires.
🛡️ Trust Rails (The Core Moat)
Every metric rendered across DeFi Garden derives from live on-chain and API data through strict, non-negotiable trust rails:
APY_SANITY_LIMIT = 1000%: Anomalous, short-lived spikes can never enter a plan. In analytics, anomalous pools are demoted, flagged with ⚠, and forced to high-risk classification.DEFAULT_MIN_TVL = $100K: Low-liquidity pools below the safety floor are filtered out to protect savers from illiquid exits and sudden deprecations.- Dual-Oracle Divergence Guard: Modules verify mark vs. oracle price divergence ($<15\text{ bps}$ tripwire) to alert on basis dislocation and squeeze risk.
- Deterministic Math Layer: LLMs may narrate or explain mechanisms, but numbers, projections, and compounded yields are calculated deterministically.
🎨 Design System — "Quiet"
DeFi Garden uses the "Quiet" design system — a restrained, clean-minimal, table-first interface designed for clarity and focus:
- Surface Tokens (
--ui-*):
- Backgrounds:
--ui-bg (#F7F8FA light / #161A20 dark), --ui-surface (#FFFFFF / #1E242C), --ui-surface-muted, --ui-surface-sunken.
- Separation: Single-pixel hairline borders (
--ui-border: #E4E7EE, --ui-border-strong: #CBD2DF).
- Text: High-contrast hierarchy (
--ui-text: #10151F, --ui-text-secondary: #5A6478, --ui-text-muted: #8A93A6).
- Accents: Fixed trust-blue palette (
--ui-accent: #3B82F6, --ui-accent-hover: #2563EB, --ui-accent-soft: #EFF5FF).
- Radii: Clean geometric squircles (
--ui-radius-sm: 8px, --ui-radius-md: 12px, --ui-radius-lg: 16px, --ui-radius-pill: 999px).
- No Heavy Shadows or Skeuomorphic Skeins: Depth is created through crisp hairline borders and subtle surface tone steps, not artificial dual-direction shadows or background gradients.
- Physical Press Physics: Interactive controls sink 1px on
:active (transform: translateY(1px)), respecting prefers-reduced-motion.
- First-Class Bilingual Support (
translations.js): Complete English (en) and Korean (ko) localization synchronized across all user-facing strings.
🛠️ Architecture & Technology Stack
- Zero Build Step: Runs natively on vanilla web standards. React 18 UMD loaded via script tag; components written in pure
React.createElement (no JSX compilation step required).
- Data Ingestion: Client-side integration with
https://yields.llama.fi/pools and Hyperliquid Info API (https://api.hyperliquid.xyz/info).
- State Management:
- Theme:
localStorage.getItem('theme') with data-theme="light|dark" attribute on <html>.
- Language: URL param
?lang= + localStorage.getItem('defi-garden-lang').
- Saved Plan:
localStorage.getItem('garden-plan').
- SEO & Machine Readability:
- Automated dynamic sitemaps (
generate-sitemap.js).
- AI Context endpoints:
llms.txt and llms-full.txt (generate-llms.js).
- Model Context Protocol (MCP) server integration (
mcp_server.js).
📁 Repository Structure
defi_garden/
├── home.html # Master router & analytics app shell
├── plan.html # Standalone Garden Planner entry
├── hype-harvest.html # HYPE Funding Harvest module
├── planner.js # Conversational Garden Planner engine
├── app.js # Core analytics grid & pool filtering
├── PoolDetail.js # In-depth pool analytics & calculator
├── hype-harvest.js # HYPE funding harvest React UMD module
├── translations.js # Bilingual dictionary (EN + KO)
├── translations.min.js # Production-minified translation dictionary
├── style.css # "Quiet" design system tokens & base styles
├── planner-styles.css # Planner-specific layout styles
├── pool-detail-styles.css # Pool detail drawer styles
├── hype-harvest.css # Funding harvest layout styles
├── trust-rails.js # Shared trust-rail constants
├── canonical.js # URL canonicalization logic
├── keeper/ # Autonomous execution & risk keeper scripts
│ ├── keeper_engine.py # Core risk keeper engine
│ └── hype_funding_harvest.py # Hyperliquid HYPE funding rate worker
├── tests/ # Python unit & integration test suite
│ ├── test_keeper_engine.py
│ └── test_keeper_hype_harvest.py
└── test_*.js # JavaScript offline test suite (71+ test files)
🧪 Development & Testing
DeFi Garden requires no build pipeline. Serve locally with any static HTTP server:
# Start local server
python3 -m http.server 8000
# Open in browser: http://localhost:8000
Running Tests
# Run all unit tests in fast plain mode
npm run test:fast
# Run the complete test suite (plain + browser)
npm test
# Minify production assets
npm run minify
📜 License
MIT License. See LICENSE for details.
