Skip to content

Pritam-mb/celo-hackathon

BranchesTags

Repository files navigation

🌍 GeoLand NFT Platform

Democratizing Real Estate Through Blockchain Technology

Celo React TypeScript Solidity Hardhat

A tokenized real-estate marketplace for Kolkata powered by the Celo blockchain, making property ownership accessible, transparent, and tradeable.

Live Demo • Documentation • Video Walkthrough

📋 Table of Contents

🎯 Overview

GeoLand is a revolutionary NFT-based real estate platform built on the Celo blockchain that transforms how people invest in property. By tokenizing real estate in Kolkata's neighborhoods, we enable fractional ownership, transparent transactions, and growth-linked rewards through our innovative Area Growth Token (AGT) system.

Why Celo?

We chose Celo for its:

  • 🌱 Carbon-negative blockchain infrastructure
  • 💰 Low transaction fees making micro-transactions viable
  • 📱 Mobile-first approach aligning with our accessibility goals
  • 🌍 Social impact mission supporting financial inclusion
  • ⚡ Fast finality enabling smooth user experiences

🔍 The Problem

Traditional real estate investment faces critical barriers:

  • High Entry Costs: Property investment requires significant capital
  • Illiquidity: Selling real estate is slow and expensive
  • Geographic Limitations: Investors limited to local markets
  • Lack of Transparency: Opaque pricing and ownership records
  • Complex Processes: Legal paperwork and intermediaries add friction

💡 Our Solution

GeoLand leverages blockchain technology to:

  1. Fractional Ownership: Own portions of properties as NFTs starting from minimal investment
  2. Instant Liquidity: Trade property NFTs on secondary markets anytime
  3. Global Access: Invest in Kolkata real estate from anywhere in the world
  4. Transparent Records: Immutable on-chain ownership and transaction history
  5. Automated Rewards: Earn AGT tokens based on neighborhood development metrics
  6. Simple UX: MetaMask integration with intuitive map-based browsing

🚀 Key Features

🗺️ Interactive Map Marketplace

  • Browse 20+ Kolkata neighborhoods with OpenStreetMap integration
  • Real-time price display in CELO cryptocurrency
  • Visual property boundaries and development indicators
  • Filter by price range, location, and growth potential

💳 Seamless Payment Gateway

  • End-to-end purchase flow with MetaMask integration
  • Automatic NFT minting upon successful transaction
  • AGT reward distribution based on property value
  • On-chain ownership record with transaction receipts

🎨 Modern Responsive Interface

  • Built with React 18 and TypeScript for type safety
  • TailwindCSS with brutalist UI design principles
  • Mobile-responsive across all screen sizes
  • Optimistic UI updates for better perceived performance

📊 Portfolio Management

  • View all owned property NFTs in one dashboard
  • Track AGT token balance and rewards history
  • Monitor property value appreciation
  • Export transaction history

🔐 Secure Oracle Integration

  • Node.js/Express backend with MongoDB storage
  • JWT-based authentication system
  • Real-time property valuation feeds
  • Development event tracking for AGT calculations

🔄 Multi-Network Support

  • Celo Alfajores testnet integration
  • Celo Sepolia support for testing
  • Automatic network switching prompts
  • Real-time balance synchronization

🛠️ Technology Stack

Blockchain Layer

Celo Solidity Hardhat OpenZeppelin

Frontend

React TypeScript TailwindCSS Ethers.js

Backend & Infrastructure

Node.js Express MongoDB JWT

DevOps & Deployment

Vercel GitHub Actions MetaMask

Smart Contract Addresses

Smart Contracts: Deployed on Celo Sepolia Testnet

NFT: 0x4135a9cd9c1ce07f4f54c0e45503186ed14f9356 AGT: 0x6b122cf6cf7eaab566276c8699c468c3ca7b02ef Oracle: 0x2961474521ff01a9ea8f99d62d4365e518c3672a Frontend: Ready for Vercel deployment

Environment: Celo Sepolia RPC (Ankr) Chain ID: 11142220 Backend: Ready for Railway/Render/Fly.io

CORS configured for frontend origin

Mapping & APIs

