Aureus

A private, portable reputation layer built on the Semaphore Protocol. Aureus enables users to generate zero-knowledge identities locally, receive attestations from trusted issuers, and prove claims without revealing underlying data.

Overview

Aureus provides a framework for private reputation management:

• Identity Generation: Users create Semaphore identities client-side. A private key and public commitment are derived locally and never transmitted.
• Issuer Stamps: Authorized entities (banks, governments, platforms) can add signed attestations to an identity's public commitment. Stamps live off-chain, linked to the identity.
• Zero-Knowledge Proofs: Users can prove they hold valid stamps without revealing which stamps or their identity. This enables selective disclosure and anonymous verification.
• Wallet Integration: RainbowKit provides familiar wallet connection for on-chain interactions.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Device                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐  │
│  │  Identity Gen   │  │  Local Storage  │  │  Proof Builder │  │
│  │  (Semaphore)    │  │  (Private Key)  │  │  (ZK Circuits) │  │
│  └─────────────────┘  └─────────────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Public Commitment Only
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Smart Contracts                             │
│  ┌─────────────────┐  ┌─────────────────┐                       │
│  │  Semaphore      │  │  Stamp          │                       │
│  │  Group          │  │  Verifier       │                       │
│  │  Contract       │  │  Contract       │                       │
│  └─────────────────┘  └─────────────────┘                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Issuers                                  │
│  Banks  │  Governments  │  Platforms  │  Verification Services  │
└─────────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), React 18
Styling	Tailwind CSS
Wallet	RainbowKit, Wagmi, Viem
ZK Identity	@semaphore-protocol/identity
ZK Proofs	@semaphore-protocol/proof
Smart Contracts	Solidity 0.8.20, Hardhat
Testing	Hardhat Chai Matchers
Deployment	Ethers.js, Hardhat Deploy

Getting Started

Prerequisites

• Node.js 18+ and npm
• MetaMask or compatible wallet
• WalletConnect Project ID (free at walletconnect.com)

Installation

# Clone the repository
git clone https://github.com/yourusername/aureus.git
cd aureus

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

Configuration

Edit .env.local with your values:

# WalletConnect (required for frontend)
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

# Deployment (required for deploying contracts)
PRIVATE_KEY=your_private_key
AMOY_RPC_URL=https://rpc-amoy.polygon.technology

# Optional: Contract verification
POLYGONSCAN_API_KEY=your_polygonscan_key

Development

# Start development server
npm run dev

# Compile smart contracts
npm run compile

# Run contract tests
npm run test:contracts

# Start local Hardhat node
npm run node

Open http://localhost:3000 to view the application.

Usage Flow

1. Generate Identity

When a user first visits, they generate a Semaphore identity:

import { Identity } from "@semaphore-protocol/identity";

const identity = new Identity();
const commitment = identity.getCommitment();
const privateKey = identity.getPrivateKey();

The commitment is public; the private key stays in localStorage.

2. Receive Stamps

Issuers (banks, platforms) verify user credentials off-chain, then sign attestations:

function addStamp(address member, bytes32 stamp) external onlyIssuer;

Stamps are stored off-chain, referenced by the member's commitment.

3. Generate Proofs

Users prove claims without revealing data:

import { generateProof } from "@semaphore-protocol/proof";

const proof = await generateProof(identity, group, externalNullifier, signal);

4. Verify Proofs

dApps verify proofs on-chain:

function verifyProof(
    uint256[2] calldata signal,
    uint256[8] calldata proof,
    uint256 merkleTreeRoot
) external view returns (bool);

Smart Contracts

AureusSemaphoreGroup

Manages the Semaphore group and issuer permissions:

• join(uint256 identityCommitment) - Add identity to group
• addIssuer(address issuer) - Grant stamp permissions (admin)
• addStamp(address member, bytes32 stamp) - Add attestation (issuer only)

AureusStampVerifier

Verifies zero-knowledge proofs:

• verifyProof(...) - Validate a ZK proof against a signal
• hasValidStamp(...) - Check if member holds required stamps

Deployment

# Deploy to local Hardhat
npm run deploy:local

# Deploy to Polygon Amoy testnet
npm run deploy:amoy

After deployment, update contract addresses in .env.local.

Project Structure

aureus/
├── app/                        # Next.js application
│   ├── globals.css             # Global styles
│   ├── layout.tsx              # Root layout
│   ├── page.tsx                # Home page
│   ├── providers.tsx           # Context providers
│   └── wagmi.ts                # Wagmi config
├── contracts/                  # Solidity contracts
│   ├── AureusSemaphoreGroup.sol
│   └── AureusStampVerifier.sol
├── scripts/                    # Deployment scripts
│   └── deploy.ts
├── test/                       # Contract tests
│   └── AureusSemaphoreGroup.test.ts
├── hooks/                      # React hooks
├── lib/                        # Utilities
├── hardhat.config.ts           # Hardhat config
├── package.json
├── tailwind.config.ts          # Tailwind config
└── tsconfig.json

Available Stamps

Stamp Type	Description	Example Issuer
bank.kyc	KYC verification passed	Banks, payment processors
gov.id	Government ID verified	National ID systems
human.proof	Proof of humanity	Worldcoin, IAPs
platform.rep	Platform reputation score	Any Web2 platform

Security Considerations

• Private keys never leave the user's device
• Identity generation uses cryptographically secure randomness
• Proofs are generated client-side using circom circuits
• Contract access is controlled via role-based permissions

Roadmap

• Core identity generation
• Semaphore group integration
• Issuer stamp system
• ZK proof generation UI
• Issuer dashboard
• Example dApp integration
• Mainnet deployment

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/name)
3. Commit changes (git commit -m 'Add feature')
4. Push to branch (git push origin feature/name)
5. Open a Pull Request

License

MIT License - see LICENSE for details.