NullPay

Privacy-first payment protocol built on Aleo blockchain with zero-knowledge proofs

NullPay is a decentralized invoice and payment system that leverages Aleo's zero-knowledge cryptography to enable private, verifiable transactions. Merchants can create invoices without revealing sensitive information on-chain, and payers can settle invoices while maintaining complete anonymity.

Live Application: https://nullpay.app/
Wave 5 Demo: https://youtu.be/RzCMaCgremE
V28 Smart Contract: zk_pay_proofs_privacy_v29.aleo
V5 Wallet Contract: zk_pay_proofs_privacy_wallet_v6.aleo
NullPay Node SDK: @nullpay/node NullPay MCP Package: @nullpay/mcp
Vision: https://nullpay.app/vision
Documentation: https://nullpay.app/docs
SDK Testing Website: https://testing-website-frontend.vercel.app/ (Test the full SDK flow here)

🚀 What's New in Wave 5 (April 2026)

Wave 5 expands NullPay across checkout, merchant operations, messaging surfaces, and developer distribution. This release brings OpenClaw reach for MCP, live oracle-backed token conversion, the NullPay Card flow, Telegram merchant controls, optional fee estimation, stronger audit tooling, and better batching and payment UX.

🔮 Oracle Conversion & Settlement Integrity

Live Oracle Conversion: Standard and multipay flows can now settle with a different token from the invoice base token while preserving contract-side verification.
Proof-Backed Execution: Quotes are fetched off-chain, but the converted amount and compliance-proof path are validated inside the final Aleo execution.

💳 Card Checkout & Fee Modes

NullPay Card: Added a card profile flow with PIN + card secret unlock, card-specific balance management, top-ups from the main wallet, and wallet-free checkout execution.
Fee Estimation Toggle: Shielded payments still default to fixed fee. Users can optionally enable fee estimation when they want a more dynamic fee path, with the tradeoff that the Shield popup can take longer to appear.

🤖 Messaging, MCP, and Merchant Control

OpenClaw Rollout: NullPay's MCP flow can now be exposed across chat surfaces such as Telegram, WhatsApp, Discord, Slack, Signal, and other OpenClaw-connected channels.
Telegram Bot: Merchants can link accounts, inspect dashboard summaries, fetch invoices, open payment links, manage notifications, and trigger browser handoff flows directly from Telegram.
Client Coverage Expansion: The MCP/docs surface now covers @nullpay/mcp usage across clients like Antigravity, Codex, Cursor, and other stdio-compatible setups.

📊 Dashboard, Audit, and Payment Utility

Sharper Merchant Dashboard: Earnings display, invoice search, and timeline analytics were improved across invoice hash, salt, memo, merchant notes, invoice title, and time-based tracking views.
Selective Disclosure & Audit Verify: Credits reporting now supports selective disclosure, formal audit export flows, and a separate auditor verification center.
Batch Pay, Gift History, and Notes: Batch pay execution, stronger gift-card history, invoice titles, payment notes, and a more capable NullBot broaden the everyday payment surface.

🚀 What's New in Wave 4 (March 2026)

This release expands NullPay's merchant lifecycle with AI-native tooling, broader payment methods, and delegated infrastructure.

🤖 MCP Server & Context-Aware NullBot

NullPay MCP: Shipped an installable MCP server package (@nullpay/mcp) allowing AI clients to create invoices, inspect merchant flows, and execute supported payment actions natively.
NullBot Integrations: The AI assistant (NullBot) now lives inside the dashboard, developer portal, and docs with route-specific context capabilities, transforming it into a live merchant copilot.

🛠️ SDK & CLI Expansion

Rich Node SDK: The @nullpay/node SDK now handles local invoice manifests (nullpay.json), resolves invoice shortcuts, creates hosted checkout sessions, and verifies webhook signatures.
CLI Onboarding Workflow: The @nullpay/cli handles generating salts, submitting invoices to the relayer, polling on-chain resolutions, and writing the final manifest into your project.

💳 Deep Payment Infrastructure

Gift Card Ecosystem: Full-flow support for creating gift cards, balance scanning, wallet redemption, and direct invoice payment paths.
Delegated Proving & Sponsorship: Introduced backend-sponsored execution endpoints (/api/dps/sponsor-sweep) to relay proving and fee paths, reducing direct wallet dependency.
Realtime Hosted Checkout: Standard hosted invoices now natively surface live payment status via Supabase realtime listeners, eliminating the need for merchants to wire custom websocket monitors.

🚀 What's New in Wave 3 (March 2025)

We've just released our biggest update yet, expanding NullPay from a basic payment tool to a full-fledged privacy infrastructure.

📦 NullPay Node SDK & API Standardization

Universal SDK: The new @nullpay/node SDK allows merchants to create hosted checkout sessions, retrieve payment statuses, and verify webhooks.
Clean API: We've completely removed legacy /v1 versioning across the entire stack (Backend, SDK, and Frontend) for a more stable and professional /api structure.
Hosted Checkout: Merchants can now redirect customers to a high-conversion, hosted payment page that handles all ZK proof generations automatically.

