[jhayniffy]

Summary

Add per-vault delta-hedging policy and hedge P&L attribution

What was solved

#297 — Implement Dynamic Delta-Hedging Automation for Vault-Written Option Positions

Add an optional, per-vault delta-hedging policy for option-writing vaults: define the policy object (enabled, delta band, instrument, max notional, cadence, kill switch), compute vault-level Greeks from open written positions via the shared pricing library, route hedge orders through a dedicated execution path separate from option sales, persist hedge trades in the epoch ledger with hedge P&L attributed separately from option premium, and surface hedge status/P&L through the vaults API. Hedging must be idempotent, keeper-driven with on-chain bounds enforcement, fail safe on stale/missing price feeds, rate-limited against churn, disableable mid-epoch without book inconsistency, and must never violate collateral custody rules.

Addressed:

• Changed: src/lib/pricing.ts, src/lib/api/vaults.ts, contracts/fixtures/AggregateGreeksSchema.json
• Define a per-vault hedging policy object: enabled flag, delta band (target ± tolerance), hedge instrument, max hedge notional, rehedge cadence, and a hard kill switch.
• Compute vault-level Greeks (at minimum delta, ideally gamma/vega awareness) from open written positions using the shared pricing library.
• Route hedge orders through a dedicated execution path separate from the option-sale execution mechanism.

#298 — Build a Vault Data Warehouse and Analytics ETL Pipeline for Epoch, Flow, and Strategy Metrics

Add a vault analytics ETL pipeline: warehouse schemas (vault registry snapshots, epoch facts, flow facts, share-price series, redemption-queue depth), idempotent replayable ETL jobs with indexer-cursor watermarking, versioned analytical views, and data-quality checks that fail loudly. Deliver as backend vault service modules plus docs and CI wiring, without touching depositor-facing charts or frontend telemetry.

Addressed:

• Changed: docs/LEDGER.md
• Define warehouse schemas for vault registry snapshots, epoch facts (open/close, NAV, premium collected, fees, realized P&L), flow facts (deposits, withdrawals, queue entries/exits), share-price time series, and redemption-queue depth
• Implement idempotent, replayable ETL jobs with watermarking against the indexer cursor so backfills and restatements do not double count
• Publish documented, versioned analytical views/tables queryable by the analytics surface and reporting exports instead of operational DBs

#299 — Implement Distributed Tracing and Correlation IDs Across Vault Services, the Indexer, and Contract Calls

Instrument the Phase 2 vault stack with OpenTelemetry-style distributed tracing and a shared correlation-ID convention spanning frontend deposit/withdraw requests, BFF routes, the vault backend, the event indexer, keeper epoch transitions, and Soroban transaction submission. The correlation ID must propagate through BFF headers, backend request context, async job payloads, and on-chain memo/metadata where the wallet flow permits, be surfaced in structured logs and error responses, and be recorded on idempotency records so replays link to the original trace. Trace export wires to the existing observability backend with a sampling policy that never drops error traces.

Addressed:

• Changed: src/env.ts
• Adopt and document a correlation-ID convention: one ID per user-initiated action, propagated through BFF headers, backend request context, job payloads, and on-chain memo/metadata where the wallet flow permits
• Emit spans for vault API handlers, database queries in vault services, indexer batch processing, keeper epoch operations, and Soroban RPC submission/confirmation
• Expose the correlation ID in structured logs and in error responses so support tooling and the read-only support console can surface it to depositors

#300 — Build a Secondary Transfer Facility for Vault LP Shares With NAV-Based Pricing and Order Matching

Add a NAV-anchored secondary transfer facility for vault LP shares: off-chain order store with on-chain atomic settlement, price bounded by a configurable band around attested NAV, expiry/nonce/replay protection, compliance/lockup/eligibility gating, cancellability, and a discoverable order surface in the vault UI. Scope excludes a full on-chain matching engine with maker/taker rebates and any redemption-queue changes.

Addressed:

• Changed: src/lib/api/vaults.ts
• Support resting and immediately-fillable orders for vault LP shares (per vault, per tranche if tranching exists), priced in the vault's share price terms
• Bound order price by a configurable band around the latest attested NAV
• Atomic settlement: shares and payment move together or not at all; support partial fills where the order allows

Changes

• src/lib/pricing.ts (modify)
• src/lib/api/vaults.ts (modify)
• contracts/fixtures/AggregateGreeksSchema.json (modify)
• docs/LEDGER.md (modify)
• src/env.ts (modify)

Approach

1. Implement Dynamic Delta-Hedging Automation for Vault-Written Option Positions #297 — Implement Dynamic Delta-Hedging Automation for Vault-Written Option Positions (Changed: src/lib/pricing.ts, src/lib/api/vaults.ts, contracts/fixtures/AggregateGreeksSchema.json)
2. Build a Vault Data Warehouse and Analytics ETL Pipeline for Epoch, Flow, and Strategy Metrics #298 — Build a Vault Data Warehouse and Analytics ETL Pipeline for Epoch, Flow, and Strategy Metrics (Changed: docs/LEDGER.md)
3. Implement Distributed Tracing and Correlation IDs Across Vault Services, the Indexer, and Contract Calls #299 — Implement Distributed Tracing and Correlation IDs Across Vault Services, the Indexer, and Contract Calls (Changed: src/env.ts)
4. Build a Secondary Transfer Facility for Vault LP Shares With NAV-Based Pricing and Order Matching #300 — Build a Secondary Transfer Facility for Vault LP Shares With NAV-Based Pricing and Order Matching (Changed: src/lib/api/vaults.ts)

Issues

Closes #297
Closes #298
Closes #299
Closes #300

[drips-wave]

@jhayniffy 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