NixProtocol Documentation

import { NixAuditorClient } from '@nixprotocol/nix-wallet';

// Initialize auditor client with the designated Grumpkin private key
const auditorClient = new NixAuditorClient({
  auditorPrivateKey: process.env.AUDITOR_GRUMPKIN_KEY,
  poolAddress: '0x94e5f37c557dA9B2C0F0636BbCDB3743B30Ba6B1', // NixPool on Fuji
});

// Decrypt ECIES-encrypted note data from on-chain events
const decryptedNotes = await auditorClient.decryptPoolNotes({
  fromBlock: 1000000,
  toBlock: 'latest',
});

// Generate compliance report from decrypted data
const report = await auditorClient.generateComplianceReport({
  notes: decryptedNotes,
  fromDate: '2025-01-01',
  toDate: '2025-12-31',
});

import { NixRelayer } from '@nixprotocol/relayer';

const relayer = new NixRelayer({
  url: 'https://relayer.nixprotocol.com',
  chainId: 43113, // Avalanche Fuji testnet
});

// User signs, relayer pays gas
const result = await relayer.sendPrivateTransfer({
  signer: userSigner,           // User's wallet (MetaMask, etc.)
  token: USDC_ADDRESS,
  recipient: recipientAddress,
  proof: transferProof,
  feeToken: USDC_ADDRESS,       // Pay fee in USDC
  maxFee: ethers.parseUnits('1', 6), // Max 1 USDC fee
});

console.log('Tx hash:', result.txHash);

// server.ts - Your own relayer backend
import { NixRelayerServer } from '@nixprotocol/relayer/server';

const relayer = new NixRelayerServer({
  privateKey: process.env.RELAYER_PRIVATE_KEY,
  rpcUrl: process.env.RPC_URL,
  supportedTokens: [USDC, USDT, DAI],
  feePercentage: 0.1, // 0.1% fee
});

// Validate and execute meta-transactions
app.post('/relay', async (req, res) => {
  const { signedRequest } = req.body;

  // Verify signature and fee payment
  const isValid = await relayer.verifyRequest(signedRequest);
  if (!isValid) return res.status(400).json({ error: 'Invalid request' });

  // Execute on-chain
  const result = await relayer.execute(signedRequest);
  res.json({ txHash: result.hash });
});

import { NixError, NixErrorCode } from '@nixprotocol/nix-wallet';

try {
  const tx = await nixPool.privateTransfer(recipient, proof);
  await tx.wait();
} catch (error) {
  if (error instanceof NixError) {
    switch (error.code) {
      case NixErrorCode.INVALID_PROOF:
        // Regenerate proof with fresh randomness
        const newProof = await generateTransferProof(/*...*/);
        break;
      case NixErrorCode.INSUFFICIENT_BALANCE:
        // Show user their actual balance
        const balance = await getDecryptedBalance();
        throw new Error(`Insufficient balance: ${balance}`);
      default:
        console.error('Nix error:', error.message);
    }
  }
  throw error;
}

// Key Generation
function deriveNixKeyFromSignature(walletClient: WalletClient): Promise<NixKeyPair>;
function generateNixKeyPair(): NixKeyPair;
function importNixKey(privateKeyHex: string): NixKeyPair;
function exportNixKey(keyPair: NixKeyPair): string;

interface Point {
  x: bigint;
  y: bigint;
}

interface NixKeyPair {
  privateKey: bigint;       // Grumpkin scalar
  publicKey: Point;         // Grumpkin curve point
  commitment: bigint;       // Poseidon2(pk.x, pk.y)
}

// ECIES Encryption
namespace ecies {
  function encrypt(value: bigint, randomness: bigint, receiverPk: Point): ECIESCiphertext;
  function decrypt(sk: bigint, authKeyX: bigint, authKeyY: bigint, encrypted: bigint): bigint;
}

interface ECIESCiphertext {
  authKeyX: bigint;
  authKeyY: bigint;
  encrypted: bigint;
}

// Poseidon2 Hash
function poseidon2Hash(inputs: bigint[]): bigint;
function computeCommitment(pkx: bigint, pky: bigint): bigint;

// Note Commitments
function createNoteCommitment(value: bigint, pubKey: Point, salt: bigint): bigint;

