harb/kraiken-lib/CLAUDE.md

Kraiken Library - CLAUDE.md

TypeScript helper library for interacting with KRAIKEN protocol contracts and The Graph.

Purpose

This library provides:

• Type-safe contract interactions
• GraphQL query helpers for subgraph data
• Staking position calculations
• Helper functions for UI development

Architecture

Key Files

• src/kraiken.ts - Main KRAIKEN token interaction helpers
• src/stake.ts - Staking position calculations and Harberger tax logic
• src/chains.ts - Chain configuration and constants
• src/queries/ - GraphQL queries for subgraph data
• src/__generated__/graphql.ts - Auto-generated GraphQL types

Development Commands

# Install dependencies
npm install --legacy-peer-deps

# Generate GraphQL types from subgraph schema
npm run compile

# Run tests
npm test

# Watch mode for GraphQL generation
npm run watch

GraphQL Code Generation

The library uses GraphQL Code Generator to create type-safe queries:

1. Schema Source: Points to subgraph schema

2. Scalar Mappings:

   • BigInt → string
   • BigDecimal → string
   • Bytes → string
   • Int8 → number

3. Generated Types: All GraphQL operations get full TypeScript typing

Usage Examples

import { getStakePositions, calculateTaxRate } from 'kraiken-lib';

// Fetch all stake positions
const positions = await getStakePositions(graphqlClient);

// Calculate annual tax rate
const yearlyRate = calculateTaxRate(dailyRate);

Integration Notes

• Used by the web interface for data fetching
• Used by services/txnBot for position monitoring
• Provides consistent calculations across all frontend components

Code Quality

• All GraphQL queries must be typed
• Use generated types, never any
• Keep calculations pure (no side effects)
• Test edge cases for tax calculations