{"_id":"@0xio/pvac","_rev":"2-d395a34fdae73ab3c97719cb1288c58c","name":"@0xio/pvac","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@0xio/pvac","version":"1.0.0","keywords":["0xio","octra","pvac","fhe","homomorphic-encryption","privacy","range-proof","crypto"],"author":{"url":"https://0xio.xyz","name":"0xio Labs"},"license":"MIT","_id":"@0xio/pvac@1.0.0","maintainers":[{"name":"0xgery","email":"gery@0xio.xyz"}],"homepage":"https://github.com/0xio-xyz/0xio-pvac#readme","bugs":{"url":"https://github.com/0xio-xyz/0xio-pvac/issues"},"dist":{"shasum":"8540c0bfdc2365242163dbffd4310df19ab0bdb3","tarball":"https://registry.npmjs.org/@0xio/pvac/-/pvac-1.0.0.tgz","fileCount":21,"integrity":"sha512-Vi33lN3lzqcmOgdsYk2yK7+ETUpo0WY3hi2yY6o1qMue9lIWbaPoBRPqHxpiPj6aUEt7qNu4G6oa/3MaSVI/gw==","signatures":[{"sig":"MEQCIDlVFTFuc1xTsMcAf3TP8oOtnDfeh08ymUs2JGqU8mhPAiApsSyLDlp092VxbKhipP2xC9BvIi9+qoLufavEbeRH4Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3556495},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.esm.js","gitHead":"9b383bd01f8fb09df185cfa4de6ebea47296496e","scripts":{"build":"rollup -c","typecheck":"tsc --noEmit"},"_npmUser":{"name":"0xgery","email":"gery@0xio.xyz"},"repository":{"url":"git+https://github.com/0xio-xyz/0xio-pvac.git","type":"git"},"_npmVersion":"11.11.1","description":"PVAC-HFHE privacy primitives for Octra Network — FHE encryption, range proofs, and cipher arithmetic","directories":{},"_nodeVersion":"20.19.4","_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.8.1","rollup":"^4.0.0","typescript":"^5.9.0","@rollup/plugin-typescript":"^12.3.0","@rollup/plugin-node-resolve":"^15.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pvac_1.0.0_1777610806831_0.9681512141563962","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@0xio/pvac","version":"1.0.1","description":"PVAC-HFHE privacy primitives for Octra Network — FHE encryption, stealth addresses, confidential tokens, compliance proofs, Groth16 ZK verification","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","typecheck":"tsc --noEmit"},"keywords":["0xio","octra","pvac","fhe","homomorphic-encryption","privacy","range-proof","crypto"],"author":{"name":"0xio Labs","url":"https://0xio.xyz"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/0xio-xyz/0xio-pvac.git"},"devDependencies":{"@rollup/plugin-node-resolve":"^15.0.0","@rollup/plugin-typescript":"^12.3.0","rollup":"^4.0.0","tslib":"^2.8.1","typescript":"^5.9.0"},"gitHead":"15ceb55c01551512446703420eefd763a26c562a","_id":"@0xio/pvac@1.0.1","bugs":{"url":"https://github.com/0xio-xyz/0xio-pvac/issues"},"homepage":"https://github.com/0xio-xyz/0xio-pvac#readme","_nodeVersion":"20.19.4","_npmVersion":"11.11.1","dist":{"integrity":"sha512-rUoZH53Axh8BE056Biny6he3cXm8Uv/JAkcwYwB5Z0zbrrNeTyUzq4MaQD2omggEBeqn019Y+edx5caeareuVg==","shasum":"4a4b3baf0266714d046338b62260eab878ca5ada","tarball":"https://registry.npmjs.org/@0xio/pvac/-/pvac-1.0.1.tgz","fileCount":30,"unpackedSize":3828956,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCzJgQWbukPFBMFJWbGCAGNrDQOpZSDTjlk1x5C2t8jngIhAJBszVz8JwnIMF6bJgYgU10hMZgV/TkzmSdDQb0zdAQQ"}]},"_npmUser":{"name":"0xgery","email":"gery@0xio.xyz"},"directories":{},"maintainers":[{"name":"0xgery","email":"gery@0xio.xyz"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pvac_1.0.1_1777948476950_0.7840431672492376"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-01T04:46:46.640Z","modified":"2026-05-05T02:34:37.286Z","1.0.0":"2026-05-01T04:46:47.011Z","1.0.1":"2026-05-05T02:34:37.161Z"},"bugs":{"url":"https://github.com/0xio-xyz/0xio-pvac/issues"},"author":{"name":"0xio Labs","url":"https://0xio.xyz"},"license":"MIT","homepage":"https://github.com/0xio-xyz/0xio-pvac#readme","keywords":["0xio","octra","pvac","fhe","homomorphic-encryption","privacy","range-proof","crypto"],"repository":{"type":"git","url":"git+https://github.com/0xio-xyz/0xio-pvac.git"},"description":"PVAC-HFHE privacy primitives for Octra Network — FHE encryption, stealth addresses, confidential tokens, compliance proofs, Groth16 ZK verification","maintainers":[{"name":"0xgery","email":"gery@0xio.xyz"}],"readme":"# @0xio/pvac\n\nPrivacy primitives for Octra Network. FHE encryption, stealth addresses, confidential tokens, compliance proofs, Groth16 ZK verification, and Web Worker offloading.\n\n**Browser only (WASM).** Runs in browsers, extensions, and web workers.\n\n| Platform | Use |\n|---|---|\n| Web DApps / Browser | `@0xio/pvac` (this package) |\n| Browser Extension | `@0xio/pvac` or bundled WASM directly |\n| React Native (mobile) | `pvac-rs` native FFI (.so/.dylib) |\n| Tauri / Desktop | `pvac-rs` Rust crate |\n\n## Installation\n\n```bash\nnpm install @0xio/pvac\n```\n\nWASM module is bundled — no extra setup needed.\n\n## Modules\n\n| Module | Description | Speed |\n|---|---|---|\n| `PvacContext` | Core FHE: encrypt, decrypt, cipher arithmetic, proofs | varies |\n| `PrivateTransfer` | One-call encrypt/decrypt with progress callbacks | encrypt ~1s, decrypt 30-60s |\n| `ConfidentialBalance` | Fetch + decrypt + cache + format encrypted balances | ~2s (cached: instant) |\n| `StealthAddress` | Stealth payments: generate, send, scan, claim | ~5ms per output |\n| `ConfidentialToken` | ORC20 token with encrypted balances | ~1s per tx |\n| `ComplianceProof` | Prove balance ≥/≤/in-range without revealing value | 30-60s |\n| `ProofWorker` | Web Worker offload — proofs don't freeze UI | same, off-thread |\n| `Groth16` | BN254 ZK proof generation + on-chain verification | ~2-5s |\n\n---\n\n## Quick Start\n\n```typescript\nimport { PvacContext, initPvac, PrivateTransfer } from '@0xio/pvac';\n\n// 1. Load WASM\nconst wasm = await initPvac();\n\n// 2. Create context from wallet seed\nconst ctx = await PvacContext.create(seed, wasm, {\n  preWarm: true,\n  threads: navigator.hardwareConcurrency,\n});\n\n// 3. Encrypt 1 OCT into private balance (one call, ~1s)\nconst tx = PrivateTransfer.encrypt(ctx, 1_000_000n, (phase, pct) => {\n  console.log(`${phase}: ${pct}%`);\n});\n// tx.encrypted_data is ready for SDK callContract\n\n// 4. Decrypt back to public (one call, 30-60s with range proof)\nconst dtx = PrivateTransfer.decrypt(ctx, 500_000n, currentCipher, currentBalance, (phase, pct) => {\n  progressBar.value = pct;\n});\n```\n\n---\n\n## Private Transfers\n\nEncrypt/decrypt in one call with progress tracking.\n\n```typescript\nimport { PrivateTransfer } from '@0xio/pvac';\n\n// Public → Private (fast, ~1s)\nconst encryptTx = PrivateTransfer.encrypt(ctx, 1_000_000n, (phase, pct) => {\n  // phase: 'generating-seed' | 'encrypting' | 'commitment' | 'bound-proof' | 'encoding' | 'done'\n  updateUI(phase, pct);\n});\n\n// Private → Public (slow, 30-60s — range proof)\nconst decryptTx = PrivateTransfer.decrypt(\n  ctx,\n  500_000n,         // amount to decrypt\n  currentCipher,     // current encrypted balance (raw bytes)\n  currentBalance,    // current decrypted value\n  (phase, pct) => {\n    // phase: 'range-proof' at pct 30 = the slow part\n    progressBar.value = pct;\n  },\n);\n\n// Submit via SDK\nawait wallet.callContract({\n  contract: 'self',\n  method: encryptTx.op_type,\n  params: [],\n  encrypted_data: encryptTx.encrypted_data,\n});\n```\n\n---\n\n## Confidential Balance\n\nFetch, decrypt, cache, and display encrypted balances.\n\n```typescript\nimport { ConfidentialBalance } from '@0xio/pvac';\n\nconst balance = new ConfidentialBalance(ctx, 'http://YOUR_OCTRA_RPC:8080');\n\n// Subscribe to updates\nbalance.onUpdate((snapshot) => {\n  const formatted = ConfidentialBalance.format(snapshot, octPrice);\n  console.log(`Public: ${formatted.public} OCT`);\n  console.log(`Private: ${formatted.private} OCT`);\n  console.log(`Total: ${formatted.total} OCT ($${formatted.totalUsd})`);\n});\n\n// Fetch + decrypt (cached on second call)\nconst snapshot = await balance.fetch(myAddress, async (address) => {\n  // Sign the RPC auth challenge\n  const sig = wallet.signMessage(address);\n  return { signature: sig, publicKey: myPubKey };\n});\n\n// After encrypt/decrypt tx, invalidate cache\nbalance.invalidate(myAddress);\n```\n\n---\n\n## Stealth Addresses\n\nSend private payments that only the recipient can detect.\n\n```typescript\nimport { StealthAddress } from '@0xio/pvac';\n\n// === Sender ===\n\n// 1. Create a stealth output for the recipient\nconst { output, ephSk } = await StealthAddress.createOutput(\n  recipientViewPub,  // recipient's view public key (32 bytes)\n  1_000_000n,        // 1 OCT\n  blinding,          // 32-byte blinding factor\n);\n// output = { ephPub, tag, encAmount } — include in the transaction\n\n// === Recipient ===\n\n// 2. Derive view keypair from wallet\nconst { viewSk, viewPub } = await StealthAddress.deriveViewKeypair(privateKeyB64);\n\n// 3. Scan chain outputs to find payments addressed to you\nconst mine = await StealthAddress.scan(chainOutputs, viewSk, myAddress);\nfor (const m of mine) {\n  console.log(`Found ${m.amount} microOCT at index ${m.index}`);\n  // m.claimSecret — use to claim/spend the funds\n  // m.blinding — use for proof generation\n}\n\n// 4. Compute claim public key for spending\nconst claimPub = await StealthAddress.computeClaimPub(m.claimSecret, myAddress);\n```\n\n---\n\n## Confidential Token\n\nORC20 tokens with encrypted balances.\n\n```typescript\nimport { ConfidentialToken } from '@0xio/pvac';\n\nconst token = new ConfidentialToken(ctx, 'octTokenContractAddress...');\n\n// Get token info (cached)\nconst info = await token.info();\nconsole.log(`${info.symbol} (${info.decimals} decimals)`);\n\n// Check balance\nconst bal = await token.balanceOf(myAddress);\nconsole.log(`Balance: ${await token.formatAmount(bal)}`);\n\n// Build a private transfer\nconst tx = token.buildTransfer(recipientAddress, 500_000n, (phase, pct) => {\n  console.log(`${phase}: ${pct}%`);\n});\n// tx = { contract, method, args, encrypted_data } — ready for SDK\n\n// Approve + transferFrom\nconst approveTx = token.buildApprove(spenderAddress, 1_000_000n);\nconst fromTx = token.buildTransferFrom(ownerAddress, toAddress, 500_000n);\n```\n\n---\n\n## Compliance Proofs\n\nProve properties about encrypted balances without revealing them. For DeFi collateral checks, regulatory compliance, AML thresholds.\n\n```typescript\nimport { ComplianceProof } from '@0xio/pvac';\n\n// Prove: \"my encrypted balance ≥ 100 OCT\" (without revealing actual balance)\nconst proof = ComplianceProof.balanceAbove(\n  ctx,\n  encryptedCipher,    // your encrypted balance\n  actualBalance,       // known plaintext (for proof generation)\n  100_000_000n,        // 100 OCT threshold\n  (phase, pct) => progressBar.value = pct,\n);\n\n// Verify (on-chain or off-chain)\nconst valid = ComplianceProof.verify(ctx, proof.shiftedCipher, proof.rangeProof);\n\n// Prove: \"my balance ≤ 10,000 OCT\" (for regulatory limits)\nconst limitProof = ComplianceProof.balanceBelow(ctx, cipher, balance, 10_000_000_000n);\n\n// Prove: \"my balance is between 100 and 10,000 OCT\"\nconst rangeProof = ComplianceProof.balanceInRange(ctx, cipher, balance, 100_000_000n, 10_000_000_000n);\n```\n\n---\n\n## Web Worker Offload\n\nRange proofs take 30-60s. Don't freeze the UI.\n\n```typescript\nimport { ProofWorker } from '@0xio/pvac';\n\n// Create worker (loads WASM in background thread)\nconst worker = new ProofWorker('/wasm/pvac_rs_bg.wasm');\nawait worker.createContext(seed);\n\n// Encrypt — fast, but still off-thread\nconst enc = await worker.encrypt(1_000_000n, {\n  onProgress: (phase, pct) => console.log(`${phase}: ${pct}%`),\n});\n\n// Decrypt — the slow one, now off main thread\nconst dec = await worker.decrypt(500_000n, currentCipher, currentBalance, {\n  onProgress: (phase, pct) => {\n    progressBar.value = pct;\n    statusText.textContent = phase === 'range-proof' ? 'Generating proof...' : phase;\n  },\n});\n\n// enc.encrypted_data / dec.encrypted_data — ready for chain\n\n// Cleanup\nworker.terminate();\n```\n\n---\n\n## Groth16 ZK Proofs (BN254)\n\nGenerate and verify Groth16 zero-knowledge proofs on Octra. Uses the on-chain verifier at `oct3rzJZucw9BsS7LRWBNoKRoaBsXAhhSK4LmfRvg45ppSs`.\n\n```typescript\nimport { Groth16, loadCircuit } from '@0xio/pvac';\n\n// Load circuit (requires snarkjs as peer dep)\nconst circuit = await loadCircuit('/circuits/MyCircuit');\n\n// Generate proof\nconst { proofB64, inputsB64 } = await Groth16.prove(circuit, {\n  publicInput1: 42n,\n  publicInput2: recipientField,\n  privateWitness: secretValue,\n});\n\n// Verify on Octra (calls on-chain BN254 verifier)\nconst valid = await Groth16.verifyOnChain(proofB64, inputsB64, callerAddress);\n\n// Or verify locally (off-chain)\nconst localValid = await Groth16.verifyLocal(circuit, proof, publicSignals);\n```\n\nPeer dependency for proof generation:\n```bash\nnpm install snarkjs\n```\n\n---\n\n## Core FHE API\n\nLow-level FHE operations for advanced use cases.\n\n```typescript\nimport { PvacContext, initPvac } from '@0xio/pvac';\n\nconst wasm = await initPvac();\nconst ctx = await PvacContext.create(seed, wasm, { preWarm: true, threads: 8 });\n\n// Encrypt / Decrypt\nconst cipher = ctx.encrypt(1_000_000n);\nconst value = ctx.decrypt(cipher);                      // → 1000000n\n\n// Cipher arithmetic (homomorphic)\nconst sum = ctx.ctAdd(cipherA, cipherB);                // enc(a + b)\nconst diff = ctx.ctSub(cipherA, cipherB);               // enc(a - b)\n\n// Proofs\nconst rangeProof = ctx.makeRangeProofParallel(cipher, value);   // 15-30s\nconst boundProof = ctx.makeBoundProof(cipher, value, blinding); // <1s\nconst commitment = ctx.pedersenCommit(value, blinding);         // <1ms\n\n// Verification\nctx.verifyRangeProof(cipher, rangeProof);               // → boolean\nctx.verifyBoundProof(cipher, proof, commitment);         // → boolean\n\n// Full encrypt (encrypt + bound proof + encode in one call)\nconst result = ctx.fullEncrypt(1_000_000n);\n// result = { cipher, cipherB64, boundProof, boundProofEncoded }\n\n// Serialization (for PVAC registration)\nconst pubkey = ctx.serializePubkey();                    // ~3MB, 5-15s\n\n// Encoding\nctx.encodeCipher(cipher);       // → 'hfhe_v1|<base64>'\nctx.encodeRangeProof(proof);    // → 'rp_v1|<base64>'\nctx.encodeZeroProof(proof);     // → 'zkzp_v2|<base64>'\n```\n\n---\n\n## Requirements\n\n- **Browser only** — Chrome, Firefox, Edge, Brave\n- WebAssembly support\n- SharedArrayBuffer + COOP/COEP headers (for rayon thread parallelism)\n- ~100MB RAM for PVAC context\n- WASM module is bundled (3.2MB)\n\n## License\n\nMIT License. Copyright 2026 0xio Labs.\n","readmeFilename":"README.md"}