NullCash · documentation

The manual.

Everything about how NullCash seals, moves and releases money, from the first click to the circuit.

Start here

What NullCash is

NullCash gives a Solana wallet a second, sealed balance. Money goes in publicly, moves around privately, and comes out wherever you point it.

Think of it as two layers. Your normal wallet is the street-level account everyone can look at. Your NullCash vault is a back room on the same chain: the network can confirm every action in it is valid, but it cannot see who did it, how much moved, or (if you pay fees in private SOL) which token was involved.

Chain
Solana mainnet
Custody
Non-custodial; secrets are created and kept in your browser
Privacy engine
Zero-knowledge proofs (Groth16) over a shared note pool
Ways out
Fresh one-time Solana address, or any chain via cross-chain routes
Privacy grows with the crowd. Odd amounts, instant in-and-out timing and rare tokens make you easier to spot, so spread things out.
Start here

Quickstart

From zero to your first private payment in about two minutes.

  1. 1Open a vaultHit Connect wallet and pick Create a NullCash vault. Choose a password for this device. You get a recovery key once; store it offline.
  2. 2ShieldGo to Shield, pick a token and amount, and approve one signature from your public wallet. Your tokens become sealed notes.
  3. 3Use itSend to any null2… address, trade inside the pool, or exit. No pop-ups: a relayer submits each proof for you.
  4. 4LeaveWithdraw to a brand-new address, or use Private route / Privacy swap to land on another chain.
Start here

Swapping without a vault

You can bridge out of Solana privately without creating anything.

Private route and Privacy swap both run on a manual-deposit model. You get a quote, place an order, and then decide whether to fund it by sending SOL or a token from any wallet you like. Placing the order itself moves nothing.

  • No sign-up and no wallet connection
  • Each order has its own deposit address and deadline
  • Track any order with its receipt ID
Concepts

Notes and the pool

Your private balance is not a number on-chain; it is a set of sealed notes only you can open.

A note bundles four things: a token mint, an amount, an owner key and a random blinding value. What lands on-chain is only its fingerprint (a commitment), written as a leaf in a Poseidon Merkle tree that is 26 levels deep, which is room for 67,108,864 notes.

When you spend a note you publish its nullifier, a one-way tag the program stores in a spent list. The same note can never be spent twice, and nobody can trace which commitment a nullifier belongs to.

Incoming payments are found by your browser trial-decrypting each new note ciphertext with your viewing key. The indexer serves everyone the same feed, so it never learns which notes are yours.

Concepts

Proofs, not promises

Encryption hides data and relayers hide senders, but only a proof shows the chain the action is legitimate.

Every private action ships with a zero-knowledge proof that says, in effect: I own a note that is really in the pool, I am allowed to spend it, and the totals add up. The verifier checks the maths and learns nothing else.

  • Membership: each spent note sits under the current Merkle root
  • Authority: the spender holds the matching spending key
  • Uniqueness: nullifiers are derived correctly, so no double-spends
  • Conservation: inputs + public amount = outputs + fees
proof system   Groth16 on BN254
circuit        Transaction(levels 26, in 4, out 3)
public inputs  13
hashing        Poseidon
on-chain check alt_bn128 syscalls
Concepts

Relayers

Someone has to pay Solana gas; it should not be you, because your wallet would show up.

A relayer takes your finished proof, wraps it in a transaction and pays the network fee, taking a small relayer fee from the note in return. The recipient, amount, fee and any swap terms are bound into the proof hash, so a relayer that tampers with anything just produces a failed transaction.

Private trades run in two moves. swap_prepare locks the input into a dedicated escrow, then swap_execute runs the route. The program confirms the escrow paid exactly the input and the vault got at least your minimum; if not, swap_refund puts everything back.

Concepts

Keys and recovery

One random seed, several keys, and nothing tied to your public wallet.

Your vault starts as 32 random bytes. From that seed the browser derives a spending key, a viewing key and an endless supply of single-use receive addresses. On this device the bundle is locked with your password (PBKDF2 at 600k rounds, then AES-GCM).

The recovery key is shown once and restores the whole vault anywhere. Because it is independent of your public wallet, losing one never exposes the other.

There is no reset button. If both this browser and the recovery key are gone, the funds are unrecoverable.
Cross-chain

Private route

Multi-hop swaps out of Solana to any chain, compared side by side.

  1. 1Pick a pairChoose a Solana token to send and any destination token and chain.
  2. 2CompareSeveral live routes appear with output, ETA and limits. They refresh before they expire.
  3. 3Place the orderAdd the receiving address. You get a deposit address, plus a memo if one is required.
  4. 4Fund itSend the exact amount on Solana before the timer runs out.
  5. 5Watch itStatus runs: waiting for deposit, confirming, exchanging, sending, completed.
The minimum order is worth about $3. That is a size floor, not a charge; provider fees and price impact are already inside the quoted output.
Cross-chain

Privacy swap

Intent-based swaps where solvers compete to fill your order inside a confidential shard.

You describe the outcome you want: an exact Solana input, a destination asset and chain, a recipient and a Solana refund address. Market makers bid to deliver it and the best bid becomes your quote. Once you confirm, you get deposit instructions; after your deposit lands the solver pays out on the destination chain and the settlement contract finalises atomically. Failures refund to your Solana address.

Processing happens in a private shard run by permissioned validators, with encryption and restricted visibility. That is confidential execution rather than a zero-knowledge pool, so those validators sit inside the trust boundary.

Destinations
Solana, NEAR, Ethereum, Arbitrum, Base, Optimism, Polygon, BNB Chain, plus native Zcash (receive-only, shielded address)
Partner fee
0.40%, already reflected in the quote
Refunds
Always to the Solana refund address you set
Cross-chain

Tracking an order

Every order gets a receipt ID you can look up at any time.

Open Track, paste the receipt ID and the page polls the live status every few seconds. Recent orders are remembered in this browser so you can jump back with one tap.

Reference

On-chain instructions

What the Solana program exposes.

InstructionWhat it does
transactThe workhorse: one proof covers a deposit, a payment or a cash-out, burning up to 4 notes and minting up to 3
swap_prepare / swap_execute / swap_refundEscrow first, run the venue second, and roll back automatically if the minimum is missed
register_assetAdds support for a new coin; permissionless, with on-chain screening
collect_feesSweeps what the protocol has earned into its treasury
set_* / accept_adminAdmin knobs behind a 2-of-2 multisig (rates, limits, venue list, emergency pause). None of them can touch user notes
Reference

Relayer and indexer API

Plain HTTP and JSON-RPC, served through the gateway. No secrets ever leave your device.

EndpointPurpose
GET /v1/infoWho the relayer is, which venues are approved, current rates
GET /v1/fee?mint&inputsPrice check: relayer cost for this coin and this many notes
POST /v1/relayHand over a finished proof and let the relayer broadcast it
POST /v1/sponsorLets a deposit go through with the relayer covering gas, after a strict check
GET /v1/quoteWhat a private trade or lending move would return, net of protocol cut
GET /v1/positionsLive lending markets with rates and share prices
GET /v1/commitmentsThe full ordered stream of note fingerprints and ciphertexts
GET /v1/nullifiers, /v1/rootEverything already spent, plus the latest tree root
POST /rpc, WS /rpcA plain Solana RPC endpoint with live subscriptions
GET  /api/ds/tokens?side=source|destination&term=&chain=
GET  /api/ds/quotes?from=&to=&amount=
POST /api/ds/orders        { from, to, amount, address, ... }
GET  /api/ds/orders/{id}   -> status, deposit, payout
Reference

Fees

Every cost is shown before you confirm. Private sends carry no NullCash fee.

ActionProtocol feeNetwork cost
Shield0.3% addedYour wallet pays Solana gas
Pay privatelyFreeGas + rent per note
Trade or earn privately0.3% of what you put inGas + rent
Cash out0.3% of the amountGas + rent
Route to another chainBuilt into the quoteSolana gas for your deposit
Intent swap0.40% partner cut, in the quoteGas on each chain
Reference

What is public

An honest map of what the chain can and cannot see.

ActionChain seesStays sealed
ShieldingYour public wallet, the coin and the amount going inEverything that follows
Paying someoneA transfer took place, its relayer fee, how many notes were spentPayer, payee, amount, and the coin if fees are paid in private SOL
TradingThe pool swapped through an approved venueWhich person and which notes
Cashing outA one-time address received fundsWho funded it and from which notes
Going cross-chainA Solana deposit and a payout on the far sideThe processing itself and any link to your wallet
Staying safe

Good habits

The protocol hides links. Your habits decide how well.

  • Let funds sit a while between shielding and withdrawing
  • Avoid unique amounts; round numbers blend in
  • Keep some private SOL so fees do not reveal the token
  • Withdraw to a fresh address, never back to the wallet you shielded from
  • Store the recovery key offline, away from this device
No tool makes anyone 100% anonymous. NullCash removes the on-chain link; it cannot hide patterns you create yourself.