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/staking.ts - Harberger staking helpers for delinquency checks and snatch math.
• src/snatch.ts - Snatch selection engine and supporting types.
• src/ids.ts - Position ID encoding helpers.
• src/subgraph.ts - Byte utilities shared between the GraphQL layer and clients.
• src/abis.ts - Contract ABIs imported directly from onchain/out/ forge artifacts. Single source of truth for all ABI consumers.
• src/taxRates.ts - Generated from onchain/src/Stake.sol by scripts/sync-tax-rates.mjs; never edit by hand.
• src/version.ts - Version validation system tracking KRAIKEN_LIB_VERSION and COMPATIBLE_CONTRACT_VERSIONS for runtime dependency checking.

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 kraiken-lib/abis, kraiken-lib/staking, and kraiken-lib/subgraph for ABI resolution and ID conversion.
• txnBot relies on kraiken-lib/staking and kraiken-lib/ids to evaluate profitability and tax windows.
• Ponder imports kraiken-lib/abis for indexing, and kraiken-lib/version for cross-service version checks.
• When the Ponder schema changes, rerun npm run compile and commit regenerated types to prevent drift.

Import Guidance

• The legacy helpers.ts barrel has been removed. Always import from the narrow subpaths (e.g. kraiken-lib/abis, kraiken-lib/staking, kraiken-lib/snatch, kraiken-lib/subgraph).
• Avoid importing kraiken-lib directly; the root module no longer re-exports the helper surface and exists only to raise build-time errors for bundle imports.

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 "./staking.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 Mount: Docker services bind-mount dist/ read-only from the host. Run ./scripts/build-kraiken-lib.sh before docker-compose up or keep scripts/watch-kraiken-lib.sh running to rebuild automatically.

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.