Vault Contract v2 Improvements

[techrebelgit]

---

PRD — Vault Contract v2 Improvements

Enhancing ROI visibility, transparency, and developer experience for Tokenization Lego

---

1. Overview

The current Vault Contract supports claiming ROI but lacks the read/view functions needed for:

• investor dashboards

• transparency portals

• tokenization analytics

• indexer integrations

• future chain expansion

This PRD defines the improvements needed to make the Vault Contract production-ready, developer-friendly, and easy to integrate in open source.

The goal is not to change high-level business logic — only to simplify on-chain read access, add safety, and improve UX.

---

2. Goals

Primary Goals

• Add missing getter/view functions

• Allow ROI preview before claiming

• Make vault data accessible without custom RPC logic

• Emit events during claim actions

• Clarify contract storage and naming

Secondary Goals

• Improve safety around storage and balances

• Make the contract indexer-friendly (Goldsky/SubQuery)

• Improve maintainability

---

3. Current Issues

Issue	Description
No view/getter functions	Requires manual storage reads + frontend recomputation
No ROI preview	Cannot display “claimable ROI” on dashboards
No vault-level metadata	Must manually read raw storage keys from frontend
No events	Hard for explorers or indexers to track claims
Storage keys untyped	Raw string keys reduce safety + readability
Naming unclear	“price” is ambiguous (is it ROI %, multiplier, etc?)

---

Events

New:

ClaimEvent emitted during successful claim.

---

6. Acceptance Criteria

Functional

• All getter/view functions implemented

• Claim behavior unchanged

• ClaimEvent emitted correctly

• VaultOverview returns a complete snapshot

• Comprehensive test coverage (unit + snapshot)

• No storage breaks (backwards compatible)

Developer Experience

• Values return in JS-native convertible formats

• Clean storage pattern (typed keys)

• Easy to integrate in frontends and indexers

---

7. Future Extensions (Not Included)

• Multi-tier ROI

• Time-based accrual

• Multi-token vault

• Vault deposit/withdraw functionality

• Oracle-based ROI

---

8. Summary for Developers

This update transforms the Vault Contract from a minimalistic ROI-distribution contract into a fully observable, dashboard-friendly, and open-source integrator-friendly module.

These changes are essential for:

• the Claim ROI page

• investor dashboards

• transparency apps

• tokenization products

• third-party integrations

---

9. Questions for Alignment

1. Should ROI be expressed as a percentage, premium, or multiplier?

2. Should the claim logic remain “all-or-nothing,” or allow partial claims?

3. Do we want to expose a claim history view function for analytics?

---

When you're ready, I can generate:

• the full contract code diff

• updated test suites

• a GitHub issue description for OnlyDust bounties

• frontend integration specs to match the new contract methods