Feat/portfolio pnl 2

[w84april]

Description

This PR introduces a new holdings PnL engine for GET /api/holdings/pnl.

It adds:

• FIFO lot-based PnL tracking per Yearn vault family
• family-level accounting that treats the base vault and staking wrapper as a single position
• transaction-scoped enrichment so router flows, stake/unstake flows, and supported migrations can preserve basis when possible
• conservative handling of ambiguous transfers by marking lots as unknown-basis instead of inventing cost basis
• USD mark-to-market PnL for known-basis lots using acquisition-time, realization-time, and current underlying token prices
• configurable unknown transfer handling via strict, zero_basis, and windfall
• completeness metadata (status, costBasisStatus, isComplete) so the API makes uncertainty explicit
• supporting DefiLlama price-fetching/cache improvements needed to make repeated PnL requests fast and reusable
• product / contributor documentation in api/lib/holdings/PNL.md

How Has This Been Tested?

Automated:

• unit coverage for core PnL ledger / lot behavior in api/lib/holdings/services/pnl.test.ts
• regression coverage for DefiLlama batching, missing-pair fetching, and requested-timestamp caching in api/lib/holdings/services/defillama.test.ts
• bun run tslint
• bun run lint:fix

Manual:

• exercised GET /api/holdings/pnl against real wallets with deposits, withdrawals, staking wrappers, and transfer-heavy histories
• repeated the same request to verify historical prices are cached under requested timestamps and warm requests only fetch fresh current prices

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 41075bd.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
yearnfi	Ready	Preview, Comment	Apr 6, 2026 8:29pm

[rossgalloway]

When visiting the portfolio page, I get 502 errors on the api/holdings endpoint for multiple wallets (although one worked, but was not showing the correct balance)

Is there a way to test the PNL endpoint from the UI or does it need to be called from a CLI?

[w84april]

@rossgalloway my bad, this should have been drafted instead. this pr focuses on pnl api and likely breaks related stuff