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/cryptoBasic 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
| Program | Mainnet | Devnet |
|---|---|---|
| Ghost Registry | GhostR3gistryProgramId... | GhostR3gistryProgramId... |
| Payment Escrow | PaymentEscrowProgramId... | PaymentEscrowProgramId... |
| Conditional Escrow | ConditionalEscrowProgram... | ConditionalEscrowProgram... |
| Multisig Escrow | 8QUdvFopS9nukXFZ8gCVheQ9DEHsqEhiXWvMKSzdEbm3 | 8QUdvFopS9nukXFZ8gCVheQ9DEHsqEhiXWvMKSzdEbm3 |
Next Steps
- Architecture Overview - Deep dive into system design
- SDK Reference - Complete API documentation
- Crypto Library - Cryptographic primitives
- Integration Guide - Step-by-step integration
- Examples - Code samples and tutorials
Support
- GitHub: github.com/priv-protocol/priv
- Discord: discord.gg/priv
- Documentation: docs.priv.xyz