🌊 Water Resource Management Platform

A privacy-preserving water allocation system powered by Fully Homomorphic Encryption (FHE) on Ethereum, enabling confidential resource distribution while maintaining transparent governance.

Built with Zama FHEVM - Demonstrating practical privacy-preserving applications for critical infrastructure management.

Live Demo: https://fhe-water-resource-manager.vercel.app/

Video: demo.mp4

🔐 Privacy Model

What's Private

Regional demand data - Water requirements encrypted using FHE (euint32)
Allocation amounts - Distribution quantities computed homomorphically
Priority levels - Region priority scores remain confidential
Justification scores - Request justifications processed without decryption

What's Public

Region registration - Names and manager addresses
Allocation periods - Timeframes and participation count
Transaction metadata - Timestamps and blockchain events
System state - Active/inactive status and period lifecycle

Decryption Permissions

Regional Managers: Can decrypt their own region's allocation data
Central Authority: Can decrypt aggregate totals for distribution processing
Contract: Performs homomorphic computations without seeing plaintext values

✨ Features

🔐 Confidential Water Demand - Regions submit encrypted requirements
🧮 Homomorphic Allocation - Fair distribution computed on encrypted data
⚡ Emergency Response - Priority allocation for critical situations
🏛️ Decentralized Governance - Transparent authority management
📊 Period-Based Distribution - Time-boxed allocation cycles
🔒 Access Control - Role-based permissions (Authority, Region Managers)
🎯 Priority Weighting - Encrypted priority levels influence allocation
📈 Audit Trail - Immutable blockchain records for compliance

🏗️ Architecture

Frontend/Client Layer
├── Web3 wallet integration (MetaMask)
├── FHE encryption libraries
└── Real-time status monitoring

Smart Contract Layer (Solidity)
├── Region Registration & Management
├── Allocation Period Lifecycle
├── Water Request Processing
├── Emergency Allocation System
└── Encrypted Data Storage

Zama FHEVM Layer
├── Fully Homomorphic Encryption (euint32, ebool)
├── Encrypted computation operations
├── Decryption request handling
└── Sepolia testnet deployment

Data Flow
┌─────────────────┐
│  Region Manager │
│  Submits Request│
└────────┬────────┘
         │ FHE.encrypt(demand)
         ▼
┌─────────────────┐
│  Smart Contract │
│  Stores euint32 │
└────────┬────────┘
         │ FHE operations
         ▼
┌─────────────────┐
│   Distribution  │
│   Algorithm     │
└────────┬────────┘
         │ Allocations
         ▼
┌─────────────────┐
│  Encrypted      │
│  Results        │
└─────────────────┘

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm or yarn
MetaMask wallet
Sepolia testnet ETH (faucet)

Installation

# Clone the repository
git clone <repository-url>
cd water-resource-management-platform

# Install dependencies
npm install

# Configure environment
cp .env.example .env

Environment Setup

Create a .env file with the following configuration:

# Network Configuration
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY
PRIVATE_KEY=your_private_key_here

# Contract Addresses (after deployment)
CONTRACT_ADDRESS=0x...

# Etherscan Verification
ETHERSCAN_API_KEY=your_etherscan_api_key

# Optional: Gas Reporting
REPORT_GAS=true
COINMARKETCAP_API_KEY=your_cmc_api_key

Compile Contracts

# Compile smart contracts
npm run compile

# Clean build artifacts
npm run clean

Run Tests

# Run full test suite
npm test

# Run with gas reporting
npm run test:gas

# Generate coverage report
npm run test:coverage

🔧 Technical Implementation

Core Smart Contract

File: contracts/WaterResourceManager.sol

import { FHE, euint32, ebool } from "@fhevm/solidity/lib/FHE.sol";

