PRIV ProtocolPRIV Docs

Architecture

Complete technical overview of PRIV Protocol's monorepo structure, 4-layer stack, and Base L2 integration.

Monorepo Structure

PRIV Protocol is organized as an npm workspace monorepo with clear separation of concerns.

priv-protocol/
├── apps/
│   ├── web/          # Main dashboard (Next.js 15, React 19)
│   ├── api/          # API service (Next.js API routes)
│   ├── landing/      # Token launch landing page
│   ├── docs/         # Documentation site (Fumadocs)
│   └── mobile/       # Mobile VPN app (React Native/Expo)
├── extensions/
│   └── chrome/       # Chrome extension (Vite, Manifest V3)
├── packages/
│   ├── contracts/    # Solidity smart contracts (Foundry)
│   ├── sdk/          # @priv/sdk - Analytics SDK (<5KB)
│   ├── types/        # @priv/types - Shared TypeScript types
│   ├── ui/           # @priv/ui - Shared React components
│   └── compliance-sdk/ # B2B GDPR compliance SDK
└── supabase/
    └── functions/    # Supabase Edge Functions

Apps

User-facing applications: web dashboard, mobile app, API service, landing page, and documentation.

Packages

Shared libraries: smart contracts, SDK, TypeScript types, UI components, and compliance tools.

Extensions

Browser extensions for passive data collection with user consent.

Supabase

Edge Functions for serverless backend logic and real-time capabilities.

Technology Stack

LayerTechnologyPurpose
FrontendNext.js 15, React 19Server components, App Router
StylingTailwind CSS, shadcn/uiDesign system and components
BackendSupabase (PostgreSQL)Database, Auth, Realtime
CacheUpstash RedisRate limiting, session cache
BlockchainBase L2 (OP Stack)Token, marketplace, governance
ContractsSolidity, FoundrySmart contract development
ExtensionVite, Manifest V3Browser extension bundling
MobileReact Native, ExpoCross-platform mobile app
HostingVercelEdge deployment
TypesTypeScript (strict)End-to-end type safety

4-Layer Architecture

PRIV Protocol is built on a 4-layer architecture that separates concerns and enables scalability.

Layer 1: Frontend

The frontend layer consists of multiple user-facing applications:

ApplicationTechnologyDescription
Web DashboardNext.js 15User earnings, consent management, staking
Mobile VPNReact NativePassive mobile data collection
Browser ExtensionVite + MV3Desktop browsing data collection
Analytics SDKTypeScriptWebsite integration for publishers

Layer 2: API Layer

The API layer handles all business logic and data validation:

// API route structure
apps/api/src/app/api/v1/
├── analytics/      # SDK event ingestion
├── events/         # Event tracking
├── identify/       # User identification
├── billing/        # Stripe integration
├── marketplace/    # DataXchange API
└── user/           # User management

Key responsibilities:

  • Request validation with Zod schemas
  • Authentication via JWT and API keys
  • Rate limiting via Upstash Redis
  • CORS management (tiered by endpoint type)

Layer 3: Database

Supabase PostgreSQL provides the data layer:

-- Core tables
users              -- User accounts and profiles
api_keys           -- Hashed SDK API keys
events             -- Raw analytics events
contributions      -- User data contributions
consent_records    -- GDPR consent tracking
earnings           -- Pending/paid earnings

Features:

  • Row Level Security (RLS) for multi-tenancy
  • Real-time subscriptions for live updates
  • Generated TypeScript types via Supabase CLI

Layer 4: Blockchain

Smart contracts on Base L2 handle value transfer:

ContractAddressPurpose
PRIVToken0x...ERC20 with voting delegation
PRIVStaking0x...Stake for rewards and governance
DataXchange0x...Data listing and purchasing
PRIVGovernor0x...DAO proposal and voting
PRIVTimelock0x...Governance execution delay

Data Flow Diagrams

SDK Event Ingestion

Data Contribution Flow

Multi-Oracle Consensus

For high-value data transactions, PRIV uses multi-oracle consensus to ensure data quality:

How it works:

  1. Submission: User submits data with consent metadata
  2. Distribution: Data is sent to multiple independent oracles
  3. Validation: Each oracle scores data quality independently
  4. Consensus: Results are aggregated (2/3 majority required)
  5. Settlement: Smart contract releases payment based on quality score

Oracle criteria:

  • Data authenticity (not synthetic)
  • Consent validity (proper opt-in)
  • Format compliance (meets schema requirements)
  • Uniqueness (no duplicate submissions)

Why Base L2?

PRIV Protocol chose Base (Coinbase's Ethereum L2) for strategic reasons:

Low-Cost Transactions

Essential for high-frequency micro-payments. Gas costs are cents, not dollars.

Coinbase Integration

Direct access to 100M+ users and seamless fiat on/off ramps.

Ethereum Security

Inherits L1 security guarantees while reducing costs 100x.

EVM Equivalence

Standard Solidity tooling, Foundry, and ecosystem compatibility.

Base advantages for PRIV:

FeatureBenefit
OP StackOpen source, aligned with decentralization ethos
Fast finality2-second block times for responsive UX
Native bridgingEasy ETH/USDC bridging from mainnet
Growing ecosystemActive DeFi and social protocols

Security Architecture

PRIV implements defense-in-depth security:

Client-Side

  • All sensitive data encrypted before transmission
  • API keys never stored in plaintext
  • Content Security Policy enforcement

API Layer

  • Input validation with Zod schemas
  • Rate limiting per API key
  • CORS restrictions (tiered by endpoint type)
  • SHA-256 API key hashing

Database

  • Row Level Security (RLS) policies
  • Encrypted connections (TLS 1.3)
  • Regular automated backups

Smart Contracts

  • Timelock for governance actions
  • Multi-sig admin controls
  • Audited by [Audit Firm]
  • Bug bounty program

See the Security Overview for complete details.

Development Workflow

Prerequisites

# Required
node --version  # 18+
npm --version   # 9+

# For smart contracts
curl -L https://foundry.paradigm.xyz | bash
foundryup

Common Commands

# Install all workspace dependencies
npm install

# Run specific app in development
npm run dev --workspace=@priv/web
npm run dev --workspace=@priv/api

# Build specific package
npm run build --workspace=@priv/sdk

# Run contract tests
cd packages/contracts && forge test

# Generate Supabase types
npx supabase gen types typescript --project-id "$PROJECT_ID" > packages/types/src/database.ts

TypeScript Configuration

All packages use strict TypeScript:

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "noUncheckedIndexedAccess": true
  }
}

Next Steps

Getting Started

Install the SDK and start tracking in 5 minutes

Smart Contracts

Explore the deployed contracts on Base

API Reference

Complete API documentation

Edit on GitHub

Getting Started

Integrate PRIV analytics into your application in under 5 minutes.

Installation

Install the PRIV SDK in your project using npm, pnpm, yarn, or CDN.

On this page

Monorepo Structure
Technology Stack
4-Layer Architecture
Layer 1: Frontend
Layer 2: API Layer
Layer 3: Database
Layer 4: Blockchain
Data Flow Diagrams
SDK Event Ingestion
Data Contribution Flow
Multi-Oracle Consensus
Why Base L2?
Security Architecture
Client-Side
API Layer
Database
Smart Contracts
Development Workflow
Prerequisites
Common Commands
TypeScript Configuration
Next Steps