Restructure docs and update core contract

Author: HananeBendisari

README.md

@@ -6,7 +6,7 @@
 
 ### A Housing Blockchain Solution for Social Good
 
-**OpenEscrow** is a free, open source app for transparent and fair management of the rental security deposit, that builds trust and unlocks financial opportunity between tenants and landlords by using smart contracts to serve as a neutral 3rd party escrow agent. 
+**OpenEscrow** is a free, open source app for transparent and fair management of the rental security deposit, that builds trust and unlocks financial opportunity between tenants and landlords by using smart contracts to serve as a neutral 3rd party escrow agent.
 
 Built as a digital public good — not for profit — OpenEscrow promotes financial inclusion, housing stability, and real-world trust without centralized control.
 
@@ -16,71 +16,35 @@ There is no company, licensing fee, or monetization model behind OpenEscrow —
 
 ## System Wireframe
 
-     [Tenant Wallet]
-            |
-     createAgreement()
-            |
-     +-------------+
-     | OpenEscrow  |---> (optional call) ---> [RulesModule]
-     |   Core      |---> (optional call) ---> [YieldModule]
-     +-------------+
-            |
-     [Factory]--- createVault() ---> [UserVaults]
-            |
-      [EscrowViewer]
-            |
-     read info/multicall
-            v
-      [Dashboard / UI]
+This flow illustrates the full life cycle of a rental deposit agreement through OpenEscrow. It reflects a more transparent and tenant-centric logic, where the deposit is considered the tenant's property by default. A notice period is required before any release process can begin, and the landlord must submit a claim that is externally validated to override the default refund. The flow also includes optional integration with a yield module (for on-chain interest) and a read-only viewer contract to power the UI.
 
----
+> 💡 **Token Choice Note:**  
+> WYST is the default payment token, but users may also choose supported stablecoins such as USDC or USDY. As long as sufficient liquidity exists on DEXs or CEXs, no dedicated pool is required. Users without a balance in their selected token will be prompted to swap before depositing.
 
-### Project Overview
-
-OpenEscrow provides:
-
-- Smart contract-based escrow management for rental deposits
-- Invoice upload requirement for each deduction
-- Automated on-chain notifications
-- Tenant dispute/approval mechanics
-- Optional yield generation through U.S. Treasury-backed stablecoins
-- One-click report generation
-- Opt-in reputation system
-- Future-dated refunds
-- Web2 interface, no wallet, transaction interaction (unless desired)
-- Fiat on/off ramps via services like Moonpay or NowPayments
-- Wallet abstraction for email/social media login support
-- Multilingual and globally accessible deployment
-- Can be deployed on any chain without need for cross-chain functionality
-- Future plans to support other types of escrow arrangements
+➡️ [View full protocol flow](docs/protocol-flow.md) — lifecycle, logic, and onchain events  
+🛠️ [View developer reference](docs/dev-reference.md) — functions, structs, and module interfaces
 
 ---
 
 ### Why OpenEscrow Matters
 
-OpenEscrow also aligns with key priorities for public goods and the public sector in general:
-- Promoting financial inclusion for underserved communities
-- Supporting tenant and landlord trust and protections
-- Reducing cost and complexity in housing dispute resolution
-- Providing transparent, trust-minimized security deposit management
+OpenEscrow redefines how rental deposits are handled by aligning with the reality that **the deposit legally belongs to the tenant** until a valid claim proves otherwise.
+
+This updated model:
 
-There is no company, profit model, or licensing fee behind OpenEscrow. It is a digital public good - free infrastructure for communities, governments, and NGOs to adopt, build on top of, or deploy as needed.
+* Promotes financial inclusion for underserved communities
+* Prevents abuse of power by landlords
+* Aligns with small claims court principles: burden of proof is on the claimant (landlord)
+* Reduces stress and legal cost for tenants
+* Provides programmable transparency through `rulesModule`
+* Makes claims auditable, reproducible, and automated
 
-Security deposit handling is a major global pain point:
-- 25%+ of tenants report disputes with landlords over deposits
-- Lack of transparency and legal fees cause housing insecurity
-- Small claims courts are flooded with deposit dispute cases
-- Many jurisdictions impose triple damages for improper withholding
+Traditional models transfer the deposit unless the tenant proves otherwise. OpenEscrow **inverts that logic** to reflect real-world fairness: if there is no valid claim, **the tenant keeps the deposit**.
+
+---
 
-These issues are generally due to:
-- Lack of transparency or controls in deductions
-- No standardized documentation
+(Le reste du README reste inchangé : Project Overview, Roadmap, Technical Stack, Tests, Features, Funding Plan, Team Bios, Contribution instructions...)
 
-By leveraging blockchain:
-- OpenEscrow creates **transparent and trust-minimized** management
-- Reduces legal costs and landlord/tenant disputes
-- Supports affordable housing programs with better financial controls
-- Demonstrates how blockchain can serve real-world needs, not speculation
 
 ---
 
@@ -191,7 +155,7 @@ We are seeking **$60,000** to build, audit, and launch a secure, fully open-sour
 
 > All core flows are tested and production-grade.
 
-**For a detailed breakdown of all smart contract objects, functions, technical flows, and developer documentation, see [technical-overview.md](./technical-overview.md).**
+**For a detailed breakdown of smart contract architecture, lifecycle logic, and developer references, see [docs/technical-overview.md](./docs/technical-overview.md) and [docs/dev-reference.md](./docs/dev-reference.md).**
 
 ---
 

ROADMAP.md

@@ -1,36 +1,46 @@
 # OpenEscrow – MVP Roadmap
 
-This roadmap tracks the key milestones for the MVP delivery in 2025.
+This roadmap tracks the key milestones for MVP delivery across 2025–2026.
 
 ---
 
 ## Phase 1: Core Smart Contracts (Q3 2025)
-- Finalize modular contract architecture
-- Integrate placeholder for yield logic (mocked)
-- Include validator hooks (optional)
+- Finalize modular contract architecture (`OpenEscrowCore`, factory, viewer)
+- Add support for:
+  - IPFS invoice validation
+  - Onchain dispute flagging
+  - Optional `rulesModule` and `yieldModule`
 - Deploy to Optimism testnet
-- Write base tests + basic documentation
+- Write unit and integration tests (Foundry)
+- Document technical overview and lifecycle logic (Mermaid)
 
 ---
 
 ## Phase 2: Web & Backend Integration (Q3–Q4 2025)
-- Build web frontend (React)
-- Connect to deployed contracts
-- Handle deposits, refunds, release logic
-- Add notifications (mock or on-chain)
+- Build minimal web frontend (React or SvelteKit)
+- Connect to deployed smart contracts
+- Implement deposit, refund, release, and yield actions
+- Add onchain/offchain notifications (event logs + UI)
+- Display agreement status via `EscrowViewer`
 
 ---
 
-## Phase 3: Feature Expansion (Q4 2025–Q1 2026)
-- Yield logic (USDC + 1 yield-bearing option)
-- Reputation module (opt-in)
-- Multilingual UX
-- Fiat ramps integration (optional)
-- Partial refund logic (per agreement, state tracked, mutual validation)
+## Phase 3: Feature Expansion (Q4 2025 – Q1 2026)
+- Yield strategy integration (e.g., USDC + yield-bearing token support)
+- Add support for multiple ERC20 tokens (e.g. WYST, USDY)
+- Enable partial refund logic (state tracked, validated per agreement)
+- Optional modules:
+  - Reputation system
+  - Wallet abstraction
+  - Fiat ramps (e.g., MoonPay)
+- UX: Multilingual interface and mobile optimization
 
 ---
 
-## Phase 4: Public Launch (Q1 2026)
-- Finalize documentation and onboarding
-- Deploy to mainnet
-- Publish open-source repo and reach out to housing partners
+## Phase 4: Public Launch & Ecosystem Outreach (Q1 2026)
+- Finalize audit & documentation (NatSpec, `CONTRIBUTING.md`)
+- Deploy mainnet version (Optimism or Base)
+- Open-source the full repo
+- Outreach to housing partners, NGOs, and legal clinics
+- Prepare for legal admissibility pilot (court-compatible proofs)
+

contracts/OpenEscrowCore.sol

@@ -101,17 +101,12 @@ contract OpenEscrowCore {
 
      // Handle yield module if defined
         if (agreement.yieldModule != address(0)) {
-            (uint256 tenantShare, uint256 landlordShare) = IYieldModule(agreement.yieldModule).claimYield(_agreementId);
+            (uint256 tenantShare, ) = IYieldModule(agreement.yieldModule).claimYield(_agreementId);
 
             if (tenantShare > 0) {
                 (bool okTenant, ) = agreement.tenant.call{value: tenantShare}("");
                 require(okTenant, "Yield transfer to tenant failed");
             }
-
-            if (landlordShare > 0) {
-                (bool okLandlord, ) = agreement.landlord.call{value: landlordShare}("");
-                require(okLandlord, "Yield transfer to landlord failed");
-            }
         }