🛡️ Burner Wallets & Merchant Anonymity

Zero Identity Linkage: Generate anonymous Burner Wallets locally in your browser. Decouple your main identity from your business payments.
On-Chain Recovery: Burner credentials are encrypted with your main wallet key and optionally backed up to the Aleo chain for cross-device synchronization.

💵 Comprehensive Token Support (Credits, USDCx, USAD)

Stablecoin Integration: Full support for USAD alongside USDCx and Aleo Credits.
Token Denomination: All transitions support native decimal precisions (e.g., 6-decimal precision for USAD/USDCx).
Dual Receipts: Every payment atomically mints a PayerReceipt and MerchantReceipt on-chain, enabling private, off-chain proof of purchase.

🔔 Enterprise Realtime Infrastructure

Supabase Realtime: Replaced legacy Socket.io with a robust, cloud-native notification system. Receive payments instantly without polling.
Interactive Alerts: Built-in 3-tone chime sound and toast notifications allow merchants to keep the dashboard open and hear every new sale.
Automatic Polling Fallbacks: Implemented 4-layer redundancy for transaction verification (WebSockets -> DB Polling -> Block Explorer API -> Shield Provider) ensuring no payment is ever missed.

🔄 Token-Agnostic Donation Campaigns

Universal Invoices: Create donation links that accept any supported private token. The protocol automatically detects the payer's choice and routes to the correct on-chain transition.

📱 NullPay Mobile Version (Beta V1)

Access NullPay on the go directly through the Shield Wallet browser (available on the Play Store). While we are actively refining the design and performance for V2, the current V1 release is fully functional for all core payments.

⚠️ Current Limitations (Shield Wallet)

Auto-Decryption: Limited support — users may need to manually decrypt records (one-click).

Despite these minor inconveniences, NullPay Mobile is fully operational for creating invoices, sending payments, and managing history.

Invoice	Payment	Profile

Why Mobile?

Payments need to be instant and accessible anywhere. The mobile version bridges the gap between digital assets and real-world transactions:

Scan & Pay: Instantly scan QR codes to make payments at physical stores.
On-the-Go Access: Manage your invoices and payments without needing a laptop.
Seamless Sync: Access the full-fledged dashboard on desktop anytime for detailed management.

NullPay Architecture

Features

Core Capabilities

Zero-Knowledge Invoices: Merchant addresses and amounts are hashed on-chain using BHP256, preserving privacy
Private Transfers: Payments executed via Aleo's transfer_private (Credits) and private programs for USDCx and USAD
Standard & Multi-Pay: Support for single-settlement invoices and multi-contributor campaigns
Multi-Token Oracle: Pay invoices in any token with live ZK-verified price conversion
NullPay Card: Wallet-less payments using Card PIN and Secret credentials
Selective Disclosure: Cryptographic audit reports for privacy-compliant financial tracking
Batch Payments: Settle dozens of records or invoices in a single transaction
Encrypted Metadata: Off-chain data encrypted with AES-256-GCM (now including Invoice Titles and Notes)
Payment Receipts: Unique receipt keys generated via cryptographic commitments for multi-pay tracking

User Experience

Wallet Integration: Seamless connection with Aleo wallet adapters (Leo Wallet, Puzzle Wallet, Shield, etc.)
Invoice Explorer: Real-time tracking of invoice status and transaction history
Merchant Dashboard: Track created invoices, payment status, and live balances across all supported tokens
Responsive Design: Premium glassmorphism UI with fluid animations

Architecture

NullPay consists of three main layers:

Layer 1: Frontend (React + TypeScript)

The client-side application handles:

Salt generation using crypto.getRandomValues() (128-bit entropy)
Wallet adapter integration for transaction signing
Invoice hash computation (client-side verification)
Transaction submission to Aleo network
Burner wallet management (local encryption)

Layer 2: Smart Contract (Leo)

The on-chain protocol zk_pay_proofs_privacy_v29.aleo enforces:

Hash integrity verification (assert_eq(computed_hash, stored_hash))
Invoice status management (0 = Open, 1 = Settled)
Multi-token support (Credits, USDCx, USAD)
Replay protection via payment receipt tracking
Dual receipt generation (PayerReceipt and MerchantReceipt)

Layer 3: Backend (Node.js + Supabase)

The indexer and database layer provides:

Clean /api structure (unversioned for stability)
Fast invoice lookups and state tracking
AES-256-GCM encrypted storage for merchant/payer addresses
Supabase Realtime integration for live notifications

Data Flow:

Merchant → Frontend → Smart Contract → Blockchain
                ↓
           Backend DB (Encrypted)
                ↓
           Payer → Frontend → Verify Hash → Pay Invoice

Technology Stack

Blockchain:

Aleo Testnet (Privacy-preserving L1)
Leo Programming Language (Smart contract development)
BHP256 Hash Function (ZK-optimized hashing)

Frontend:

React 18 with TypeScript
Tailwind CSS (Styling)
Framer Motion (Animations)
@nullpay/node (Integration SDK)

Backend:

Node.js with Express
Supabase (PostgreSQL + Realtime)
AES-256-GCM Encryption
CORS-enabled REST API

