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.

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.

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.