johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/kraiken-lib/AGENTS.md
johba 6cbb1781ce tax rate, version and compose (#70) 
resolves #67

Co-authored-by: johba <johba@harb.eth>
Reviewed-on: https://codeberg.org/johba/harb/pulls/70
2025-10-07 19:26:08 +02:00

3.4 KiB
Raw Blame History

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.
  • 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 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 Mount: Podman/Docker services now bind-mount dist/ read-only from the host. Run ./scripts/build-kraiken-lib.sh before podman-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.