diff --git a/contracts/price-oracle/src/storage.md b/contracts/price-oracle/src/storage.md
new file mode 100644
index 0000000..531917e
--- /dev/null
+++ b/contracts/price-oracle/src/storage.md
@@ -0,0 +1,91 @@
+# 🦀 StellarFlow-Contracts
+*The High-Fidelity Oracle for African Corridors on Soroban.*
+
+StellarFlow is a decentralized data oracle built on the Stellar Network. It provides real-time, verified exchange rates for African currencies (NGN, KES, GHS) to the Soroban ecosystem, enabling the next generation of localized DeFi, cross-border payments, and yield protocols.
+
+# 🏛️ Architecture Overview
+The contract acts as a secure, authorized ledger for price data. It is designed to be:
+
+Authorized: Only whitelisted providers (Relayers) can update prices.
+
+Immutable: All updates are time-stamped and emitted as events for transparency.
+
+Interoperable: Designed to be called by other Soroban smart contracts (C2C).
+
+# 🚀 Getting Started
+Prerequisites
+> Rust
+
+Soroban CLI
+> Target: wasm32-unknown-unknown
+
+### Installation
+
+**Clone the repository:**
+
+```Bash
+git clone https://github.com/SFN/stellarflow-contracts.git
+cd stellarflow-contracts
+```
+
+**Build the contract:**
+
+```Bash
+soroban contract build 
+```
+📂 Project Structure
+
+├── src/
+
+|            ├── lib.rs          # Main contract entry point and public interface
+
+│            ├── types.rs        # Custom structs (PriceData) and Enums (DataKey)
+
+│            ├── storage.rs      # Persistent and Instance storage logic
+
+│            ├── auth.rs         # require_auth and Admin-check functions
+
+│            └── test.rs         # Comprehensive unit and integration tests
+
+├── Cargo.toml          # Project dependencies (soroban-sdk)
+
+└── README.md
+
+
+
+# 🛠️ Public Interface (API)
+**Admin Functions**
+> initialize(admin: Address): Sets the global contract administrator.
+
+> add_provider(provider: Address): Whitelists a backend relayer to push data.
+
+> rescue_tokens(token: Address, to: Address, amount: i128): Admin-only function to recover trapped assets from the contract.
+
+**Data Submission (Authorized)**
+update_price(source: Address, asset: Symbol, price: i128): Updates the price for a specific asset. Requires source authorization.
+
+**Data Retrieval (Public)**
+> get_price(asset: Symbol) -> PriceData: Returns the latest price, timestamp, and provider info.
+
+> get_all_assets() -> Vec<Symbol>: Returns a list of all currently tracked currency pairs.
+
+# 🧪 Testing Policy
+
+***We maintain a "No Test, No Merge" policy.***
+
+All Pull Requests (PRs) must include a updated test.rs file. To run the test suite:
+
+```Bash
+cargo test
+```
+
+**Tests must verify:**
+
+> Success Paths: Correct data storage and retrieval.
+
+> Security Paths: Rejection of unauthorized update_price calls.
+
+> Edge Cases: Handling of missing assets or zero-value inputs.
+
+# 📜 License
+This project is licensed under the MIT License - see the LICENSE file for details.