johba/harb

openhands de3c8eef94 docs: consolidate and update all documentation for launch readiness

- Rewrite root README.md with proper project overview, tech stack, and repo structure
- Remove duplicate CLAUDE.md files (root, onchain, ponder) — AGENTS.md is the standard
- Update HARBERG.md to reflect Stage 1 completion and Stage 2 evolution
- Delete stale onchain/testing_todos.md (all high-priority items completed)
- Update VERSION_VALIDATION.md for VERSION=2
- Trim root AGENTS.md: replace Docker duplication with docs/docker.md reference
- Trim onchain/AGENTS.md (129→71 lines): reference TECHNICAL_APPENDIX for formulas
- Trim web-app/AGENTS.md (278→55 lines): remove internal API docs, keep architecture
- Rewrite onchain/README.md: add contract table, deployment addresses, analysis links
- Trim services/ponder/README.md: remove stale subgraph comparison
- Add otterscan to docs/docker.md service topology
- Update TECHNICAL_APPENDIX.md references

Net: -388 lines across documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-13 19:22:34 +00:00

3 KiB

Raw Blame History

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

npm install

2. Configure Environment

cp .env.example .env

Edit .env to select your network:

PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK - Local Anvil fork managed by scripts/dev.sh
PONDER_NETWORK=BASE_SEPOLIA - Base Sepolia testnet
PONDER_NETWORK=BASE - Base mainnet

3. Local Development (Anvil Fork)

# 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)

PONDER_NETWORK=BASE_SEPOLIA npm run dev

5. Production Deployment (Base Mainnet)

PONDER_NETWORK=BASE npm run start

GraphQL Queries

Once running, access the GraphQL playground at http://localhost:42069/graphql

Example Queries

Get Protocol Stats

{
  stats(id: "0x01") {
    kraikenTotalSupply
    stakeTotalSupply
    outstandingStake
    mintedLastWeek
    mintedLastDay
    mintNextHourProjected
    burnedLastWeek
    burnedLastDay
    burnNextHourProjected
  }
}

Get All Positions

{
  positions(where: { status: "Active" }) {
    items {
      id
      owner
      share
      taxRate
      kraikenDeposit
      taxPaid
      createdAt
    }
  }
}

Get User Positions

{
  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

Deployment

Self-Hosted

DATABASE_URL=postgresql://... PONDER_NETWORK=BASE npm run start

Troubleshooting

"No chain configured": Ensure PONDER_NETWORK is set in .env
Slow initial sync: Provide a faster RPC URL
Database errors: Use PostgreSQL for production (DATABASE_URL env var)

License

GPL-3.0-or-later

3 KiB Raw Blame History