feat: init portfolio history

[w84april]

Description

This branch expands the portfolio backend from a historical balance chart API into a broader holdings platform with:

• a cached holdings history API
• a FIFO-based portfolio PnL API
• a vault-level drilldown API for accounting inspection
• better handling for staking, migrations, router flows, rewards, and selected CoW settlement buys
• more reliable price fetching and caching
• frontend integration for Portfolio PnL, Economic Gain, and stable vs volatile breakdowns

It also adds operational support for lazy cache invalidation when new vaults are indexed, plus cleanup chores for stale cache rows.

What Was Added

Public API surfaces

• GET /api/holdings/history
  • returns chart-ready daily USD portfolio history
  • uses cache-first aggregation and recalculates only missing days
  • supports version, refresh, fetchType, and paginationMode
• GET /api/holdings/pnl
  • returns compact portfolio PnL summary plus vault-family rows
  • supports strict, zero_basis, and windfall handling for unknown-basis transfer-ins
  • exposes both totalPnlUsd and totalEconomicGainUsd
  • includes stable vs volatile category breakdowns
• GET /api/holdings/pnl/drilldown
  • returns the same valuation basis as /pnl, but expanded with lots, realized consumption, unknown-basis receipts/withdrawals, and journal-style inspection data
  • intended for detailed accounting/debug UI
• POST /api/admin/invalidate-cache
  • records vault invalidations so users holding newly indexed vaults refresh lazily on next request
• POST /api/holdings/chores
  • cleanup endpoint for stale cache maintenance

Accounting Model

The PnL engine now models Yearn positions as vault-family FIFO lots rather than simple balance snapshots.

It:

• groups underlying vaults and staking wrappers into a single family
• tracks lot location (vault vs staked) instead of treating staking as a new investment
• uses acquisition-time PPS and acquisition-time token prices for known-basis USD accounting
• separates Portfolio PnL from Economic Gain
• supports three unknown-basis policies:
  • strict: exclude ambiguous lots from PnL
  • zero_basis: treat ambiguous receipts as zero-cost basis
  • windfall: split receipt-time value from later market PnL
• keeps conservative partial-basis behavior when full reconstruction is not possible

Processing Flow

History flow

1. Load cached daily totals.
2. Detect stale cache via vault invalidation timestamps.
3. Fetch Envio events when missing days require recomputation.
4. Build a share-balance timeline.
5. Resolve vault metadata and PPS from Kong.
6. Fetch underlying asset prices from DefiLlama.
7. Compute daily USD totals.
8. Persist results back to cache.

PnL flow

1. Fetch address-scoped events.
2. Enrich with tx-scoped context for same-hash router, staking, and migration flows.
3. Normalize into vault-family ledgers.
4. Build FIFO lots and realized entries.
5. Value remaining lots with current PPS and token price.
6. Apply the chosen unknown-basis policy.
7. Materialize summary rows and drilldown payloads.

Data Sources

The holdings and PnL pipeline now combines:

• Envio GraphQL for deposits, withdrawals, and transfers
• Kong for vault metadata and historical/current PPS
• DefiLlama for historical/current USD prices of the vault asset token
• Ethereum RPC + CoW settlement logs for selected known-basis synthetic acquisition enrichment

Pricing / Performance Improvements

This branch also hardens price fetching significantly:

• tuned DefiLlama batching for reliability
• pro/free GET fallback behavior
• request splitting on infra-sized failures
• exact positive-price caching
• exact negative-cache for unsupported price points with TTL
• support for fetchType=parallel and paginationMode=all on both history and PnL surfaces
• support for the same fetch controls on Vercel handlers, not only the Bun server

Frontend Integration

The Portfolio page now consumes the new APIs and surfaces:

• chart history from /api/holdings/history
• Portfolio PnL and Economic Gain from /api/holdings/pnl
• tooltip copy explaining the metric formulas
• stable vs volatile breakdowns under PnL and Economic Gain
• updated response typing and schema validation

Operational Changes

This branch adds lazy cache invalidation for newly indexed vaults:

1. After deploying an indexer update with new vaults, call POST /api/admin/invalidate-cache.
2. Vault invalidation timestamps are recorded in the database.
3. On the next user request, the system checks whether any held vaults were invalidated after cache creation.
4. If stale, the affected user cache is cleared and recalculated lazily.

It also adds a chores endpoint for stale cache cleanup.

Documentation

This branch ships with dedicated docs for both the high-level holdings system and the accounting model:

• api/lib/holdings/README.md
• api/lib/holdings/PNL.md

Testing

The work includes substantial coverage across:

• history aggregation
• GraphQL event fetching
• DefiLlama batching and caching
• Kong metadata/PPS integration
• CoW settlement enrichment
• PnL mode behavior
• vault metadata resolution
• drilldown and summary materialization

Screenshots

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
yearnfi	Ready	Preview, Comment	Apr 10, 2026 11:09pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
yearnfi-nextjs	Ignored	Preview	Apr 10, 2026 11:09pm

[github-actions]

Dependency Review

The following issues were found:

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 1 package(s) with unknown licenses.

See the Details below.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 794104e.

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.

License Issues

package.json

Package	Version	License	Issue Type
@neondatabase/serverless	^1.0.2	Null	Unknown License

Allowed Licenses:

MIT, Apache-2.0, BSD-3-Clause, BSD-2-Clause, ISC, CC0-1.0, CC-BY-3.0, CC-BY-4.0, Unlicense

OpenSSF Scorecard

Package	Version	Score	Details
npm/@neondatabase/serverless	^1.0.2	Unknown	Unknown
npm/@types/pg	^8.16.0	Unknown	Unknown

Scanned Files

• package.json

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​pg@​8.20.0
	@​neondatabase/​serverless@​1.0.2

View full report

[0xeye]

Is this permissioned access? We shouldn't have DELETE api endpoints exposed publicly

Also, can we merge in feat/portfolio-history-adjustments - it just replaces let/for to const/maps, something I've expanded the CLAUDE.md doc to include in future

[w84april]

Oh! Sure, this was added for simpler testing purposes only. Thanks for pointing it out

[murderteeth]

if we have an error and don't return anything, this should probably collapse or be hidden and not take up space.

for the empty state (not the same as error state) instead of collapse or hide, lets show a placeholder\mockup. something that communicates "this is how awesome your portfolio would look if you had one" followed with a clear call to action, Explore Vaults, or whatever. use muted colors and\or a badge that clearly says "example", so it's clear we're not showing real holdings.

the portfolio page is popular, users spend a lot of time on it. we dont want to undersell it.