OpenStreetMap Leaflet

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND LAYER                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ React Pages  │  │  Components  │  │   Services   │         │
│  │  - Explore   │  │  - Map View  │  │  - Contract  │         │
│  │  - Market    │  │  - Auth      │  │  - API       │         │
│  │  - Payment   │  │  - Cards     │  │  - Wallet    │         │
│  │  - Portfolio │  │  - Modals    │  │              │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ HTTPS / WebSocket
                              │
┌─────────────────────────────┴───────────────────────────────────┐
│                      ORACLE SERVICE LAYER                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Express API │  │  Auth (JWT)  │  │   MongoDB    │         │
│  │  - REST      │  │  - Middleware│  │  - Users     │         │
│  │  - Endpoints │  │  - Sessions  │  │  - Valuations│         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ JSON-RPC (ethers.js)
                              │
┌─────────────────────────────┴───────────────────────────────────┐
│                      BLOCKCHAIN LAYER (Celo)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ GeoLandNFT   │  │AreaGrowthTkn │  │OracleRegistry│         │
│  │ - ERC-721    │  │ - ERC-20     │  │ - Valuations │         │
│  │ - Minting    │  │ - Rewards    │  │ - Events     │         │
│  │ - Transfers  │  │ - Staking    │  │ - Access Ctl │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘

Data Flow

  1. User Authentication: JWT tokens issued by Oracle Service
  2. Property Discovery: Frontend fetches listings from Oracle, displays on map
  3. Purchase Initiation: User selects property, MetaMask prompts for signature
  4. Smart Contract Execution: purchaseLand() mints NFT, distributes AGT
  5. Oracle Update: Backend monitors events, updates database
  6. Portfolio Sync: Frontend queries blockchain for user's NFTs

📜 Smart Contracts

GeoLandNFT.sol

ERC-721 compliant NFT contract for property ownership

Key Functions:

  • purchaseLand(area, price) - Mint NFT and transfer AGT rewards
  • tokenURI(tokenId) - Return metadata for property
  • transferFrom() - Standard ERC-721 transfer with royalties

Security Features:

  • Reentrancy guards on all state-changing functions
  • Rate limiting (30s cooldown between purchases)
  • Owner-only administrative functions
  • Pausable for emergency stops

AreaGrowthToken.sol

ERC-20 reward token tied to neighborhood development

Key Functions:

  • mint(address, amount) - Oracle-triggered reward distribution
  • stake(amount) - Lock tokens for boosted rewards
  • calculateRewards(area) - Real-time APY based on development metrics

Tokenomics:

  • 1M AGT total supply (capped)
  • 10% reward on every property purchase
  • Variable APY (5-25%) based on neighborhood growth

OracleRegistry.sol

Decentralized oracle for off-chain data feeds

Key Functions:

  • updateValuation(area, price) - Submit property valuation
  • recordEvent(area, eventType) - Log development events
  • getLatestPrice(area) - Query current market price

Access Control:

  • Multi-sig authorization for oracle updates
  • Reputation system for data providers
  • Slashing mechanism for bad actors

🚀 Getting Started

Prerequisites

Ensure you have the following installed:

  • Node.js (v18 or higher) - Download
  • npm or Yarn package manager
  • MetaMask browser extension - Install
  • MongoDB (local or Atlas) - Setup Guide
  • Git for version control

Environment Setup

1. Clone the Repository

git clone https://github.com/yourusername/geoland-nft-platform.git
cd geoland-nft-platform

2. Install Dependencies

# Install root dependencies (Hardhat & contracts)
npm install

# Install frontend dependencies
cd frontend
npm install

# Install oracle service dependencies
cd ../oracle-service
npm install

3. Configure Environment Variables

Create .env files in the following locations:

Root .env (for contract deployment)

PRIVATE_KEY=your_wallet_private_key_without_0x_prefix
CELO_SEPOLIA_RPC=https://forno.celo-sepolia.celo-testnet.org
ALFAJORES_RPC=https://alfajores-forno.celo-testnet.org
CELOSCAN_API_KEY=your_celoscan_api_key_optional

frontend/.env

