feat(depth): walkPoolDepth per-region depth walk (0.17.0)

[lukemacauley]

Summary

• New walkPoolDepth export: maxFillablePerpDelta's tick walk emitting each constant-liquidity region (DepthRegion: price bounds, terminating tick, active liquidity, perp and USD legs) instead of a single sum. Feeds order book style depth displays in the client.
• USD-leg rounding matches computeSwapStepToken0 at tick boundaries, so cumulative notional over any region prefix reproduces simulateTakerSwapExact to the wei.
• Backfills the missing 0.15.0 / 0.16.0 CHANGELOG entries; bumps to 0.17.0.

Tests

• New walkPoolDepth invariant suite against the V4Quoter-anchored mainnet fixture: per-side totals equal maxFillablePerpDelta exactly (MAX_LONG/MAX_SHORT); every prefix's cumulative USD matches simulateTakerSwapExact to the wei; contiguous outward region bounds; active-liquidity consistency.
• pnpm run ci green locally (build + 304 unit tests + tsc + lint).
• pnpm run test:integration green against live Arbitrum mainnet (41 tests incl. the V4Quoter differential).

Part of the order book panel plan (perpcity-client thoughts/shared/plans/2026-07-24-order-book-panel.md, Phase 1).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added depth computation across multiple constant-liquidity regions.
  • Added exact multi-tick taker swap simulation.
  • Added optional fee handling with both effective fee-inclusive pricing and raw curve pricing.
  • Added taker fee-rate calculations and liquidity-limit indicators for high-impact trades.

• Documentation

  • Updated release notes for versions 0.15.0, 0.16.0, and 0.17.0.

• Chores

  • Bumped the package version to 0.17.0.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cc559e93-5425-4b6a-905a-3b8283b71d69

📥 Commits

Reviewing files that changed from the base of the PR and between b1b05ee and 3345613.

📒 Files selected for processing (4)

• CHANGELOG.md
• package.json
• src/__tests__/unit/swapExact.test.ts
• src/utils/swapExact.ts

---

📝 Walkthrough

Walkthrough

Adds exported tick-walking pool depth computation for long and short sides, validates region outputs against exact swap simulation, and updates release notes and package version to 0.17.0.

Changes

Pool depth walking

Layer / File(s)	Summary
Depth API and validation src/utils/swapExact.ts, src/__tests__/unit/swapExact.test.ts	Adds DepthRegion and walkPoolDepth, calculates token deltas across initialized liquidity regions, and tests traversal, boundaries, liquidity, and fill invariants.
Release metadata CHANGELOG.md, package.json	Documents releases 0.15.0–0.17.0 and changes the package version to 0.17.0.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UnitTests
  participant walkPoolDepth
  participant PoolTickMap
  participant swapMath
  UnitTests->>walkPoolDepth: request one-sided pool depth
  walkPoolDepth->>PoolTickMap: traverse initialized ticks
  walkPoolDepth->>swapMath: compute token0 and token1 deltas
  swapMath-->>walkPoolDepth: return regional deltas
  walkPoolDepth-->>UnitTests: return DepthRegion rows

Loading

Possibly related PRs

• StrobeLabs/perpcity-sdk#62: Updates related taker swap simulation outputs and liquidity limitation handling.
• StrobeLabs/perpcity-sdk#63: Adds the related exact multi-tick simulation used by the depth traversal.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding walkPoolDepth for per-region depth walking.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/depth-levels

---

_{Comment @coderabbitai help to get the list of available commands.}