Skip to content

feat(invoices): add NAV fair value indicator (#546) - #560

Merged
TS-mfon merged 1 commit into
StellarState:devfrom
johnsmccain:feature/546-nav-fair-value-indicator
Oct 21, 2026
Merged

TS-mfon merged 1 commit into
StellarState:devfrom
johnsmccain:feature/546-nav-fair-value-indicator

Conversation

@johnsmccain

Copy link
Copy Markdown
Contributor

Summary

Shows the computed NAV (fair value) of an invoice against its current market price, so an investor can see at a glance whether the market is paying a premium or a discount.

Closes #546.

Scope

  • lib/nav.ts — the pricing rules as pure, testable helpers: where the price sits relative to NAV (above / at / below), the gap in basis points, when a NAV is stale, and how a per-fraction price is formatted.
  • lib/api — fetchInvoiceNav reads GET /invoices/:id/nav and normalises the field spellings the endpoint has shipped (nav_per_fraction / navPerFraction / fair_value, and so on). A 404 means "this invoice has no NAV", which is not an error: it resolves to null so an unpriced invoice hides the chip rather than failing.
  • hooks/useInvoiceNav.ts — the query hook. Polling is suspended while the tab is hidden, and stops entirely for invoices the backend has no NAV for, so an unpriced invoice is not re-requested every minute.
  • components/marketplace/NavChip.tsx — the chip, on the marketplace grid card and on the list row.
  • components/invoices/InvoiceNavPanel.tsx — the NAV, current price and premium/discount figures in the invest panel on the invoice detail page.

Acceptance criteria

  • Above/At/Below NAV chip rendered correctly for all three states
  • Premium/discount bps computed and displayed accurately in the invest panel
  • Staleness warning shown correctly when the NAV is stale
  • Chip renders correctly on both grid and list invoice views
  • NAV chip hidden for invoices with no NAV data

Notes

  • Premiums are measured against the NAV, not the price: a price of 2.20 against a NAV of 2.00 is a +1000 bps premium.
  • A price within 25 bps of the NAV reads as "At NAV", matching the band the sector benchmark chip already uses.
  • A missing computed_at is not treated as stale. There is nothing to compare it against, and warning on every invoice whose payload omits the field would be noise. The staleness warning therefore needs a real timestamp to fire.
  • The chip and the panel both fall back to the invoice's fraction_price when the endpoint reports no market price of its own, so an open invoice with no secondary market still has something to compare.
  • The NAV panel sits inside the invest card for every branch of it, including the not-connected and not-KYC-approved ones: fair value is public information, so it is shown whether or not this particular wallet is allowed to invest. It is also shown on funded and settled invoices, where the primary market has closed but the secondary market is still trading.

Also included

components/invoices/FeeTierDisplay.tsx had a pre-existing type error (discountedFeeAmount possibly null) that was failing tsc --noEmit on dev — and with it the CI run for the last merge, #553. It is a one-line guard addition, included here so this PR can go green.

Verification

  • npx tsc --noEmit — clean
  • npm run lint — clean (only pre-existing warnings in unrelated files)
  • npm run build — succeeds
  • npm test — 1460 passed / 190 files, including 30 new tests across lib/__tests__/nav.test.ts, components/marketplace/__tests__/NavChip.test.tsx, components/invoices/__tests__/InvoiceNavPanel.test.tsx and app/marketplace/__tests__/marketplace-nav-chip.test.tsx

Adds the computed NAV of an invoice against its current market price, so
an investor can see whether the market is paying a premium or a discount.

- lib/nav.ts: the pricing rules as pure helpers — where the price sits
  relative to NAV, the gap in basis points, and when a NAV is stale.
- lib/api: fetchInvoiceNav reads GET /invoices/:id/nav and normalises the
  field spellings the endpoint has shipped. A 404 is "no NAV", not an
  error, so an unpriced invoice hides the chip instead of failing.
- NavChip on the marketplace card and list row, and InvoiceNavPanel in the
  invest panel on the invoice detail page.
- The chip and panel render nothing when an invoice has no NAV, and warn
  once the NAV is more than an hour old.

Also fixes a pre-existing type error in FeeTierDisplay that was failing
`tsc --noEmit` on dev, and with it the last merged CI run.

Fixes StellarState#546
@TS-mfon
TS-mfon merged commit cb5231b into StellarState:dev Oct 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add invoice NAV fair value indicator on invoice cards and detail page

2 participants