Skip to content

Commit 7c25245

Browse files
JunirezzJunirezz
authored
Merge pull request #1263 from victorEdeh/feat/fixed
improved repo-wide document
2 parents b1362eb + 0f3a696 commit 7c25245

6 files changed

Lines changed: 554 additions & 1 deletion

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,14 @@ This project is structured as a monorepo containing both the Stellar Soroban sma
99
- `/contracts/vault/`: Contains the Rust Soroban smart contract for handling the vault logic, fractional share minting (`yvUSDC`), scaling withdrawals, and simulated yield accrual.
1010
- `/contracts/mock-strategy/`: Contains test mock contracts for the Korean sovereign debt strategy and price oracle.
1111
- `/frontend/`: Contains the React + Vite frontend application, integrating `@stellar/freighter-api` for seamless user wallet connections and a premium UI to interact with the protocol.
12-
- `/docs/`: Contains the Product Requirements Document (PRD), Architecture Document, [Domain Glossary](./docs/GLOSSARY.md), and tracked GitHub issues. See also the [Deposit & Withdrawal Lifecycle](./docs/DEPOSIT_WITHDRAWAL_LIFECYCLE.md) for sequence diagrams and the [Deposit & Withdrawal Troubleshooting Guide](./docs/DEPOSIT_WITHDRAWAL_TROUBLESHOOTING.md) for diagnosing failed operations.
12+
- `/docs/`: Contains the Product Requirements Document (PRD), Architecture Document, [Domain Glossary](./docs/GLOSSARY.md), and tracked GitHub issues. See also the [Deposit & Withdrawal Lifecycle](./docs/DEPOSIT_WITHDRAWAL_LIFECYCLE.md) for sequence diagrams, the [Deposit & Withdrawal Troubleshooting Guide](./docs/DEPOSIT_WITHDRAWAL_TROUBLESHOOTING.md) for diagnosing failed operations, and the [Dependency Update Policy](./docs/DEPENDENCY_UPDATE_POLICY.md) for upgrade cadence, testing gates, CVE SLAs, and high-risk library requirements.
1313

1414
## Architecture
1515

1616
For a comprehensive overview of the smart contract architecture, module responsibilities, and interaction boundaries, see **[Contracts Architecture](./docs/CONTRACTS_ARCHITECTURE.md)**.
1717

18+
For a cross-layer view of ownership boundaries, API flow maps, event propagation, and interface assumptions between the frontend, backend, and contracts, see **[System Ownership & Data Flow](./docs/SYSTEM_OWNERSHIP_AND_DATA_FLOW.md)**.
19+
1820
### Contract Modules
1921

2022
| Module | Purpose |

‎docs/BACKEND_MODULE_OWNERSHIP.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
This document maps every backend module to its functional domain, primary owner, and secondary reviewer. Use it to route issues, PR reviews, and incident escalations to the correct maintainer quickly.
44

55
Related documents:
6+
- [SYSTEM_OWNERSHIP_AND_DATA_FLOW.md](./SYSTEM_OWNERSHIP_AND_DATA_FLOW.md) — Layer ownership boundaries, API flow maps, event flow, and cross-layer assumptions
67
- [TRIAGE_AND_REVIEW.md](../TRIAGE_AND_REVIEW.md) — Triage workflow and review criteria
78
- [docs/TRIAGE_ROTATION_CALENDAR.md](./TRIAGE_ROTATION_CALENDAR.md) — Weekly rotation schedule and escalation timeline
89
- [docs/SERVICE_DEPENDENCY_MATRIX.md](./SERVICE_DEPENDENCY_MATRIX.md) — Cross-service dependencies and startup order

‎docs/CONTRACTS_ARCHITECTURE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
**soroban-sdk Version:** 22.0.0
66
**Last Updated:** May 29, 2026
77

8+
> **See also:** [System Ownership & Data Flow](./SYSTEM_OWNERSHIP_AND_DATA_FLOW.md) for layer ownership boundaries, the backend ↔ contract interface assumptions (§5.2), and the full event flow map showing how on-chain events propagate to webhook subscribers.
9+
810
---
911

1012
## 1. Project Overview

‎docs/DEPENDENCY_REVIEW_PROCESS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Recurring Dependency Review Process and Ownership
22

3+
> **Policy companion:** See [Dependency Update Policy](./DEPENDENCY_UPDATE_POLICY.md) for the authoritative rules on upgrade cadence, testing gates, high-risk library list, CVE severity SLAs, and major-update owner requirements. This document covers the recurring *workflow* — how reviews are scheduled, executed, and documented.
4+
35
This document defines a recurring process for reviewing third-party dependencies, assigning accountable owners, tracking outcomes, and keeping updates safe for YieldVault-RWA.
46