Development Tools:

Leo CLI (Contract compilation)
npm (Package management)
Git (Version control)

Getting Started

Prerequisites

Node.js (v18 or higher)
npm

Installation

1. Clone the repository:

git clone https://github.com/geekofdhruv/NullPay.git
cd NullPay

2. Install dependencies:

# Frontend
cd frontend && npm install
# Backend
cd ../backend && npm install

Environment Setup

Frontend (frontend/.env):

VITE_PROGRAM_ID=zk_pay_proofs_privacy_v29.aleo
VITE_BACKEND_URL=https://nullpay.app/api

Backend (backend/.env):

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
ENCRYPTION_KEY=your_64_char_hex_key

5. Start the backend:

cd backend
npm start

6. Start the frontend:

cd frontend
npm run dev

The application will be available at http://localhost:5173

Project Structure

AleoZKPay/
├── contracts/
│   └── zk_pay/
│       └── src/
│           └── main.leo          # Smart contract (v11)
├── frontend/
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   ├── hooks/                # Custom React hooks
│   │   │   ├── useCreateInvoice.ts
│   │   │   └── usePayment.ts
│   │   ├── pages/                # Route pages
│   │   │   ├── CreateInvoice.tsx
│   │   │   ├── PaymentPage.tsx
│   │   │   ├── Explorer.tsx
│   │   │   ├── Profile.tsx
│   │   │   ├── Privacy.tsx
│   │   │   └── Docs.tsx
│   │   ├── services/
│   │   │   └── api.ts            # Backend API client
│   │   ├── utils/
│   │   │   └── aleo-utils.ts     # Salt generation, hash fetching
│   │   └── App.tsx
│   └── package.json
├── backend/
│   ├── index.js                  # Express server
│   ├── encryption.js             # AES-256-GCM encryption
│   └── package.json
├── docs/
│   └── future_wave.md            # Roadmap
└── README.md

Smart Contract

The core contract zk_pay_proofs_privacy_v29.aleo is deployed on Aleo Testnet.

Explorer Link: https://testnet.explorer.provable.com/program/zk_pay_proofs_privacy_v29.aleo

Key Transitions

1. `create_invoice_any`

Creates a universal donation invoice that accepts any supported token.

2. `pay_invoice_usad` / `pay_invoice_usdcx`

Executes private token payments with atomic receipt generation.

3. `backup_burner_wallet`

Securely backs up encrypted burner wallet credentials to the chain for cross-device recovery.

Security

On-Chain Privacy

Merchant Address: Hashed with BHP256 before storage
Invoice Amount: Hashed with BHP256 before storage
Salt: 128-bit entropy (2^128 search space)
Payment Receipts: Commitment scheme prevents receipt forgery

Off-Chain Security

AES-256-GCM Encryption: Merchant and payer addresses encrypted at rest
Authenticated Encryption: GCM mode provides integrity and confidentiality
Environment Variables: Encryption keys stored securely
HTTPS Required: Production deployments must use HTTPS

Attack Mitigations

Replay Protection: Payment receipts prevent duplicate payments with same secret
Hash Verification: assert_eq(computed_hash, stored_hash) prevents tampering
Expiry Enforcement: Block height checks prevent payment of expired invoices

License

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

Acknowledgments

Built with Aleo's privacy-preserving blockchain technology.

Resources:

Contact: For questions or support, please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 287 Commits
assets		assets
backend		backend
contracts		contracts
docs		docs
frontend		frontend
packages		packages
testing-website		testing-website
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

NullPay

🚀 What's New in Wave 5 (April 2026)

🔮 Oracle Conversion & Settlement Integrity

💳 Card Checkout & Fee Modes

🤖 Messaging, MCP, and Merchant Control

📊 Dashboard, Audit, and Payment Utility

🚀 What's New in Wave 4 (March 2026)

🤖 MCP Server & Context-Aware NullBot

🛠️ SDK & CLI Expansion

💳 Deep Payment Infrastructure

🚀 What's New in Wave 3 (March 2025)

📦 NullPay Node SDK & API Standardization

🛡️ Burner Wallets & Merchant Anonymity

💵 Comprehensive Token Support (Credits, USDCx, USAD)

🔔 Enterprise Realtime Infrastructure

🔄 Token-Agnostic Donation Campaigns

📱 NullPay Mobile Version (Beta V1)

⚠️ Current Limitations (Shield Wallet)

Why Mobile?

NullPay Architecture

Features

Core Capabilities

User Experience

Architecture

Layer 1: Frontend (React + TypeScript)

Layer 2: Smart Contract (Leo)

Layer 3: Backend (Node.js + Supabase)

Technology Stack

Getting Started

Prerequisites

Installation

Environment Setup

Project Structure

Smart Contract

Key Transitions

1. create_invoice_any

2. pay_invoice_usad / pay_invoice_usdcx

3. backup_burner_wallet

Security

On-Chain Privacy

Off-Chain Security

Attack Mitigations

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `create_invoice_any`

2. `pay_invoice_usad` / `pay_invoice_usdcx`

3. `backup_burner_wallet`

Packages