🛡️ KidSafe Age Verification System

A blockchain-based age verification system that empowers parents to protect their children online while maintaining privacy and ensuring accountability from online services.

🎯 Problem Statement

Online services often claim they "don't know" a user's real age, allowing them to avoid responsibility for child safety. Children can easily lie about their age during registration, and parents have no way to enforce accurate age reporting.

💡 Solution

KidSafe creates an immutable, parent-controlled age verification system on the blockchain where:

• Parents register their children's real birth dates
• Online services can verify age requirements without accessing personal data
• Companies can no longer claim ignorance about user ages
• Complete audit trail ensures accountability

✨ Key Features

🔒 Tamper-Proof Age Records

• Birth dates stored immutably on blockchain
• Cryptographic proof of authenticity
• Real-time age calculation using blockchain timestamps

👨‍👩‍👧‍👦 Parental Control

• Parents maintain full control until child reaches 18
• Transfer custody capabilities for family changes
• Bulk management of multiple children

🕵️ Privacy-Preserving Verification

• Services only receive pass/fail verification results
• No personal data (birth dates, exact ages) shared
• Zero-knowledge proof architecture

📊 Complete Audit Trail

• All verification requests logged on-chain
• Transparent accountability for services
• Historical verification data for compliance

🔧 Easy Integration

• RESTful API for seamless service integration
• Multiple verification modes (single age, age ranges)
• Comprehensive rate limiting and security

🏗️ System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Parent App    │    │   Service API   │    │ Smart Contract  │
│                 │    │                 │    │                 │
│ • Register kids │◄──►│ • Age verify    │◄──►│ • Store records │
│ • Manage perms  │    │ • Audit logs    │    │ • Calculate age │
│ • Transfer ctrl │    │ • Rate limiting │    │ • Event logging │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                        │                        │
        └────────────────────────┼────────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Blockchain    │
                    │                 │
                    │ • Ethereum      │
                    │ • Polygon       │
                    │ • Other EVM     │
                    └─────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Git
• MetaMask or compatible wallet

1. Clone and Setup

git clone https://github.com/yourusername/kidsafe-age-verification.git
cd kidsafe-age-verification
chmod +x scripts/setup.sh
./scripts/setup.sh

2. Configure Environment

cp .env.example .env
# Edit .env with your configuration:
# - Add your wallet private key
# - Configure RPC endpoints
# - Set API security keys

3. Deploy Locally

# Terminal 1: Start local blockchain
npx hardhat node

# Terminal 2: Deploy contracts
npm run deploy

# Terminal 3: Start development servers
npm run dev

4. Access the Application

• Parent Interface: http://localhost:3001
• API Documentation: http://localhost:3000/health
• Contract Address: Check console output from deploy command

📱 Usage Guide

For Parents

1. Connect Your Wallet

• Open the parent interface
• Click "Connect Wallet"
• Approve connection in MetaMask

2. Register Your Child

Child's Wallet Address: 0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904
Birth Date: 2010-05-15
Document Hash: (auto-generated or provide birth certificate hash)

3. Manage Children

• View all registered children
• Transfer parental control (custody changes)
• Deactivate records when child reaches 18

For Online Services

1. Register Your Service

curl -X POST http://localhost:3000/api/register-service \
  -H "Content-Type: application/json" \
  -d '{
    "serviceAddress": "0x8ba1f109551bD432803012645Hac136c4cccccccc",
    "serviceName": "YourPlatform",
    "contactEmail": "compliance@yourplatform.com"
  }'

2. Verify User Age

const verifyAge = async (childAddress, minimumAge) => {
  const response = await fetch('/api/verify-age', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key',
      'x-service-address': 'your-service-address'
    },
    body: JSON.stringify({
      childAddress,
      minimumAge,
      returnActualAge: false // Privacy-preserving mode
    })
  });
  
  const result = await response.json();
  return result.verified; // true/false
};

3. Age Range Verification

// Check multiple age thresholds at once
const checkAgeRanges = async (childAddress) => {
  const response = await fetch('/api/verify-age-range', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key',
      'x-service-address': 'your-service-address'
    },
    body: JSON.stringify({
      childAddress,
      ageRanges: [13, 16, 18] // Check 13+, 16+, 18+
    })
  });
  
  const result = await response.json();
  // Returns which thresholds the child meets
  return result.verificationResults;
};

🔧 API Reference

Authentication

All service endpoints require:

• x-api-key: Your service API key
• x-service-address: Your registered Ethereum address

Endpoints

POST /api/register-child

Register a new child in the system.

Request:

{
  "childAddress": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
  "birthTimestamp": 1589155200,
  "documentHash": "0x1234...",
  "parentAddress": "0x8ba1f109551bD432803012645Hac136c4cccccccc"
}

Response:

{
  "success": true,
  "message": "Child registered successfully",
  "childAddress": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
  "age": 15,
  "transactionHash": "0xabc123...",
  "registrationDate": "2024-01-15T10:30:00.000Z"
}

