Merge pull request #35 from onflow/refactor/better-code

refactor: implement phase 0 - extract pure math functions from positionHealth

Author: kgrgpg

.github/pr_bodies/PR_36.md

@@ -0,0 +1,49 @@
+# Phase 0: availableBalance refactor to pure helpers + tests
+
+This PR is stacked on top of [PR #35](https://github.com/onflow/TidalProtocol/pull/35) (base: `refactor/better-code`). It completes the Phase 0 vertical slice for health/withdraw by wiring the public query path to pure helpers while preserving existing top-up behavior.
+
+## Summary
+- **availableBalance**:
+  - Preserves deposit-assisted path when `pullFromTopUpSource=true` by delegating to `fundsAvailableAboveTargetHealthAfterDepositing(...)`.
+  - Otherwise uses the new pure pipeline: `buildPositionView(pid)` + `maxWithdraw(...)` with 18-decimal `UInt256` math.
+- **Pure math tests**: Adds `cadence/tests/phase0_pure_math_test.cdc` covering `healthFactor` and `maxWithdraw` (both debt-increase and collateral-drawdown paths). Expectations computed in `UInt256` to match on-chain truncation.
+- **Docs**: Regenerates `REFACTORING_PLAN.md` code sections to use current Cadence syntax and mirror the implemented Phase 0 shape (incl. top-up path note).
+- **Housekeeping**: Removes deprecated `DeFiBlocks/` and `REFACTOR_EVALUATION.md` (superseded by DeFiActions and current plan).
+
+## Rationale
+- Introduces a clean functional-core / imperative-shell boundary without changing end-user semantics.
+- Greatly improves testability of the core math (`healthFactor`, `maxWithdraw`).
+- Keeps deposit-assisted behavior intact for platforms relying on `topUpSource`.
+
+## Implementation Notes
+- `buildPositionView(pid)` creates immutable snapshots per token (price, indices, risk) and copies of position balances; no storage mutation.
+- `maxWithdraw(view, withdrawSnap, withdrawBal, targetHealth)` solves the linear constraint to maintain target health; handles both credit and debit cases.
+- `availableBalance` now chooses:
+  - Top-up path → original async/deposit-assisted logic.
+  - Pure path → view + helper + `uint256ToUFix64(...)`.
+- Rounding is explicit in 18-decimal `UInt256` arithmetic to match chain truncation.
+
+## Tests
+- Added: `cadence/tests/phase0_pure_math_test.cdc`
+  - `test_healthFactor_zeroBalances_returnsZero`
+  - `test_healthFactor_simpleCollateralAndDebt`
+  - `test_maxWithdraw_increasesDebtWhenNoCredit`
+  - `test_maxWithdraw_fromCollateralLimitedByHealth`
+- All existing suites remain passing with `run_tests.sh`.
+
+## Backward Compatibility
+- No change to deposit-assisted semantics when `pullFromTopUpSource=true`.
+- Query-only behavior updated to use pure math; results validated against existing suites.
+
+## Documentation
+- `REFACTORING_PLAN.md` snippets updated to current Cadence (`access(all)`, correct entitlements/types) and reflect the preserved top-up path in `availableBalance`.
+
+## Next Phases (follow-ups)
+- Phase 1: introduce `applyWithdraw`/`applyDeposit`/`applyAccrual`/`applyLiquidation` with pre/post invariants, using the same pure helpers for validation before mutation.
+- Phase 2+: rate/capacity pure math; async queue refactor; governance resource & snapshots.
+
+## How to verify locally
+```bash
+./run_tests.sh
+```
+All tests should pass, including the new Phase 0 tests.