harb/CHANGELOG_VERSION_VALIDATION.md

Changelog: Version Validation System & Tax Rate Index Refactoring

Date: 2025-10-07

Summary

This release implements a comprehensive version validation system to ensure contract-indexer-frontend compatibility and completes the tax rate index refactoring to eliminate fragile decimal lookups.

Major Features

1. Version Validation System

Contract Changes:

• onchain/src/Kraiken.sol: Added VERSION = 1 constant (line 28)
  • Public constant for runtime validation
  • Must be incremented for breaking changes to TAX_RATES, events, or data structures

kraiken-lib:

• kraiken-lib/src/version.ts (NEW): Central version tracking
  • KRAIKEN_LIB_VERSION = 1
  • COMPATIBLE_CONTRACT_VERSIONS = [1]
  • isCompatibleVersion() validation function
  • getVersionMismatchError() for detailed error reporting
• kraiken-lib/package.json: Added ./version export

Ponder Indexer:

• services/ponder/src/helpers/version.ts (NEW): Contract version validation
  • Reads VERSION from deployed contract at startup
  • Validates against COMPATIBLE_CONTRACT_VERSIONS
  • Fails hard (exit 1) on mismatch to prevent indexing wrong data
• services/ponder/src/kraiken.ts: Integrated version check on first Transfer event
• services/ponder/ponder-env.d.ts: Fixed permissions (chmod 666)

Frontend:

