Docs/Sdk/Installation

SDK Installation

Install the ZKMix SDK

SDK Installation

The ZKMix SDK (@zkmix/sdk) is a TypeScript/JavaScript library that provides a complete interface for interacting with the ZKMix protocol. It handles deposit commitment generation, Merkle proof construction, zero-knowledge proof generation, relayer communication, and transaction building.

Installation

Install the SDK using npm, yarn, or pnpm:

bash

# npm
npm install @zkmix/sdk

# yarn
yarn add @zkmix/sdk

# pnpm
pnpm add @zkmix/sdk

Peer Dependencies

The SDK requires the following peer dependencies, which must be installed separately:

bash

npm install @solana/web3.js @coral-xyz/anchor

Required Peer Dependencies

Package	Version	Purpose
`@solana/web3.js`	`^1.87.0`	Solana RPC client and transaction building
`@coral-xyz/anchor`	`^0.29.0`	Anchor program interaction and IDL parsing

Optional Dependencies

These packages are optional but recommended for specific use cases:

Package	Version	Purpose
`@solana/spl-token`	`^0.3.0`	Required for SPL token pool interactions
`snarkjs`	`^0.7.0`	Required if generating proofs client-side
`circomlibjs`	`^0.1.7`	Poseidon hash implementation for commitments

If you plan to use SPL token pools (USDC, USDT, etc.), install the SPL token library:

bash

npm install @solana/spl-token

For client-side proof generation (required for both browser and Node.js usage), install snarkjs and circomlibjs:

bash

npm install snarkjs circomlibjs

Browser vs Node.js Setup

The ZKMix SDK works in both browser and Node.js environments, but the setup differs slightly due to the cryptographic operations involved in proof generation.

Node.js Setup

Node.js usage is straightforward. The SDK automatically uses Node.js crypto primitives and the file system for loading proving keys.

typescript

import { Connection } from "@solana/web3.js";
import { ZKMix } from "@zkmix/sdk";

const connection = new Connection("https://api.mainnet-beta.solana.com");

const zkmix = new ZKMix({
  connection,
  cluster: "mainnet-beta",
});

Node.js v18 or later is required due to the use of the native crypto.subtle API for certain hashing operations. If you are using an earlier version of Node.js, you will need to provide a polyfill or upgrade.

Browser Setup

Browser usage requires additional configuration to handle WebAssembly modules used by snarkjs for proof generation. The proving key and WASM circuit files need to be served as static assets.

typescript

import { Connection } from "@solana/web3.js";
import { ZKMix } from "@zkmix/sdk";

const connection = new Connection("https://api.mainnet-beta.solana.com");

const zkmix = new ZKMix({
  connection,
  cluster: "mainnet-beta",
  provingKeyUrl: "/assets/zkmix_proving_key.zkey",
  wasmUrl: "/assets/zkmix_circuit.wasm",
});

Static Assets

The SDK requires two static files for client-side proof generation:

File	Size	Description
`zkmix_proving_key.zkey`	~25 MB	Groth16 proving key from trusted setup
`zkmix_circuit.wasm`	~2 MB	Compiled circom circuit in WASM

These files can be downloaded from the ZKMix release assets or installed via a companion package:

bash

npm install @zkmix/circuit-assets

Then copy the files to your public/static directory:

bash

cp node_modules/@zkmix/circuit-assets/zkmix_proving_key.zkey public/assets/
cp node_modules/@zkmix/circuit-assets/zkmix_circuit.wasm public/assets/

Webpack Configuration

If you are using Webpack, you may need to configure it to handle WASM files and exclude Node.js-specific modules:

javascript

// webpack.config.js
module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
  resolve: {
    fallback: {
      crypto: require.resolve("crypto-browserify"),
      stream: require.resolve("stream-browserify"),
      buffer: require.resolve("buffer/"),
      path: false,
      fs: false,
    },
  },
};

Vite Configuration

For Vite-based projects:

typescript

// vite.config.ts
import { defineConfig } from "vite";
import wasm from "vite-plugin-wasm";

export default defineConfig({
  plugins: [wasm()],
  optimizeDeps: {
    exclude: ["@zkmix/sdk"],
  },
});

Next.js Configuration

For Next.js projects, the SDK should only be used on the client side since proof generation requires browser APIs:

typescript

// next.config.js
module.exports = {
  webpack: (config) => {
    config.experiments = {
      ...config.experiments,
      asyncWebAssembly: true,
    };
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      path: false,
    };
    return config;
  },
};

Use dynamic imports to ensure the SDK is only loaded on the client:

typescript

import dynamic from "next/dynamic";

const MixerComponent = dynamic(() => import("../components/Mixer"), {
  ssr: false,
});

TypeScript Support

The SDK is written in TypeScript and ships with full type declarations. No additional @types packages are needed.

TypeScript Configuration

The SDK requires the following minimum TypeScript configuration:

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "lib": ["ES2020", "DOM"]
  }
}

The ES2020 target is required for BigInt support, which is used extensively for field element arithmetic. If your project targets an earlier ECMAScript version, ensure that BigInt is available in your runtime environment.

Type Imports

The SDK exports all relevant types for use in your application:

typescript

import type {
  ZKMixConfig,
  DepositResult,
  WithdrawResult,
  DepositNote,
  PoolInfo,
  ProofData,
  RelayerInfo,
} from "@zkmix/sdk";

Verifying Installation

After installation, verify that everything is working correctly:

typescript

import { ZKMix } from "@zkmix/sdk";
import { Connection, clusterApiUrl } from "@solana/web3.js";

async function verify() {
  const connection = new Connection(clusterApiUrl("devnet"));
  const zkmix = new ZKMix({ connection, cluster: "devnet" });

  // Fetch available pools to confirm connectivity
  const pools = await zkmix.getPools();
  console.log(`Connected. Found ${pools.length} active pools.`);

  for (const pool of pools) {
    console.log(
      `  ${pool.token} ${pool.denominationFormatted} - ` +
      `${pool.anonymitySetSize} deposits`
    );
  }
}

verify().catch(console.error);

Expected output:

Connected. Found 7 active pools.
  SOL 0.1 SOL - 1,247 deposits
  SOL 1 SOL - 8,432 deposits
  SOL 10 SOL - 2,156 deposits
  SOL 100 SOL - 312 deposits
  USDC 100 USDC - 3,891 deposits
  USDC 1,000 USDC - 1,204 deposits
  USDC 10,000 USDC - 187 deposits

Upgrading

When upgrading the SDK, check the changelog for any breaking changes. The SDK follows semantic versioning:

bash

# Check current version
npm list @zkmix/sdk

# Upgrade to latest
npm update @zkmix/sdk

# Or install a specific version
npm install @zkmix/sdk@2.0.0

Major version bumps may include breaking changes to the API. Minor and patch versions are backward-compatible.

Back to Docs