REACT_APP_API_URL=http://localhost:3001/api/v1
REACT_APP_CHAIN_ID=44787
REACT_APP_RPC_URL=https://alfajores-forno.celo-testnet.org
REACT_APP_NFT_ADDRESS=0xYourDeployedGeoLandNFTAddress
REACT_APP_AGT_ADDRESS=0xYourDeployedAreaGrowthTokenAddress
REACT_APP_ORACLE_ADDRESS=0xYourDeployedOracleRegistryAddress

oracle-service/.env

PORT=3001
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/geoland-oracle
JWT_SECRET=your_secure_random_string_min_32_chars
JWT_EXPIRY=7d
CELO_SEPOLIA_RPC=https://forno.celo-sepolia.celo-testnet.org
PRIVATE_KEY=your_wallet_private_key_without_0x_prefix
CORS_ORIGIN=http://localhost:3000

Local Development

1. Start MongoDB

# If using local MongoDB
mongod --dbpath /path/to/your/data/directory

# Or use MongoDB Atlas (cloud) - update MONGODB_URI accordingly

2. Compile Smart Contracts

# From root directory
npx hardhat compile

3. Deploy Contracts to Local Network (Optional)

# Terminal 1 - Start local Hardhat node
npx hardhat node

# Terminal 2 - Deploy contracts
npx hardhat run scripts/deploy.js --network localhost

4. Start Oracle Service

# Terminal 3 (or 2 if using testnet)
cd oracle-service
npm run dev

5. Start Frontend Development Server

# Terminal 4 (or 3 if using testnet)
cd frontend
npm start

6. Access the Application

Open your browser and navigate to:

http://localhost:3000

Get Test Funds

Visit the Celo Alfajores faucet to get test CELO tokens:

🌐 Deployment

Smart Contract Deployment

Deploy to Celo Alfajores Testnet

npx hardhat run scripts/deploy.js --network celoAlfajores

Important: Save the deployed contract addresses displayed in the console:

✅ GeoLandNFT deployed to:

https://sepolia.celoscan.io/address/0x4135a9cd9c1ce07f4f54c0e45503186ed14f9356

✅ AreaGrowthToken deployed to:

https://sepolia.celoscan.io/address/0x6b122cf6cf7eaab566276c8699c468c3ca7b02ef

✅ OracleRegistry deployed to:

https://sepolia.celoscan.io/address/0x2961474521ff01a9ea8f99d62d4365e518c3672a

Update these addresses in:

  • frontend/.env → REACT_APP_*_ADDRESS variables
  • oracle-service/.env → Contract interaction configurations

Verify Contracts (Optional but Recommended)

npx hardhat verify --network celoAlfajores DEPLOYED_CONTRACT_ADDRESS "Constructor" "Arguments"

Frontend Deployment (Vercel)

Option 1: Vercel CLI

# Install Vercel CLI
npm i -g vercel

# Deploy from frontend directory
cd frontend
vercel

# Production deployment
vercel --prod

Option 2: GitHub Integration

  1. Push code to GitHub
  2. Import repository in Vercel Dashboard
  3. Configure environment variables in Vercel project settings
  4. Deploy automatically on every push to main

Vercel Environment Variables:

REACT_APP_API_URL=https://your-oracle-service.railway.app/api/v1
REACT_APP_CHAIN_ID=44787
REACT_APP_RPC_URL=https://alfajores-forno.celo-testnet.org
REACT_APP_NFT_ADDRESS=0xYourDeployedAddress
REACT_APP_AGT_ADDRESS=0xYourDeployedAddress
REACT_APP_ORACLE_ADDRESS=0xYourDeployedAddress

Oracle Service Deployment (Railway/Render)

Using Railway

# Install Railway CLI
npm i -g @railway/cli

# Login and initialize
railway login
railway init

# Deploy
railway up

Using Render

  1. Create new Web Service on Render Dashboard
  2. Connect your GitHub repository
  3. Configure build command: cd oracle-service && npm install
  4. Configure start command: cd oracle-service && npm start
  5. Add environment variables from oracle-service/.env
  6. Deploy

Important: Update CORS_ORIGIN in oracle service to match your Vercel domain:

