The ZK Payroll Dashboard is a privacy-first web application designed for managing decentralized payroll operations on the Stellar network. It leverages Zero-Knowledge Proofs (ZKPs) to ensure salary amounts and payment details remain confidential while maintaining on-chain verifiability.
- Connect Wallet: Seamless integration with Stellar-compatible wallets (Freighter, Albedo).
- Privacy-Preserving Payroll: Execute batch payroll transactions where salary amounts are hidden using ZK commitments.
- Employee Management: Register and manage employees with encrypted metadata.
- Transaction History: Verifiable history of all payroll events.
- Transaction Detail View: 🆕 Comprehensive transaction inspection with verification metadata, timestamps, and blockchain details.
- Compliance View: Optional view-key generation for auditing purposes.
- Employer Onboarding Timeline: 🆕 Activity timeline item for employer onboarding events with privacy-safe employer identifiers and setup progress.
- Cancellation Panel: 🆕 Payroll detail panel explaining why a batch was cancelled and what actions remain available, without exposing salary values.
- Approval Expiry Badge: 🆕 Badge showing whether payroll approvals are active, expiring soon, expired, or missing before execution.
- Asset Symbol Normalization Warning: 🆕 Small UI warning when an entered asset symbol is normalized (trimmed/uppercased) before validation or submission.
- Framework: Next.js 14 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- Icons: Lucide React
- Blockchain Interaction:
@zk-payroll/sdk,stellar-sdk
- Node.js 18+
- npm or yarn
- A Stellar testnet account (funded via Friendbot)
-
Clone the repository
git clone https://github.com/zkpayroll/zk-payroll-dashboard.git cd zk-payroll-dashboard -
Install dependencies
npm install
-
Configure Environment Copy the example env file and adjust values as needed:
cp .env.example .env.local
The default variables (already set for Stellar Testnet):
NEXT_PUBLIC_STELLAR_NETWORK=TESTNET NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
-
Run Development Server
npm run dev
Open http://localhost:3000 to view the dashboard.
zk-payroll-dashboard/
├── app/ # Next.js App Router pages
│ ├── globals.css # Global styles & Tailwind directives
│ ├── layout.tsx # Root layout with providers
│ └── page.tsx # Dashboard home
├── components/ # React UI components
│ ├── features/ # Feature-specific components
│ │ └── transactions/ # Transaction-related components
│ │ ├── TransactionHistory.tsx
│ │ └── TransactionDetailDrawer.tsx 🆕
│ ├── layout/ # Structural components (Sidebar, Header)
│ └── ui/ # Reusable UI elements
│ ├── button.tsx
│ ├── badge.tsx 🆕
│ ├── sheet.tsx 🆕
│ └── scroll-area.tsx 🆕
├── docs/ # Documentation 🆕
│ ├── TRANSACTION_DETAIL_FEATURE.md
│ └── TRANSACTION_DETAIL_USAGE.md
├── lib/ # Utilities and helper functions
├── public/ # Static assets
└── package.json
Click the "Connect Wallet" button in the top right header. Select your preferred Stellar wallet.
Navigate to the Dashboard tab. You will see a summary of active employees and total payroll volume. Click "Process Payroll" to initiate a ZK-proof generation for the current pay period.
Once the transaction is confirmed, it will appear in the Transaction History table. The "Verified" status indicates that the on-chain ZK verifier successfully validated the payment proof.
Click any transaction row or the "Details" button to open a comprehensive detail view that shows:
- Transaction Summary: Total amount and employee count
- Verification Status: With detailed metadata and explanations
- Zero-Knowledge Proof: Masked by default for privacy, viewable on demand
- Blockchain Details: Transaction hash with explorer link
- Timeline: Creation and verification timestamps
- Privacy Protection: Clear indication of what remains encrypted
For detailed usage instructions, see Transaction Detail Usage Guide.
- Contributor setup (env vars, run commands, install fixes) 🆕
- Dashboard setup guide (wallet, Friendbot, checklist)
- Admin recovery guide
- Wallet signing failure recovery guide 🆕
- Content style guide
Full copy-paste reference: docs/setup.md. Short version:
Env vars (cp .env.example .env.local then edit):
| Variable | Example | Notes |
|---|---|---|
NEXT_PUBLIC_STELLAR_NETWORK |
TESTNET |
Network selector |
NEXT_PUBLIC_HORIZON_URL |
https://horizon-testnet.stellar.org |
Must match network |
NEXT_PUBLIC_SOROBAN_RPC_URL |
https://soroban-testnet.stellar.org |
Soroban RPC matching network |
SESSION_SECRET |
32+ random chars (openssl rand -base64 32) |
≥32 chars or boot throws (lib/env.ts) |
ADMIN_PUBLIC_KEY |
G... (56 chars) |
Your testnet public key (Freighter → Copy Address) |
Commands (prefer npm — repo uses package-lock.json; pnpm also works):
npm install && cp .env.example .env.local # install + env
npm run dev # dev on http://localhost:3000 (or -p 3001 if busy)
npm test && npm run test:smoke # unit + critical journeys
npm run lint && npm run typecheck # lint + types
npm run build && npm start # production buildCommon install fixes: Node 18+ required (nvm install 20); missing .env.local → Invalid environment variables; SESSION_SECRET too short → regenerate; port 3000 busy → lsof -ti:3000 | xargs kill -9 or -p 3001; Freighter not detected → install/unlock/refresh + switch to Testnet. Details + full table: docs/setup.md / CONTRIBUTING.md.
Privacy: logs and tests never emit raw salary values — only asset codes and commitment hashes (see
lib/privacy/).
Contributions are welcome! Please check out the issues page. Before opening a PR, please review our Contributor Issue Validation Checklist.
This project is licensed under the MIT License - see the LICENSE file for details.