Skip to content

README.md

Latest commit

 

History

History
336 lines (232 loc) · 9.99 KB

README.md

File metadata and controls

336 lines (232 loc) · 9.99 KB

🌙 Midnight Counter App Playground

Midnight Network TypeScript React Node.js

A comprehensive monorepo template for building privacy-preserving applications on the Midnight blockchain

🚀 Overview

The Midnight Counter App Template is a full-featured monorepo showcasing how to build privacy-preserving decentralized applications on the Midnight blockchain. This template demonstrates smart contract development, wallet integration, credential management, and age verification using zero-knowledge proofs.

✨ Key Features

  • 🔒 Privacy-Preserving Smart Contracts - Built with Compact language for zero-knowledge computations
  • 👤 Age Verification System - Credential management with ZK proofs
  • 🌐 Multi-Platform Support - Web UI, CLI tools, and API libraries
  • 🔐 Wallet Integration - Seamless integration with Midnight Lace wallet
  • 🧪 Testing Framework - Comprehensive unit tests and simulation tools
  • 🛠️ Developer Tools - CLI utilities for contract deployment and testing

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Web App UI    │    │   CLI Tools      │    │  Smart Contract │
│                 │    │                  │    │                 │
│ • React Frontend│    │ • Contract Deploy│    │ • Counter Logic │
│ • Wallet Connect│◄──►│ • Credential Mgmt│◄──►│ • Age Verify    │
│ • Age Verify    │    │ • Testing Utils  │    │ • ZK Proofs     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                        ┌──────────────────┐
                        │   Counter API    │
                        │                  │
                        │ • Core Logic     │
                        │ • Provider Setup │
                        │ • Type Defs      │
                        └──────────────────┘

📦 Project Structure

🎯 Applications

  • apps/web/ - React web application with Material-UI
    • Interactive counter interface
    • Midnight Lace wallet integration
    • Age verification forms
    • Real-time contract state updates

📚 Core Packages

  • packages/contracts/counter/ - Smart contract implementation

    • Compact language source code
    • Unit tests and simulators
    • ZK circuit generation

  • packages/api/counter/ - Unified API layer

    • Browser and Node.js compatibility
    • Provider abstractions
    • Contract interaction utilities

  • packages/cli/counter/ - Command-line interface

    • Contract deployment tools
    • Credential management system
    • Development and testing utilities

🛠️ Supporting Packages

  • packages/ui/ - Reusable React components
  • packages/eslint-config/ - Shared linting configuration
  • packages/typescript-config/ - TypeScript configurations
  • packages/compact/ - Smart contract compilation tools

🎮 Getting Started

Prerequisites

  • Node.js (v18 or higher)
  • Yarn package manager
  • Midnight Lace Wallet (for web UI)

Installation

# Install dependencies
yarn install

# Build all packages
yarn build

🌐 Running the Web Application

# Start the React web app
yarn start

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

💻 Using the CLI

Basic Counter Operations

# Run CLI on testnet (without proof server)
yarn counter-cli-remote

# Run CLI with integrated proof server
yarn counter-cli-remote-ps

CLI Features

The CLI provides an interactive menu with the following options:

  1. 🚀 Deploy Contract - Deploy a new counter contract
  2. 🔗 Connect to Contract - Connect to an existing contract
  3. ➕ Increment Counter - Increment the counter value (requires age verification)
  4. 📊 View Counter - Display current counter value
  5. 👤 Set Credentials - Configure your age verification credentials
  6. ✅ Check Verification - View your verification status

Credential Management

The CLI includes a comprehensive credential management system:

# Set your credentials (interactive prompts)
Enter your first name: John
Enter your last name: Doe
Enter your birth year (YYYY): 1990
Enter your birth month (1-12): 5
Enter your birth day (1-31): 15

Note: You must be at least 21 years old to increment the counter, as verified through zero-knowledge proofs.

🔐 Smart Contract Details

Contract Features

The counter contract demonstrates:

  • Public State Management - Maintains a counter value on the blockchain
  • Age Verification - Requires proof of being 21+ to increment
  • Credential Storage - Securely stores user credentials in private state
  • Zero-Knowledge Proofs - Verifies age without revealing exact birthdate

Contract Source

// Public ledger state
export ledger round: Counter;

// Private state for credentials
circuit privateState: CredentialSubject;

// Increment function with age verification
export circuit increment(): [] {
  // Verify user is at least 21 years old
  require(isAtLeast21(privateState.birth_timestamp));
  
  // Increment the counter
  round.increment(1);
}

Building the Contract

# Compile the smart contract
yarn compact

# Run contract tests
yarn test-contract

# Generate ZK circuits (production)
yarn compact --zk

🧪 Testing

Integration Tests

# Run API integration tests
yarn test-api

# Run contract simulation tests
yarn test-contract

🔧 Development

Building

# Build all packages
yarn build

# Build specific package
yarn workspace @midnight-ntwrk/counter-contract build

Linting

# Lint all packages
yarn lint

# Fix linting issues
yarn lint:fix

Type Checking

# Type check all packages
yarn typecheck

🌟 Key Concepts

Privacy-Preserving Credentials

This template showcases how to implement privacy-preserving credential management:

  • Private State Storage - User credentials stored securely in contract private state
  • Zero-Knowledge Age Verification - Prove you're 21+ without revealing exact age
  • Wallet-Based Identity - Credentials tied to wallet public keys for security

Midnight Blockchain Integration

  • Compact Smart Contracts - Privacy-focused smart contract language
  • ZK Circuit Generation - Automatic zero-knowledge proof generation
  • Wallet Provider Integration - Seamless wallet connectivity
  • State Management - Both public and private state handling

📖 Documentation

🤝 Contributing

We welcome contributions! Please read our contribution guidelines and:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Add tests for new features
  • Update documentation as needed
  • Ensure all linting passes

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

🆘 Support

  • Documentation: Comprehensive guides in each package
  • Issues: Report bugs and request features via GitHub Issues
  • Community: Join the Midnight Network community for discussions

Built with ❤️ for the Midnight Network ecosystem

🌐 Website • 📚 Docs • 💬 Community

yarn counter-cli-remote-ps ```

The Counter Contract

The counter-contract subdirectory contains:

Building the Smart Contract

Compile the contract:

yarn compact

You should see the following output from npm and the Compact compiler:

> compact
> compactc --skip-zk packages/contracts/counter/src/counter.compact packages/contracts/counter/src/managed/counter

Compactc version: 0.24.0

The compiler will complete very quickly because we've instructed it to skip ZK key generation with the option --skip-zk. The compiler's output files will be placed in the directory packages/contracts/counter/src/managed/counter.

Run contract's tests:

yarn test-contract

Test Files 1 passed (1) - Tests 3 passed (3)

Contributing

Contributions are welcome! Please open issues or pull requests as needed.

For more details, see the README files in each package or app directory.