contract WaterResourceManager {
    struct Region {
        string name;
        euint32 waterDemand;      // Encrypted demand
        euint32 allocatedAmount;  // Encrypted allocation
        euint32 priorityLevel;    // Encrypted priority
        bool isActive;
        address manager;
    }

    // Submit encrypted water request
    function submitWaterRequest(
        uint32 _requestedAmount,
        uint32 _justificationScore
    ) external {
        euint32 encryptedRequest = FHE.asEuint32(_requestedAmount);
        euint32 encryptedJustification = FHE.asEuint32(_justificationScore);

        // Store encrypted values
        waterRequests[currentPeriod][regionId] = WaterRequest({
            requestedAmount: encryptedRequest,
            justificationScore: encryptedJustification,
            timestamp: block.timestamp
        });
    }
}

FHE Operations

Encrypted Data Types:

euint32: 32-bit encrypted unsigned integers
ebool: Encrypted boolean values

Homomorphic Operations:

// Encrypted addition
FHE.add(encryptedValue1, encryptedValue2)

// Encrypted comparison
ebool isGreater = FHE.ge(totalAllocated, threshold)

// Encrypted selection
FHE.select(condition, valueIfTrue, valueIfFalse)

Key Functions

Function	Visibility	Description
`registerRegion()`	Authority Only	Register new water region
`startAllocationPeriod()`	Authority Only	Begin allocation cycle
`submitWaterRequest()`	Region Manager	Submit encrypted demand
`processAllocation()`	Authority Only	Distribute water resources
`emergencyWaterAllocation()`	Authority Only	Emergency priority allocation
`getRegionInfo()`	Public View	Query region details
`getCurrentPeriodInfo()`	Public View	Query active period status

📋 Usage Guide

Step 1: Register a Region (Authority)

npx hardhat run scripts/interact.js --network sepolia

// Register new region
await contract.registerRegion(
  "Northern Valley",  // Region name
  8,                  // Priority level (1-10)
  managerAddress      // Region manager wallet
);

Step 2: Start Allocation Period (Authority)

// Start 24-hour allocation period with 10,000 units available
await contract.startAllocationPeriod(
  10000,  // Total available water
  24      // Duration in hours
);

Step 3: Submit Water Request (Region Manager)

// Region manager submits encrypted request
await contract.connect(regionManager).submitWaterRequest(
  1500,  // Requested amount
  75     // Justification score (1-100)
);

Step 4: Process Distribution (Authority)

// Authority triggers allocation algorithm
await contract.processAllocation();

// System computes distribution using homomorphic operations
// Allocations remain encrypted until authorized decryption

Step 5: Query Allocation Status

// Check region allocation (decrypted for authorized user)
const info = await contract.getRegionInfo(regionId);
console.log("Region:", info.name);
console.log("Active:", info.isActive);
console.log("Last Update:", info.lastUpdateTime);

🌐 Deployment

Deploy to Sepolia Testnet

# Deploy contract
npm run deploy

# Verify on Etherscan
npm run verify

Deployment Script

File: scripts/deploy.js

