harb/onchain/TODO_DEBUGGING_IMPROVEMENTS.md

TODO: Debugging Improvements

Based on the floor position calculation bug investigation, here are the key areas that need improvement:

1. Document Uniswap V3 Mechanics & Token Flows

Problem: Confusion about ETH flow direction during trades and which token amounts are calculated in different positions.

Tasks:

• Create a visual diagram showing token flows during trades (when ETH flows IN vs OUT)
• Document the relationship between token0/token1 and WETH/KRAIKEN
• Explain how getAmount0ForLiquidity vs getAmount1ForLiquidity work with different tick ranges
• Add examples showing what happens in each position type (ANCHOR, DISCOVERY, FLOOR) when token0isWeth=true
• Create a reference table: "When calculating X, use Y function to get Z token"

Acceptance Criteria: Developer can quickly determine which token is being calculated in any liquidity operation without trial and error.

2. Document Optimizer Parameters & Effects

Problem: Misunderstanding of how parameters like anchorShare and capitalInefficiency affect the protocol behavior.

Tasks:

• Create detailed documentation for each optimizer parameter:
  • capitalInefficiency (0-100%): How it affects KRAIKEN valuation for reserves (0% = 70% value, 100% = 170% value)
  • anchorShare (0-100%): How it reduces floor ETH allocation (95% = 90.1% floor, not 95% anchor)
  • anchorWidth (0-100): How it sets anchor position range as percentage of price
  • discoveryDepth (0-100%): How it controls discovery liquidity density (2x-10x multiplier)
• Add examples showing how each parameter affects floor position placement
• Create scenarios: "In a bull market with X parameters, expect floor at Y"

Acceptance Criteria: Developer can predict where positions will be placed given optimizer parameters and market conditions.

3. Implement Calculation Tracing & Visualization Tools

Problem: Console.log doesn't work properly in Forge scripts, making it hard to debug complex calculations. Token flows are not visible.

Tasks:

• Create a DebugEvent system that works in all contexts:

  event DebugCalculation(string label, uint256 value, string unit);
  event DebugTokenFlow(string from, string to, address token, uint256 amount);
  

• Build a script to parse these events and display them nicely:

  [CALC] Outstanding Supply: 91,373,741 KRAIKEN
  [FLOW] LiquidityManager -> UniswapPool: 96,159,882 KRAIKEN
  [CALC] After subtraction: 91,373,741 KRAIKEN (ERROR: should be ~2.4M)
  

• Add debug mode flag to contracts that enables detailed calculation logging
• Create visualization tool that shows token balances at each step of recenter

Acceptance Criteria: Developer can trace exact values through complex calculations without modifying contracts.

4. Improve Code Quality: Type Safety, Tests & Invariants

Problem: Easy to mix up ETH and KRAIKEN amounts (both uint256). Tests don't catch intermediate calculation errors.

Tasks:

• Implement type-safe token amounts:

  library TokenAmounts {
      struct EthAmount { uint256 value; }
      struct KraikenAmount { uint256 value; }
  }
  

• Add unit tests for intermediate calculations:

  function test_discoveryAmountIsKraiken() {
      // Test that discoveryAmount represents KRAIKEN, not ETH
  }
  

• Implement runtime invariant checks:

  require(floorTick - anchorUpperTick < 50000, "Floor too far from anchor");
  require(outstandingSupply < totalSupply / 2, "Outstanding supply unrealistic");
  

• Add invariant fuzzing tests that verify protocol assumptions always hold

Acceptance Criteria: Bugs like wrong token type in calculations are caught at compile time or immediately during testing.