Skip to main content

System Architecture

This document provides an overview of the Lunarys confidential DEX architecture built on Zama's fhEVM.

System Overview​

Lunarys is a decentralized exchange that maintains complete privacy through Fully Homomorphic Encryption. The system consists of two independent but complementary subsystems:

1. PrivacyPool System​

Confidential AMM for private token swaps with encrypted liquidity.

Read Pool Architecture →

Key Components:

  • PrivacyPool: AMM contract with encrypted reserves
  • PrivacyPoolFactory: Pool deployment and registry
  • Hook Contracts: Extensible integrations

Features:

  • Encrypted reserve accounting
  • Private swap execution
  • Oracle-based settlement
  • Extensible hook system

2. DAO Governance System​

Encrypted governance with confidential voting and treasury management.

Read DAO Architecture →

Key Components:

  • ConfidentialGovernor: Proposal and voting management
  • ConfidentialGovernanceToken: ERC7984 governance token
  • ConfidentialTimelock: Delayed execution controller
  • ConfidentialTreasury: Fund management

Features:

  • Encrypted voting power
  • Private vote tallying
  • Timelock security
  • Confidential fund disbursement

Technology Stack​

Zama fhEVM​

All contracts utilize Zama's Fully Homomorphic Encryption:

Encrypted Types:

  • euint8 - 8-bit encrypted unsigned integer
  • euint16 - 16-bit encrypted unsigned integer
  • euint64 - 64-bit encrypted unsigned integer (primary type)
  • euint128 - 128-bit encrypted unsigned integer
  • ebool - Encrypted boolean

Operations:

  • Arithmetic: FHE.add(), FHE.sub(), FHE.mul(), FHE.div()
  • Comparison: FHE.lt(), FHE.gt(), FHE.eq(), FHE.gte()
  • Logical: FHE.and(), FHE.or(), FHE.not()
  • Conditional: FHE.select(condition, ifTrue, ifFalse)

Smart Contracts​

Language: Solidity ^0.8.24

Libraries:

  • OpenZeppelin: Access control, reentrancy protection
  • Zama fhEVM: Encryption operations
  • ERC7984: Confidential token standard

Network: Ethereum Sepolia Testnet (Chain ID: 11155111)

Frontend​

Framework: Next.js 15 with React

Key Libraries:

  • fhevmjs: Zama's FHE SDK for encryption
  • ethers.js: Blockchain interaction
  • Reown: Wallet connection (WalletConnect)
  • shadcn/ui: UI components

Core Principles​

Privacy Through FHE​

All sensitive data remains encrypted on-chain:

Never Revealed:

  • Token balances
  • Pool reserves
  • Swap amounts
  • Vote weights
  • Vote tallies

Only Revealed:

  • Transaction occurred (events)
  • Addresses involved
  • Proposal outcomes (passed/failed)
  • Public metadata

Oracle-Based Decryption​

When plaintext values are needed:

  1. Contract requests decryption via FHE.requestDecryption()
  2. Off-chain oracle service receives request
  3. Oracle decrypts using threshold cryptography
  4. Oracle calls callback with plaintext and proof
  5. Contract verifies proof via FHE.checkSignatures()
  6. Execution continues with decrypted value

Security: Multiple oracle nodes, threshold signatures, no single point of decryption

Permission Model​

Each encrypted value has an Access Control List:

// Grant permission to address
FHE.allow(encryptedValue, recipientAddress);

// Grant permission to contract
FHE.allowThis(encryptedValue);

Required for:

  • Contract operations on encrypted values
  • User decryption of their own data
  • Hook contract access to encrypted handles

Project Structure​

Lunarys-Dex/
├── fhevm-hardhat-template/
│   ├── contracts/
│   │   ├── PrivacyPool.sol
│   │   ├── PrivacyPoolFactory.sol
│   │   ├── PositionNFT.sol
│   │   ├── interfaces/
│   │   └── dao/
│   │       ├── ConfidentialGovernor.sol
│   │       ├── ConfidentialGovernanceToken.sol
│   │       ├── ConfidentialTimelock.sol
│   │       ├── ConfidentialTreasury.sol
│   │       └── ConfidentialEmissionsController.sol
│   └── test/
│
├── frontend/
│   ├── app/
│   ├── components/
│   ├── hooks/
│   └── providers/
│
└── docs-web/
    └── docs/

Deployment​

Contract Deployment Order​

  1. Deploy ConfidentialGovernanceToken
  2. Deploy ConfidentialTimelock
  3. Deploy ConfidentialGovernor
  4. Deploy ConfidentialTreasury
  5. Deploy ConfidentialEmissionsController
  6. Deploy PrivacyPoolFactory
  7. Create pools via factory

Configuration​

Post-deployment:

  • Grant roles to contracts (proposer, executor)
  • Configure governance parameters
  • Set timelock delays
  • Approve operators for token transfers
  • Configure hooks on pools

Security Model​

Access Control​

Pool Owner:

  • Bootstrap liquidity
  • Configure hooks
  • Transfer ownership

DAO Admin:

  • Cancel malicious proposals
  • Adjust governance parameters
  • Emergency operations

Timelock:

  • Execute approved proposals
  • Control treasury
  • Manage emissions

Reentrancy Protection​

All state-changing functions use nonReentrant modifier.

Encrypted Data​

All sensitive values stored as euintX types, never in plaintext.

Performance​

Gas Costs​

FHE operations are more expensive than standard EVM:

OperationApproximate Gas
Pool bootstrap~800K
Swap initiation~600K
Swap settlement~400K
Proposal creation~300K
Vote casting~250K

Optimization​

  • Batch operations when possible
  • Minimize FHE operations in loops
  • Cache decrypted values appropriately
  • Use efficient data structures

Integration​

For Developers​

Frontend Integration:

import { useFhevmDex } from "@/providers/fhevm-dex-provider";
import { useDAO } from "@/hooks/useDAO";

// Use FHE instance
const { fhevm, account } = useFhevmDex();

// Use DAO functions
const { depositTokens, castVote } = useDAO();

Smart Contract Integration:

import {FHE, euint64} from "@fhevm/solidity/lib/FHE.sol";

// Perform FHE operations
euint64 result = FHE.add(encryptedA, encryptedB);

Documentation​

Detailed documentation for each subsystem:

Pool System​

Governance System​

General​

Next Steps​