async function main() {
  const WaterResourceManager = await ethers.getContractFactory("WaterResourceManager");
  const contract = await WaterResourceManager.deploy();
  await contract.waitForDeployment();

  console.log("Contract deployed to:", await contract.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Network Configuration

Sepolia Testnet:

Chain ID: 11155111
Explorer: https://sepolia.etherscan.io/
Faucet: https://sepoliafaucet.com/
RPC: Infura, Alchemy, or public endpoints

🧪 Testing

Test Suite Overview

80+ test cases covering all contract functionality
~95% code coverage across all components
Gas optimization verified for production readiness

Test Categories

Deployment Tests (4 tests)

Contract initialization
Authority assignment
Initial state verification

Region Management (12 tests)

Registration workflow
Priority validation
Manager permissions
Input validation

Allocation Periods (10 tests)

Period lifecycle
Duration validation
Active state management

Water Requests (11 tests)

Request submission
Duplicate prevention
Justification scoring

Emergency Allocations (8 tests)

Priority processing
Authorization checks
Amount validation

Administrative Functions (12 tests)

Manager updates
Region deactivation
Permission controls

Edge Cases (14 tests)

Boundary values
Maximum amounts
Extreme scenarios

For detailed testing documentation, see TESTING.md.

📊 Project Structure

water-resource-management-platform/
├── contracts/
│   └── WaterResourceManager.sol     # Main smart contract
├── scripts/
│   ├── deploy.js                    # Deployment script
│   ├── verify.js                    # Contract verification
│   ├── interact.js                  # Interaction examples
│   └── simulate.js                  # Simulation scenarios
├── test/
│   ├── WaterResourceManager.test.js           # Core tests (36 tests)
│   └── WaterResourceManager.extended.test.js  # Extended tests (45+ tests)
├── docs/
│   ├── TESTING.md                   # Testing documentation
│   ├── DEPLOYMENT.md                # Deployment guide
│   └── HARDHAT_GUIDE.md             # Hardhat usage
├── hardhat.config.js                # Hardhat configuration
├── package.json                     # Dependencies and scripts
└── README.md                        # This file

🔒 Security Considerations

Privacy Guarantees

Individual region demands never exposed on-chain
Allocation amounts computed homomorphically
Decryption only permitted to authorized parties
No plaintext leakage during computation

Access Control

Authority-only functions for system administration
Region manager isolation - managers cannot access other regions
Permission validation on all sensitive operations

Smart Contract Security

Input validation on all parameters
SafeMath operations (Solidity 0.8+)
Reentrancy protection where applicable
Event emission for audit trails

Known Limitations

Decryption requests require off-chain oracle coordination
Gas costs higher than non-FHE contracts due to encryption overhead
Sepolia testnet deployment - not production mainnet

⚙️ Tech Stack

Smart Contract Layer

Solidity: ^0.8.24
Zama FHEVM: Fully Homomorphic Encryption library
@fhevm/solidity: FHE operations and types
Hardhat: Development environment

Testing & Development

Hardhat: ^2.19.0 - Testing framework
Ethers.js: ^6.9.0 - Ethereum library
Chai: ^4.2.0 - Assertion library
Mocha: Built-in - Test runner
Solidity Coverage: ^0.8.0 - Code coverage

Deployment & Verification

Sepolia Testnet: Ethereum test network
Etherscan: Contract verification
Hardhat Verify: Automated verification plugin

Code Quality

Solhint: Solidity linting
Prettier: Code formatting
Husky: Git hooks
Gas Reporter: Gas usage analysis

📈 Gas Costs

Operation Benchmarks (Sepolia)

Operation	Gas Used	Estimated Cost (20 gwei)
Deploy Contract	~3,500,000	~0.07 ETH
Register Region	~200,000	~0.004 ETH
Start Allocation Period	~150,000	~0.003 ETH
Submit Water Request	~180,000	~0.0036 ETH
Process Allocation	~250,000	~0.005 ETH
Emergency Allocation	~120,000	~0.0024 ETH

Note: FHE operations incur additional gas costs compared to standard Solidity operations

🛠️ Development

Build Commands

# Compile contracts
npm run compile

# Clean artifacts
npm run clean

# Run linter
npm run lint

# Fix linting issues
npm run lint:sol:fix

# Format code
npm run format

# Check formatting
npm run format:check

Running Local Node

# Start Hardhat network
npm run node

# Deploy to local network
npm run deploy:local

Security Audit

# Run security checks
npm run security

# Fix vulnerabilities
npm run security:fix

🐛 Troubleshooting

Common Issues

1. Compilation Errors

# Clear cache and rebuild
npm run clean
npm run compile

2. Test Failures

# Run tests with verbose output
npx hardhat test --verbose

# Run specific test
npx hardhat test --grep "Region Registration"

3. Deployment Issues

Ensure sufficient Sepolia ETH in deployer wallet
Verify RPC URL is correct in .env
Check network connectivity

4. Gas Estimation Failures

Increase gas limit in hardhat config
Check for contract logic errors
Verify FHE library compatibility

Debug Mode

# Enable Hardhat console logs
npx hardhat test --verbose --show-stack-traces

# Check gas usage
REPORT_GAS=true npm test

🌐 Live Demo

Coming Soon: Frontend interface deployment on Vercel

Contract Address (Sepolia): Deploy and add address here

Etherscan: View Contract

🗺️ Roadmap

Phase 1: Core Platform (Completed)

✅ Smart contract implementation
✅ FHE integration
✅ Comprehensive testing suite
✅ Deployment scripts

Phase 2: Frontend Development (In Progress)

🚧 React-based UI
🚧 MetaMask integration
🚧 Real-time status dashboard
🚧 Request submission interface

Phase 3: Enhanced Features (Planned)

📋 Multi-period analytics
📋 Historical allocation reports
📋 Advanced priority algorithms
📋 Regional cooperation mechanisms

Phase 4: Production Readiness (Future)

📋 Security audit completion
📋 Mainnet deployment
📋 Performance optimization
📋 Governance token integration

🤝 Contributing

We welcome contributions to improve the Water Resource Management Platform!

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Contribution Guidelines

Write comprehensive tests for new features
Follow existing code style and formatting
Update documentation for API changes
Ensure all tests pass before submitting
Add gas usage benchmarks for new functions

📚 Resources

Zama Documentation

FHEVM Documentation - Official FHEVM guide
FHE Use Cases - Real-world applications
Zama GitHub - Open source repositories

Development Tools

Hardhat Documentation - Development environment
Ethers.js - Ethereum library
Solidity Docs - Smart contract language

Blockchain Resources

Sepolia Testnet - Testnet information
Ethereum.org - Developer portal
OpenZeppelin - Security best practices

📄 License

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

MIT License

Copyright (c) 2024 Water Resource Management Team

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:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🏆 Acknowledgments

Built for the Zama FHE Challenge - Demonstrating practical privacy-preserving applications for critical infrastructure management.

Special Thanks:

Zama Team for developing FHEVM technology
Ethereum Foundation for Sepolia testnet
Hardhat team for development tools
Open source contributors

📞 Contact & Support

Issues: Open an issue on GitHub
Documentation: See /docs folder for detailed guides
Community: Join discussions and share feedback

Last Updated: November 2024 Version: 1.0.0 Status: Production Ready (Testnet)

Built with privacy, transparency, and sustainability in mind 🌊🔐

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github/workflows		.github/workflows
.husky		.husky
contracts		contracts
scripts		scripts
test		test
water-resource-management		water-resource-management
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.solhint		.solhint
API.md		API.md
ARCHITECTURE.md		ARCHITECTURE.md
CI_CD.md		CI_CD.md
CI_CD_COMPLETION.md		CI_CD_COMPLETION.md
CI_CD_VERIFICATION.md		CI_CD_VERIFICATION.md
DEPLOYMENT.md		DEPLOYMENT.md
ENHANCEMENTS.md		ENHANCEMENTS.md
FRAMEWORK_SUMMARY.md		FRAMEWORK_SUMMARY.md
HARDHAT_GUIDE.md		HARDHAT_GUIDE.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
PROJECT_COMPLETION.txt		PROJECT_COMPLETION.txt
QUICK_REFERENCE.md		QUICK_REFERENCE.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY_PERFORMANCE.md		SECURITY_PERFORMANCE.md
SECURITY_PERFORMANCE_COMPLETION.md		SECURITY_PERFORMANCE_COMPLETION.md
TESTING.md		TESTING.md
TEST_COMPLETION_REPORT.md		TEST_COMPLETION_REPORT.md
codecov.yml		codecov.yml
demo.mp4		demo.mp4
hardhat.config.js		hardhat.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation