@nana0x/fherand-contracts

FHERand Smart Contracts - Fully Homomorphic Encryption Randomness Protocol

Overview

This package contains the smart contracts for the FHERand protocol, providing encrypted randomness as a service for any dApp.

Contracts

Core Contracts

• FHERand.sol - Main service contract for random number generation

  • Handles subscription management
  • Generates encrypted random numbers
  • Manages pricing and access control

• FHERandLibrary.sol - Utility library for advanced randomness operations

  • Range mapping for non-power-of-2 ranges
  • Weighted random selection
  • Bounded randomness utilities

• FHERandSubscriptionHelper.sol - Helper contract for subscription management

  • Subscription tier management
  • Access control utilities

• SubscriptionManager.sol - Subscription tier and payment management

  • Manages subscription tiers (FREE, BASIC, PRO, ENTERPRISE)
  • Handles subscription payments and renewals
  • Tracks subscription status

Installation

For Consumers (Using the Published Package)

If you're using FHERand contracts in your own project:

npm install @nana0x/fherand-contracts
# or
pnpm add @nana0x/fherand-contracts

Note: The published package includes contract source files and pre-compiled artifacts. If you need to compile contracts yourself, also install:

pnpm add @fhevm/solidity @openzeppelin/contracts

Usage

Import Contracts

import "@nana0x/fherand-contracts/contracts/FHERand.sol";
import "@nana0x/fherand-contracts/contracts/FHERandLibrary.sol";

Basic Integration

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {FHERand} from "@nana0x/fherand-contracts/contracts/FHERand.sol";
import {FHE, euint32} from "@fhevm/solidity/lib/FHE.sol";

contract MyGame {
    FHERand public fherand;
    
    constructor(address _fherand) {
        fherand = FHERand(_fherand);
    }
    
    function rollDice() external returns (uint256) {
        // Request random number
        uint256 requestId = fherand.requestRandomUint32();
        
        // Get encrypted value
        euint32 encryptedValue = fherand.getRandomValue(requestId);
        
        // Use encrypted value in your logic
        // ... your game logic here
        
        return requestId;
    }
}

Development

For Contributors

If you're contributing to the FHERand contracts repository:

# Clone the repository
git clone https://github.com/0xNana/fherand.git
cd fherand/packages/contracts

# Install all dependencies (including @fhevm/solidity, @openzeppelin/contracts, Hardhat, etc.)
pnpm install

# Compile contracts
pnpm compile

# Run tests
pnpm test

# Generate TypeScript types
pnpm typechain

Scripts

# Compile contracts
pnpm compile

# Run all tests
pnpm test

# Run tests on Sepolia
pnpm test:sepolia

# Lint Solidity
pnpm lint:sol

# Lint TypeScript
pnpm lint:ts

# Format code
pnpm prettier:write

# Generate coverage report
pnpm coverage

Deployment

# Deploy to Sepolia
pnpm deploy:sepolia

# Deploy FHERand only
pnpm deploy:fherand:sepolia

# Verify contracts on Etherscan
pnpm verify:sepolia

Contract API

FHERand

Random Generation

• requestRandomUint8() → uint256 - Request encrypted random uint8 (0-255)
• requestRandomUint32() → uint256 - Request encrypted random uint32
• requestRandomInRange(uint256 min, uint256 max) → uint256 - Request random in range
• requestRandomBounded(uint256 upperBound) → uint256 - Request bounded random (power of 2)
• requestWeightedRandom(uint256[] weights) → uint256 - Request weighted random selection
• requestFreeRandom() → uint256 - Request free random (10/day limit)
• requestOneTimeRandom() → uint256 - Pay-as-you-go random
• requestBatchRandom(uint256 count) → uint256[] - Request multiple random numbers

Query Functions

• getRandomValue(uint256 requestId) → euint32 - Get encrypted random value
• getRequestInfo(uint256 requestId) → RandomRequest - Get request details
• getUserRequests(address user) → uint256[] - Get user's request history
• getPaygPrice() → uint256 - Get PAYG price

Subscription

• subscribe(Tier tier) - Subscribe to service
• isSubscribed(address user) → bool - Check subscription status
• getSubscriptionInfo(address user) → SubscriptionInfo - Get subscription details

FHERandLibrary

Utility Functions

• mapToRange(euint32 value, uint256 min, uint256 max) → euint32 - Map to range
• weightedSelect(euint32 random, uint256[] weights) → uint256 - Weighted selection
• shuffle(euint32[] array, euint32 seed) → euint32[] - Shuffle array

Testing

Tests are located in the test/ directory:

• FHERand.test.ts - Core protocol tests
• FHERandSubscriptionHelper.test.ts - Subscription helper tests
• SubscriptionManager.test.ts - Subscription manager tests

Run tests:

pnpm test

Contract Addresses

Sepolia Testnet

• FHERand: 0x6Dda240942a346f549881fDe5ff05f3A919E62aF
• SubscriptionManager: 0xAB8b8629dEea1d918bd8Ed338254bbE18FDe204c

Environment Variables:

FHERAND_SEPOLIA_ADDRESS=0x6Dda240942a346f549881fDe5ff05f3A919E62aF
SUBSCRIPTION_MANAGER_SEPOLIA_ADDRESS=0xAB8b8629dEea1d918bd8Ed338254bbE18FDe204c

Security

• Contracts use OpenZeppelin's battle-tested libraries
• ReentrancyGuard protection on critical functions
• Pausable for emergency stops
• Ownable for admin functions
• Comprehensive test coverage

License

BSD-3-Clause-Clear - See LICENSE file for details.

Links

• Documentation
• SDK Package
• GitHub Repository

Contributing

Contributions are welcome! Please ensure all tests pass and code is properly formatted before submitting PRs.