constructor(config: ZKMixConfig)

interface ZKMixConfig {
  /** Solana RPC connection */
  connection: Connection;

  /** Solana cluster identifier */
  cluster: "mainnet-beta" | "devnet" | "localnet";

  /** URL to the proving key file (required for browser proof generation) */
  provingKeyUrl?: string;

  /** URL to the WASM circuit file (required for browser proof generation) */
  wasmUrl?: string;

  /** Path to the proving key file (Node.js only) */
  provingKeyPath?: string;

  /** Path to the WASM circuit file (Node.js only) */
  wasmPath?: string;

  /** Override the default Mixer Program ID */
  mixerProgramId?: PublicKey;

  /** Override the default Verifier Program ID */
  verifierProgramId?: PublicKey;
}

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

const zkmix = new ZKMix({
  connection: new Connection("https://api.mainnet-beta.solana.com"),
  cluster: "mainnet-beta",
});

async deposit(params: DepositParams): Promise<DepositResult>

interface DepositParams {
  /** Wallet to sign the transaction and fund the deposit */
  wallet: Keypair | WalletAdapter;

  /** Token symbol ("SOL") or mint address for SPL tokens */
  token: string | PublicKey;

  /** Deposit amount in smallest units (lamports for SOL, base units for SPL) */
  denomination: number | bigint;

  /** Optional transaction configuration */
  options?: TransactionOptions;
}

interface TransactionOptions {
  /** Confirmation commitment level */
  commitment?: "processed" | "confirmed" | "finalized";

  /** Maximum number of retry attempts */
  maxRetries?: number;

  /** Whether to skip preflight simulation */
  skipPreflight?: boolean;

  /** Compute unit limit override */
  computeUnits?: number;

  /** Priority fee in microlamports per compute unit */
  priorityFee?: number;
}

interface DepositResult {
  /** The deposit note containing secret, nullifier, and metadata */
  note: DepositNote;

  /** The transaction signature */
  txSignature: string;

  /** The commitment hash inserted into the Merkle tree */
  commitment: string;

  /** The leaf index in the Merkle tree */
  leafIndex: number;

  /** The block time of the confirmed transaction */
  blockTime: number;
}

const result = await zkmix.deposit({
  wallet: myKeypair,
  token: "SOL",
  denomination: 1_000_000_000,
});

console.log(`Deposited! Leaf index: ${result.leafIndex}`);
// Save result.note.serialize() securely

async withdraw(params: WithdrawParams): Promise<WithdrawResult>

interface WithdrawParams {
  /** The deposit note from a previous deposit */
  deposit: DepositNote;

  /** The recipient address for the withdrawn funds */
  recipient: PublicKey;

  /** Whether to use a relayer for gas-less withdrawal */
  useRelayer?: boolean;

  /** Specific relayer URL (overrides automatic selection) */
  relayerUrl?: string;

  /** Wallet to sign and pay for the transaction (required if useRelayer is false) */
  wallet?: Keypair | WalletAdapter;

  /** Optional transaction configuration */
  options?: TransactionOptions;
}

interface WithdrawResult {
  /** The transaction signature */
  txSignature: string;

  /** The nullifier hash that was spent */
  nullifierHash: string;

  /** The relayer fee paid (0 if no relayer was used) */
  relayerFee: number;

  /** The net amount received by the recipient */
  amountReceived: number;

  /** The block time of the confirmed transaction */
  blockTime: number;
}

const result = await zkmix.withdraw({
  deposit: savedNote,
  recipient: freshAddress,
  useRelayer: true,
});

console.log(`Withdrawn! Tx: ${result.txSignature}`);
console.log(`Amount received: ${result.amountReceived} lamports`);

async getDeposits(params: GetDepositsParams): Promise<DepositEvent[]>

interface GetDepositsParams {
  /** Token symbol or mint address */
  token: string | PublicKey;

  /** Pool denomination */
  denomination: number | bigint;

  /** Starting leaf index (inclusive, default: 0) */
  fromIndex?: number;

  /** Ending leaf index (exclusive, default: latest) */
  toIndex?: number;

  /** Maximum number of events to return */
  limit?: number;
}

interface DepositEvent {
  /** The commitment hash */
  commitment: string;

  /** The leaf index in the Merkle tree */
  leafIndex: number;

  /** Unix timestamp of the deposit */
  timestamp: number;

  /** Transaction signature */
  txSignature: string;
}

// Get the last 100 deposits to the SOL-1 pool
const deposits = await zkmix.getDeposits({
  token: "SOL",
  denomination: 1_000_000_000,
  limit: 100,
});

console.log(`Found ${deposits.length} recent deposits`);
deposits.forEach((d) => {
  console.log(`  Leaf ${d.leafIndex}: ${d.commitment} at ${new Date(d.timestamp * 1000)}`);
});

async generateProof(params: GenerateProofParams): Promise<ProofData>

interface GenerateProofParams {
  /** The deposit note */
  deposit: DepositNote;

  /** The recipient address */
  recipient: PublicKey;

  /** The relayer fee (use 0 for direct withdrawals) */
  relayerFee: number | bigint;

  /** The Merkle tree state (fetched automatically if not provided) */
  treeState?: MerkleTreeState;
}

interface ProofData {
  /** The serialized proof */
  proof: {
    a: [string, string];
    b: [[string, string], [string, string]];
    c: [string, string];
  };

