Installation

This guide covers everything you need to install and configure Priv Protocol in your project.

Package Installation

Core Packages

Install the main Priv Protocol packages:

npm install @priv/sdk @priv/crypto @priv/common

@priv/sdk - Main client library with high-level APIs
@priv/crypto - Cryptographic utilities for stealth addresses
@priv/common - Shared constants and types

Peer Dependencies

Priv Protocol requires Solana libraries as peer dependencies:

npm install @solana/web3.js @solana/spl-token

@solana/web3.js - Solana blockchain interaction
@solana/spl-token - SPL token program utilities

Complete Installation

Install everything at once:

npm install @priv/sdk @priv/crypto @priv/common @solana/web3.js @solana/spl-token

Solana Connection Setup

Devnet Configuration

For development, connect to Solana devnet:

import { Connection, clusterApiUrl } from '@solana/web3.js';

// Use public devnet RPC
const connection = new Connection(clusterApiUrl('devnet'));

// Or use a custom RPC endpoint for better performance
const connection = new Connection('https://api.devnet.solana.com');

Mainnet Configuration

For production, use mainnet-beta:

import { Connection } from '@solana/web3.js';

// Use a reliable RPC provider
const connection = new Connection('https://api.mainnet-beta.solana.com');

// Or use a premium RPC service
const connection = new Connection('https://your-rpc-provider.com', {
  commitment: 'confirmed',
  wsEndpoint: 'wss://your-rpc-provider.com'
});

Program IDs

Priv Protocol consists of four on-chain programs. These IDs are the same across all networks:

// Program addresses (same on devnet and mainnet)
export const PROGRAM_IDS = {
  GHOST_REGISTRY: 'GYkaCmNsSBYpsfrBwxsPbR5dPhcpqVguiWSNg23NdD2H',
  PAYMENT_ESCROW: 'DkpPVJVzT6fpc7NqCdUbhAA1NPVp996Z8W8ikUqXhKo8',
  MULTISIG: '8QUdvFopS9nukXFZ8gCVheQ9DEHsqEhiXWvMKSzdEbm3',
  CONDITIONAL: '2FqiStCQC47NiQZTsvJf2KvhtLfdjPCXrD9sQLwjS2aU'
};

The SDK automatically uses these program IDs, so you don't need to configure them manually.

TypeScript Configuration

Basic Setup

Add TypeScript configuration for optimal development experience:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}

Path Aliases (Optional)

Set up path aliases for cleaner imports:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/lib/*": ["src/lib/*"],
      "@/types/*": ["src/types/*"]
    }
  }
}

Then create clean imports:

// Instead of: import { PrivClient } from '../../../lib/priv'
import { PrivClient } from '@/lib/priv';

Environment Variables

Required Variables

Set up environment variables for your application:

# .env.local
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_SOLANA_NETWORK=devnet

# Optional: Custom relayer endpoint
NEXT_PUBLIC_RELAYER_URL=https://relayer.priv.dev

Usage in Code

Access environment variables safely:

const getRpcUrl = () => {
  const url = process.env.NEXT_PUBLIC_SOLANA_RPC_URL;
  if (!url) {
    throw new Error('NEXT_PUBLIC_SOLANA_RPC_URL not configured');
  }
  return url;
};

const connection = new Connection(getRpcUrl());

Wallet Integration

Wallet Adapter Interface

Priv SDK expects a wallet adapter with this interface:

interface WalletAdapter {
  publicKey: PublicKey;
  signTransaction: (transaction: Transaction) => Promise<Transaction>;
}

Popular Wallet Integrations

Phantom Wallet

import { PublicKey } from '@solana/web3.js';

const getPhantomAdapter = () => {
  if (!window.solana?.isPhantom) {
    throw new Error('Phantom wallet not found');
  }

  return {
    publicKey: window.solana.publicKey,
    signTransaction: async (tx) => {
      return await window.solana.signTransaction(tx);
    }
  };
};

Solflare Wallet

const getSolflareAdapter = () => {
  if (!window.solflare) {
    throw new Error('Solflare wallet not found');
  }

  return {
    publicKey: window.solflare.publicKey,
    signTransaction: async (tx) => {
      return await window.solflare.signTransaction(tx);
    }
  };
};

Using @solana/wallet-adapter

For React applications, use the official wallet adapter:

npm install @solana/wallet-adapter-react @solana/wallet-adapter-wallets

import { useWallet } from '@solana/wallet-adapter-react';

const MyComponent = () => {
  const { publicKey, signTransaction } = useWallet();

  const walletAdapter = {
    publicKey: publicKey!,
    signTransaction: signTransaction!
  };

  const client = new PrivClient(connection, walletAdapter);
  // ...
};

Verification

Test Your Setup

Create a simple test to verify everything works:

import { Connection } from '@solana/web3.js';
import { PrivClient, generateMetaAddress } from '@priv/sdk';

async function testSetup() {
  try {
    // Test connection
    const connection = new Connection('https://api.devnet.solana.com');
    const version = await connection.getVersion();
    console.log('✅ Solana connection:', version);

    // Test key generation
    const { spendKeypair, viewKeypair } = generateMetaAddress();
    console.log('✅ Key generation works');

    // Test client initialization (without wallet for now)
    console.log('✅ Setup complete!');
  } catch (error) {
    console.error('❌ Setup failed:', error);
  }
}

testSetup();

Common Issues

Module Resolution Errors

If you see module resolution errors, ensure you have the correct Node.js version:

node --version  # Should be 18+
npm --version   # Should be 8+

TypeScript Errors

For TypeScript projects, you might need additional type definitions:

npm install --save-dev @types/node

Polyfill Issues (Browser)

For browser applications, you might need polyfills:

npm install buffer process

Add to your bundler config:

// webpack.config.js or vite.config.js
export default {
  define: {
    global: 'globalThis',
  },
  resolve: {
    alias: {
      buffer: 'buffer',
      process: 'process/browser',
    }
  }
};

Next Steps

With installation complete, you're ready to:

Learn Core Concepts - Understand how Priv Protocol works
Send Your First Payment - Complete step-by-step tutorial
Explore the API - Dive into detailed documentation

Getting Help

If you run into issues:

Check our Troubleshooting Guide
Join our Discord Community
Open an issue on GitHub

Installation

On this page