ciphera-sdk

Zero-Knowledge KYC for Algorand — TypeScript/JavaScript SDK

Generate ZK proofs in the browser. Verify KYC on-chain. Zero personal data exposed.

Install

npm install ciphera-sdk

What is Ciphera?

Ciphera is a privacy-preserving zero-knowledge KYC system on Algorand. Users prove they are verified Indian adults without exposing any personal information. ZK proofs are generated entirely in the browser using snarkjs — private inputs (Aadhaar hash, wallet secret) are computed locally and then destroyed.

How it works

Step	Actor	Action
1	User	Uploads Aadhaar XML → SDK generates Groth16 ZK proof in-browser
2	Issuer	Calls verifyProof() → registers nullifier on Algorand
3	dApp	Calls verifyKYC() → checks on-chain registry

Quick Start

🌐 Browser — Generate ZK Proof

import { CipheraProver } from 'ciphera-sdk';

const prover = new CipheraProver({
  wasmUrl: 'https://your-cdn.com/kyc.wasm',
  zkeyUrl: 'https://your-cdn.com/kyc_final.zkey',
});

const result = await prover.generateProof({
  aadhaarHash: '123456789012345...',  // SHA-256 of Aadhaar XML as BN254 field element
  walletSecret: '987654321098765...',  // Random secret tied to user's wallet
  appId: 756272073,                    // NullifierRegistry app ID
  dobYear: 2000,                       // User's birth year (age >= 18 enforced by circuit)
});

console.log(result.nullifierHex);   // '3b1f8a2c...' — 32-byte hex for on-chain use
console.log(result.proveTimeMs);    // e.g. 4200ms
// → Send result.proof + result.publicSignals to your issuer backend

🖥️ Issuer Backend — Verify Proof & Register On-Chain

import { verifyProof, CipheraClient } from 'ciphera-sdk';
import verificationKey from './verification_key.json' assert { type: 'json' };

// 1. Verify the ZK proof
const verification = await verifyProof(
  verificationKey,
  proof,
  publicSignals,
  756272073  // Expected appId (prevents cross-app replay attacks)
);

if (!verification.valid) throw new Error(verification.error);

// 2. Register nullifier on Algorand Testnet
const client = new CipheraClient();
const txId = await client.registerNullifier(
  process.env.ISSUER_MNEMONIC!,
  verification.nullifierHex!,
  userWalletAddress
);

console.log('Registered:', CipheraClient.explorerTxUrl(txId));
// → https://allo.info/tx/<txid>

🏗️ dApp — Gate Access by KYC Status

import { CipheraClient } from 'ciphera-sdk';

const client = new CipheraClient();

// Check registry-level KYC
const status = await client.verifyKYC(userWalletAddress);
if (status.isVerified) {
  // Grant access
}

// Or check a specific nullifier directly
const registered = await client.isNullifierRegistered(nullifierHex);

API Reference

CipheraProver

new CipheraProver({ wasmUrl, zkeyUrl, smtDepth? })

Method	Returns	Description
generateProof(inputs)	Promise<KYCProofResult>	Generate Groth16 ZK proof entirely in-browser

ProveInputs parameters:

Parameter	Type	Required	Description
aadhaarHash	string | bigint	✅	SHA-256 of Aadhaar XML as BN254 field element
walletSecret	string | bigint	✅	Random secret binding proof to wallet
appId	number | string | bigint	✅	NullifierRegistry app ID
dobYear	number | string	✅	Year of birth (circuit enforces age ≥ 18)
currentYear	number | string	❌	Defaults to current year
merkleSiblings	string[]	❌	SMT proof path (20 elements, defaults to zeros)
merklePos	string[]	❌	SMT path bits (20 elements, defaults to zeros)

CipheraClient

new CipheraClient(config?)

Method	Returns	Description
verifyKYC(walletAddress?)	Promise<KYCStatus>	Check registry KYC status
isNullifierRegistered(hex)	Promise<boolean>	Direct nullifier box check
registerNullifier(mnemonic, hex, wallet)	Promise<string>	Register on-chain (issuer only)
getCredentialAsaId()	number	KYCRED ASA ID
CipheraClient.explorerTxUrl(txId)	string	Allo.info TX explorer URL
CipheraClient.explorerAppUrl(appId)	string	Allo.info app explorer URL

CipheraConfig options:

Option	Type	Default	Description
algodServer	string	Algorand Testnet (AlgoNode)	Custom Algod endpoint
algodToken	string	""	Algod API token
contractIds	Partial<ContractIds>	Testnet defaults	Override deployed contract IDs
wasmUrl	string	—	Path/URL to kyc.wasm
zkeyUrl	string	—	Path/URL to kyc_final.zkey

verifyProof(vk, proof, signals, appId?)

Verify a Groth16 ZK proof off-chain.

Parameter	Type	Description
verificationKey	VerificationKey	Groth16 verification key (from verification_key.json)
proof	Groth16Proof	Proof object from the browser SDK
publicSignals	string[]	Public signals array
expectedAppId	number | string	(Optional) Guard against cross-app attacks

Returns: { valid, nullifierHex?, publicSignals?, error? }

Crypto Utilities

import { mimcHash, computeNullifier, computeNullifierHex } from 'ciphera-sdk';

// Compute nullifier directly (without generating a full proof)
const hex = computeNullifierHex(aadhaarHash, appId, walletSecret);

// Low-level MiMC hash (Miyaguchi-Preneel, BN254 field)
const hash = mimcHash([field1, field2]);

Types

interface KYCProofResult {
  proof: Groth16Proof;
  publicSignals: KYCPublicSignals;
  nullifierHex: string;     // 32-byte hex for on-chain use
  proveTimeMs: number;      // Proof generation time in milliseconds
}

interface KYCStatus {
  isVerified: boolean;
  totalRegistered?: number;
  nullifier?: string;
  appId: number;
}

interface KYCPublicSignals {
  nullifier: string;        // BN254 field element (decimal string)
  merkleRoot: string;       // SMT root
  appId: string;            // Algorand app ID
  isIndian: "1";            // Circuit-enforced
  isAdult: "1";             // Circuit-enforced (age >= 18)
  isKYCVerified: "1";       // Circuit-enforced
}

Deployed Contracts (Algorand Testnet)

Contract	App ID	Explorer
NullifierRegistry	756272073	allo.info ↗
SMTRegistry	756272075	allo.info ↗
KYCBoxStorage	756272299	allo.info ↗
CredentialManager	756281076	allo.info ↗
KYCRED ASA	756281102	allo.info ↗

Links

GitHub · npm · PyPI · Issues

License

MIT © Aditya Pandey