PVAC SDK (@0xio/pvac) - 0xio Documentation

Overview

@0xio/pvac (v1.0.2) provides standalone FHE (Fully Homomorphic Encryption) primitives for DApps that need to work with encrypted balances on Octra Network. It runs entirely client-side via WASM: no wallet extension dependency for cryptographic operations. The primitives are built on the Ristretto255 group (curve25519-dalek): exponential-ElGamal ciphers, Bulletproofs-style range proofs, and Pedersen commitments.

PVAC’s confidentiality rests on the discrete-log hardness assumption (Ristretto255). It is not lattice-based and is not post-quantum / quantum-safe.

Use @0xio/pvac for FHE crypto, and @0xio/sdk for wallet signing. They work together:

Package	Purpose
`@0xio/pvac`	Encrypt, decrypt, proofs, cipher math
`@0xio/sdk`	Connect wallet, sign transactions, broadcast

Installation

npm install @0xio/pvac

Quick Start

import { PvacContext, initPvac } from '@0xio/pvac';

// 1. Initialize WASM module
const wasm = await initPvac();

// 2. Create context from wallet seed (seed must be exactly 32 bytes)
const seed = new Uint8Array(32); // derive from wallet key
const ctx = await PvacContext.create(seed, wasm);

// For parallel range proofs, opt into the rayon thread pool:
// const ctx = await PvacContext.create(seed, wasm, { preWarm: true, threads: 8 });

// 3. Encrypt an amount
const cipher = ctx.encrypt(100_000_000n); // 100 OCT in microOCT

// 4. Create proofs
const blinding = crypto.getRandomValues(new Uint8Array(32));
const boundProof = ctx.makeBoundProof(cipher, 100_000_000n, blinding);
const commitment = ctx.pedersenCommit(100_000_000n, blinding);

API Reference

Encryption

Method	Description
`encrypt(value)`	Encrypt an amount (bigint)
`encryptSeeded(value, seed)`	Encrypt with deterministic seed
`encryptZero()`	Encrypt zero (for account initialization)
`decrypt(cipher)`	Decrypt a cipher to bigint

Cipher Arithmetic

Method	Description
`ctAdd(a, b)`	Add two ciphers: `enc(a) + enc(b) = enc(a+b)`
`ctSub(a, b)`	Subtract: `enc(a) - enc(b) = enc(a-b)`

Proofs

Method	Description	Time
`makeBoundProof(cipher, value, blinding)`	Prove cipher encrypts specific value	~100ms
`makeRangeProof(cipher, value)`	Prove decrypted value ≥ 0	30-60s
`makeRangeProofParallel(cipher, value)`	Parallel range proof (rayon): requires `threads` in `create()`	15-30s
`pedersenCommit(value, blinding)`	Create Pedersen commitment	~1ms
`verifyRangeProof(cipher, proof)`	Verify a range proof	~100ms
`verifyBoundProof(cipher, proof, commitment)`	Verify a bound proof	~50ms

Private DEX Example

import { PvacContext, initPvac } from '@0xio/pvac';
import { ZeroXIOWallet } from '@0xio/sdk';

// Setup
const wasm = await initPvac();
const ctx = await PvacContext.create(seed, wasm);
const wallet = new ZeroXIOWallet({ appName: 'My DEX' });
await wallet.initialize();
await wallet.connect();

// Open private account on pool contract
const pubkey = ctx.serializePubkey();
const zeroCipher = ctx.encryptZero();
const blinding = crypto.getRandomValues(new Uint8Array(32));
const zeroProof = ctx.makeBoundProof(zeroCipher, 0n, blinding);
const rangeProof = ctx.makeRangeProof(zeroCipher, 0n);

await wallet.callContract({
  contract: 'octYourPoolAddress...',
  method: 'open_private_account',
  params: [
    btoa(String.fromCharCode(...pubkey)),
    btoa(String.fromCharCode(...zeroCipher)),
    btoa(String.fromCharCode(...zeroProof)),
    btoa(String.fromCharCode(...rangeProof)),
  ],
  amount: 0,
});

Subtracting a Public Amount

To subtract a known amount from an encrypted balance (e.g., after a swap):

// Subtract 50 OCT from encrypted balance
const amountCipher = ctx.encrypt(50_000_000n);
const newBalance = ctx.ctSub(currentCipher, amountCipher);

// Prove remaining balance ≥ 0
const proof = ctx.makeRangeProof(newBalance, expectedNewValue);

This is mathematically identical to fhe_sub_const. Both produce enc(balance - amount).

Network Proof Rules

Each network states which proof rules it accepts. 0xio wallets read them before any private action and again right before signing.

Where: octra_pvacMigrationStatus for the address. proof_math is "wide" or "prior" and sets the challenge arithmetic. proof_key (true or false) says whether proofs are bound to the registered encryption key.
Fallback: when the answer has no proof_math, only the devnet runtime the Octra reference client lists (read from octra_runtimeVersion) counts, and it means wide arithmetic without key binding.
No rules: a network that states neither gets no private operation from the wallet. The user sees that private actions are paused, and nothing is sent.
Rules changed: when the rules read right before signing differ from the ones the proofs were built under, nothing is sent and the action is prepared again.
Key binding: on a proof_key network every key switch carries owner_cipher and owner_proof, a proof that the sender owns the key being registered.
Migration: when the network opens its cipher proof route, a balance held under an older key migrates with a cipher_proof payload instead of the older migration format.

A proof built under one setting fails under the other. If your dApp builds proofs itself, check the same status first: a proof that does not match the network’s rules is refused.

Platform Support

Platform	Package	Notes
Browser / Web DApp	`@0xio/pvac`	Full support via WASM
Browser Extension	`@0xio/pvac`	Same WASM, runs in page context
React Native	`pvac-rs` FFI	Native ARM binary
Desktop (Tauri)	`pvac-rs` crate	Native Rust
Node.js	Not supported	No WASM threading

When your DApp calls wallet.callContract(), the 0xio extension shows an approval popup:

Amount = native value sent to the contract. amount is raw micro-OCT (1 OCT = 1000000) and is passed to the wallet as is; amountOct takes OCT and is converted by the SDK. Set amount: 0 if none.
Fee = OU (operational units / gas). Shown separately below the amount.

If you see a non-zero amount and expect 0, check your amount parameter.

Overview

Installation

Quick Start

API Reference

Encryption

Cipher Arithmetic

Proofs

Private DEX Example

Subtracting a Public Amount

Network Proof Rules

Platform Support

Approval Popup