Private Payments for Stellar

[!WARNING] This project is a Work in progress (WIP). It is intended to serve as a reference implementation of privacy pools for Stellar. The code has not yet been audited and should not be used in production environments with real assets as of now. The security hardening work is planned. Expect breaking changes and necessity to clear your local storage for the demo app/cli until the first stable release.

A privacy-preserving payment system for the Stellar network using zero-knowledge proofs. This implementation enables users to deposit, transfer, and withdraw tokens while maintaining transaction privacy through Groth16 proofs.

The system incorporates Association Set Provider (ASPs) as a control mechanism to provide illicit activity safeguards through association sets. ASPs maintain membership and non-membership Merkle trees that allow proving whether specific deposits are part of approved or blocked sets, enabling pool operators to enforce administrative controls without compromising user privacy.

To run your own pool or ASP, start with the operator manual.

Features

• Private Payments: Deposit, transfer, and withdraw tokens without revealing transaction amounts or sender/receiver relationships
• Zero-Knowledge Proofs: Groth16 (over BN254) proofs generated via Circom circuits.
• Administrative Controls: ASP-based membership and non-membership proofs for illicit activity safeguards
• Browser-Based Proving: Client-side proof generation using WebAssembly
• Stellar Integration: Built on Soroban smart contracts
• SEP-0043 Wallet Interface: Standardized wallet signing calls with structured user-rejection codes; connect/permission calls remain wallet-specific while SEP-0043 is Draft (see app/ARCHITECTURE.md)

Learn more in the blogpost.

Demo Application

The demo application consists on three main parts:

• Frontend: Provides a nice user interface for interacting with the system.
• Circuits: Where the real zk-magic happens and constraints are defined.
• Smart Contracts: They define the state of the system, and how transactions are processed.

The Frontend includes the user-facing part and an example of an ASP admin page which will be separated according to roles in the main application.

The demo app demonstrates integration of the Stellar Private Payments JS/TS SDK.

Architecture Overview

Transaction Flow

1. Deposit: User deposits tokens into the pool, creating a commitment (UTXO). No input notes are spent, creates output notes.
2. Withdraw: User proves ownership of commitments and withdraws tokens. Inputs notes are spent, no output notes are created.
3. Transfer: User spends existing commitments and creates new ones, all done privately. Input notes are spent, and output notes under a new public key are created.
4. Transact: Enables advanced users with experience on privacy-preserving protocols to generate their own transactions. Spending, creating and transferring notes at will.

ASP Admin Page

This is the administrative control panel for managing the pools and the Association Set Provider (ASP) membership trees. It allows you to:

1. Add/insert public keys to the ASP membership tree - Controls which public keys are approved
2. Manage the exclusion list - Block specific public keys via the non-membership Merkle tree, several in one call
3. Pause deposits, re-point pools, and pre-sign pauses on the Pools tab
4. Transfer a contract's admin in two steps on the Admins tab

This provides illicit activity safeguards while maintaining user privacy. The ASP membership trees work with the zero-knowledge proofs to prove that deposits either belong to approved accounts or don't belong to blocked accounts—without compromising privacy.

Every admin call is a transaction from the contract's admin account. When the connected Freighter account can sign it alone, the page signs and sends it at once; otherwise the account's signers read and sign it in turn in the page's Admin Transaction card. The governance runbook covers the account, each procedure, and the response to each incident.

Zero-Knowledge Circuits

The main transaction circuit proves:

• Ownership of input UTXOs (knowledge of private keys)
• Correct nullifier computation (prevents double-spending)
• Valid Merkle proofs for input commitments
• Correct output commitment computation
• Balance conservation (inputs + public amount = outputs). The pool requires the public amount to be ext_amount - fee: the tokens the call sends in (negative for a withdrawal) minus the pool fee, which get_fee returns.
• ASP membership and/or non-membership proofs, depending on pool policy flags (none = unrestricted; allowlist, blocklist, or allowlist-blocklist)

Smart Contracts

• Pool: Main contract handling deposits, transfers, withdrawals, and the admin's fee claims
• Circom Groth16 (BN254) Verifier: On-chain verification of ZK proofs
• ASP Membership: Merkle tree of approved public keys
• ASP Non-Membership: Sparse Merkle tree for exclusion proofs
• Public key registry: A public address book mapping Stellar addresses to user's SPP public keys.
  (allows transfers by using just a standard Stellar address)

Install the CLI

The spp command-line tool can be installed with a single command:

curl -fsSL https://nethermindeth.github.io/stellar-private-payments/install.sh | sh

This downloads the release binary for your platform (Linux/macOS, x86_64/aarch64), verifies its checksum, installs spp to ~/.local/bin, and provisions the runtime data dir (circuits, policy proving keys, license/notice texts). Then run spp --help.

