> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zkterm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# zkToolkit

> Complete zero-knowledge cryptographic primitives library

## Overview

zkToolkit (`@zkterm/zktoolkit`) provides 10 cryptographic modules for building privacy-preserving applications. All primitives are optimized for ZK circuits.

## Module Summary

| Module        | Operations               | Description                |
| ------------- | ------------------------ | -------------------------- |
| **hash**      | poseidon, pedersen, mimc | ZK-friendly hash functions |
| **commit**    | create, reveal, verify   | Pedersen commitments       |
| **merkle**    | create, prove            | Merkle trees and proofs    |
| **range**     | prove                    | Range proofs               |
| **sign**      | keypair, sign, verify    | EdDSA signatures           |
| **nullifier** | create, verify           | Double-spend prevention    |
| **field**     | add, mul, inv, pow       | BN254 field arithmetic     |
| **ec**        | mulbase, add, isoncurve  | Baby JubJub curve          |
| **shamir**    | split, combine           | Secret sharing             |
| **proof**     | generate                 | Groth16 zkSNARKs           |

## Terminal Commands

All zkToolkit commands use the format:

```bash theme={null}
zk toolkit <category> <operation> [input]
```

### Show Help

```bash theme={null}
zk toolkit help
```

Shows all available categories and examples.

### Category Help

```bash theme={null}
zk toolkit <category> help
```

Shows detailed help for a specific category.

***

## Hash Functions

ZK-optimized hash functions with low circuit constraints.

```bash theme={null}
zk toolkit hash poseidon "hello world"
zk toolkit hash pedersen "secret"
zk toolkit hash mimc "data" --key "optional"
```

| Function | Constraints | Use Case                  |
| -------- | ----------- | ------------------------- |
| Poseidon | \~300       | Most ZK circuits          |
| Pedersen | \~1000      | Commitments (homomorphic) |
| MiMC     | \~500       | Keyed hashing             |

**Example:**

```bash theme={null}
> zk toolkit hash poseidon "hello"

Poseidon Hash Result

Input: "hello"

Hash:
  8765432109876543210987654321098765432109876543210987654321098765
```

***

## Commitments

Hide values and reveal them later with proof.

```bash theme={null}
zk toolkit commit create 100 --secret "my_secret"
zk toolkit commit reveal <commitment> 100 --secret "my_secret"
zk toolkit commit verify <commitment> 100 <salt>
```

**Use Cases:** Sealed-bid auctions, voting, commit-reveal randomness

***

## Merkle Trees

Build trees and generate inclusion proofs.

```bash theme={null}
zk toolkit merkle create alice bob charlie dave
zk toolkit merkle proof <root> <leaf> <index>
```

**Features:**

* Fixed depth 32
* Poseidon-based hashing
* Efficient proof generation

***

## Range Proofs

Prove a value lies within a range without revealing it.

```bash theme={null}
zk toolkit range prove 25 --min 18 --max 100
```

**Use Cases:** Age verification, credit score ranges, balance thresholds

***

## Signatures

EdDSA signatures on the Baby JubJub curve.

```bash theme={null}
zk toolkit sign keypair
zk toolkit sign sign <message> --privateKey <key>
zk toolkit sign verify <message> <signature> --publicKey <key>
```

***

## Nullifiers

Prevent double-spending in privacy protocols.

```bash theme={null}
zk toolkit nullifier create "my_secret" --scope "tx:001"
zk toolkit nullifier verify <nullifier> <secret> <scope>
```

**Use Cases:** Privacy coins, anonymous voting, one-time credentials

***

## Field Arithmetic

Finite field operations modulo BN254 prime.

```bash theme={null}
zk toolkit field add 5 7           # 12
zk toolkit field mul 6 7           # 42
zk toolkit field inv 5             # Modular inverse
zk toolkit field pow 2 256         # 2^256 mod p
```

**Prime:**

```
p = 21888242871839275222246405745257275088548364400416034343698204186575808495617
```

***

## Elliptic Curves

Baby JubJub twisted Edwards curve operations.

```bash theme={null}
zk toolkit ec mulbase <scalar>     # Scalar * Generator
zk toolkit ec add <x1,y1> <x2,y2>  # Point addition
zk toolkit ec isoncurve <x,y>      # Verify point on curve
```

**Curve Parameters:**

```
a = 168700
d = 168696
Equation: a*x² + y² = 1 + d*x²*y²
```

***

## Shamir Secret Sharing

Split secrets into threshold shares.

```bash theme={null}
zk toolkit shamir split "secret" --threshold 3 --shares 5
zk toolkit shamir combine <share1>,<share2>,<share3>
```

**Example:**

```bash theme={null}
# Split secret into 5 shares, need 3 to reconstruct
> zk toolkit shamir split "secret" --threshold 3 --shares 5
Share 1: 1:abc123...
Share 2: 2:def456...
Share 3: 3:ghi789...
Share 4: 4:jkl012...
Share 5: 5:mno345...

# Combine any 3 shares
> zk toolkit shamir combine 1:abc123...,2:def456...,3:ghi789...
Secret: secret
```

**Use Cases:** Multi-party key management, distributed custody, threshold signatures

***

## Groth16 Proofs

Generate zkSNARK proofs.

```bash theme={null}
zk toolkit proof generate --inputs "a=5,b=7"
```

***

## API Reference

All zkToolkit endpoints are under `/api/zk-toolkit/`.

### Hash Functions

```bash theme={null}
POST /api/zk-toolkit/hash/poseidon
Content-Type: application/json

{ "input": "hello world" }
```

**Response:**

```json theme={null}
{
  "algorithm": "Poseidon",
  "input": "hello world",
  "hash": "8765432109876543210..."
}
```

### Commitments

```bash theme={null}
POST /api/zk-toolkit/commit/create
Content-Type: application/json

{ "value": "100", "secret": "my_secret" }
```

**Response:**

```json theme={null}
{
  "commitment": "1234567890...",
  "salt": "abcdef..."
}
```

### Field Arithmetic

```bash theme={null}
POST /api/zk-toolkit/field/add
Content-Type: application/json

{ "a": "5", "b": "7" }
```

**Response:**

```json theme={null}
{
  "operation": "add",
  "a": "5",
  "b": "7",
  "result": "12"
}
```

### Elliptic Curves

```bash theme={null}
POST /api/zk-toolkit/ec/mulbase
Content-Type: application/json

{ "scalar": "12345" }
```

**Response:**

```json theme={null}
{
  "point": {
    "x": "1234567890...",
    "y": "9876543210..."
  }
}
```

***

## NPM Package

Install for use in your own applications:

```bash theme={null}
npm install @zkterm/zktoolkit
```

## Usage

```typescript theme={null}
import { hash, field, ec, shamir, proof } from '@zkterm/zktoolkit';

// Hash
const h = await hash.poseidon("hello");

// Field arithmetic
const sum = field.add(5n, 7n);

// EC operations
const point = ec.mulBase(12345n);

// Secret sharing
const shares = shamir.split(42n, 3, 5);

// Generate proof
const p = await proof.generate({ a: 5, b: 7 });
```

## Why ZK-Friendly Primitives?

Traditional cryptographic functions are inefficient in ZK circuits:

| Function | ZK Constraints |
| -------- | -------------- |
| SHA-256  | \~25,000       |
| Poseidon | \~300          |
| Pedersen | \~1,000        |
| MiMC     | \~500          |

zkToolkit uses primitives designed for algebraic operations native to ZK circuits, making proofs 10-100x more efficient.