harb/kraiken-lib/AGENTS.md

# Kraiken Library - Agent Guide

Shared TypeScript helpers used by the landing app, txnBot, and other services to talk to KRAIKEN contracts and the Ponder GraphQL API.

## Responsibilities
- Provide type-safe contract interaction helpers (encoding inputs, parsing results).
- Supply Ponder GraphQL query helpers and generated types for protocol stats and staking positions.
- Centralise staking math (tax calculations, snatch selection, share conversions) for reuse across clients.

## Key Modules
- `src/kraiken.ts` - Token-facing helpers and supply utilities.
- `src/stake.ts` - Staking math, Harberger tax helpers, snatch scoring.
- `src/chains.ts` - Chain constants and deployment metadata.
- `src/queries/` - GraphQL operations that target the Ponder schema.
- `src/__generated__/graphql.ts` - Codegen output consumed throughout the stack.
- `src/abis.ts` - Contract ABIs imported directly from `onchain/out/` forge artifacts. Single source of truth for all ABI consumers.

## GraphQL Code Generation
- Schema source points to the Ponder GraphQL endpoint for the active environment.
- Scalar mappings: `BigInt` -> `string`, `BigDecimal` -> `string`, `Bytes` -> `string`, `Int8` -> `number`.
- Always import the generated DocumentNodes; avoid `any` casts to keep inference intact.

## Package Scripts
- `npm install --legacy-peer-deps`
- `npm run compile` - Regenerate GraphQL types.
- `npm run watch` - Continuously regenerate on schema changes.
- `npm test` - Execute Jest suite for helper coverage.

## Integration Notes
- Landing app consumes helpers for UI projections and staking copy.
- txnBot relies on the same helpers to evaluate profitability and tax windows.
- When the Ponder schema changes, rerun `npm run compile` and commit regenerated types to prevent drift.

## ES Module Architecture
- **Module Type**: This package is built as ES modules (`"type": "module"` in package.json). All consumers must support ES modules.
- **Import Extensions**: All relative imports in TypeScript source files MUST include `.js` extensions (e.g., `from "./helpers.js"`). This is required for ES module resolution even though the source files are `.ts`.
- **JSON Imports**: JSON files (like ABI artifacts) must use import assertions: `import Foo from './path.json' assert { type: 'json' }`.
- **TypeScript Config**: `tsconfig.json` must specify:
  - `"module": "esnext"` - Generate ES module syntax
  - `"moduleResolution": "node"` - Enable proper module resolution
  - `"rootDir": "./src"` - Ensure flat output structure in `dist/`
- **Build Output**: Running `npx tsc` produces ES module `.js` files in `dist/` that can be consumed by both browser (Vite) and Node.js (≥14 with `"type": "module"`).
- **Container Volumes**: In Podman/Docker setups, `dist/` is often a named volume. After changing module format or imports, delete the volume (`podman volume rm harb_kraiken-dist`) before restarting to force a clean rebuild.

## Quality Guidelines
- Keep helpers pure and side-effect free; they should accept explicit dependencies.
- Prefer narrow exports so downstream consumers can tree-shake bundles.
- Extend typings instead of loosening them; reject `any` as a quick fix.