// Proof Generation
function generateRegistrationProof(keyPair: NixKeyPair): Promise<ProofResult>;
function generateDepositProof(params: DepositParams): Promise<ProofResult>;
function generateTransactProof(params: TransactParams): Promise<ProofResult>;

interface ProofResult {
  proof: `0x${string}`;        // UltraHonk proof bytes
  publicInputs: `0x${string}`[];
}

// NixAddress encoding/decoding
function encodeNixAddress(data: NixAddressData): string;
function decodeNixAddress(nixAddress: string): NixAddressData;
function nixAddressFromKeyPair(keyPair: NixKeyPair): string;

interface NixAddressData {
  commitment: bigint;           // Poseidon2(pk.x, pk.y)
  publicKey: Point;             // Grumpkin curve point
}
// Format: "nix:<commitment>:<pk.x>:<pk.y>"

// NixWallet class - high-level wallet interface
class NixWallet {
  static create(config: NixWalletConfig): Promise<NixWallet>;
  register(): Promise<void>;
  deposit(token: Address, amount: bigint): Promise<void>;
  transfer(recipientNixAddress: string, amount: bigint): Promise<void>;
  withdraw(token: Address, amount: bigint, to: Address): Promise<void>;
  syncBalances(): Promise<void>;
  exportPrivateKey(): string;
}

go get github.com/nixprotocol/poseidon2-go

func Hash(inputs []fr.Element) fr.Element
func Hash2(a, b fr.Element) fr.Element
func HashToBytes(inputs []fr.Element) [32]byte
func Permute(s *[4]fr.Element)

package main

import (
    "fmt"
    poseidon2 "github.com/nixprotocol/poseidon2-go"
    "github.com/consensys/gnark-crypto/ecc/bn254/fr"
)

func main() {
    var a, b fr.Element
    a.SetUint64(1)
    b.SetUint64(2)

    h := poseidon2.Hash2(a, b)
    fmt.Println("hash:", h.String())

    raw := poseidon2.HashToBytes([]fr.Element{a, b})
    fmt.Printf("bytes: %x\n", raw)
}

npm install @nixprotocol/mcp-server

# Add to your MCP config (e.g. claude_desktop_config.json)
{
  "mcpServers": {
    "nixprotocol": {
      "command": "npx",
      "args": ["@nixprotocol/mcp-server"],
      "env": {
        "NIX_RPC_URL": "https://api.avax-test.network/ext/bc/C/rpc",
        "NIX_CONTRACT_ADDRESS": "0x94e5...",
        "NIX_CHAIN_ID": "43113",
        "NIX_CIRCUIT_PATH": "./circuits",
        "NIX_RELAYER_URL": "https://relayer.nixprotocol.com"
      }
    }
  }
}

# Clone and run your own relayer
npm install @nixprotocol/relayer

# Configure environment
export PRIVATE_KEY="0x..."
export RPC_URL="https://api.avax-test.network/ext/bc/C/rpc"
export PORT=3001

# Start
npx nix-relayer

import { decryptAuditorNote, decryptRecipientCommitment } from '@nixprotocol/sdk';

// Auditor decrypts a deposit note
const note = decryptAuditorNote(
  encryptedCiphertext,
  auditorPrivateKey
);
console.log('Amount:', note.amount);
console.log('Blinding:', note.blinding);

// Auditor decrypts recipient identity
const recipient = decryptRecipientCommitment(
  recipientCiphertext,
  auditorPrivateKey
);

import { PoolClient } from '@nixprotocol/sdk';
import { createPublicClient, http } from 'viem';
import { avalancheFuji } from 'viem/chains';

const publicClient = createPublicClient({
  chain: avalancheFuji,
  transport: http(),
});

const pool = new PoolClient({
  contractAddress: '0x94e5...',
  publicClient,
});

// Fetch all notes from the pool
const notes = await pool.getNotes();

// Check if a nullifier has been spent
const spent = await pool.isSpent(nullifierHash);

import { NoteManager } from '@nixprotocol/sdk';

const noteManager = new NoteManager({
  poolClient,
  privateKey: nixPrivateKey,
});

// Scan for new notes (uses IndexedDB cache)
await noteManager.scan();

// Get spendable balance
const balance = noteManager.getBalance();
console.log('Balance:', balance.toString());

// Get unspent notes for building transactions
const notes = noteManager.getUnspentNotes();