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>
This commit is contained in:
openhands 2026-02-13 19:22:34 +00:00
parent b7260b2eaf
commit de3c8eef94
14 changed files with 249 additions and 701 deletions

View file

@ -1 +0,0 @@
AGENTS.md

View file

@ -126,69 +126,17 @@ Once running, access the GraphQL playground at `http://localhost:42069/graphql`
- 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
```
## Deployment
### Self-Hosted
```bash
DATABASE_URL=postgresql://... npm run start
DATABASE_URL=postgresql://... PONDER_NETWORK=BASE 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
### 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