POST /api/verify-age

Verify if a child meets minimum age requirement.

Request:

{
  "childAddress": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
  "minimumAge": 13,
  "returnActualAge": false
}

Response:

{
  "verified": true,
  "minimumAge": 13,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "transactionHash": "0xdef456..."
}

GET /api/children/:parentAddress

Get all children registered by a parent.

Response:

{
  "children": [
    {
      "address": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
      "age": 15,
      "isActive": true,
      "registrationDate": "2024-01-15T10:30:00.000Z"
    }
  ]
}

GET /api/verification-logs

Get verification audit logs for your service.

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00.000Z",
      "childAddress": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
      "serviceAddress": "0x8ba1f109551bD432803012645Hac136c4cccccccc",
      "minimumAge": 13,
      "verified": true,
      "transactionHash": "0xabc123..."
    }
  ],
  "total": 1
}

🔒 Security Features

Blockchain Security

• Immutable Records: Birth dates cannot be altered once stored
• Cryptographic Verification: All data protected by blockchain cryptography
• Decentralized: No single point of failure

API Security

• Rate Limiting: 100 requests per 15 minutes per IP
• API Key Authentication: Secure service verification
• Input Validation: All inputs sanitized and validated
• CORS Protection: Configurable allowed origins

Privacy Protection

• Minimal Data Exposure: Services only receive verification results
• No Personal Data Storage: API doesn't store sensitive information
• Audit Transparency: All verifications logged for accountability

🧪 Testing

Run Smart Contract Tests

npm test

Test API Endpoints

cd backend
npm test

Manual Testing

# Test age verification
curl -X POST http://localhost:3000/api/verify-age \
  -H "Content-Type: application/json" \
  -H "x-api-key: demo-key" \
  -H "x-service-address: 0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904" \
  -d '{
    "childAddress": "0x742d35Cc6634C0532925a3b8D43Cc6fe7C3C8904",
    "minimumAge": 13
  }'

📋 Deployment

Local Development

npx hardhat node          # Start local blockchain
npm run deploy            # Deploy contracts locally
npm run dev              # Start frontend + backend

Testnet Deployment

# Configure .env with testnet RPC URL and private key
npx hardhat run scripts/deploy.js --network sepolia

Mainnet Deployment

# ⚠️ Ensure thorough testing before mainnet deployment
npx hardhat run scripts/deploy.js --network mainnet

Production API Server

cd backend
npm install --production
NODE_ENV=production npm start

🌍 Network Support

Supported Networks

• Ethereum Mainnet: Production deployment
• Polygon: Lower cost alternative
• Arbitrum: Layer 2 scaling
• Optimism: Layer 2 scaling
• Sepolia: Ethereum testnet
• Mumbai: Polygon testnet

Gas Optimization

• Contract optimized for minimal gas usage
• Batch operations for multiple children
• Efficient storage patterns

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Submit a pull request

Development Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation
• Ensure security best practices

📄 License

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

⚠️ Disclaimer

Important: This is a proof-of-concept implementation designed to demonstrate blockchain-based age verification. Before production use:

• Conduct thorough security audits
• Review legal compliance requirements
• Test extensively on testnets
• Consider professional smart contract auditing

🆘 Support

Getting Help

• Documentation: Check this README and inline code comments
• Issues: Create a GitHub issue for bugs or feature requests
• Community: Join our Discord for community support

Common Issues

Q: Contract deployment fails A: Check your private key and RPC URL in .env

Q: Frontend can't connect to MetaMask A: Ensure MetaMask is connected to the correct network

Q: API returns 401 Unauthorized A: Verify your API key and service address headers

Q: Age verification returns false for valid child A: Check that the child is registered and birth date is correct

🗺️ Roadmap

Phase 1: Core Features ✅

• Basic age verification smart contract
• Parent registration interface
• Service API with authentication

Phase 2: Enhanced Privacy 🚧

• Zero-knowledge proof implementation
• Selective disclosure protocols
• Enhanced anonymization

Phase 3: Mobile & Integration 📱

• Mobile app for parents
• WordPress/Shopify plugins
• Social media platform SDKs

Phase 4: Advanced Features 🔮

• Multi-parent/guardian support
• International legal compliance
• Cross-chain compatibility

🎯 Real-World Impact

For Parents

• Peace of Mind: Know your child's real age is being used online
• Control: Maintain authority over your child's digital presence
• Transparency: See which services have verified your child's age

For Online Services

• Compliance: Meet age verification requirements with confidence
• Liability Protection: Demonstrable due diligence in age verification
• User Trust: Show commitment to child safety

For Children

• Safety: Appropriate content and interaction filtering
• Privacy: Personal data not shared with services
• Growth: Automatic permission updates as they age

---

Built with ❤️ for child safety and digital privacy

"In a world where children's safety online is paramount, KidSafe provides the tools parents need to protect their children while respecting privacy and ensuring accountability."