# RealEstateFraction NFT A blockchain-based platform for tokenized fractional real estate ownership with automated revenue distribution. ## 🏗️ Overview This project enables investors to purchase fractional ownership of real estate properties through NFTs. Each NFT represents a specific fraction of property ownership and automatically receives proportional rental income through smart contracts. ## ✨ Features - **Fractional Ownership**: Properties are divided into tradeable NFT fractions - **Legal SPV Structure**: Each property is held by a Special Purpose Vehicle (SPV) - **Automated Revenue Distribution**: Smart contracts automatically distribute rental income - **Monthly Rental Payouts**: Automated monthly distributions to NFT holders - **Transparent**: All transactions recorded on blockchain - **Tradeable**: NFT fractions can be bought/sold on secondary markets ## 🏛️ Legal Structure ``` Property → SPV (Legal Entity) → Smart Contract → NFT Fractions → Investors ``` ⚠️ **Important**: This system must comply with local securities laws, real estate regulations, and KYC/AML requirements. Consult legal counsel before deployment. ## 🔧 Technical Stack - **Smart Contracts**: Solidity 0.8.20 - **Framework**: Hardhat - **Standards**: ERC-721 (NFT), OpenZeppelin - **Frontend**: React.js - **Network**: Ethereum (compatible with L2s) ## 📦 Installation ```bash npm install ``` ## 🚀 Quick Start 1. Copy environment variables: ```bash cp .env.example .env ``` 2. Edit `.env` with your configuration 3. Compile contracts: ```bash npm run compile ``` 4. Run tests: ```bash npm test ``` 5. Deploy locally: ```bash npm run node # Terminal 1 npm run deploy:localhost # Terminal 2 ``` ## 📝 Smart Contracts ### RealEstateFractionNFT.sol Main NFT contract representing fractional property ownership. ### RevenueDistributor.sol Handles automatic distribution of rental income to NFT holders. ### RentalPayoutAutomation.sol Automates monthly rental payments using Chainlink Keepers or similar. ## 🔐 Security Considerations - Owner/admin controls for property management - Pausable functionality for emergencies - Reentrancy guards - Access control for sensitive functions - Regular security audits recommended ## 📊 Usage Flow 1. **Property Acquisition**: SPV acquires property 2. **Tokenization**: Property fractionalized into NFTs 3. **Sale**: Investors purchase NFT fractions 4. **Revenue**: Rental income deposited to contract 5. **Distribution**: Smart contract distributes to NFT holders 6. **Claim**: Investors claim their proportional share ## ⚖️ Legal Compliance ⚠️ **CRITICAL**: See [LEGAL_COMPLIANCE.md](./LEGAL_COMPLIANCE.md) for comprehensive legal guidance. **Must address:** - Securities regulations (SEC, MiFID, etc.) - Real estate laws - SPV formation and operating agreement - KYC/AML requirements - Tax obligations and reporting - Investor accreditation verification - Property disclosure requirements - Ongoing compliance and reporting **Consult qualified legal counsel before deployment.** ## 🧪 Testing Run comprehensive test suite: ```bash npm test ``` Test coverage includes: - NFT minting and transfers - Revenue distribution calculations - Automated payout execution - Access controls and security - Integration tests ## 📡 Deployment ### Testnet Deployment ```bash npm run deploy:testnet ``` ### Mainnet Deployment ⚠️ Only after: 1. Complete security audit 2. Legal compliance verification 3. Thorough testing 4. Insurance obtained ```bash npm run deploy:mainnet ``` ## 🎯 Post-Deployment 1. Verify contracts on Etherscan 2. Add KYC verified addresses 3. Setup property management 4. Configure Chainlink Automation 5. Deploy frontend 6. Begin marketing (compliance permitting) ## 👥 Roles & Permissions - **Admin**: Contract deployment, configuration - **Minter**: NFT minting authority - **Property Manager**: Rental payment deposits - **KYC Provider**: Investor verification - **Investors**: NFT holders with revenue rights ## 💰 Fee Structure - Admin Fee: 2.5% of revenue (configurable) - Property Management: As per agreement - Blockchain Gas Fees: Paid by transaction initiator ## 🔗 Contract Interactions ### For Investors 1. **Purchase Fraction**: ```javascript await nftContract.purchaseFraction(metadataURI, { value: fractionPrice }); ``` 2. **Claim Revenue**: ```javascript await distributorContract.claimAllUnclaimed(); ``` 3. **Check Ownership**: ```javascript const balance = await nftContract.balanceOf(address); const percentage = await nftContract.ownershipPercentage(address); ``` ### For Property Manager 1. **Deposit Rental Income**: ```javascript await automationContract.receiveRentalIncome( "January 2026 Rent", { value: rentalAmount } ); ``` 2. **Execute Payout**: ```javascript await automationContract.executeImmediatePayout( "Monthly Distribution" ); ``` ## 🎨 Frontend ### Installation ```bash cd frontend npm install ``` ### Configuration Update `frontend/src/App.js` with deployed contract addresses: ```javascript const CONTRACTS = { nft: '0x...', // Your deployed NFT address distributor: '0x...', // Your deployed Distributor address automation: '0x...' // Your deployed Automation address }; ``` ### Run ```bash npm start ``` Frontend will be available at http://localhost:3000 ## 🛠️ Scripts - `npm run compile` - Compile smart contracts - `npm test` - Run test suite - `npm run node` - Start local Hardhat node - `npm run deploy:localhost` - Deploy to local network - `npm run deploy:testnet` - Deploy to Sepolia testnet - `cd frontend && npm start` - Start frontend dev server ## 📁 Project Structure ``` . ├── contracts/ # Solidity smart contracts │ ├── RealEstateFractionNFT.sol │ ├── RevenueDistributor.sol │ └── RentalPayoutAutomation.sol ├── scripts/ # Deployment and interaction scripts │ ├── deploy.js │ └── interact.js ├── test/ # Comprehensive test suite │ └── RealEstateFractionNFT.test.js ├── frontend/ # React frontend application │ ├── src/ │ │ ├── App.js │ │ ├── App.css │ │ └── index.js │ └── public/ ├── hardhat.config.js # Hardhat configuration ├── package.json ├── .env.example # Environment variables template ├── LEGAL_COMPLIANCE.md # Comprehensive legal guide └── README.md ``` ## ⚡ Automation Options ### Chainlink Keepers Recommended for production: 1. Register upkeep at https://automation.chain.link 2. Fund with LINK tokens 3. Contract automatically calls `performUpkeep()` ### Manual Execution Property manager can manually trigger payouts: ```bash node scripts/interact.js ``` ## 🔐 Security Best Practices 1. **Smart Contracts**: - Professional audit required - Use latest OpenZeppelin standards - Implement emergency pause - Multi-sig for admin functions 2. **Key Management**: - Hardware wallet for production - Never commit private keys - Use environment variables - Multi-signature wallets 3. **Frontend**: - Input validation - Secure wallet integration - HTTPS only - Regular dependency updates ## 🐛 Known Limitations - No automated secondary market - Manual KYC verification required - Gas fees can be significant during high network usage - Limited to EVM-compatible chains - Requires off-chain legal agreements ## 🚀 Future Enhancements - [ ] DAO governance for major decisions - [ ] Secondary marketplace integration - [ ] Mobile app - [ ] Multi-property portfolio support - [ ] Yield optimization strategies - [ ] Insurance protocol integration - [ ] Layer 2 deployment for lower fees - [ ] Cross-chain bridge support ## 🤝 Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass 5. Submit a pull request ## 📄 License MIT License - see LICENSE file for details ## ⚠️ Disclaimer This software is provided "as is" without warranty. The developers assume no liability for use of this code. Users must ensure compliance with all applicable laws and regulations. **Consult legal counsel before deployment.** ## 📞 Support For technical issues, please open an issue on GitHub. For legal/compliance questions, consult qualified counsel. ## 🙏 Acknowledgments - OpenZeppelin for secure contract libraries - Hardhat for development framework - React for frontend framework - Ethers.js for blockchain interaction --- **Built with ❤️ for the future of real estate investing** *Last Updated: February 2026* ## 🧪 Testing ```bash npm test ``` ## 🌐 Deployment ### Testnet ```bash npm run deploy:testnet ``` ### Mainnet (Use with caution) ```bash npm run deploy:mainnet ``` ## 📄 License MIT License - See LICENSE file for details ## ⚠️ Disclaimer This is a template/example project. You MUST: - Consult legal counsel - Obtain necessary licenses - Comply with local regulations - Implement proper KYC/AML - Consider tax implications - Get security audits NOT FINANCIAL OR LEGAL ADVICE. # RealEstateFraction-NFT