57
---

‎docs/DEPENDENCY_UPDATE_POLICY.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Dependency Update Policy
2+
3+
> **Related docs:**
4+
> - [Dependency Review Process](./DEPENDENCY_REVIEW_PROCESS.md) — recurring review cadence, ownership, and outcome documentation
5+
> - [Security Scanning Guide](./SECURITY_SCANNING_GUIDE.md) — CVE tooling and scanner configuration
6+
> - [Code Review Standards](./CODE_REVIEW_STANDARDS.md) — general PR review expectations
7+
> - [CODEOWNERS](../.github/CODEOWNERS) — authoritative owner list per surface
8+
9+
This document defines **policy** — the rules governing how dependencies are upgraded across the YieldVault-RWA monorepo. It applies to all three layers: Soroban smart contracts (Rust/Cargo), backend (Node.js/npm), and frontend (Node.js/npm). The companion [Dependency Review Process](./DEPENDENCY_REVIEW_PROCESS.md) covers the recurring review workflow and outcome documentation requirements.
10+
11+
---
12+
13+
## 1. Scope
14+
15+
| Layer | Manifest | Package manager |
16+
|-------|----------|-----------------|
17+
| Contracts | `/Cargo.toml`, `*/Cargo.toml` | Cargo |
18+
| Backend | `backend/package.json` | npm |
19+
| Frontend | `frontend/package.json` | npm |
20+
| Root tooling | `/package.json` | npm |
21+
22+
All four surfaces are in scope. Transitive (indirect) dependencies surfaced by Dependabot alerts or audit tools are subject to the same rules as direct dependencies.
23+
24+
---
25+
26+
## 2. Upgrade Cadence
27+
28+
### 2.1 Automated Dependabot updates
29+
30+
Dependabot is configured for daily runs on all three surfaces. PRs raised automatically by Dependabot follow this merge policy:
31+
32+
| Update type | Target SLA | Who may merge |
33+
|-------------|-----------|---------------|
34+
| **Security patch** (any severity) | ≤ 48 hours | Surface owner (after CI green) |
35+
| **Patch** (non-security) | ≤ 2 weeks | Surface owner (after CI green) |
36+
| **Minor** | Next scheduled sprint | Surface owner with one peer review |
37+
| **Major** | Requires owner sign-off (see §4) | Surface owner + one additional maintainer |
38+
39+
### 2.2 Manual / planned upgrades
40+
41+
Outside Dependabot, dependency upgrades are permitted only via a `chore/*` branch (see [CONTRIBUTING.md](../CONTRIBUTING.md#branching-strategy)). Examples:
42+
43+
```
44+
chore/upgrade-prisma-6
45+
chore/bump-stellar-sdk-minor
46+
chore/rust-soroban-sdk-2
47+
```
48+
49+
Manual upgrades follow the same review criteria as automated ones but require the author to explicitly document the reason in the PR description.
50+
51+
### 2.3 Layer-specific cadence
52+
53+
| Layer | Patch | Minor | Major |
54+
|-------|-------|-------|-------|
55+
| **Frontend** (user-facing) | As PRs arrive (≤ 2 weeks) | Sprint boundary | Planned release only |
56+
| **Backend** (API/services) | As PRs arrive (≤ 2 weeks) | Sprint boundary | Planned release only |
57+
| **Contracts** (on-chain Rust) | As PRs arrive (≤ 2 weeks) | Sprint boundary | Security audit gate required |
58+
| **Root tooling** | As PRs arrive (≤ 1 month) | Quarterly | Quarterly |
59+
60+
Contract-layer major upgrades require a security audit checkpoint before merging. See §4.
61+
62+
---
63+
64+
## 3. Testing Gates
65+
66+
All dependency update PRs must pass the following CI gates before merge. A PR with failing gates **must not** be merged, even for security patches — fix the breakage first.
67+
68+
### 3.1 Minimum gates (all layers)
69+
70+
- [ ] Linting passes (`npm run lint` / `cargo fmt --check`)
71+
- [ ] Unit tests pass (`npm test` / `cargo test`)
72+
- [ ] Build succeeds (`npm run build` / `cargo build --release`)
73+
74+
### 3.2 Extended gates (required for minor and major updates)
75+
76+
| Layer | Additional gate |
77+
|-------|----------------|
78+
| **Frontend** | Vitest unit suite + Cypress E2E smoke (`npm run test:e2e`) |
79+
| **Backend** | Jest integration tests (`npm run test:integration`) |
80+
| **Contracts** | Full `cargo test` including mock-strategy and oracle crates |
81+
82+
### 3.3 Gate bypass
83+
84+
No bypass is permitted for security patches unless:
85+
1. The breakage is isolated to a test fixture unrelated to the vulnerability fix, **and**
86+
2. A follow-up issue is filed within 24 hours to restore the test.
87+
88+
Bypasses require explicit written approval from the relevant surface owner and must be documented in the PR.
89+
90+
---
91+
92+
## 4. Major Update Owner Requirements
93+
94+
A major version bump (semver `X.0.0` where `X` increases) triggers the following additional requirements:
95+
96+
1. **Designated owner.** The owner defined in [CODEOWNERS](../.github/CODEOWNERS) for that surface must approve the PR. Approval from a different team member is insufficient.
97+
98+
2. **Changelog review.** The PR description must include a summary of breaking changes extracted from the upstream changelog or migration guide, with explicit notes on how each breaking change is handled.
99+
100+
3. **Migration plan.** If the upgrade requires code changes (API renames, removed exports, config changes), those changes must be included in the same PR or a linked PR that merges simultaneously.
101+
102+
4. **Staging validation.** Major updates to backend or frontend must be validated in the staging environment before merge to `main`. Contract major upgrades require testnet deployment validation.
103+
104+
5. **Contract layer additional gate.** Major Rust/Soroban SDK upgrades require:
105+
- Sign-off from `@YieldVault-RWA/contracts-maintainers` **and** `@YieldVault-RWA/security-team`
106+
- A security audit checkpoint or a scoped internal audit of changed surfaces
107+
- Testnet deployment and smoke test prior to merge
108+
109+
6. **Announcement.** Post a summary in the team's governance/update channel at least 24 hours before merging a major update, to allow any last-minute objections.
110+
111+
---
112+
113+
## 5. High-Risk Library List
114+
115+
The following libraries have elevated risk due to their role in security, cryptography, or protocol correctness. Updates to these packages require explicit review by the security team (`@YieldVault-RWA/security-team`) regardless of whether the update is patch, minor, or major.
116+
117+
### 5.1 Contracts (Rust/Cargo)
118+
119+
| Crate | Risk reason |
120+
|-------|-------------|
121+
| `soroban-sdk` | Core on-chain execution environment |
122+
| `soroban-auth` | Authentication primitives |
123+
| `stellar-xdr` | Ledger XDR encoding — any change can affect fund transfers |
124+
| Any crate touching `i128` fixed-point arithmetic | Yield and share calculation correctness |
125+
126+
### 5.2 Backend (npm)
127+
128+
| Package | Risk reason |
129+
|---------|-------------|
130+
| `@stellar/stellar-sdk` | Signs and submits on-chain transactions |
131+
| `@prisma/client` / `prisma` | Database ORM; schema migration risk |
132+
| `jsonwebtoken` / `jose` | Auth token signing and verification |
133+
| `express` / `fastify` | Core HTTP server; security surface |
134+
| `helmet` | Security headers |
135+
| `bcrypt` / `argon2` | Password hashing |
136+
| Any HMAC/webhook-signing library | Webhook signature integrity |
137+
138+
### 5.3 Frontend (npm)
139+
140+
| Package | Risk reason |
141+
|---------|-------------|
142+
| `@stellar/freighter-api` | Wallet connection and transaction signing |
143+
| `@stellar/stellar-sdk` | On-chain data parsing and XDR handling |
144+
| Any content-security-policy or sanitization library | XSS risk |
145+
146+
### 5.4 Review requirements for high-risk libraries
147+
148+
- One additional approver from `@YieldVault-RWA/security-team` required (all update types).
149+
- PR description must explicitly state: "High-risk library update — security review required."
150+
- If the update is patch-only and purely a CVE fix with no API changes, the security team approver may fast-track within 24 hours.
151+
152+
---
153+
154+
## 6. CVE and Security Advisory Review Criteria
155+
156+
When a CVE or GitHub Security Advisory (GHSA) is raised against a dependency, use the following criteria to determine required action.
157+
158+
### 6.1 Severity tiers
159+
160+
| CVSS Score | Severity | Required action | SLA |
161+
|------------|----------|----------------|-----|
162+
| 9.0–10.0 | Critical | Upgrade or mitigate immediately; block release if unresolved | 24 hours |
163+
| 7.0–8.9 | High | Upgrade in current sprint; must be resolved before next release | 72 hours |
164+
| 4.0–6.9 | Medium | Upgrade in next sprint unless mitigation is in place | 2 weeks |
165+
| 0.1–3.9 | Low | Upgrade at next scheduled review | Next review cycle |
166+
167+
### 6.2 Exploitability assessment
168+
169+
Before escalating a CVE, assess:
170+
171+
1. **Is the vulnerable code path reachable?** (e.g., a server-side vulnerability in a browser-only package is irrelevant)
172+
2. **Is the affected feature used by YieldVault?** Check the relevant surface's imports.
173+
3. **Does a patched version exist?** If not, document a mitigation plan (e.g., WAF rule, feature flag, code-level guard).
174+
4. **Is this a false positive?** Consult [False Positive Handling](./FALSE_POSITIVE_HANDLING.md) before dismissing.
175+
176+
### 6.3 Breaking changes in security fixes
177+
178+
If a security patch introduces a breaking API change (uncommon but possible), the update is treated as a **major update** (see §4) with a fast-track SLA applied based on severity.
179+
180+
### 6.4 No-fix advisories
181+
182+
If no upstream fix exists within the SLA window:
183+
- Document the CVE and mitigation in the tracking issue.
184+
- Evaluate replacing the dependency with an alternative.
185+
- Escalate to `@YieldVault-RWA/security-team` for risk acceptance sign-off.
186+
- Record the risk-acceptance decision in the relevant PR or tracking issue.
187+
188+
---
189+
190+
## 7. Dependency Freeze During Release Windows
191+
192+
During release freezes (see [Release Train Cadence](./RELEASE_TRAIN_CADENCE_AND_FREEZE_POLICY.md)):
193+
194+
- Non-security dependency updates are **deferred** until the freeze lifts.
195+
- Security patches classified High or Critical **may** be merged during a freeze with explicit approval from the release engineer.
196+
- Any merge during a freeze requires a fast-follow patch release plan if it introduces unexpected breakage.
197+
198+
---
199+
200+
## 8. Dependency Addition Policy
201+
202+
Adding a **new** dependency (not an upgrade) follows stricter rules than updating an existing one:
203+
204+
1. **Necessity check.** Can the need be met with an existing dependency or standard library? If yes, prefer that.
205+
2. **Maintenance health.** Check:
206+
- Last release date (reject if >18 months with no activity, unless intentionally stable)
207+
- Number of maintainers (flag if single-maintainer)
208+
- Open critical CVEs
209+
3. **Pinned version.** New dependencies must use an exact version in the manifest (no `^` or `~` ranges for production deps in contracts and backend). Frontend may use `^` for minor ranges on non-security-sensitive packages.
210+
4. **License compatibility.** Confirm the license is compatible with YieldVault's distribution terms. Flag any GPL/AGPL-licensed package for legal review before adding.
211+
5. **Tree-shaking and bundle size.** For frontend additions, check the bundle size impact. Packages adding >20 KB gzipped to the main bundle require explicit justification.
212+
6. **Review requirement.** New dependency additions require one additional reviewer beyond the standard code owner, regardless of surface.
213+
214+
---
215+
216+
## 9. Exceptions and Waivers
217+
218+
Any deviation from this policy requires:
219+
220+
1. A written rationale in the PR description or a linked issue.
221+
2. Explicit approval from the relevant surface owner and one core maintainer.
222+
3. A follow-up issue filed to resolve the exception (with a due date).
223+
224+
Repeated exceptions for the same dependency or surface should trigger a policy review.
225+
226+
---
227+
228+
## 10. Policy Ownership and Review
229+
230+
| Role | Responsibility |
231+
|------|---------------|
232+
| `@YieldVault-RWA/core-maintainers` | Policy owner; approve material changes to this document |
233+
| `@YieldVault-RWA/security-team` | CVE criteria and high-risk library list |
234+
| `@YieldVault-RWA/contracts-maintainers` | Cargo/Soroban-specific rules |
235+
| `@YieldVault-RWA/devops-maintainers` | Dependabot config and CI gate enforcement |
236+
237+
This policy is reviewed **quarterly** alongside the dependency review metrics (see §8 of [Dependency Review Process](./DEPENDENCY_REVIEW_PROCESS.md)).
238+
239+
---
240+
241+
**Last updated:** 2026-08-25
242+
**Issue:** [#1151](https://github.com/Junirezz/YieldVault-RWA/issues/1151)

0 commit comments

Comments
 (0)