The Stellar CLI is required. Install it separately with the official command:

curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh

To install a specific release

curl -fsSL https://nethermindeth.github.io/stellar-private-payments/install.sh | sh -s -- --version v0.1.0

or the latest prerelease

curl -fsSL https://nethermindeth.github.io/stellar-private-payments/install.sh | sh -s -- --pre

CLI demonstrates integration of the Stellar Private Payments Rust SDK.

Deploying pools

Deploy a private pool tailored to your own asset, compliance policy, and privacy needs. See DEPLOY.md for details.

Selecting a network

The CLI and bootnode use runtime deployment configuration, so the same binary can serve different networks without rebuilding:

cargo build --release -p stellar-private-payments-cli
./target/release/spp --deployment deployments/testnet config show

cargo build --release --manifest-path tools/bootnode/Cargo.toml
# Required when starting the bootnode, alongside database and HTTP/TLS settings:
export BOOTNODE_DEPLOYMENT=/absolute/path/to/deployments.json

The CLI accepts a deployment directory or JSON file through --deployment, a saved config setting, or a file provisioned in its data directory. There is no embedded deployment fallback. Proof operations additionally need the deployment's circuits.json and matching circuit artifacts. The Rust SDK and NPM package also accept deployment configuration and circuit fingerprints at runtime.

For the website, SPP_NETWORK=testnet trunk build --release selects the deployment to bundle. Downstream deployers supply their configuration, contracts, and matching circuit artifacts. CI generates a temporary local-network configuration to test build selection without deploying contracts or starting localnet.

The deployment configuration records the network's public identity string (networkPassphrase) and default RPC address (rpcUrl). The website checks Freighter's identity, the CLI checks its Stellar CLI network configuration, and the bootnode checks the upstream RPC's identity against that passphrase. Display names, explorer defaults, and test-network disclaimers also come from the config.

Bootnode upgrade: storage identifiers now use v2, separating history by network and contract IDs. Existing v1 history must be re-synced; this does not change contracts or balances on the blockchain.

See Deployment configuration and networks for configuration fields, Docker builds, connection overrides, and control over retaining old bootnode data.

Limitations

As a work-in-progress, this implementation has several limitations to be resolved in the nearest future:

• Stellar Events retention: The app relies heavily on Stellar events. But RPC nodes only store events for a small retention window (7 days). This means that the demo will not work for users onboarded after 7 days of contract deployment because they couldn't re-play events history. But a user who onboarded within 7 days from the contracts deployment and keeps their app tab open in a browser, can use the app without a reset as the events digestion happens in the background.
• Not Audited: The code has not undergone security audits.
• Error Handling: Error handling may not cover all edge cases.
• Browser storage: The web app keeps its SQLite database (spp.encrypted.db) in the browser's Origin Private File System (OPFS), encrypted under a random key whose Freighter-wrapped envelope lives in localStorage. You can export and import encrypted backups from the app. If browser storage is wiped without a backup, signing again with the same wallet re-derives your privacy keys and re-syncing recovers your notes (through a bootnode once the pool is older than the 7-day RPC retention window), though local settings and operation history are lost. Because the Freighter signature unwraps the localStorage envelope rather than deriving the random database key itself, losing localStorage while encrypted OPFS files remain leaves that database unreadable; you must either restore a backup or reset local storage before onboarding again.

AI tools disclosure

The content published here may have been refined/augmented by the use of large language models (LLM), computer programs designed to comprehend and generate human language. However, any output refined/generated with the assistance of such programs has been reviewed, edited and revised by Nethermind.

License

This repository contains source code provided under a mixed license structure (Apache 2.0 and GPLv3).

Most of the source code is licensed under the Apache License, Version 2.0. See LICENSE for details.

The exception is tools/circuit-compiler which is licensed separately under the GNU General Public License v3.0 (it links iden3 Circom). See tools/circuit-compiler/LICENSE for details.

Responsibility of Deployers

The dist/ directory and its contents (including compiled WebAssembly circuits, keys, and bundled JavaScript) are generated artifacts produced by the build process. They are not checked into this repository.

If you compile, build, or deploy this project (e.g., hosting the dist/ folder on a web server), you become the distributor of those binary artifacts. It is your responsibility to:

1. Ensure all generated artifacts comply with their respective licenses (specifically the LGPLv3 requirements for compiled circuits).
2. Include the appropriate LICENSE and NOTICE files in your deployment directory.
3. Make the source code available to your end-users as required by the LGPLv3 (if you are distributing the compiled circuits).

The maintainers of this repository provide the source code "as is" and assume no responsibility for the downstream builds or deployments.

Would like to contribute?

Please check the issues. If you're an external contributor, please check the issues with the label contributors-friendly. See also Contributing.