Smart Contracts#

State Diagram#

    [Create Lottery]
           │
           ▼
    ┌─────────────┐
    │   ACTIVE    │
    │ (Can buy    │
    │ WonkaBars)  │
    └─────────────┘
           │
           ├─── Repay Loan ────► [CANCELLED] ──► Refund + ChocoChips
           │
           └─── Time Expires ──► [CONCLUDED] ──► Random Winner + ChocoChips

🎮 Lottery States Explained#

📋 Use Cases Overview#

🏦 BORROWER                    🎯 LENDER                    🤖 ORACLE
     │                            │                            │
     ├─ Create Lottery            ├─ Buy WonkaBars            ├─ Draw Winner
     └─ Repay Loan               └─ Melt WonkaBars           └─ (Automation)

🔄 Detailed Workflows#

sequenceDiagram
    participant B as Borrower
    participant M as MeltyFiNFT
    participant N as NFT Contract
    
    B->>N: approve(MeltyFiNFT, tokenId)
    B->>M: createLottery(nftContract, tokenId, price, expiry, maxSupply)
    M->>N: transferFrom(borrower, MeltyFiNFT, tokenId)
    M->>M: mint WonkaBars for lottery
    M-->>B: Lottery created ✅

sequenceDiagram
    participant L as Lender
    participant M as MeltyFiNFT
    participant B as Borrower
    participant D as DAO
    
    L->>M: buyWonkaBars(lotteryId, quantity) + ETH
    M->>M: mint WonkaBars to lender
    M->>B: transfer 95% of payment
    M->>D: transfer 5% fee
    M-->>L: WonkaBars received 🎫

sequenceDiagram
    participant B as Borrower
    participant M as MeltyFiNFT
    participant C as ChocoChip
    
    B->>M: repayLoan(lotteryId)
    M->>M: set lottery state to CANCELLED
    M->>M: transfer NFT back to borrower
    M->>C: mint ChocoChips to borrower
    M-->>B: Loan repaid, NFT returned 🎉

sequenceDiagram
    participant L as Lender
    participant M as MeltyFiNFT
    participant C as ChocoChip
    
    alt Lottery CANCELLED
        L->>M: meltWonkaBars(lotteryId, quantity)
        M->>L: refund ETH investment
        M->>C: mint ChocoChips to lender
        M-->>L: Refund + rewards received 💰
    else Lottery CONCLUDED (Winner)
        L->>M: meltWonkaBars(lotteryId, quantity)
        M->>L: transfer NFT prize
        M->>C: mint ChocoChips to lender
        M-->>L: NFT + rewards received 🏆
    else Lottery CONCLUDED (Non-winner)
        L->>M: meltWonkaBars(lotteryId, quantity)
        M->>C: mint ChocoChips to lender
        M-->>L: ChocoChips received 🍪
    end

sequenceDiagram
    participant O as Oracle
    participant M as MeltyFiNFT
    participant V as VRF Consumer
    
    O->>M: checkUpkeep() [expired lotteries?]
    M-->>O: performData [lottery IDs to conclude]
    O->>M: performUpkeep(performData)
    M->>V: requestRandomWords()
    V-->>M: fulfillRandomWords(requestId, randomWords)
    M->>M: select winner based on random number
    M->>M: set lottery state to CONCLUDED
    M-->>O: Winners drawn for expired lotteries 🎲

📈 Scenario 1: Successful Repayment#

1. Borrower creates lottery with valuable NFT
2. Multiple lenders buy WonkaBars, funding the loan
3. Borrower receives 95% of funds immediately
4. Before expiration, borrower repays the loan
5. Results:
   • ✅ Borrower gets NFT back + ChocoChips
   • ✅ Lenders get full refund + ChocoChips
   • ✅ Everyone wins!

📉 Scenario 2: Loan Default#

1. Borrower creates lottery but cannot repay
2. Lottery expires and transitions to CONCLUDED
3. Chainlink VRF randomly selects winner
4. Results:
   • 🏆 One lucky lender wins the NFT + ChocoChips
   • 🍪 Other lenders receive ChocoChips as consolation
   • 💔 Borrower loses NFT but keeps the borrowed funds

🎨 User Interface#

Built with modern React ecosystem for optimal user experience:

• React 18 - Component-based UI framework
• React-Bootstrap - Responsive design components
• Ethers.js - Ethereum blockchain interaction
• thirdweb - Web3 authentication and wallet connection
• MetaMask - Primary wallet integration
• OpenSea API - NFT metadata retrieval

📱 Pages & Features#

Prerequisites#

# Required software
- Node.js (v16 or higher)
- MetaMask browser extension
- Git

# Required tokens  
- Goerli testnet ETH (from faucet)
- LINK tokens (for oracle funding)

🔧 Backend Setup#

# Clone the repository
git clone https://github.com/VincenzoImp/MeltyFi.NFT
cd MeltyFi.NFT/src/back-end/MeltyFiProtocol

# Install dependencies
npm install

# Environment configuration
cp .env.example .env
# Add your keys:
# ALCHEMY_API_KEY=your_alchemy_key
# GOERLI_PRIVATE_KEY=your_private_key  
# ETHERSCAN_API_KEY=your_etherscan_key

