nova-privacy-sdk 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,55 @@
+name: Publish to npm when version changes
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "package.json"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+
+      - name: Get current package version
+        id: pkg
+        run: echo "version=$(node -p 'require(\"./package.json\").version')" >> $GITHUB_OUTPUT
+
+      - name: Check if version already exists on npm
+        id: check
+        run: |
+          PKG_NAME=$(node -p 'require("./package.json").name')
+          PUBLISHED=$(npm view $PKG_NAME versions --json | grep -o "\"${{ steps.pkg.outputs.version }}\"" || true)
+          if [ -n "$PUBLISHED" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Version ${{ steps.pkg.outputs.version }} already exists on npm. Skipping publish."
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build source
+        run: npm run build || echo "No build script defined."
+
+      - name: Publish to npm
+        if: steps.check.outputs.exists == 'false'
+        run: |
+          echo "Publishing version ${{ steps.pkg.outputs.version }}..."
+          npm publish --access public

package/PUBLISH.md

@@ -0,0 +1,122 @@
+# Publishing Nova Privacy SDK to GitHub and npm
+
+## Step 1: Create GitHub Repository
+
+1. Go to GitHub and create a new repository named `nova-privacy-sdk`
+2. **DO NOT** initialize with README, .gitignore, or license (we already have these)
+
+## Step 2: Update Repository URL in package.json
+
+Update the repository URL in `package.json`:
+
+```json
+"repository": "https://github.com/YOUR_USERNAME/nova-privacy-sdk"
+```
+
+Replace `YOUR_USERNAME` with your GitHub username.
+
+## Step 3: Initialize Git and Push to GitHub
+
+```bash
+# Initialize git (if not already initialized)
+git init
+
+# Add all files
+git add .
+
+# Create initial commit
+git commit -m "Initial commit: Nova Privacy SDK fork"
+
+# Add your GitHub repository as remote
+git remote add origin https://github.com/YOUR_USERNAME/nova-privacy-sdk.git
+
+# Push to GitHub
+git branch -M main
+git push -u origin main
+```
+
+## Step 4: Verify npm Account
+
+Make sure you have an npm account and are logged in:
+
+```bash
+# Check if logged in
+npm whoami
+
+# If not logged in, login
+npm login
+```
+
+## Step 5: Verify Package Name Availability
+
+Check if `nova-privacy-sdk` is available:
+
+```bash
+npm view nova-privacy-sdk
+```
+
+If it returns 404, the name is available. If it exists, you may need to choose a different name or use a scoped package like `@your-org/nova-privacy-sdk`.
+
+## Step 6: Build and Publish to npm
+
+```bash
+# Build the project
+npm run build
+
+# Dry run to see what would be published (recommended first)
+npm publish --dry-run
+
+# Publish to npm
+npm publish
+
+# For scoped packages (if needed), use:
+# npm publish --access public
+```
+
+## Step 7: Verify Installation
+
+After publishing, verify the package can be installed:
+
+```bash
+npm install nova-privacy-sdk
+```
+
+## Versioning
+
+For future updates:
+
+```bash
+# Update version
+npm version patch  # 1.0.0 -> 1.0.1
+npm version minor  # 1.0.0 -> 1.1.0
+npm version major  # 1.0.0 -> 2.0.0
+
+# Then publish
+npm publish
+```
+
+## Important Notes
+
+1. **README.md** - Already includes credits to Privacy Cash and link to https://www.privacycash.org/
+2. **Package name** - Using `nova-privacy-sdk` which is SEO-friendly and descriptive
+3. **Version** - Starting at 1.0.0
+4. **Repository** - Update the GitHub URL in package.json before pushing
+
+## SEO Keywords Included
+
+The package includes these keywords in package.json:
+- solana
+- privacy
+- zk
+- zero-knowledge
+- private-transactions
+- cryptocurrency
+- blockchain
+- sdk
+- nova
+- privacy-cash
+- private-withdraw
+- private-send
+- solana-privacy
+
+These will help users find the package when searching npm for privacy-related Solana SDKs.

package/README.md

@@ -0,0 +1,177 @@
+# Nova Privacy SDK
+
+SDK for Nova Privacy - Private cryptocurrency transactions on Solana. Enable private deposits, withdrawals, and transfers for SOL and SPL tokens (including NOVA token).
+
+## 🔗 Fork Information
+
+This SDK is a **fork of the Privacy Cash SDK**. 
+
+**Original Project:** [Privacy Cash](https://www.privacycash.org/)  
+**Original Repository:** [Privacy-Cash/privacy-cash-sdk](https://github.com/Privacy-Cash/privacy-cash-sdk)
+
+We extend our gratitude to the Privacy Cash team for their excellent work. This fork includes:
+- Support for Nova Privacy program (`SHLD11qQaY6h2N3ozXUWJEJitk1zGm9tvvAC7rjxpsp`)
+- NOVA token support with dedicated tree address
+- Custom SOL and NOVA tree configurations
+- Enhanced private transaction capabilities
+
+## 🚀 Features
+
+- **Private SOL Transactions** - Deposit and withdraw SOL privately
+- **Private SPL Token Transactions** - Support for NOVA, USDC, USDT, and other SPL tokens
+- **Zero-Knowledge Proofs** - Leverages zk-SNARKs for privacy
+- **Mainnet Ready** - Fully configured for Solana mainnet
+- **TypeScript Support** - Full TypeScript definitions included
+
+## 📦 Installation
+
+```bash
+npm install nova-privacy-sdk
+```
+
+or
+
+```bash
+yarn add nova-privacy-sdk
+```
+
+## 🔧 Quick Start
+
+```typescript
+import { PrivacyCash } from 'nova-privacy-sdk';
+import { Keypair } from '@solana/web3.js';
+
+// Initialize client
+const client = new PrivacyCash({
+  RPC_url: 'https://api.mainnet-beta.solana.com',
+  owner: yourPrivateKey // Keypair, number[], Uint8Array, or base58 string
+});
+
+// Deposit SOL privately
+const depositResult = await client.deposit({
+  lamports: 0.1 * 1_000_000_000 // 0.1 SOL
+});
+
+// Check private balance
+const balance = await client.getPrivateBalance();
+console.log('Private balance:', balance.lamports / 1_000_000_000, 'SOL');
+
+// Withdraw SOL privately
+const withdrawResult = await client.withdraw({
+  lamports: 0.05 * 1_000_000_000, // 0.05 SOL
+  recipientAddress: '9BWSPeFXTyQTPiPNWjWoaN6biqjktTmzMzqDpkEnova'
+});
+
+// Deposit NOVA token
+const novaMint = new PublicKey('3SkFJRqMPTKZLqKK1MmY2mvAm711FGAtJ9ZbL6r1coin');
+await client.depositSPL({
+  mintAddress: novaMint,
+  amount: 100 // 100 NOVA tokens
+});
+```
+
+## 📚 API Reference
+
+### SOL Transactions
+
+- `deposit({ lamports })` - Deposit SOL to private balance
+- `withdraw({ lamports, recipientAddress? })` - Withdraw SOL from private balance
+- `getPrivateBalance()` - Get current private SOL balance
+
+### SPL Token Transactions
+
+- `depositSPL({ mintAddress, amount, base_units })` - Deposit SPL tokens privately
+- `withdrawSPL({ mintAddress, amount, base_units, recipientAddress? })` - Withdraw SPL tokens privately
+- `getPrivateBalanceSpl(mintAddress)` - Get private balance for a specific SPL token
+
+### Utility Functions
+
+- `clearCache()` - Clear cached UTXO data
+- `setLogger(logger)` - Set custom logger function
+
+## ⚙️ Configuration
+
+The SDK uses environment variables for configuration. Create a `.env` file:
+
+```env
+# Your forked program ID
+NEXT_PUBLIC_PROGRAM_ID=SHLD11qQaY6h2N3ozXUWJEJitk1zGm9tvvAC7rjxpsp
+
+# RPC URL (optional, defaults to public mainnet)
+RPC_URL=https://api.mainnet-beta.solana.com
+
+# Tree addresses (optional, defaults configured)
+# NEXT_PUBLIC_SOL_TREE=DUnk81NBY7gUYRekT7GAwTU7jvabiVVwcMKZkRDs3dW9 (legacy)
+NEXT_PUBLIC_NOVASOL_TREE=FZfbN2fY3aj7hTwh87dKMfuVwpaEipY3TuGpmYJnsWcG (active for SOL)
+# NEXT_PUBLIC_NOVA_TREE=9CJ8jwAXJ7GrYtrMmD4gXBpTC59DMX7a91yMVpz25enZ
+# NEXT_PUBLIC_NOVA_MINT=3SkFJRqMPTKZLqKK1MmY2mvAm711FGAtJ9ZbL6r1coin
+```
+
+## 🌳 Supported Tokens
+
+- **SOL** - Native Solana token
+- **NOVA** - Nova Privacy token (`3SkFJRqMPTKZLqKK1MmY2mvAm711FGAtJ9ZbL6r1coin`)
+- **USDC** - USD Coin
+- **USDT** - Tether USD
+- **ZEC** - Zcash token
+- **ORE** - Ore token
+
+## 🔒 Privacy Features
+
+- **UTXO Model** - Uses unspent transaction outputs for privacy
+- **Zero-Knowledge Proofs** - Proves transaction validity without revealing details
+- **Encrypted Outputs** - All transaction outputs are encrypted
+- **No Linkability** - Transactions cannot be linked to sender or receiver
+
+## 📖 Examples
+
+Check the `/example` folder for complete working examples:
+
+```bash
+cd example
+npm install
+cp ../.env_sample .env
+# Edit .env with your configuration
+npx ts-node index.ts
+```
+
+## 🧪 Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run end-to-end tests (requires .env with PRIVATE_KEY and RPC_URL)
+npm run teste2e
+```
+
+## 📋 Requirements
+
+- Node.js version 24 or above
+- Solana wallet with sufficient balance for transaction fees
+
+## ⚠️ Disclaimer
+
+This SDK has been forked from Privacy Cash and modified for Nova Privacy. While based on audited code from Privacy Cash, please fully test before using in production and be aware of inherent software risks.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## 🙏 Credits
+
+This SDK is a fork of the [Privacy Cash SDK](https://github.com/Privacy-Cash/privacy-cash-sdk). 
+
+**Privacy Cash** - [https://www.privacycash.org/](https://www.privacycash.org/)
+
+Original Privacy Cash SDK was audited by Zigtur. We extend our gratitude to the Privacy Cash team for their excellent work on the original SDK.
+
+## 📝 License
+
+ISC
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📧 Support
+
+For issues and questions, please open an issue on the [GitHub repository](https://github.com/NovaShieldWallet/nova-privacy-shield).

package/__tests__/e2e.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeAll, beforeEach, type Mock } from "vitest";
+import dotenv from 'dotenv';
+import { PrivacyCash } from "../src";
+import { LAMPORTS_PER_SOL } from "@solana/web3.js";
+dotenv.config();
+const TEST_AMOUNT = 0.01
+
+describe('e2e test', async () => {
+    if (!process.env.PRIVATE_KEY) {
+        throw new Error('missing PRIVATE_KEY in .env')
+    }
+    if (!process.env.RPC_URL) {
+        throw new Error('missing RPC_URL in .env')
+    }
+
+    let client = new PrivacyCash({
+        RPC_url: process.env.RPC_URL,
+        owner: process.env.PRIVATE_KEY
+    })
+    let balance_original = await client.getPrivateBalance()
+
+    // deposit
+    await client.deposit({
+        lamports: TEST_AMOUNT * LAMPORTS_PER_SOL
+    })
+    let balance_after_deposit = await client.getPrivateBalance()
+
+    // withdraw wrong amount
+    it(`show throw error if withdraw amount less than 0.01`, async () => {
+        await expect(client.withdraw({
+            lamports: 0.005 * LAMPORTS_PER_SOL
+        })).rejects.toThrow()
+    })
+
+    // withdraw
+    let withdrawRes = await client.withdraw({
+        lamports: TEST_AMOUNT * LAMPORTS_PER_SOL
+    })
+    let balance_after_withdraw = await client.getPrivateBalance()
+
+    it('balance is a number', () => {
+        expect(balance_original.lamports).to.be.a('number')
+    })
+
+    it(`balance should be increased ${TEST_AMOUNT} sol`, () => {
+        expect(balance_after_deposit.lamports).equal(balance_after_withdraw.lamports + TEST_AMOUNT * LAMPORTS_PER_SOL)
+    })
+
+    it('should keep balance unchanged after depositing and withdrawing the same amount', () => {
+        expect(balance_original.lamports).equal(balance_after_withdraw.lamports)
+    })
+
+    it(`withdraw real amount plus fee should  be ${TEST_AMOUNT * LAMPORTS_PER_SOL}`, () => {
+        expect(withdrawRes.amount_in_lamports + withdrawRes.fee_in_lamports).equal(TEST_AMOUNT * LAMPORTS_PER_SOL)
+    })
+})

package/__tests__/e2espl.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeAll, beforeEach, type Mock } from "vitest";
+import dotenv from 'dotenv';
+import { PrivacyCash } from "../src";
+import { getAccount, getAssociatedTokenAddress } from "@solana/spl-token";
+import { FEE_RECIPIENT, USDC_MINT } from "../src/utils/constants";
+import { Connection } from "@solana/web3.js";
+dotenv.config();
+const TEST_AMOUNT = 2
+const units_per_token = 1_000_000
+describe('e2e test', async () => {
+    if (!process.env.PRIVATE_KEY) {
+        throw new Error('missing PRIVATE_KEY in .env')
+    }
+    if (!process.env.RPC_URL) {
+        throw new Error('missing RPC_URL in .env')
+    }
+
+    const connection = new Connection(process.env.RPC_URL)
+    let fee_recipient_ata = await getAssociatedTokenAddress(USDC_MINT, FEE_RECIPIENT, true)
+    let feeRecipientAccount = await getAccount(connection, fee_recipient_ata)
+    let feeRecipientBalance_before = feeRecipientAccount.amount
+
+    let client = new PrivacyCash({
+        RPC_url: process.env.RPC_URL,
+        owner: process.env.PRIVATE_KEY
+    })
+    let balance_original = await client.getPrivateBalanceUSDC()
+
+    // deposit
+    await client.depositUSDC({
+        base_units: TEST_AMOUNT * units_per_token
+    })
+    let balance_after_deposit = await client.getPrivateBalanceUSDC()
+
+    // withdraw wrong amount
+    it(`show throw error if withdraw amount less than 1`, async () => {
+        await expect(client.withdrawUSDC({
+            base_units: 0.9 * units_per_token
+        })).rejects.toThrow()
+    })
+
+    // withdraw
+    let withdrawRes = await client.withdrawUSDC({
+        base_units: TEST_AMOUNT * units_per_token
+    })
+
+    await new Promise(r => setTimeout(r, 10_000));
+
+    feeRecipientAccount = await getAccount(connection, fee_recipient_ata)
+    let feeRecipientBalance_after = feeRecipientAccount.amount
+
+    let balance_after_withdraw = await client.getPrivateBalanceUSDC()
+
+    it('balance is a number', () => {
+        expect(balance_original.base_units).to.be.a('number')
+    })
+
+    it(`balance should be increased ${TEST_AMOUNT} USDC`, () => {
+        expect(balance_after_deposit.base_units).equal(balance_after_withdraw.base_units + TEST_AMOUNT * units_per_token)
+    })
+
+    it('should keep balance unchanged after depositing and withdrawing the same amount', () => {
+        expect(balance_original.base_units).equal(balance_after_withdraw.base_units)
+    })
+
+    it(`withdraw real amount plus fee should  be ${TEST_AMOUNT * units_per_token}`, () => {
+        expect(withdrawRes.base_units + withdrawRes.fee_base_units).equal(TEST_AMOUNT * units_per_token)
+    })
+
+    it('fee recipient amount should be inceased by the withdraw fee', () => {
+        expect(withdrawRes.fee_base_units).equal(Number(feeRecipientBalance_after - feeRecipientBalance_before))
+    })
+})