move ponder

2025-09-23 20:29:51 +02:00 · 2025-09-23 20:29:51 +02:00 · 36b7b429ef
commit 36b7b429ef
parent a9207de195
22 changed files with 50 additions and 14 deletions
--- a/services/ponder/README.md
+++ b/services/ponder/README.md
@ -0,0 +1,195 @@
+# KRAIKEN Ponder Indexer
+
+A high-performance blockchain indexer for the KRAIKEN protocol using Ponder framework, providing 10-15x faster indexing than The Graph with superior developer experience.
+
+## Features
+
+- ✅ **Multi-network support**: Local (Anvil fork), Base Sepolia, Base mainnet
+- ✅ **Hot reload**: Instant updates during development
+- ✅ **Type safety**: Full TypeScript support with auto-completion
+- ✅ **Ring buffer**: 7-day hourly metrics with projections
+- ✅ **GraphQL API**: Auto-generated from schema
+- ✅ **Efficient indexing**: In-memory operations during sync
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` to select your network:
+- `PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK` - Local Anvil fork managed by `scripts/local_env.sh`
+- `PONDER_NETWORK=BASE_SEPOLIA` - Base Sepolia testnet
+- `PONDER_NETWORK=BASE` - Base mainnet
+
+### 3. Local Development (Anvil Fork)
+
+```bash
+# Terminal 1: Start Anvil fork of Base mainnet
+anvil --fork-url https://base.llamarpc.com
+
+# Terminal 2: Start Ponder indexer
+PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev
+```
+
+### 4. Testnet Deployment (Base Sepolia)
+
+```bash
+PONDER_NETWORK=BASE_SEPOLIA npm run dev
+```
+
+### 5. Production Deployment (Base Mainnet)
+
+```bash
+PONDER_NETWORK=BASE npm run start
+```
+
+## GraphQL Queries
+
+Once running, access the GraphQL playground at `http://localhost:42069/graphql`
+
+### Example Queries
+
+#### Get Protocol Stats
+```graphql
+{
+  stats(id: "0x01") {
+    kraikenTotalSupply
+    stakeTotalSupply
+    outstandingStake
+    mintedLastWeek
+    mintedLastDay
+    mintNextHourProjected
+    burnedLastWeek
+    burnedLastDay
+    burnNextHourProjected
+  }
+}
+```
+
+#### Get All Positions
+```graphql
+{
+  positions(where: { status: "Active" }) {
+    items {
+      id
+      owner
+      share
+      taxRate
+      kraikenDeposit
+      taxPaid
+      createdAt
+    }
+  }
+}
+```
+
+#### Get User Positions
+```graphql
+{
+  positions(where: { owner: "0x..." }) {
+    items {
+      id
+      share
+      taxRate
+      kraikenDeposit
+      stakeDeposit
+      taxPaid
+      status
+    }
+  }
+}
+```
+
+## Architecture
+
+### Schema (`ponder.schema.ts`)
+- **stats**: Global protocol metrics with ring buffer
+- **hourlyData**: 168-hour circular buffer for time-series
+- **positions**: Harberger tax staking positions
+
+### Event Handlers
+- **kraiken.ts**: Handles Transfer events for minting, burning, tax, UBI
+- **stake.ts**: Handles position lifecycle events
+
+### Ring Buffer Implementation
+- 168 hourly slots (7 days)
+- Automatic hourly rollover
+- Projection calculation using median smoothing
+- Rolling 24h and 7d aggregations
+
+## Comparison with Subgraph
+
+| Feature | Subgraph | Ponder |
+|---------|----------|---------|
+| Sync Speed | 1x | 10-15x faster |
+| Hot Reload | ❌ | ✅ |
+| Language | AssemblyScript | TypeScript |
+| Setup | Complex (PostgreSQL, IPFS, Graph Node) | Simple (Node.js) |
+| NPM Packages | ❌ | ✅ |
+| Type Safety | Requires codegen | Automatic |
+
+## Deployment Options
+
+### Railway (Recommended)
+```bash
+npm run build
+# Deploy to Railway with DATABASE_URL configured
+```
+
+### Self-Hosted
+```bash
+DATABASE_URL=postgresql://... npm run start
+```
+
+### Docker
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+ENV PONDER_NETWORK=BASE
+CMD ["npm", "run", "start"]
+```
+
+## Troubleshooting
+
+### Issue: "No chain configured"
+**Solution**: Ensure `PONDER_NETWORK` is set correctly in `.env`
+
+### Issue: Slow initial sync
+**Solution**: Provide a faster RPC URL via environment variables
+
+### Issue: Database errors
+**Solution**: For production, use PostgreSQL instead of SQLite:
+```bash
+DATABASE_URL=postgresql://user:pass@host:5432/db npm run start
+```
+
+## Migration from Subgraph
+
+This Ponder implementation maintains complete parity with the original subgraph:
+- Same entity structure (Stats, Positions)
+- Identical ring buffer logic
+- Same tax rate mappings
+- Compatible GraphQL queries
+
+Key improvements:
+- 10-15x faster indexing
+- No Docker/Graph Node required
+- Hot reload for development
+- Direct SQL access for complex queries
+- Full Node.js ecosystem access
+
+## License
+
+GPL-3.0-or-later