{"_id":"@cheny56/zk-confidential-onchain","name":"@cheny56/zk-confidential-onchain","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cheny56/zk-confidential-onchain","version":"1.0.0","description":"Confidential smart contracts using native ZK precompile (0x16). Optimized for PQC-Quorum nodes with ~10x gas savings.","main":"lib/index.js","types":"lib/index.d.ts","exports":{".":{"require":"./lib/index.js","types":"./lib/index.d.ts"},"./lib":{"require":"./lib/index.js","types":"./lib/index.d.ts"},"./client":{"require":"./client/confidential-client.js"}},"scripts":{"test":"node examples/verify-setup.js","example:balance":"node examples/basic-balance.js","example:transfer":"node examples/transfer-simulation.js","prover:build":"cd go && go build -o ../bin/prover ./prover","prover:setup":"./bin/prover setup --out ./keys","contracts:compile":"npx hardhat compile"},"keywords":["zk","zero-knowledge","zkp","snark","groth16","gnark","privacy","confidential","token","ethereum","quorum","precompile","mimc","merkle-tree","native-verification"],"author":{"name":"cheny56"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cheny56/zk-confidential-onchain.git"},"homepage":"https://github.com/cheny56/zk-confidential-onchain#readme","bugs":{"url":"https://github.com/cheny56/zk-confidential-onchain/issues"},"devDependencies":{"hardhat":"^2.19.0","@nomicfoundation/hardhat-toolbox":"^4.0.0"},"peerDependencies":{"ethers":"^6.0.0"},"engines":{"node":">=18.0.0"},"_id":"@cheny56/zk-confidential-onchain@1.0.0","gitHead":"5aef9ba68d7f501d9ddc5b7d7da2339bebf1c6bd","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-Lc1bbpEFKNrCZP9K2DYfN9rN8+CdHhkVernRXh6RROxnwwpn6RmEuQmGS3dUjAOBKwI6V54S0HIrL3l3uMNUZA==","shasum":"ac48fffe30fd55e9a98a0e430c6c312fdd9cbdf6","tarball":"https://registry.npmjs.org/@cheny56/zk-confidential-onchain/-/zk-confidential-onchain-1.0.0.tgz","fileCount":22,"unpackedSize":115661,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC/Clmb6MA1H2r/N6slY6lc3T09srvWmJ7nnJhZbxu+UQIgZgwo00yL8OqdnJDGV3G6/WfFgcz5JmBXrYKmNMnPzBk="}]},"_npmUser":{"name":"cheny56","email":"cheny5dyh@gmail.com"},"directories":{},"maintainers":[{"name":"cheny56","email":"cheny5dyh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zk-confidential-onchain_1.0.0_1768989134468_0.2887997149066861"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-21T09:52:14.396Z","1.0.0":"2026-01-21T09:52:14.599Z","modified":"2026-01-21T09:52:14.788Z"},"maintainers":[{"name":"cheny56","email":"cheny5dyh@gmail.com"}],"description":"Confidential smart contracts using native ZK precompile (0x16). Optimized for PQC-Quorum nodes with ~10x gas savings.","homepage":"https://github.com/cheny56/zk-confidential-onchain#readme","keywords":["zk","zero-knowledge","zkp","snark","groth16","gnark","privacy","confidential","token","ethereum","quorum","precompile","mimc","merkle-tree","native-verification"],"repository":{"type":"git","url":"git+https://github.com/cheny56/zk-confidential-onchain.git"},"author":{"name":"cheny56"},"bugs":{"url":"https://github.com/cheny56/zk-confidential-onchain/issues"},"license":"MIT","readme":"# @cheny56/zk-confidential-onchain\n\n**Confidential Smart Contracts using Native ZK Precompile**\n\nA privacy-preserving token system optimized for **PQC-Quorum nodes** with native ZK support:\n- ✅ **Inputs are private** - Transfer amounts are hidden\n- ✅ **State is hidden** - Balances stored as commitments  \n- ✅ **Only proofs are public** - ZK proofs verify correctness without revealing data\n- ⚡ **Native verification** - Uses precompile at `0x16` for ~10x gas savings\n\n[![npm version](https://img.shields.io/npm/v/@cheny56/zk-confidential-onchain.svg)](https://www.npmjs.com/package/@cheny56/zk-confidential-onchain)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- ⚡ **Native Precompile** - ~500K gas vs ~5M gas for Solidity verification\n- 🔐 **Go Prover** - Uses `gnark` for fast, reliable proof generation\n- 🔒 **Full Privacy** - Balances, transfers, identities all hidden\n- 🏢 **Enterprise Ready** - Designed for PQC-Quorum private networks\n\n## Prerequisites\n\nThis package requires:\n1. **PQC-Quorum node** with ZK precompile enabled at `0x16`\n2. **Go 1.21+** for proof generation\n3. **Node.js 18+** for the client SDK\n\n## Installation\n\n```bash\nnpm install @cheny56/zk-confidential-onchain\n```\n\n## Quick Start\n\n### 1. Build the Go Prover\n\n```bash\ncd go\ngo build -o ../bin/prover ./prover\n```\n\n### 2. Use the Client\n\n```javascript\nconst { ConfidentialTokenClient } = require('@cheny56/zk-confidential-onchain/client');\n\n// Initialize client\nconst client = new ConfidentialTokenClient({\n    provider: provider,\n    signer: wallet,\n    contractAddress: '0x...',\n    proverPath: './bin/prover',  // Path to Go prover binary\n});\n\nawait client.init();\n\n// Deposit 1 ETH privately\nconst { note } = await client.deposit(ethers.parseEther('1'));\nconsole.log('Private balance:', client.getBalance());\n\n// Transfer 0.5 ETH to someone\nconst recipientSecret = client.generateRecipientSecret();\nawait client.transfer(ethers.parseEther('0.5'), recipientSecret);\n\n// Withdraw to public address\nawait client.withdraw(ethers.parseEther('0.3'), recipientAddress);\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                    ON-CHAIN ZK CONFIDENTIAL TOKEN                            │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│   ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐        │\n│   │   JavaScript    │    │   Go Prover     │    │   Quorum Node   │        │\n│   │   Client SDK    │    │   (gnark)       │    │   (Precompile)  │        │\n│   └────────┬────────┘    └────────┬────────┘    └────────┬────────┘        │\n│            │                      │                      │                 │\n│            ▼                      ▼                      ▼                 │\n│   ┌─────────────────────────────────────────────────────────────────┐      │\n│   │                                                                  │      │\n│   │   1. Client prepares transaction inputs                         │      │\n│   │   2. Client calls Go prover binary with inputs                  │      │\n│   │   3. Prover generates Groth16 proof using gnark                 │      │\n│   │   4. Client sends proof to ConfidentialToken contract           │      │\n│   │   5. Contract calls precompile at 0x16 to verify                │      │\n│   │   6. Precompile verifies in ~500K gas (vs ~5M Solidity)         │      │\n│   │                                                                  │      │\n│   └─────────────────────────────────────────────────────────────────┘      │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## Precompile Interface\n\nThe ZK precompile at address `0x16` provides:\n\n```solidity\n// Verify a Groth16 proof\nfunction verifyGroth16(\n    bytes32 vkHash,       // Hash of verification key\n    bytes proof,          // The ZK proof\n    bytes publicInputs    // Public inputs to the circuit\n) external view returns (bool);\n\n// Register a verification key\nfunction registerVK(\n    bytes vk              // Serialized verification key\n) external returns (bytes32 vkHash);\n```\n\n## Table of Contents\n\n- [How It Works](#how-it-works)\n- [Go Prover Setup](#go-prover-setup)\n- [API Reference](#api-reference)\n- [Step-by-Step Guide](#step-by-step-guide)\n- [Contract Deployment](#contract-deployment)\n- [Performance](#performance)\n- [Security Considerations](#security-considerations)\n\n## How It Works\n\n### Deposit Flow\n\n```\nUser                    Client                  Go Prover           Contract\n  │                        │                        │                   │\n  │──deposit(amount)──────>│                        │                   │\n  │                        │──generateMintProof────>│                   │\n  │                        │<──────proof────────────│                   │\n  │                        │                        │                   │\n  │                        │──────deposit(commitment, proof)───────────>│\n  │                        │                        │      ┌────────────┴────┐\n  │                        │                        │      │ staticcall 0x16 │\n  │                        │                        │      │ verifyGroth16() │\n  │                        │                        │      └────────────┬────┘\n  │<───────────────────────│<──────────────────────tx confirmed─────────│\n```\n\n### Transfer Flow (Private → Private)\n\n1. **Select input notes** - Find unspent notes totaling transfer amount\n2. **Create output notes** - Recipient note + change note\n3. **Compute nullifier** - Prevents double-spending\n4. **Generate ZK proof** - Proves ownership and value conservation\n5. **Submit transaction** - Contract verifies via precompile\n\n## Go Prover Setup\n\n### Directory Structure\n\n```\ngo/\n├── circuits/\n│   ├── mint_circuit.go      # Mint circuit definition\n│   └── transfer_circuit.go  # Transfer circuit definition\n├── prover/\n│   └── prover.go            # Main prover binary\n├── go.mod\n└── go.sum\n```\n\n### Building\n\n```bash\ncd go\ngo mod tidy\ngo build -o ../bin/prover ./prover\n```\n\n### Testing the Prover\n\n```bash\n# Generate a test proof\n./bin/prover mint \\\n  --value=1000 \\\n  --secret=0x1234... \\\n  --nonce=0x5678...\n```\n\n## API Reference\n\n### ConfidentialTokenClient\n\n```javascript\nconst client = new ConfidentialTokenClient({\n    provider,           // Ethers provider\n    signer,            // Ethers signer\n    contractAddress,   // Contract address\n    proverPath,        // Path to Go prover binary\n    demoMode,          // Skip proofs for testing (default: false)\n});\n\n// Initialize\nawait client.init(masterSecret?);\n\n// Deposit (public → private)\nconst { note, tx } = await client.deposit(amount);\n\n// Transfer (private → private)\nconst { recipientNote, changeNote, tx } = await client.transfer(amount, recipientSecret);\n\n// Withdraw (private → public)\nconst { tx } = await client.withdraw(amount, recipientAddress);\n\n// Query\nclient.getBalance();          // Total private balance\nclient.getSpendableNotes();   // Spendable notes\nclient.exportWallet();        // Backup wallet\n\n// Utility\nconst secret = client.generateRecipientSecret();  // Generate recipient secret\n```\n\n### Note\n\n```javascript\nconst { Note } = require('@cheny56/zk-confidential-onchain/lib');\n\n// Create manually\nconst note = new Note(value, ownerSecret, nonce?);\nawait note.init();\n\n// Properties\nnote.value;           // Note amount\nnote.commitment;      // Public commitment\nnote.nullifier;       // Nullifier (after tree position set)\nnote.canSpend();      // Check if spendable\n```\n\n### MerkleTree\n\n```javascript\nconst { MerkleTree } = require('@cheny56/zk-confidential-onchain/lib');\n\nconst tree = new MerkleTree(20);  // depth 20\nawait tree.init();\n\nconst index = await tree.insert(commitment);\nconst { path, indices } = await tree.generateProof(index);\nconst valid = await tree.verifyProof(leaf, index, path, indices, root);\n```\n\n## Step-by-Step Guide\n\n### Step 1: Setup Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/cheny56/zk-confidential-onchain\ncd zk-confidential-onchain\n\n# Install dependencies\nnpm install\n\n# Build Go prover\ncd go && go build -o ../bin/prover ./prover && cd ..\n```\n\n### Step 2: Deploy Contract\n\n```javascript\nconst { ethers } = require('ethers');\nconst ConfidentialToken = require('./artifacts/ConfidentialToken.json');\n\n// Connect to PQC-Quorum node\nconst provider = new ethers.JsonRpcProvider('http://localhost:8545');\nconst wallet = new ethers.Wallet(PRIVATE_KEY, provider);\n\n// Deploy contract\nconst factory = new ethers.ContractFactory(\n    ConfidentialToken.abi,\n    ConfidentialToken.bytecode,\n    wallet\n);\n\nconst token = await factory.deploy(\n    'Private Token',\n    'PRIV',\n    mintVKHash,      // Hash of mint verification key\n    transferVKHash,  // Hash of transfer verification key\n    withdrawVKHash   // Hash of withdraw verification key\n);\n\nconsole.log('Contract deployed:', await token.getAddress());\n```\n\n### Step 3: Register Verification Keys\n\n```javascript\n// The verification keys are registered on first use or can be pre-registered\n// The Go prover outputs the verification keys during setup\n\n// Register via precompile (one-time)\nconst precompile = new ethers.Contract('0x0000000000000000000000000000000000000016', [\n    'function registerVK(bytes vk) returns (bytes32)'\n], wallet);\n\nconst mintVKHash = await precompile.registerVK(mintVKBytes);\nconst transferVKHash = await precompile.registerVK(transferVKBytes);\n```\n\n### Step 4: Use the Client\n\n```javascript\nconst { ConfidentialTokenClient } = require('@cheny56/zk-confidential-onchain/client');\n\nconst client = new ConfidentialTokenClient({\n    provider,\n    signer: wallet,\n    contractAddress: await token.getAddress(),\n    proverPath: './bin/prover',\n});\n\nawait client.init();\nclient.setContract(token);\n\n// Deposit 1000 wei\nawait client.deposit(1000n);\nconsole.log('Balance:', client.getBalance());\n\n// Transfer 300 to someone\nconst recipientSecret = client.generateRecipientSecret();\nawait client.transfer(300n, recipientSecret);\n\n// Withdraw 200 to public address\nawait client.withdraw(200n, '0x...');\n```\n\n### Step 5: Verify Setup\n\n```bash\n# Run verification example\nnode examples/verify-setup.js\n```\n\n## Contract Deployment\n\n### Deploy Script\n\n```bash\nnode scripts/deploy.js\n```\n\n### Manual Deployment\n\n```javascript\nconst { ethers } = require('ethers');\n\nasync function deploy() {\n    const provider = new ethers.JsonRpcProvider('http://localhost:8545');\n    const wallet = new ethers.Wallet(PRIVATE_KEY, provider);\n    \n    // Read contract artifact\n    const artifact = require('./artifacts/ConfidentialToken.json');\n    \n    // Deploy\n    const factory = new ethers.ContractFactory(\n        artifact.abi,\n        artifact.bytecode,\n        wallet\n    );\n    \n    // Verification key hashes (from Go prover setup)\n    const mintVKHash = '0x...';\n    const transferVKHash = '0x...';\n    const withdrawVKHash = '0x...';\n    \n    const contract = await factory.deploy(\n        'Confidential Token',\n        'CONF',\n        mintVKHash,\n        transferVKHash,\n        withdrawVKHash\n    );\n    \n    await contract.waitForDeployment();\n    console.log('Deployed to:', await contract.getAddress());\n}\n```\n\n## Performance\n\n### Gas Comparison\n\n| Operation | Native Precompile | Solidity Verifier | Savings |\n|-----------|-------------------|-------------------|---------|\n| Mint      | ~400K gas         | ~3M gas           | 87%     |\n| Transfer  | ~600K gas         | ~5M gas           | 88%     |\n| Withdraw  | ~500K gas         | ~4M gas           | 87%     |\n\n### Proof Generation Time\n\n| Circuit   | Time (Go/gnark) | Time (snarkjs) |\n|-----------|-----------------|----------------|\n| Mint      | ~100ms          | ~2s            |\n| Transfer  | ~500ms          | ~10s           |\n| Withdraw  | ~300ms          | ~5s            |\n\n## Security Considerations\n\n1. **Trusted Setup**: The circuit requires a one-time trusted setup\n2. **Precompile Trust**: The native precompile must be trusted\n3. **Prover Isolation**: Run the Go prover in a secure environment\n4. **Key Management**: Protect master secrets and backups\n5. **Nullifier Tracking**: On-chain nullifier set prevents double-spending\n\n## Package Contents\n\n```\nzk-confidential-onchain/\n├── lib/\n│   ├── index.js           # Main exports\n│   ├── mimc.js            # MiMC hash (gnark compatible)\n│   ├── merkle.js          # Merkle tree\n│   └── note.js            # Note management\n├── client/\n│   └── confidential-client.js  # Contract interaction\n├── contracts/\n│   ├── ConfidentialToken.sol\n│   └── CommitmentTree.sol\n├── go/\n│   ├── circuits/          # gnark circuit definitions\n│   └── prover/            # Prover binary\n├── examples/\n│   ├── basic-balance.js\n│   ├── transfer-simulation.js\n│   └── verify-setup.js\n├── scripts/\n│   └── deploy.js\n├── package.json\n└── README.md\n```\n\n## License\n\nMIT\n\n## Related\n\n- [@cheny56/zk-confidential-offchain](../zk-confidential-offchain) - Circom/snarkjs version (any EVM)\n- [@cheny56/zk-client](../zk-client/js) - Low-level ZK RPC client\n","readmeFilename":"README.md","_rev":"1-b951fae3837258dc0931b1768354928e"}