[kerenaugustine79]

Summary

Add on-chain NAV-per-share feed contract with staleness verdict

What was solved

#277 — Publish an On-Chain NAV and Share-Price Feed for Third-Party Composability

Add a thin, versioned on-chain NAV/share-price feed contract that stores each vault's latest committed NAV per share with epoch and update ledger time, exposes a staleness verdict, and is writable only through the vault epoch settlement path. Wire the settlement publish call, surface feed values in vault observability/reconciliation, and document the consumer contract (staleness semantics, precision/decimals, denomination, versioning).

Addressed:

• Changed: src/lib/api/vaults.ts
• Feed contract stores per vault: latest committed NAV per share, source epoch number, update ledger time, and a schema/version field for breaking-change detection
• Expose a staleness verdict function callable by consumers (stale when an epoch is skipped/delayed — must go stale, not lie)
• Vault/epoch settlement path publishes the value at each committed epoch; update authority is scoped so arbitrary callers cannot update and attempts outside settlement fail

#278 — Implement Epoch Share-Balance Snapshots and Merkle Commitments for Provable Redemptions

Add on-chain Merkle commitments of epoch share balances so depositors can prove historical balances and third parties can verify redemption claims without trusting the backend. The work spans the Soroban contracts (commitment storage + verifier), the indexer/registry service that builds trees and serves proofs, the /vaults API surface, and the epoch ledger UI, with a published canonical tree spec and cross-language hash vectors.

Addressed:

• Changed: src/lib/api/vaults.ts, docs/LEDGER.md
• At each committed epoch, the vault stores a Merkle root (or equivalent commitment) over that epoch's share balances alongside the already-committed NAV per share and epoch number.
• Publish the necessary proof data: canonical leaf encoding, ordering rule, and tree construction spec; the backend indexer must store/derive this so proofs can be served through the API.
• Provide a verifier entry point (contract function or documented library) that checks a claimed (account, balance, epoch, proof) against the stored root.

#279 — Surface Vault-Written Position Risk Metrics in the Vault and Portfolio Surfaces

Add a per-vault risk panel that surfaces modelled risk metrics (assignment probability, max loss, breakevens, aggregate Greeks) for the vault's open written positions, computed via the existing Black-Scholes/payoff modules through a single shared aggregation helper, and fold vault-written exposure into the portfolio surface's total risk. Inputs come from existing sources; missing/stale inputs degrade to "unavailable"; methodology is documented and linked, figures labelled as estimates. Out of scope: performance analytics (NAV/APY/attribution) and the what-if simulator.

Addressed:

• Changed: src/lib/pricing.ts, src/lib/payoff.ts, src/lib/api/vaults.ts
• Per-vault risk panel for the current epoch showing count and notional of written positions by strategy
• Aggregate delta/gamma/vega/theta across the vault's open written positions
• Per-position assignment probability with model and inputs stated

#280 — Implement a Shared NAV/Share-Price Math Library With Differential Conformance Tests

Create a canonical, integer-only NAV/share-price math library with a written spec, matching Rust (contracts/) and TypeScript (frontend/backend) reference implementations, a versioned JSON golden-vector fixture, and differential conformance tests proving byte-identical results including adversarial rounding cases.

Addressed:

• Changed: README.md
• Write a spec covering order of operations (validate → compute gross → apply fees → apply rounding → emit shares/assets), 7-decimal Stellar integer scaling, rounding direction (all dust favours the vault), minimum-share and dust thresholds, and behaviour at NAV <= 0
• Provide a Rust reference implementation in the vault contract crate under contracts/ with checked/wrapping-safe math (no panics)
• Provide a TypeScript reference implementation alongside src/lib/pricing.ts and src/lib/payoff.ts exposing only integer-in/integer-out functions

Changes

• src/lib/pricing.ts (modify)
• docs/LEDGER.md (modify)
• README.md (modify)
• src/lib/api/vaults.ts (modify)
• src/lib/payoff.ts (create)

Approach

1. Publish an On-Chain NAV and Share-Price Feed for Third-Party Composability #277 — Publish an On-Chain NAV and Share-Price Feed for Third-Party Composability (Changed: src/lib/api/vaults.ts)
2. Implement Epoch Share-Balance Snapshots and Merkle Commitments for Provable Redemptions #278 — Implement Epoch Share-Balance Snapshots and Merkle Commitments for Provable Redemptions (Changed: src/lib/api/vaults.ts, docs/LEDGER.md)
3. Surface Vault-Written Position Risk Metrics in the Vault and Portfolio Surfaces #279 — Surface Vault-Written Position Risk Metrics in the Vault and Portfolio Surfaces (Changed: src/lib/pricing.ts, src/lib/payoff.ts, src/lib/api/vaults.ts)
4. Implement a Shared NAV/Share-Price Math Library With Differential Conformance Tests #280 — Implement a Shared NAV/Share-Price Math Library With Differential Conformance Tests (Changed: README.md)

Issues

Closes #277
Closes #278
Closes #279
Closes #280

[drips-wave]

@kerenaugustine79 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits