NullTrace Local is a privacy-focused Solana transaction interface powered by Light Protocol ZK compression technology. It allows users to nullify (compress), reveal (decompress), swap, and transfer tokens privately -- all from a local-first application.
- Nullify -- Convert public tokens into private, ZK-compressed state
- Reveal -- Decompress private tokens back to public state
- Private Swap -- Swap tokens without exposing your main wallet's transaction history
- Private Transfer -- Send compressed tokens to any Solana address
- Local Privacy -- Transaction history is stored locally on your machine only
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Client (React) │ <---> │ Local Server │ <---> │ Remote Operator │
│ localhost:5173 │ │ localhost:3003 │ │ (NullTrace Infra)│
└──────────────────┘ └──────────────────┘ └──────────────────┘
│ │
Wallet Adapter Light Protocol SDK
(Phantom, etc.) Solana RPC
- Client: React + Vite frontend with Solana Wallet Adapter
- Local Server: Pre-built Node.js backend that constructs transactions and interfaces with Light Protocol
- Remote Operator: NullTrace infrastructure that handles privileged swap operations (no private keys stored locally)
- Node.js v18 or higher
- npm v9 or higher
- A Solana wallet (Phantom, Solflare, etc.)
-
Clone the repository
git clone https://github.com/NullTraceBot/null-trace-local.git cd null-trace-local -
Launch the app for your OS
OS How to start Windows Double-click start.batmacOS Double-click start.commandLinux Run chmod +x start.sh && ./start.shin a terminalThe start script will automatically:
- Install dependencies for both server and client
- Create a default
.envconfig if one doesn't exist - Start the local API server on port 3003
- Start the web interface on port 5173
-
Open the app
- Navigate to http://localhost:5173
- Connect your Solana wallet
- Click Unlock to reveal your balances
If you prefer to run components individually:
cd server
npm install --omit=dev
cp .env.example .env # Edit .env to customize RPC, port, etc.
npm startcd client
npm install
npm run dev| Variable | Default | Description |
|---|---|---|
PORT |
3003 |
Port for the local API server |
RPC_URL |
https://api.mainnet-beta.solana.com |
Solana RPC endpoint |
Tip: The default public RPC endpoint has rate limits. For better performance, use a dedicated RPC provider like Helius, QuickNode, or Triton.
Converts public tokens into ZK-compressed private state. Your tokens become invisible on block explorers.
Decompresses private tokens back to your public wallet. Useful when you need to interact with DeFi protocols.
Swap tokens privately through the NullTrace operator. Your swap history is not linked to your main wallet.
Send compressed tokens directly to another Solana address in private form.
View both your public and private token balances side-by-side.
null-trace-local/
├── client/ # React frontend
│ ├── src/
│ │ ├── App.jsx # Main application component
│ │ └── main.jsx # Entry point with wallet providers
│ ├── public/
│ ├── index.html
│ ├── package.json
│ └── vite.config.js
├── server/ # Node.js backend
│ ├── dist/
│ │ └── server.js # Pre-built server bundle
│ ├── .env.example
│ └── package.json
├── sdk/ # JavaScript SDK (npm package)
│ ├── src/
│ │ └── index.js # SDK source
│ ├── package.json
│ └── README.md
├── start.bat # Windows - double-click to launch
├── start.command # macOS - double-click to launch
├── start.sh # Linux - run in terminal
├── LICENSE
└── README.md
- No private keys are stored locally. The local server never holds or generates wallet private keys.
- Transaction history is stored in a local
db/swaps.jsonfile on your machine only. - Wallet signing is always done client-side through your browser wallet extension.
- The server bundle is a pre-built binary that communicates with NullTrace operator infrastructure for swap execution.
| Issue | Solution |
|---|---|
Server bundle not found |
Ensure you cloned the full repository including server/dist/server.js |
ECONNREFUSED on port 3003 |
Make sure the server is running before using the client |
Rate limit errors |
Configure a dedicated RPC provider in server/.env |
Wallet not connecting |
Ensure you have a Solana wallet extension installed (Phantom, Solflare, etc.) |
Insufficient balance |
Check that you have enough tokens in the correct state (public vs private) |
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m 'Add my feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
Note: The server source code (
server/src/) is not included in this repository. Contributions to the server should be discussed in an issue first.
NullTrace ships a standalone JavaScript SDK for integrating privacy features into your own apps — no local server needed:
npm install nulltrace-sdk @solana/web3.js @solana/spl-token @lightprotocol/stateless.js @lightprotocol/compressed-tokenimport { NullTrace } from 'nulltrace-sdk';
const nt = new NullTrace('https://mainnet.helius-rpc.com/?api-key=YOUR_KEY', wallet);
await nt.nullify('So11...', '0.5');
await nt.reveal('So11...', '0.5');
await nt.transfer('So11...', '1.0', 'Recipient...');
await nt.swap('So11...', 'Es9v...', '1.0');
const balances = await nt.getBalances();Requires a Helius RPC endpoint (ZK compression depends on Helius's photon indexer).
Full documentation: sdk/README.md
This project is licensed under the MIT License - see the LICENSE file for details.
- NullTrace -- Official website
- Light Protocol -- ZK compression for Solana
- Solana Wallet Adapter -- Wallet integration