npm package: @nana0x/fherand-contracts
Description: FHERand smart contracts
Latest version: 0.1.1

# @nana0x/fherand-contracts

**FHERand Smart Contracts** - Fully Homomorphic Encryption Randomness Protocol

[![License](https://img.shields.io/badge/license-BSD--3--Clause--Clear-blue.svg)](../../LICENSE)

##  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:

```bash
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:
```bash
pnpm add @fhevm/solidity @openzeppelin/contracts
```

##  Usage

### Import Contracts

```solidity
import "@nana0x/fherand-contracts/contracts/FHERand.sol";
import "@nana0x/fherand-contracts/contracts/FHERandLibrary.sol";
```

### Basic Integration

```solidity
// 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
pnpm test
```

##  Contract Addresses

### Sepolia Testnet

- **FHERand**: `0x6Dda240942a346f549881fDe5ff05f3A919E62aF`
- **SubscriptionManager**: `0xAB8b8629dEea1d918bd8Ed338254bbE18FDe204c`

**Environment Variables:**
```bash
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](../../LICENSE) file for details.

##  Links

- [Documentation](../../docs/)
- [SDK Package](../sdk/)
- [GitHub Repository](https://github.com/0xNana/fherand)

##  Contributing

Contributions are welcome! Please ensure all tests pass and code is properly formatted before submitting PRs.