[BethelDev-io]

Summary

Vault e2e tests, API hardening, pagination/caching, and loss recognition

What was solved

#219 — Add Playwright End-to-End Coverage for Vault Deposit, Withdrawal, and Epoch Flows

Extend the existing Playwright harness with mocked-backend vault coverage: add vault fixtures/routes to e2e/mockBackend.ts, add vault spec files for deposit, queued withdrawal/redemption, epoch/capacity states, error handling, and the NEXT_PUBLIC_VAULTS disabled fallback, plus visual baselines and CI wiring. Tests must run across existing Playwright projects against the mocked backend only.

Addressed:

• Changed: e2e/mockBackend.ts, e2e/vaults.spec.ts, playwright.config.ts
• Add mock backend fixtures and routes for vault list, vault detail, epoch ledger, deposit, withdrawal queue, and all documented error responses in e2e/mockBackend.ts
• Add Playwright spec(s) covering successful deposit with share-preview update, asserting both visible outcome and the request the app issued
• Add Playwright spec(s) covering a withdrawal entering the queue and a redemption completing

#220 — Harden the Vault API With Rate Limiting, Auth Scoping, and Abuse Protection

Harden the vault REST surface and its BFF proxy routes with per-wallet/per-IP rate limiting, explicit read/write/operator auth scopes, strict server-side amount/vault-id/pagination validation, idempotency-based replay protection, structured audit logging of state-changing requests, and CSRF/origin checks on BFF write routes — enforced authoritatively at the backend vault service and re-checked cheaply at the BFF, with per-environment configurable limits.

Addressed:

• Changed: src/lib/api/vaults.ts, src/env.ts
• Per-wallet (primary) and per-IP (secondary) rate limits on vault read and write endpoints, with documented limits and 429 responses that include retry hints (Retry-After / retryAfter field).
• Explicit scopes on the session/token: vault read, vault deposit/withdraw, vault operator actions; write requests rejected with 403 when the required scope is missing.
• Server-side validation of every amount, share quantity, vault id, and pagination parameter, rejecting over-precision and negative values before they reach the contract layer.

#223 — Implement Caching, Pagination, and Read-Path Performance for Vault List and Epoch History Endpoints

Add cursor-based pagination, server-side caching with freshness metadata, and N+1 elimination to the vault list and epoch history read paths, plus a typed paginated client in src/lib/api/vaults.ts. Scope is limited to the read path: no write-path changes, no contract-level RPC batching, and no CDN caching configuration.

Addressed:

• Changed: src/lib/api/vaults.ts
• Implement opaque cursor (not offset) pagination for the vault list and epoch history endpoints, with a documented maximum page size and stable ordering under concurrent writes
• Ensure cursors over a stable sort key (ids or epoch index, not timestamps) so page boundaries do not skip or duplicate rows when a new epoch lands mid-pagination
• Add server-side caching for vault list/detail and finalized epochs, with explicit invalidation on epoch close, deposit/withdraw completion, and registry changes

#225 — Implement Vault Insolvency, Bad-Debt, and Socialized-Loss Handling

Implement a deterministic vault loss-recognition waterfall (fee reserves → first-loss buffer → pro-rata share write-down) invoked only from settlement/epoch-close, emitting a structured VaultLossEvent persisted in the epoch ledger, clamping NAV/share at zero with residual bad debt recorded explicitly, disabling deposits while impaired, and surfacing loss fields through the vault API types and vault detail UI impaired/underwater state.

Addressed:

• Changed: src/lib/api/vaults.ts
• Implement loss-allocation waterfall in vault contract: fee/performance-fee reserves first, then first-loss buffer, then pro-rata share write-down (burn or NAV markdown) across all shareholders as of the loss epoch
• Restrict loss recognition to defined points (epoch close, settlement callback, failed mark-to-market check) — not arbitrary caller-supplied input; loss path must not be reachable by unprivileged callers
• Emit structured VaultLossEvent (epoch, realized loss, remaining buffer, resulting NAV/share) and persist it in the epoch ledger

Changes

• e2e/mockBackend.ts (modify)
• src/lib/api/vaults.ts (modify)
• e2e/vaults.spec.ts (create)
• src/env.ts (modify)
• playwright.config.ts (modify)

Approach

1. Add Playwright End-to-End Coverage for Vault Deposit, Withdrawal, and Epoch Flows #219 — Add Playwright End-to-End Coverage for Vault Deposit, Withdrawal, and Epoch Flows (Changed: e2e/mockBackend.ts, e2e/vaults.spec.ts, playwright.config.ts)
2. Harden the Vault API With Rate Limiting, Auth Scoping, and Abuse Protection #220 — Harden the Vault API With Rate Limiting, Auth Scoping, and Abuse Protection (Changed: src/lib/api/vaults.ts, src/env.ts)
3. Implement Caching, Pagination, and Read-Path Performance for Vault List and Epoch History Endpoints #223 — Implement Caching, Pagination, and Read-Path Performance for Vault List and Epoch History Endpoints (Changed: src/lib/api/vaults.ts)
4. Implement Vault Insolvency, Bad-Debt, and Socialized-Loss Handling #225 — Implement Vault Insolvency, Bad-Debt, and Socialized-Loss Handling (Changed: src/lib/api/vaults.ts)

Issues

Closes #219
Closes #220
Closes #223
Closes #225

[drips-wave]

@BethelDev-io 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