The Veridaq Protocol Blueprint
Every contract, every circuit, every queue, every route, every rule.
This document defines the complete architecture of privacy preserving academic credential verification on Base L2.
The Vision
Academic Credential Verification Without Trust
Veridaq solves a fundamental problem: how can an employer verify a job candidate academic claims without forcing universities to expose their entire student database and without putting private student data on a public blockchain?
The answer is a cryptographic sandwich. On one side, universities commit Poseidon hashes of student credentials to Base L2. On the other side, employers generate Groth16 Zero Knowledge Proofs that verify specific claims against those commitments. The student data never appears in plaintext on any public medium.
Three distinct portals serve three distinct roles. The Institution Portal for universities to upload and manage credential batches. The Employer Portal for organizations to submit verification requests. The Admin Portal for platform governance, KYC approval, and tier management.
A Chrome Extension companion allows employers to submit verification requests directly from any webpage without opening the full portal. All cryptographic operations happen server side. The extension never sees raw student data.
Core Principles
- No PII ever written to the public ledger
- Zero Knowledge Proofs ensure mathematical verification without data exposure
- ERC 4337 Paymaster sponsors gas for FREE tier institutions
- Employers get 3 free verifications before requiring subscription
- Revocation is append only and permanently recorded on chain
- All mutable operations protected by role based access control
What Veridaq Is Not
- Not a diploma issuance platform. Institutions remain the sole source of truth for academic records.
- Not a replacement for university transcripts. It is a mathematical verification layer.
- Not a decentralized identity system. Institutions are trusted nodes.
System Topology
System Topology
Smart Contract Layer
Eight Solidity contracts deployed on Base Sepolia, compiled with Foundry 0.8.28 and tested with forge. The contracts implement a layered architecture with clear dependency boundaries. Every public function is protected by OpenZeppelin AccessControl or custom modifiers that validate caller identity against InstitutionRegistry.
InstitutionRegistry
OwnableOn chain identity for universities
CredentialRegistry
ReentrancyGuardCredential commitment storage
RevocationRegistry
OwnableAppend only revocation list
SubscriptionManager
AccessControlTier and free verification tracking
PaymasterVault
IPaymasterERC 4337 v0.6 Paymaster
ZKVerifier
AssemblyGroth16 verification
VeridaqSimpleAccount
UUPSERC 4337 SimpleAccount
SimpleAccountFactory
Create2Deterministic account deployment
Deployment Order
Cryptographic Core
Circom 2.0 Circuit Architecture
The heart of Veridaq cryptographic guarantees is a single Circom 2.0.8 circuit called CredentialVerifier. It accepts 8 private inputs from the institution and 4 public inputs visible to everyone. The circuit produces exactly one boolean output: true if and only if the private inputs correspond to the on chain commitment AND the selected claim predicate is satisfied.
Private Inputs (8)
Public Inputs (4)
Poseidon(nameHash, matricHash, cgpa, classification, courseHash, graduationYear, blindingFactor)
commitment === commitHasher.out
Poseidon(matricHash, institutionKey)
nullifier === nullHasher.out
claimType === 1 : yearValid
claimType === 2 : classification >= 2
claimType === 3 : classification >= 3
claimType === 4 : classification === 4
claimType === 5 : cgpa >= threshold
claimType === 6 : courseHash != 0 AND yearValid
claimResult === 1
Poseidon Hash Function
Veridaq uses Poseidon instead of SHA256 or Keccak256 because Poseidon is specifically designed for Zero Knowledge applications. It requires far fewer constraints in Circom circuits resulting in faster proof generation and smaller proof sizes.
Proof Lifecycle
The complete lifecycle of a credential from issuance to verification spans 10 distinct phases across three systems. Each phase is independently auditable and cryptographically bound to the previous one.
Issuance
- Institution uploads XLSX with student records
- BullMQ worker validates each row against Zod schema
- Poseidon commitment computed for each student
- AES 256 GCM encrypts plaintext attributes
- AA UserOp submitted to CredentialRegistry via Bundler
Storage
- CredentialRegistry stores commitment nullifier pair on chain
- Backend stores encrypted plaintext in PostgreSQL
- Commitment is the only data visible on the public ledger
- Nullifier enables future revocation without revealing identity
Verification
- Employer submits institution, matric number, claim type, threshold
- Backend decrypts stored credential and looks up matric hash
- SnarkJS fullProve generates Groth16 proof in ~0.7 seconds
- ZKVerifier.sol verifies proof on chain via BN254 pairing
- Result stored in VerificationRequest and returned to employer
Revocation
- Institution admin initiates revocation with reason code
- BlockchainService calls RevocationRegistry.revokeCredential
- Nullifier marked as revoked on chain permanently
- Backend updates credential status to REVOKED
- Future verification requests return CREDENTIAL_REVOKED
Credential Lifecycle Simulation
Account Abstraction
ERC 4337 Paymaster Flow
Veridaq uses ERC 4337 Account Abstraction to separate gas payment from transaction authorship. This allows the platform to sponsor transaction fees for FREE tier institutions and enables institutions to pay for their own batches from a dedicated on chain balance.
UserOperation Construction
- 1Compute sender address via SimpleAccountFactory.getAddress
- 2Encode registerBatch calldata wrapped in SimpleAccount.execute()
- 3Build UserOp with sender, nonce, initCode, callData, callGasLimit, verificationGasLimit, preVerificationGas, maxFeePerGas, maxPriorityFeePerGas
- 4Encode paymasterAndData with institutionId and batchSize for PaymasterVault
- 5Estimate gas via bundler RPC method eth_estimateUserOperationGas
- 6Check funds: FREE tier uses sponsored pool, PAID tier uses institution balance
- 7Sign userOp hash with the AA owner private key
- 8Submit via eth_sendUserOperation and poll for UserOperationEvent receipt
ERC 4337 Account Abstraction Flow
Gas Sponsorship Decision Flow
Backend Architecture
The backend is a Fastify 5 TypeScript server with 38 source files organized across 6 directories. It runs on Node.js 22 and connects to PostgreSQL 16 via Prisma ORM and Redis 7 via ioredis.
Plugin Architecture
BullMQ Batch Processing Pipeline
- 1Upload endpoint enqueues job to batch processing queue
- 2Worker picks up job with concurrency limit of 2
- 3Reads Excel via ExcelJS row by row
- 4Validates each row against Zod schema
- 5Parses classification from text labels (first class -> 4, 2.1 -> 3, etc.)
- 6Computes Poseidon commitment and nullifier via circomlibjs
- 7Encrypts plaintext attributes with AES 256 GCM
- 8Writes Batch and Credential records in a Prisma transaction
- 9Submits AA UserOp to on chain registration
- 10Updates Batch status to CONFIRMED or FAILED with error metadata
API Surface (58 Routes)
Prisma Schema 9 Models
Email Service 8 Templates
Frontend Portals
Institution Portal
- Dashboard with credential and verification stats
- Batch upload, validation, and on chain submission
- Claim definition management with 6 claim types
- Verification request review and approval workflow
- Billing with paymaster balance sync
Employer Portal
- Dashboard with verification request history
- Credential verification with institution, matric, claim type
- Real time polling for proof generation results
- Verification history with paginated search
- PDF report generation for audit trails
Admin Portal
- Institution KYC approval and tier management
- Employer KYC approval and onboarding
- Paymaster funding and balance management
- Platform statistics with real time SSE streaming
- Institution and employer deactivation
Shared UI Architecture
State Management
TanStack Query for server state with 30 second stale time. Auth context provides login, logout, and user object globally. Zustand store for toast notifications. Access token in memory only, refresh token in httpOnly cookie.
API Client
Axios instance with base URL from NEXT_PUBLIC_BACKEND_URL. Request interceptor attaches Bearer token. Response interceptor handles 401 with automatic token refresh via refresh cookie. Retry queuing prevents race conditions during concurrent refreshes.
Design System
Tailwind CSS with CSS custom properties for dark light theming. CSS variables stored as RGB triplets for opacity modifier support. Space Grotesk font for headings, IBM Plex Mono for code. Purple accent with red error and fuchsia info palette.
Auth Guards
Each portal layout component checks authentication on mount. Orbital loading animation while verifying session. Unauthenticated users redirected to login. Role based access enforced at both frontend layout and backend route levels.
Revenue Model
Revenue Sharing Architecture
Every verification credit consumed generates revenue that is split three ways automatically. The split is calculated at the service layer by the EarningsService and recorded in the EarningTransaction model. No manual reconciliation required.
Revenue Split per Credit
Covers infrastructure, gas costs, development, and operations. The platform operator manages the Alchemy RPC, Neon database, Upstash Redis, and smart contract deployment.
Earned by the issuing university. Accrues in an earnings balance. Institutions can withdraw via crypto or fiat (where supported). The institution also earns on self verifications through the institution as employer feature.
Accumulated in a dedicated pool used to subsidize on chain gas costs for FREE tier institutions. This ensures the platform can continue offering sponsored gas to new institutions.
Batch Upload Pricing
Verification Credit Packs
Institution as Employer Feature
Institutions can optionally enable employer access through their settings page. When enabled, the institution gets a linked employer profile that allows them to verify credentials directly from the Institution portal. This is useful for internal verification departments, postgraduate admissions, and interuniversity transfers.
- Controlled by the alsoEmployer boolean field on the Institution model
- Toggled during registration or through the Settings page
- Backend automatically creates a linked Employer record on enable
- Institution earns 20 percent even on self verifications
- Requires at least one admin to be configured
Earnings and Withdrawal Flow
- 1Employer consumes a verification credit
- 2EarningsService.creditVerification runs inside a Prisma transaction
- 3Transaction creates EarningTransaction with platform share, institution share, and gas pool share
- 4Institution balance and gas pool balance incremented atomically
- 5Institution views earnings summary on the Earnings page
- 6Institution initiates withdrawal through the WithdrawModal
- 7Withdrawal can be CRYPTO (ETH sent via blockchain service) or FIAT (future)
- 8Crypto withdrawal uses PLATFORM_OPERATOR_PRIVATE_KEY to send ETH
- 9Minimum withdrawal is $10. Rate is $1,669.30 per ETH
- 10Admin can view platform revenue and gas pool on the Admin Earnings page
Browser Extension
A Manifest V3 Chrome extension that enables employers to submit verification requests without opening the full web portal. The extension shares the web app session via httpOnly cookies and a short lived extension token endpoint.
Extension Components
Security Model
- Extension never sees raw student data. All cryptographic operations happen server side.
- Session shared via httpOnly cookies. Extension uses a 5 minute token obtained from the web app.
- No external permissions required beyond host access to the Veridaq backend.
- Manifest V3 with strict CSP and no eval or remote code execution.
Extension Flow
- 1User logs into the Veridaq web app
- 2Extension obtains short lived token via POST /api/auth/extension/token
- 3User navigates to any webpage and opens the extension popup
- 4Extension sends verification request to backend API with the access token
- 5Backend processes the request and returns the result
- 6Extension displays the verification result in the popup
Deployment Topology
Infrastructure Architecture
Veridaq runs on Docker Compose for local development with PostgreSQL 16 and Redis 7 as backing services. The backend and frontend run outside Docker on the host machine. Base Sepolia serves as the L2 settlement layer.
Local Development Stack
Production Deployment Checklist
- .env file with 58 Zod validated environment variables
- Prisma migrate to create database schema
- Seed script to create admin, demo institution, demo employer, and 6 claim definitions
- Contracts deployed via forge script with --broadcast --verify
- Circuit compiled and trusted setup run with Hermez Powers of Tau
- BUNDLER_ROLE granted to VERIDAQ Admin on SubscriptionManager
- Contract addresses copied to .env for backend blockchain service
- Circuit zkey and wasm paths configured for proof service
- Alchemy RPC URL configured for Base Sepolia access
- SMTP credentials configured for email notifications
Security Model
Veridaq security operates at three layers: cryptographic guarantees at the circuit level, smart contract access controls at the protocol level, and application security at the API level. Each layer enforces independent constraints that an attacker must bypass sequentially.
Cryptographic Guarantees
- Poseidon hash is one way. On chain commitments reveal zero information about the underlying plaintext.
- Groth16 proofs are sound. A false claim cannot produce a valid proof.
- Blinding factor is 128 bits of randomness injected per credential. Brute force is computationally infeasible.
- BN254 elliptic curve pairing check ensures proof integrity on chain.
- AES 256 GCM encryption protects plaintext at rest in the backend database.
Smart Contract Security
- OpenZeppelin AccessControl for role based function gating.
- ReentrancyGuard on all state mutating functions in CredentialRegistry.
- Pausable for emergency stop capability.
- CEI pattern Checks Effects Interactions strictly followed.
- InstitutionRegistry validates caller identity before any registry operation.
- PaymasterVault uses staticcall for balance reads to prevent reentrancy.
Application Security
- All API request bodies validated with Zod schema before database access.
- bcryptjs with cost factor 12 for all password hashing.
- JWTs stored exclusively in httpOnly cookies. Never in localStorage.
- Refresh token rotation with 7 day expiry and SHA 256 server side hash.
- Rate limiting on auth endpoints: 5 attempts per 15 minutes per IP.
- No eval, no Function(), no dynamic require anywhere in the codebase.
- CORS restricted to known frontend and extension origins.
- Helmet CSP headers enabled in production.
Protocol Directives
Absolute Architectural Directives
No PII on the public ledger
No student name, matric number, CGPA, course, or any personally identifiable information may ever appear in a transaction calldata or event log on Base Sepolia. Only Poseidon commitments and nullifiers are recorded on chain.
Proofs are boolean only
ZKVerifier.sol returns exactly true or false. No intermediate data, no plaintext, no metadata about the student is returned to the caller. The employer learns only whether the claim is satisfied.
Revocation is permanent and auditable
Once a nullifier is revoked on RevocationRegistry, it cannot be unrevoked. The revocation record includes a reason code and timestamp, creating a permanent audit trail.
Access control at every layer
Every API route, every smart contract function, every frontend route enforces role based access. INSTITUTION, EMPLOYER, and ADMIN roles are strictly separated and enforced independently at each layer.
Gas sponsorship is deterministic
The PaymasterVault sponsorship decision is based purely on the institution tier and batch size. No human intervention, no discretionary approval. FREE tier batches under 1000 students are always sponsored.
Plaintext is ephemeral
Student plaintext attributes exist in application memory only during proof generation. After SnarkJS fullProve completes, the plaintext buffer is cleared. The only persistent storage of plaintext is AES 256 GCM ciphertext in the database.
Institutions are the sole source of truth
Veridaq does not issue credentials. Institutions upload commitments of their own records. Veridaq provides the cryptographic verification layer. If an institution registers a false commitment, that is an institutional issue, not a protocol issue.
Verification is permissionless
Any employer with a valid account and available verification credits can verify any credential from any institution. No bilateral agreement, no API key exchange, no manual approval is required for individual verifications.
Explore the Protocol
Dive deeper into the contracts, circuit, and API documentation.