CORS_ORIGIN=https://your-app.vercel.app

🧪 Testing

Unit Tests

# Test smart contracts
npx hardhat test

# Test with gas reporting
REPORT_GAS=true npx hardhat test

# Test specific file
npx hardhat test test/GeoLandNFT.test.js

Integration Tests

# Frontend tests
cd frontend
npm test

# Oracle service tests
cd oracle-service
npm test

Test Coverage

npx hardhat coverage

Manual Testing Checklist

  • MetaMask connection and network switching
  • Property browsing and filtering on map
  • Purchase flow end-to-end
  • NFT minting and ownership verification
  • AGT token reward distribution
  • Portfolio page displays owned NFTs
  • Oracle service updates valuations
  • Rate limiting prevents spam transactions

🔧 Troubleshooting

Common Issues

Transaction Reverted / Failed

  • ✅ Ensure contract is deployed and address updated in .env
  • ✅ Check you have sufficient CELO balance for gas + purchase
  • ✅ Verify 30-second cooldown period has passed since last purchase
  • ✅ Confirm MetaMask is connected to correct network

MetaMask Network Issues

  • ✅ Add Celo Alfajores manually:
    • Network Name: Celo Alfajores Testnet
    • RPC URL: https://alfajores-forno.celo-testnet.org
    • Chain ID: 44787
    • Currency Symbol: CELO
    • Block Explorer: https://alfajores.celoscan.io

Oracle Service Connection Failed

  • ✅ Verify MongoDB is running and accessible
  • ✅ Check MONGODB_URI in oracle-service/.env
  • ✅ Ensure CORS_ORIGIN matches frontend URL
  • ✅ Confirm port 3001 is not in use by another service

Frontend Build Errors

  • ✅ Clear cache: rm -rf node_modules package-lock.json && npm install
  • ✅ Verify all environment variables are set
  • ✅ Check Node.js version compatibility (v18+)

🗺️ Roadmap

Phase 1: MVP (Current) ✅

  • Core smart contracts on Celo
  • Interactive map marketplace
  • MetaMask integration
  • Basic oracle service
  • NFT minting and transfers

Phase 2: Enhanced Features (Q1 2025)

  • Secondary marketplace for NFT trading
  • Fractional ownership (multiple owners per property)
  • Mobile app (React Native)
  • Advanced analytics dashboard
  • Multi-language support (Bengali, Hindi)

Phase 3: Expansion (Q2 2025)

  • Expand to Mumbai, Delhi, Bangalore
  • Integration with real property registries
  • KYC/AML compliance layer
  • Fiat on-ramp partnerships
  • DAO governance for protocol upgrades

Phase 4: Ecosystem (Q3-Q4 2025)

  • Developer API for third-party integrations
  • Property management tools for owners
  • Rental yield tokenization
  • Cross-chain bridges (Ethereum, Polygon)
  • Institutional investor portal

👥 Team

**Pritam Patra, Soumyadeep Dey, Srijeet Prasad Banerjee *

GitHub LinkedIn Twitter

Special Thanks:

  • GitHub Copilot for AI-powered development assistance
  • Celo Foundation for blockchain infrastructure
  • OpenStreetMap contributors for mapping data
  • The Celo hackathon community for feedback and support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Pritam Mukherjee

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

[Full MIT License text...]

🙏 Acknowledgments

Built with ❤️ for the Celo Hackathon 2025

This project aims to democratize real estate access and contribute to Celo's mission of prosperity for all. By leveraging blockchain technology, we're creating a more inclusive financial system that empowers individuals to participate in real estate markets previously inaccessible to them.

Why This Matters

  • Financial Inclusion: 1.7 billion adults globally lack access to banking services
  • Real Estate Barriers: Traditional property investment requires $50k+ minimum
  • Transparency: Blockchain eliminates intermediaries and reduces fraud
  • Sustainability: Celo's carbon-negative blockchain aligns with ESG goals

🌟 Star us on GitHub — it helps!

GitHub stars GitHub forks

Report Bug • Request Feature • Join Discord

Made with 💚 on the Celo blockchain

About

geo-space.vercel.app

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages