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:**
   ```bash
   ./scripts/dev.sh stop
   ```

2. **Clean Ponder state:**
   ```bash
   rm -rf services/ponder/.ponder/
   ```

3. **Rebuild kraiken-lib:**
   ```bash
   ./scripts/build-kraiken-lib.sh
   ```

4. **Rebuild contracts (if needed):**
   ```bash
   cd onchain && forge build
   ```

5. **Start the stack:**
   ```bash
   ./scripts/dev.sh start
   ```

6. **Verify version validation:**
   ```bash
   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:**
   ```solidity
   uint256 public constant VERSION = 2;
   ```

2. **Update COMPATIBLE_CONTRACT_VERSIONS in kraiken-lib/src/version.ts:**
   ```typescript
   export const KRAIKEN_LIB_VERSION = 2;
   export const COMPATIBLE_CONTRACT_VERSIONS = [2]; // Or [1, 2] for backward compat
   ```

3. **Rebuild and redeploy:**
   ```bash
   ./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
```bash
# 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`