# Compile smart contracts
npx hardhat compile

# Run comprehensive test suite
npx hardhat test

# Deploy to Goerli (if needed)
npx hardhat run scripts/deploy.js --network goerli

# Verify contracts on Etherscan
npx hardhat verify --network goerli CONTRACT_ADDRESS

🎨 Frontend Setup#

# Navigate to frontend directory
cd src/front-end/meltyfi.nft

# Install React dependencies
npm install

# Start development server
npm start

# Build for production
npm run build

The application will be available at http://localhost:3000

🔍 Reading Contract State#

// Get lottery information
function getLotteryInfo(uint256 lotteryId) 
    external view returns (Lottery memory);

// Check WonkaBar balance
function balanceOf(address account, uint256 lotteryId) 
    external view returns (uint256);

// Get ChocoChip balance
function balanceOf(address account) 
    external view returns (uint256);

// Check if address won lottery
function isWinner(address account, uint256 lotteryId) 
    external view returns (bool);

✍️ Writing Contract State#

// Create new lottery
function createLottery(
    IERC721 _prizeContract,
    uint256 _prizeTokenId, 
    uint256 _wonkaBarPrice,
    uint256 _expirationDate,
    uint256 _wonkaBarsMaxSupply
) external;

// Purchase lottery tickets
function buyWonkaBars(uint256 _lotteryId, uint256 _amount) 
    external payable;

// Repay loan and cancel lottery  
function repayLoan(uint256 _lotteryId) external;

// Claim rewards and prizes
function meltWonkaBars(uint256 _lotteryId, uint256 _amount) 
    external;

// Manually trigger winner selection
function drawWinner(uint256 _lotteryId) external;

🛡️ Smart Contract Security#

• OpenZeppelin Standards: Battle-tested contract implementations
• Reentrancy Guards: Protection against common attack vectors
• Access Control: Role-based permissions and ownership
• Input Validation: Comprehensive parameter checking
• Emergency Controls: Circuit breakers for critical functions

🔒 Oracle Security#

• Chainlink VRF: Provably random and tamper-proof randomness
• Direct Funding: Anyone can fund oracles to ensure availability
• Fallback Mechanisms: Manual winner drawing if automation fails
• No External Dependencies: Floor price independence eliminates oracle manipulation

🚨 Protocol Safety#

• No Liquidation Risk: Borrowers cannot lose NFTs unexpectedly
• Fair Distribution: Proportional lottery chances based on investment
• Transparent Operations: All actions recorded on-chain
• Automated Processes: Reduced human error through smart contracts

📍 Contract Addresses (Goerli Testnet)#

🚀 Live Applications#

• MeltyFi.NFT DApp: https://meltyfi.nft
• MeltyFi.DAO DApp: https://meltyfi.dao (Coming Soon)

📝 Example Transactions#

• Create Lottery: 0xe68f3f6...
• Melt WonkaBars: 0xd957d27...

🐌 Protocol Limitations#

• Slow Funding: Loans require multiple lenders to participate
• Uncertainty: Three possible outcomes create complexity for lenders
• Gas Costs: Complex lottery mechanics increase transaction costs
• Testnet Only: Currently deployed on Goerli for testing

🔧 Technical Limitations#

• Oracle Dependency: Relies on Chainlink for automation and randomness
• Frontend Gaps: DAO interface not yet implemented
• Scalability: May face congestion on mainnet deployment

🎯 Phase 1: Production Ready#

• ✅ Mainnet deployment with audited contracts
• ✅ Layer 2 integration (Polygon, Arbitrum, Optimism)
• ✅ Enhanced security audits and bug bounties
• ✅ Mobile-responsive interface improvements

🎯 Phase 2: Advanced Features#

• 🔄 Dutch auction lottery mechanisms
• 🎯 Multi-NFT collateral lotteries
• 💎 Fractional NFT support
• 🏪 NFT marketplace integration

🎯 Phase 3: Ecosystem Expansion#

• 📱 Native mobile application
• 🌉 Cross-chain bridge functionality
• 🏛️ Fully functional DAO governance
• 🎮 Gamification enhancements

🔧 Development Guidelines#

1. Fork the repository and create a feature branch
2. Follow existing code style and conventions
3. Add comprehensive tests for new functionality
4. Update documentation as needed
5. Test thoroughly on Goerli testnet

📋 Contribution Areas#

• 🐛 Bug fixes and security improvements
• ✨ New features and enhancements
• 📚 Documentation and tutorials
• 🎨 UI/UX improvements
• 🧪 Testing and quality assurance

🌐 Project Resources#

• GitHub Repository: VincenzoImp/MeltyFi.NFT
• Live Application: meltyfi.nft
• Documentation: Available in repository /docs directory

🔧 Development Tools#

• Goerli Faucet: goerlifaucet.com
• OpenSea Testnet: testnets.opensea.io
• Remix IDE: remix.ethereum.org

📚 Educational Resources#

• Ethereum Documentation: ethereum.org
• OpenZeppelin Contracts: openzeppelin.com
• Chainlink Documentation: docs.chain.link

MeltyFi Protocol - Where Charlie’s chocolate factory meets DeFi innovation! 🍫✨

Making illiquid NFTs liquid through the magic of lottery mechanics and community-driven finance.