Privacyx SDK

The Privacyx SDK provides a clean, unified JavaScript/TypeScript interface to interact with the PrivacyX Standards Framework (PXP).

PrivacyX introduces a family of privacy-preserving access primitives using zero-knowledge proofs, Merkle commitments, and nullifier-based anti-replay.

Current modules:

• PXP-101 — Balance Pass (fully implemented & live)
• PXP-102 — Identity Pass (read-only methods live, proof submission experimental)
• PXP-103 — Reputation Pass (future module)

🚀 Live modules & documentation

PXP-101 dApp (demo / reference)

https://pass.privacyx.tech

PXP-101 Standard Specification

https://github.com/Privacyx-org/privacyx-balance-pass/blob/main/PXP-101.md

PXP-102 Standard Specification (Draft)

https://github.com/Privacyx-org/privacyx-balance-pass/blob/main/PXP-102.md

PXP-102 Live Deployment (mainnet)

• Network: Ethereum mainnet (chainId: 1)
• IdentityPass contract:
  0x2b8899B3ACDe63Fd5ABefa0D75d5982622665498
• Status API (reference deployment):
  Base URL: https://identitypass-api.privacyx.tech

Examples:

# Healthcheck
curl https://identitypass-api.privacyx.tech/health

# Demo issuer + nullifier (requires x-api-key in production)
curl -H "x-api-key: YOUR_API_KEY" \
  https://identitypass-api.privacyx.tech/pxp-102/status/default

# Generic issuer / nullifier lookup
curl -H "x-api-key: YOUR_API_KEY" \
  "https://identitypass-api.privacyx.tech/pxp-102/status?issuer=0xISSUER&nullifier=0xNULLIFIER"

Playground dApp (Status + dev integrations):
https://identitypass.privacyx.tech

📦 Installation

npm install privacyx-sdk ethers

🧭 Usage (PXP-101: Balance Pass)

import { PrivacyX } from "privacyx-sdk";
import { BrowserProvider } from "ethers";

const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const px = PrivacyX({
  chainId: 1,
  provider,
  balancePassAddress: "0x8333b589ad3A8A5fCe735631e8EDf693C6AE0472",
});

// Read Merkle root & threshold
await px.balancePass.getRoot();
await px.balancePass.getThreshold();

// Submit Groth16 proof
await px.balancePass.submitProof(signer, proof, [root, nullifierHash]);

// Listen to AccessGranted events
px.balancePass.onAccessGranted((ev) => {
  console.log("ZK Access:", ev);
});

🔒 ZK Helpers — Groth16 IO parsing

The SDK exposes utilities to parse Groth16 proofs and public signals (snarkjs-compatible), shared across PXP-101 and PXP-102.

import {
  parseGroth16Proof,
  parsePubSignals,
} from "privacyx-sdk";

// Proof parser
const proof = parseGroth16Proof(proofJson);
// → { pi_a: bigint[3], pi_b: bigint[3][2], pi_c: bigint[3] }

// Public signals parser
const pubSignals = parsePubSignals(pubSignalsJson, expectedLength);
// → bigint[]

These utilities ensure:

• consistent bigint conversion
• validated JSON shape
• predictable input format across passes

Example usage: examples/identity-parse.example.mjs

📚 SDK Modules Overview

✅ PXP-101 — Balance Pass (implemented)

Allows users to prove they meet an off-chain balance threshold without revealing wallet or holdings.

Features:

• Read current Merkle root
• Read required threshold
• Check nullifier usage
• Submit Groth16 proofs
• Listen to AccessGranted events

Standard:
👉 https://github.com/Privacyx-org/privacyx-balance-pass/blob/main/PXP-101.md

🧩 PXP-102 — Identity Pass (read-only live, proofs experimental)

Enables users to prove possession of a valid identity attestation without revealing personal data or wallet address.

Read-only methods are wired to the mainnet deployment.
Proof submission helpers are experimental (0.2.x planned).

➤ Import & read-only usage

import { JsonRpcProvider } from "ethers";
import { IdentityPass } from "privacyx-sdk";

const provider = new JsonRpcProvider(process.env.RPC_URL);

const idPass = new IdentityPass({
  chainId: 1,
  provider,
  address: "0x2b8899B3ACDe63Fd5ABefa0D75d5982622665498",
});

// Read Merkle root
const root = await idPass.getCurrentRoot(issuerHex);

// Check nullifier usage
const used = await idPass.isNullifierUsed(nullifierHex);

➤ Proof submission (experimental)

await idPass.submitProof(signer, proof, [root, issuerHash, nullifierHash]);
// → TransactionReceipt

idPass.onIdentityPassUsed((event) => {
  console.log(event);
});
// → unsubscribe function

⚠️ Production-ready today:
getCurrentRoot and isNullifierUsed (used by official Status API).

⚠️ Experimental:
submitProof and event wiring.

➤ Standards & Contracts

Draft spec:
👉 https://github.com/Privacyx-org/privacyx-balance-pass/blob/main/PXP-102.md

Reference contracts:
👉 https://github.com/Privacyx-org/privacyx-identity-pass

🛰 PXP-102 Status API (reference server)

A small Express server packaged in this SDK:

• File: examples/identity-pass-mainnet-status-api.example.mjs
• Docs: PXP102_STATUS_API.md

Exposes:

• GET /health
• GET /pxp-102/status/default
• GET /pxp-102/status?issuer=0x...&nullifier=0x...

Typical backend usage:

import axios from "axios";

const BASE_URL =
  process.env.PXP102_STATUS_API_BASE_URL ??
  "https://identitypass-api.privacyx.tech";

export async function checkIdentityStatus(issuerHex, nullifierHex) {
  const res = await axios.get(`${BASE_URL}/pxp-102/status`, {
    headers: { "x-api-key": process.env.PXP102_API_KEY },
    params: { issuer: issuerHex, nullifier: nullifierHex },
  });

  return res.data;
}

Security:
Status API should run behind your infrastructure → attach API-key → never expose RPC secrets.

🧩 PXP-103 — Reputation Pass (future)

Will enable zero-knowledge proofs of:

• stake-based reputation
• governance participation
• historical activity
• time-based eligibility

Without revealing the underlying identity or history.

Current placeholder:

import { ReputationPass } from "privacyx-sdk";

const repPass = new ReputationPass({
  chainId: 1,
  provider,
  address: "0x...",
});

🔖 Versioning

• v0.1.x — PXP-101 implemented
• v0.2.x — PXP-102 read-only + proof helpers
• v0.3.x — PXP-103
• v1.0.0 — Full PXP suite stabilized

📄 License

MIT