de3c8eef94
- 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>
143 lines
3 KiB
Markdown
143 lines
3 KiB
Markdown
# 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/dev.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
|
|
|
|
## Deployment
|
|
|
|
### Self-Hosted
|
|
```bash
|
|
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
|