[vincentpeter0041-art]

Summary

Vault security & realtime: KMS signer, emergency redemption, live ticks, TWAB

What was solved

#269 — Implement Vault Admin Key Custody With KMS/HSM Signing and Role Rotation

Add a KMS/HSM-backed vault admin signing service with per-role policy enforcement, role separation and rotation, audit logging, non-secret signer configuration, and a key-management policy document — without touching the approval/timelock workflow or contract-side authorization.

Addressed:

• Changed: src/env.ts, .env.local.example, .github/workflows/release.yml, security/key-management-policy.md
• Introduce a signing service/BFF module exposing a narrow 'sign this approved intent' API (no raw arbitrary-bytes signing) that validates intents against role policy server-side before invoking KMS/HSM and returns only the signature.
• Ensure no privileged secret material is readable by application code or present in the repo, CI variables, or container images; keys live in managed KMS/HSM.
• Define explicit role separation with distinct keys for at least: contract admin/upgrade, parameter/strategy control, oracle submission, emergency pause, and treasury; roles independently rotatable.

#270 — Implement an Emergency Break-Glass Withdrawal Path That Bypasses Epoch Locks

Add a narrowly-scoped emergency break-glass redemption path for vault depositors, gated by a single on-chain emergency_conditions_met() predicate (halt flag, stale NAV, or lifecycle failure state), priced off the last committed epoch snapshot NAV, with a configurable bps exit penalty, per-epoch rate limits and TVL caps, a distinct event for observability/audit, and corresponding frontend adapter + operator console + confirm-dialog disclosure. Normal epoch-boundary redemption and queued-withdrawal processing are explicitly out of scope.

Addressed:

• Changed: src/lib/api/vaults.ts
• Provide a contract entry point (e.g. emergency_redeem) callable only when at least one objective on-chain trigger is true: operator-set halt flag, NAV timestamp older than the staleness window, or lifecycle state machine reporting a failure state.
• Centralize gating logic in a single unit-testable emergency_conditions_met() predicate.
• Compute redeemable amount from the last committed epoch snapshot NAV (not a live mark) so the exit is deterministic and not exploitable via a stale-oracle window.

#271 — Stream Live Vault NAV, Epoch Progress, and Redemption Queue State Over the Existing Spot Feed

Extend the existing shared SpotFeed WebSocket context to also deliver live vault data (NAV per share, epoch number, seconds-to-epoch-close, queue depth, last-updated) keyed by vault id, expose typed hooks like useVaultTicks(vaultId), and render these live on the /vaults list and detail surfaces with a stale/offline indicator and reconnect-with-backoff. Reuse the existing socket owner and message envelope/versioning rather than adding a new realtime mechanism.

Addressed:

• Changed: src/lib/context/SpotFeedContext.tsx, src/lib/api/vaults.ts, src/env.ts, docs/realtime-protocol.md
• Generalize or extend src/lib/context/SpotFeedContext.tsx to subscribe to vault topics keyed by vault id, delivering NAV per share, epoch number, seconds-to-epoch-close, queue depth, and last-updated timestamps
• Expose typed selectors/hooks (e.g. useVaultTicks(vaultId)) so components never touch the raw socket
• Render live values on the /vaults list and detail surfaces with a clear stale/offline indicator when the socket drops

#272 — Implement Time-Weighted Average Balance (TWAB) Tracking for Vault Shares

Add a checkpointed cumulative-balance TWAB accumulator to the SEP-41 vault share token so governance weight and future tiering mechanisms read duration-weighted stake instead of instantaneous balances. Implement binary-searchable checkpoints written only on share mint/burn/transfer, expose balance_at(account, timestamp) and twab(account, start, end), specify rounding/zero-window semantics, document checkpoint retention/compaction, and migrate governance voting weight to read TWAB.

Addressed:

• Changed: docs/governance-proposal-wizard.md, docs/security/invariants.md
• Maintain a checkpointed cumulative-balance accumulator with binary-searchable checkpoints in the vault share token contract
• Expose balance_at(account, timestamp) and twab(account, start, end)
• Write checkpoints only on share mint, burn, and transfer; no unbounded loops; bounded checkpoint history

Changes

• src/env.ts (modify)
• .env.local.example (modify)
• .github/workflows/release.yml (modify)
• security/key-management-policy.md (create)
• src/lib/api/vaults.ts (modify)
• src/lib/context/SpotFeedContext.tsx (create)
• docs/realtime-protocol.md (modify)
• docs/governance-proposal-wizard.md (modify)
• docs/security/invariants.md (modify)

Approach

1. Implement Vault Admin Key Custody With KMS/HSM Signing and Role Rotation #269 — Implement Vault Admin Key Custody With KMS/HSM Signing and Role Rotation (Changed: src/env.ts, .env.local.example, .github/workflows/release.yml, security/key-management-policy.md)
2. Implement an Emergency Break-Glass Withdrawal Path That Bypasses Epoch Locks #270 — Implement an Emergency Break-Glass Withdrawal Path That Bypasses Epoch Locks (Changed: src/lib/api/vaults.ts)
3. Stream Live Vault NAV, Epoch Progress, and Redemption Queue State Over the Existing Spot Feed #271 — Stream Live Vault NAV, Epoch Progress, and Redemption Queue State Over the Existing Spot Feed (Changed: src/lib/context/SpotFeedContext.tsx, src/lib/api/vaults.ts, src/env.ts, docs/realtime-protocol.md)
4. Implement Time-Weighted Average Balance (TWAB) Tracking for Vault Shares #272 — Implement Time-Weighted Average Balance (TWAB) Tracking for Vault Shares (Changed: docs/governance-proposal-wizard.md, docs/security/invariants.md)

Issues

Closes #269
Closes #270
Closes #271
Closes #272

[drips-wave]

@vincentpeter0041-art 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