  /** The public inputs */
  publicInputs: {
    root: string;
    nullifierHash: string;
    recipient: string;
    fee: string;
  };

  /** Time taken to generate the proof in milliseconds */
  generationTime: number;
}

// Generate proof without submitting
const proofData = await zkmix.generateProof({
  deposit: savedNote,
  recipient: freshAddress,
  relayerFee: 3_000_000,
});

console.log(`Proof generated in ${proofData.generationTime}ms`);
console.log(`Root: ${proofData.publicInputs.root}`);
console.log(`Nullifier hash: ${proofData.publicInputs.nullifierHash}`);

// Submit the proof manually through a custom relayer
const response = await fetch("https://my-custom-relayer.com/relay", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    proof: proofData.proof,
    ...proofData.publicInputs,
    poolAddress: poolAddress.toBase58(),
  }),
});

async getPools(): Promise<PoolInfo[]>

interface PoolInfo {
  /** Pool account address */
  address: PublicKey;

  /** Token symbol */
  token: string;

  /** Token mint address */
  tokenMint: PublicKey;

  /** Denomination in smallest units */
  denomination: bigint;

  /** Human-readable denomination */
  denominationFormatted: string;

  /** Total number of deposits */
  depositCount: number;

  /** Number of withdrawals (spent nullifiers) */
  withdrawalCount: number;

  /** Current anonymity set size (deposits - withdrawals) */
  anonymitySetSize: number;

  /** Whether the pool is accepting deposits */
  isActive: boolean;

  /** Merkle tree capacity */
  treeCapacity: number;

  /** Current tree utilization (0.0 to 1.0) */
  treeUtilization: number;

  /** Vault balance in smallest units */
  vaultBalance: bigint;
}

const pools = await zkmix.getPools();

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

async getPoolInfo(token: string | PublicKey, denomination: number | bigint): Promise<PoolInfo>

const info = await zkmix.getPoolInfo("SOL", 1_000_000_000);
console.log(`Anonymity set: ${info.anonymitySetSize}`);
console.log(`Vault balance: ${info.vaultBalance} lamports`);

parseNote(noteString: string): DepositNote

const note = zkmix.parseNote("zkmix-1.0-devnet-SOL-1000000000-0x3a4b...-0x9e0f...-42");
console.log(`Token: ${note.token}`);
console.log(`Denomination: ${note.denomination}`);
console.log(`Leaf index: ${note.leafIndex}`);

async isNoteSpent(note: DepositNote): Promise<boolean>

const spent = await zkmix.isNoteSpent(savedNote);
if (spent) {
  console.log("This deposit has already been withdrawn");
} else {
  console.log("This deposit is still available for withdrawal");
}

async getRelayers(poolAddress?: PublicKey): Promise<RelayerInfo[]>

interface RelayerInfo {
  /** Relayer's Solana address */
  address: PublicKey;

  /** Relayer's HTTP endpoint */
  url: string;

  /** Fee percentage in basis points */
  feePercentage: number;

  /** Whether the relayer is currently active */
  isActive: boolean;

  /** Pools the relayer supports */
  supportedPools: PublicKey[];

  /** SOL staked by the relayer */
  stake: bigint;
}

const relayers = await zkmix.getRelayers();
console.log(`${relayers.length} relayers available`);

for (const relayer of relayers) {
  console.log(`  ${relayer.url} - ${relayer.feePercentage / 100}% fee`);
}

async verifyVaultIntegrity(token: string | PublicKey, denomination: number | bigint): Promise<VaultIntegrityResult>

interface VaultIntegrityResult {
  /** Whether the vault balance is correct */
  isValid: boolean;

  /** Expected vault balance */
  expectedBalance: bigint;

  /** Actual vault balance */
  actualBalance: bigint;

  /** Difference (0 if valid) */
  difference: bigint;
}

const integrity = await zkmix.verifyVaultIntegrity("SOL", 1_000_000_000);

if (integrity.isValid) {
  console.log("Vault integrity verified");
} else {
  console.error(
    `Vault mismatch! Expected ${integrity.expectedBalance}, ` +
    `got ${integrity.actualBalance}`
  );
}

class DepositNote {
  /** The random secret (private, never shared) */
  readonly secret: Uint8Array;

  /** The random nullifier (private, never shared) */
  readonly nullifier: Uint8Array;

  /** The commitment hash (public, stored on-chain) */
  readonly commitment: string;

  /** The nullifier hash (public, revealed during withdrawal) */
  readonly nullifierHash: string;

  /** Token identifier */
  readonly token: string;

  /** Pool denomination */
  readonly denomination: bigint;

  /** Leaf index in the Merkle tree */
  readonly leafIndex: number;

  /** Network cluster */
  readonly cluster: string;
}

serialize(): string

const noteString = note.serialize();
// "zkmix-1.0-devnet-SOL-1000000000-0x3a4b5c6d...-0x9e0f1a2b...-42"

toJSON(): object

const json = note.toJSON();
// {
//   version: "1.0",
//   cluster: "devnet",
//   token: "SOL",
//   denomination: "1000000000",
//   secret: "0x3a4b5c6d...",
//   nullifier: "0x9e0f1a2b...",
//   commitment: "0x1234abcd...",
//   leafIndex: 42
// }