Skip to content

Latest commit

 

History

History
274 lines (199 loc) · 7.85 KB

README.md

File metadata and controls

274 lines (199 loc) · 7.85 KB

Midnight Network Midnight Contracts Library

License: GPL v3 Tests

🎯 Library Objectives

A comprehensive smart contract library for the Midnight blockchain ecosystem. This library provides production-ready, auditable, and reusable contract implementations written in the Compact language.

  • Accelerate Development: Use ready-to-integrate, well-tested contract modules for a wide range of use cases
  • Promote Reusability: Import and compose modular contracts for tokens, governance, privacy, and more
  • Ensure Security: All modules are designed with security and best practices in mind
  • Enable Customization: Build your own authorization, business logic, and workflows on top of robust primitives
  • Foster Innovation: Focus on your application logic, not reinventing contract basics
  • Maintain Quality: Comprehensive testing, documentation, and continuous integration
  • Support Privacy: Special focus on privacy-preserving and zero-knowledge contract patterns

🎯 Library Architecture

This isn't just contracts - it's a modular library:

  • 📦 Import modules: Get core functionality.
  • 🔧 Add your logic: Wrap circuits with your own logic or export them directly from your contract.
  • 🎨 Unlimited flexibility: Create any governance, payment, or access control system

The Modular Pattern

modules/Nft   - Core module for public NFTs
modules/NftZk - Core module for privacy NFTs

Just import it in your contract to get access to all the circuits.

import "midnight-contracts/contracts/tokens/nft/src/modules/Nft";

Key insight: The modules give you ALL the circuits. YOU decide how to authorize them.

🚀 Quick Start

Installation

Currently available as a GitHub dependency while we prepare for npm publishing:

{
  "dependencies": {
    "midnight-contracts": "git+https://github.com/riusricardo/midnight-contracts.git"
  }
}

Or install directly:

# Using npm
npm install git+https://github.com/riusricardo/midnight-contracts.git

# Using yarn
yarn add git+https://github.com/riusricardo/midnight-contracts.git

⚙️ Compact Compiler Path Setup

The Compact compiler (compactc) needs to know where to find imported libraries, especially when using dependencies installed in node_modules.

Set the COMPACT_PATH environment variable before compiling:

export COMPACT_PATH="$COMPACT_PATH:./node_modules:../node_modules"
  • This ensures the compiler can resolve imports from your project's node_modules and any parent directory's node_modules.
  • You can add this line to your shell profile (e.g., .bashrc, .zshrc) or run it in your terminal before running any Compact compilation commands.
  • The provided yarn compact and npm run compact scripts already set this variable automatically.

Why is this needed?

Compact modules and libraries are distributed via npm and installed in node_modules. Setting COMPACT_PATH allows the compiler to find and use these dependencies just like with JavaScript/TypeScript projects.

Basic Usage

pragma language_version 0.16;

import CompactStandardLibrary;
import "midnight-contracts/contracts/tokens/nft/src/modules/Nft";

// 1. Export safe circuits directly from module
export { 
  balanceOf,
  ownerOf,
  approve,
  getApproved,
  setApprovalForAll,
  isApprovedForAll,
  transfer,
  transferFrom
};

// 2. Create your authorization wrapper
export circuit mintPaid(to: ZswapCoinPublicKey, tokenId: Uint<64>): [] {
  // Add payment logic, governance, time locks, etc.
  assert(paymentReceived(), "Payment required");
  mint(to, tokenId);
}

// 3. Your wrapped version replaces the raw circuit

📦 Available Modules

Token Modules

🎨 NFT (Non-Fungible Token)

  • Module: contracts/tokens/nft/src/modules/Nft.compact
  • Exports: mint, burn, transfer, approve, balanceOf, ownerOf, etc.
  • Description: Complete ERC721-like NFT implementation
  • Your choice: Add payment, governance, time-locks, or any authorization you want

🔒 NFT-ZK (Privacy-Preserving NFT)

  • Module: contracts/tokens/nft-zk/src/modules/NftZk.compact
  • Exports: mint, burn, transfer, approve, balanceOf, ownerOf, etc.
  • Description: Privacy-focused NFT with hidden ownership using zero-knowledge proofs
  • Your choice: Add anonymous payments, private governance, or confidential authorization

🛠️ Usage Examples

Example 1: Admin-Only NFT (Simple)

pragma language_version 0.16;

import CompactStandardLibrary;
import "midnight-contracts/contracts/tokens/nft/src/modules/Nft";

// Export safe circuits from the module
export { 
  balanceOf,
  ownerOf,
  approve,
  getApproved,
  setApprovalForAll,
  isApprovedForAll,
  transfer,
  transferFrom
};

export ledger contractAdmin: ZswapCoinPublicKey;

constructor() {
  contractAdmin = ownPublicKey();
}

// Only admin can mint tokens
export circuit mintAdmin(to: ZswapCoinPublicKey, tokenId: Uint<64>): [] {
  const senderPublicKey = ownPublicKey();
  assert(senderPublicKey == contractAdmin, "Not authorized to mint.");
  mint(to, tokenId);
}

// Only admin can burn tokens
export circuit burnAdmin(tokenId: Uint<64>): [] {
  const senderPublicKey = ownPublicKey();
  assert(senderPublicKey == contractAdmin, "Not authorized to burn.");
  const tokenOwner = ownerOf(tokenId);
  burn(tokenOwner, tokenId);
}

Example 2: Payment-Based NFT (Advanced)

pragma language_version 0.16;

import CompactStandardLibrary;
import "midnight-contracts/contracts/tokens/nft/src/modules/Nft";

export { 
  balanceOf,
  ownerOf,
  transfer,
  approve
};

export ledger mintPrice: Uint<64>;
export ledger treasury: ZswapCoinPublicKey;

constructor() {
  mintPrice = 1000n;
  treasury = ownPublicKey();
}

// Anyone can mint by paying
export circuit mintPaid(to: ZswapCoinPublicKey, tokenId: Uint<64>): [] {
  // Verify payment (implementation would check actual payment)
  assert(paymentAmount() >= mintPrice, "Insufficient payment");
  
  // Process payment to treasury 
  ...

🔧 Development Setup

Prerequisites

  • Node.js 20+
  • Yarn or npm
  • Midnight development environment

Local Development

  1. Clone the repository

    git clone https://github.com/riusricardo/midnight-contracts.git
cd midnight-contracts

  2. Install dependencies

    yarn install

  3. Build contracts

    yarn compact
yarn build

  4. Run tests

    yarn test

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

What this means:

  • ✅ Free to use in open source projects
  • ✅ Free to modify and distribute
  • ⚠️ Must remain open source if distributed
  • ⚠️ Must include license notice in derivative works

Built with ❤️ for the Midnight ecosystem

Empowering developers to build privacy-first applications with confidence.