• web-app/src/composables/useVersionCheck.ts (NEW): Version validation composable
  • Validates KRAIKEN_LIB_VERSION loads correctly
  • Placeholder for future GraphQL-based 3-way validation
  • Warns (doesn't fail) on mismatch

CI/CD:

• .github/workflows/validate-version.yml (NEW): Automated version validation
  • Validates contract VERSION is in COMPATIBLE_CONTRACT_VERSIONS
  • Runs on PRs and pushes to master/main
  • Prevents merging incompatible versions

Documentation:

• VERSION_VALIDATION.md (NEW): Complete architecture and workflows
  • System architecture diagram
  • Version bump workflow
  • Troubleshooting guide
  • Maintenance guidelines

2. Container Orchestration Fix

Problem: Container dependency graph validator can fail with "container not found in input list" errors when containers have depends_on metadata.

Solution:

• docker-compose.yml: Removed ALL depends_on declarations from:

  • bootstrap
  • ponder
  • webapp
  • landing
  • txn-bot
  • caddy

• scripts/dev.sh: Implemented phased startup with explicit health checks:

  1. Create all containers (docker-compose up --no-start)
  2. Start anvil & postgres, wait for healthy
  3. Start bootstrap, wait for completion
  4. Start ponder, wait for healthy
  5. Start webapp/landing/txn-bot
  6. Start caddy

Result: Stack starts reliably without dependency graph errors.

3. Tax Rate Index Refactoring (Completion)

Web App:

• web-app/src/composables/useSnatchSelection.ts:

  • Replaced position.taxRate >= maxTaxRateDecimal with posIndex >= selectedTaxRateIndex
  • Fixed test data to match index-based logic

• web-app/src/composables/usePositions.ts:

  • Replaced decimal-based sorting with index-based sorting
  • Changed threshold calculation from average percentage to average index

• web-app/src/components/collapse/CollapseActive.vue:

  • Changed low tax detection from decimal to index comparison

• web-app/src/views/GraphView.vue: DELETED (dead code, 63 lines)

Ponder:

• services/ponder/ponder.schema.ts:

  • CRITICAL FIX: Import TAX_RATE_OPTIONS from kraiken-lib instead of hardcoded array
  • Added taxRateIndex column to positions table
  • Added index on taxRateIndex column

• services/ponder/src/stake.ts:

  • Extract and store taxRateIndex from contract events

Tests:

• kraiken-lib/src/tests/taxRates.test.ts: Fixed Jest ES module compatibility
• kraiken-lib/jest.config.js → kraiken-lib/jest.config.cjs: Renamed for CommonJS
• web-app/src/composables/__tests__/useSnatchSelection.spec.ts: Fixed test data inconsistencies

File Changes

Added Files (7)

1. .github/workflows/validate-version.yml - CI/CD validation
2. VERSION_VALIDATION.md - Documentation
3. kraiken-lib/src/version.ts - Version tracking
4. kraiken-lib/jest.config.cjs - Jest config
5. services/ponder/src/helpers/version.ts - Ponder validation
6. web-app/src/composables/useVersionCheck.ts - Frontend validation
7. scripts/sync-tax-rates.mjs - Tax rate sync script

Deleted Files (2)

1. web-app/src/views/GraphView.vue - Dead code
2. kraiken-lib/jest.config.js - Replaced with .cjs

Modified Files (29)

1. .gitignore - Added test artifacts, logs, ponder state
2. CLAUDE.md - Added Version Validation and Podman Orchestration sections
3. kraiken-lib/AGENTS.md - Added version.ts to Key Modules
4. kraiken-lib/package.json - Added ./version export
5. kraiken-lib/src/index.ts - Export version validation functions
6. kraiken-lib/src/taxRates.ts - Generated tax rates with checksums
7. kraiken-lib/src/tests/taxRates.test.ts - Fixed Jest compatibility
8. onchain/src/Kraiken.sol - Added VERSION constant
9. docker-compose.yml - Removed all depends_on declarations
10. scripts/build-kraiken-lib.sh - Updated build process
11. scripts/dev.sh - Implemented phased startup
12. services/ponder/AGENTS.md - Updated documentation
13. services/ponder/ponder-env.d.ts - Fixed permissions
14. services/ponder/ponder.schema.ts - Import from kraiken-lib, add taxRateIndex
15. services/ponder/src/kraiken.ts - Added version validation
16. services/ponder/src/stake.ts - Store taxRateIndex
17. tests/e2e/01-acquire-and-stake.spec.ts - Test updates
18. web-app/README.md - Documentation updates
19. web-app/env.d.ts - Type updates
20. web-app/src/components/StakeHolder.vue - Index-based logic
21. web-app/src/components/collapse/CollapseActive.vue - Index comparison
22. web-app/src/components/fcomponents/FSelect.vue - Index handling
23. web-app/src/composables/__tests__/useSnatchSelection.spec.ts - Fixed tests
24. web-app/src/composables/useAdjustTaxRates.ts - Index-based adjustments
25. web-app/src/composables/usePositions.ts - Index-based sorting and threshold
26. web-app/src/composables/useSnatchSelection.ts - Index-based filtering
27. web-app/src/composables/useStake.ts - Index handling 28-29. Various documentation and configuration updates

Breaking Changes

For Contract Deployments

• New VERSION constant must be present in Kraiken.sol
• Ponder will fail to start if VERSION is missing or incompatible

For Ponder

• Schema migration required: Add taxRateIndex column to positions table
• Database reset recommended: Delete .ponder/ directory before starting
• New import required: Import TAX_RATE_OPTIONS from kraiken-lib

For kraiken-lib Consumers

• New export: kraiken-lib/version must be built
• Run ./scripts/build-kraiken-lib.sh to regenerate dist/

Migration Guide

Updating to This Version

1. Stop the stack:

   ./scripts/dev.sh stop
   

2. Clean Ponder state:

   rm -rf services/ponder/.ponder/
   

3. Rebuild kraiken-lib:

   ./scripts/build-kraiken-lib.sh
   

4. Rebuild contracts (if needed):

   cd onchain && forge build
   

5. Start the stack:

   ./scripts/dev.sh start
   

6. Verify version validation:

   docker logs harb_ponder_1 | grep "version validated"
   

   Should output: ✓ Contract version validated: v1 (kraiken-lib v1)

Future Version Bumps

When making breaking changes to TAX_RATES, events, or data structures:

1. Increment VERSION in Kraiken.sol:

   uint256 public constant VERSION = 2;
   

2. Update COMPATIBLE_CONTRACT_VERSIONS in kraiken-lib/src/version.ts:

   export const KRAIKEN_LIB_VERSION = 2;
   export const COMPATIBLE_CONTRACT_VERSIONS = [2]; // Or [1, 2] for backward compat
   

3. Rebuild and redeploy:

   ./scripts/build-kraiken-lib.sh
   rm -rf services/ponder/.ponder/
   cd onchain && forge script script/Deploy.s.sol
   

Validation

Unit Tests

• ✅ kraiken-lib tests pass
• ✅ web-app tests pass
• ✅ Ponder codegen succeeds
• ✅ onchain tests pass

Integration Tests

• ✅ Stack starts without dependency errors
• ✅ Ponder validates contract version successfully
• ✅ Ponder indexes events with taxRateIndex
• ✅ GraphQL endpoint responds
• ✅ Version validation logs appear in Ponder output

Manual Verification

# Check Ponder logs for version validation
docker logs harb_ponder_1 | grep "version validated"
# Output: ✓ Contract version validated: v1 (kraiken-lib v1)

# Check contract VERSION
cast call $KRAIKEN_ADDRESS "VERSION()" --rpc-url http://localhost:8545
# Output: 1

# Query positions with taxRateIndex
curl -X POST http://localhost:42069/graphql \
  -d '{"query":"{ positions { id taxRateIndex taxRate } }"}'

Known Issues

None. All blocking issues resolved.

Contributors

• Claude Code (Anthropic)

References

• Full architecture: VERSION_VALIDATION.md
• Podman orchestration: CLAUDE.md § Podman Orchestration
• Tax rate system: kraiken-lib/src/taxRates.ts