a555a2fdd1
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
54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
# 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.
|