johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/kraiken-lib/AGENTS.md
johba a555a2fdd1 refactor: migrate kraiken-lib to explicit subpath imports (BREAKING CHANGE) (#89) 
Removes the barrel export pattern in favor of explicit subpath imports
for better tree-shaking and clearer dependencies.

## Breaking Changes
- Removed `src/helpers.ts` barrel export
- Removed `./helpers` from package.json exports
- Root `kraiken-lib` import now raises build errors
- Consumers MUST use explicit subpaths:
  - `kraiken-lib/abis` - Contract ABIs
  - `kraiken-lib/staking` - Staking helpers
  - `kraiken-lib/snatch` - Snatch selection
  - `kraiken-lib/ids` - Position ID utilities
  - `kraiken-lib/subgraph` - Byte conversion utilities
  - `kraiken-lib/taxRates` - Tax rate constants
  - `kraiken-lib/version` - Version validation

## Changes
- kraiken-lib:
  - Bumped version to 1.0.0 (breaking change)
  - Updated src/index.ts to raise build errors
  - Added backward-compatible ABI aliases (KraikenAbi, StakeAbi)
  - Updated all test files to use .js extensions and new imports
  - Updated documentation (README, AGENTS.md)

- Consumer updates:
  - services/ponder: Updated ponder.config.ts to use kraiken-lib/abis
  - web-app: Updated all imports to use subpaths
    - composables/usePositions.ts: kraiken-lib/subgraph
    - contracts/harb.ts: kraiken-lib/abis
    - contracts/stake.ts: kraiken-lib/abis

## Migration Guide
```typescript
// OLD
import { getSnatchList } from 'kraiken-lib/helpers';
import { KraikenAbi } from 'kraiken-lib';

// NEW
import { getSnatchList } from 'kraiken-lib/snatch';
import { KraikenAbi } from 'kraiken-lib/abis';
```

Fixes #86

Co-authored-by: openhands <openhands@all-hands.dev>
Reviewed-on: https://codeberg.org/johba/harb/pulls/89
2025-11-20 18:54:53 +01:00

3.8 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/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.