Priv Protocol
Developers

Developer Documentation

Complete developer reference for building with PRIV protocol - SDK, crypto libraries, and architecture guides.

Developer Documentation

Welcome to the PRIV protocol developer documentation. PRIV enables private, stealth payments on Solana using advanced cryptographic techniques including stealth addresses, ECDH key exchange, and AES-256-GCM encryption.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                         │
├─────────────────┬─────────────────┬─────────────────────────┤
│   @priv/sdk     │  @priv/crypto   │     @priv/widget        │
│  High-level     │  Pure crypto    │   React components      │
│  client API     │  primitives     │   for payments          │
└─────────────────┴─────────────────┴─────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     Off-chain Layer                         │
├─────────────────────────┬───────────────────────────────────┤
│    Relayer Service      │         API Server                │
│  Transaction relay      │    REST API endpoints             │
│  Gas abstraction        │    Payment link generation        │
└─────────────────────────┴───────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      On-chain Layer                         │
├──────────────┬──────────────┬──────────────┬───────────────┤
│ Ghost        │ Payment      │ Conditional  │ Multisig      │
│ Registry     │ Escrow       │ Escrow       │ Escrow        │
│ Program      │ Program      │ Program      │ Program       │
└──────────────┴──────────────┴──────────────┴───────────────┘

Package Ecosystem

Core Packages

@priv/sdk

High-level TypeScript client for interacting with PRIV protocol. Provides the PrivClient class with methods for creating payment links, claiming payments, scanning for stealth addresses, and more.

Key Features:

  • Complete payment lifecycle management
  • Stealth address scanning and discovery
  • Automatic transaction building and signing
  • Built-in error handling and validation

@priv/crypto

Pure TypeScript cryptographic library with no Solana dependencies. Implements stealth address derivation, metadata encryption, and claim secret management using industry-standard libraries.

Key Features:

  • Ed25519 stealth address derivation
  • AES-256-GCM metadata encryption
  • Meta-address encoding/decoding
  • Constant-time cryptographic operations

Supporting Packages

@priv/common

Shared types, constants, and utilities used across all packages. Contains Solana program IDs, account structures, and common error types.

@priv/relayer-client

Client library for interacting with PRIV relayer services. Handles transaction relay, gas abstraction, and off-chain coordination.

@priv/widget

React components and hooks for building payment UIs. Provides drop-in components for payment links, claim forms, and transaction status.

Quick Start

Installation

npm install @priv/sdk @priv/crypto

Basic Usage

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

// Initialize client
const connection = new Connection('https://api.mainnet-beta.solana.com');
const client = new PrivClient(connection, wallet);

// Generate recipient meta-address
const metaAddress = generateMetaAddress();
const encodedAddress = encodeMetaAddress(
  metaAddress.spendPubkey, 
  metaAddress.viewPubkey
);

// Create payment link
const result = await client.createPaymentLink({
  recipientMetaAddress: encodedAddress,
  amount: BigInt(1000000), // 1 USDC (6 decimals)
  tokenMint: new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
  expirySeconds: 7 * 24 * 60 * 60 // 7 days
});

console.log('Payment URL:', result.paymentUrl);

Program IDs

ProgramMainnetDevnet
Ghost RegistryGhostR3gistryProgramId...GhostR3gistryProgramId...
Payment EscrowPaymentEscrowProgramId...PaymentEscrowProgramId...
Conditional EscrowConditionalEscrowProgram...ConditionalEscrowProgram...
Multisig Escrow8QUdvFopS9nukXFZ8gCVheQ9DEHsqEhiXWvMKSzdEbm38QUdvFopS9nukXFZ8gCVheQ9DEHsqEhiXWvMKSzdEbm3

Next Steps

Support

On this page