Fhenix Confidential Contracts

A privacy-preserving FHERC-20 token standard implementation built on Fhenix Protocol's Fully Homomorphic Encryption (FHE).

Warning: These contracts are in active development and have not been audited. Use at your own risk.

Overview

This library provides Solidity smart contracts for confidential ERC-20 tokens using FHE. Token balances and transfer amounts remain encrypted on-chain while still supporting standard token operations.

Key Features

• FHERC20 - Base confidential token with encrypted balances
• FHERC20Permit - EIP-712 signature-based operator approval
• FHERC20Wrapper - Wrap standard ERC-20 tokens into confidential tokens
• FHERC20UnwrapClaim - Claim management for unwrapping back to ERC-20

Installation

Hardhat (npm/yarn/pnpm)

npm install fhenix-confidential-contracts
# or
yarn add fhenix-confidential-contracts
# or
pnpm add fhenix-confidential-contracts

Foundry

forge install FhenixProtocol/fhenix-confidential-contracts

Linking ERC20ConfidentialLib (required)

The confidential FHE orchestration lives in ERC20ConfidentialLib, an external library that is delegatecalled by the token. This is what keeps confidential tokens under the EIP-170 24KB bytecode limit: the heavy logic is deployed once per chain instead of being embedded in every token.

Every contract that inherits ERC20Confidential, ERC20ConfidentialUpgradeable, ERC20ConfidentialCoreUpgradeable, or either wrapper must be linked against it at deploy time. The address is baked into the token's bytecode and cannot be changed afterwards.

const LIB_FQN = "contracts/ERC20Confidential/ERC20ConfidentialLib.sol:ERC20ConfidentialLib";

// 1. Deploy the library once per chain (see deploy/00_deploy_confidential_lib.ts, which also
//    forces explorer verification and records the address under deployments/<network>/).
const lib = await ethers.deployContract(LIB_FQN);
await lib.waitForDeployment();

// 2. Link it into every token factory.
const factory = await ethers.getContractFactory("MyConfidentialToken", {
  libraries: { [LIB_FQN]: await lib.getAddress() },
});

// 3. Upgradeable tokens additionally need the OZ upgrades plugin to allow linked libraries.
await upgrades.deployProxy(factory, [...args], { unsafeAllowLinkedLibraries: true });

Forgetting step 2 fails at deploy time with an unresolved-link error, not silently.

Usage

Basic FHERC20 Token

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

import { FHERC20 } from "fhenix-confidential-contracts/contracts/FHERC20.sol";

contract MyConfidentialToken is FHERC20 {
    constructor() FHERC20("My Confidential Token", "eMCT", 18) {
        // Mint initial supply to deployer
        _mint(msg.sender, 1000000 * 10**18);
    }
}

FHERC20 with Permit

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

import { FHERC20 } from "fhenix-confidential-contracts/contracts/FHERC20.sol";
import { FHERC20Permit } from "fhenix-confidential-contracts/contracts/FHERC20Permit.sol";

contract MyPermitToken is FHERC20, FHERC20Permit {
    constructor()
        FHERC20("My Permit Token", "eMPT", 18)
        FHERC20Permit("My Permit Token")
    {
        _mint(msg.sender, 1000000 * 10**18);
    }
}

Wrapping Existing ERC-20 Tokens

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

import { FHERC20Wrapper } from "fhenix-confidential-contracts/contracts/FHERC20Wrapper.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract MyWrappedToken is FHERC20Wrapper {
    constructor(IERC20 underlyingToken)
        FHERC20Wrapper(underlyingToken, "")
    {}
}

// Usage:
// 1. Deploy with existing ERC-20 address
// 2. Approve the wrapper contract to spend your ERC-20 tokens
// 3. Call wrap(recipient, amount) to mint confidential tokens
// 4. Call unwrap(recipient, encryptedAmount) to initiate unwrapping
// 5. Call claimUnwrapped(ctHash) after decryption completes

Contract Architecture

Behavior lives in shared *Core mixins; the concrete contracts are thin hosts that only supply setup (constructor vs. initializer) and ERC-165 answers. The FHE orchestration sits one level deeper still, in the external linked ERC20ConfidentialLib.

ERC20ConfidentialLib (external, linked, delegatecall'd - deploy once per chain)
  ▲ used by every core below

FHERC20Core (encrypted balances, operators, indicator layer, disclosure)
├── FHERC20                                  (constructor host)
├── FHERC20Upgradeable                        (proxy host)
├── FHERC20ERC20WrapperCore                   (wrap/shield/unshield/claim)
│   ├── FHERC20ERC20Wrapper
│   └── FHERC20ERC20WrapperUpgradeable
└── FHERC20NativeWrapperCore                  (native/WETH shield/unshield/claim)
    ├── FHERC20NativeWrapper
    └── FHERC20NativeWrapperUpgradeable

ERC20ConfidentialCoreUpgradeable (dual-ledger confidential layer over a host's public ERC-20;
│   reaches the ledger through _ledgerMint / _ledgerTransfer / _ledgerBalanceOf, and gates
│   account-initiated moves through _beforeConfidentialMove)
├── ERC20Confidential                         (constructor host, OZ ERC20 ledger)
└── ERC20ConfidentialUpgradeable              (proxy host, OZ ERC20Upgradeable ledger)

Interfaces:
├── IFHERC20 / IERC7984 / IERC7984Receiver
├── IERC20Confidential
├── IERC20ConfidentialCore    (confidential-only; no OZ IERC20/IERC165, so it composes
│                              with hosts that bring their own stack)
├── IFHERC20ERC20Wrapper / IFHERC20NativeWrapper
└── IWETH

Utilities:
├── FHERC20Utils
├── FHERC20Errors
├── FHERC20WrapperClaims      (claim bookkeeping over the library's claim store)
├── ERC20ConfidentialIndicator
└── FHESafeMath

Unshield claims are keyed by a unique per-claimant id (keccak256(to, nonce++, handle)), not by the ciphertext handle: CoFHE handles are content-addressed, so two unshields with an identical burned-amount lineage produce the same handle, and handle-keyed claims could overwrite each other. Read claim ids from getClaim / getUserClaims; the handle is retained as Claim.ctHash to bind the decryption proof.

Key Concepts

Indicated Balances

FHERC20 tokens use an "indicator" system for backwards compatibility with existing ERC-20 infrastructure (wallets, block explorers). The balanceOf function returns a value between 0.0000 and 0.9999 that indicates balance changes without revealing actual amounts.

This allows wallets to detect when balances change while keeping the actual amounts private.

Operators vs Allowances

Traditional ERC-20 allowances are replaced with time-limited operators to prevent encrypted balance leakage. Unlike allowances where you approve a specific amount, operators can transfer any amount on behalf of a holder until their permission expires.

// Set an operator (replaces approve)
token.setOperator(spender, deadline);

// Check if address is an operator
bool isOp = token.isOperator(holder, spender);

// Transfer as operator (replaces transferFrom with allowance)
token.confidentialTransferFrom(from, to, encryptedAmount);

Confidential Transfers

// Direct encrypted transfer
token.confidentialTransfer(to, encryptedAmount);

// Operator-initiated transfer
token.confidentialTransferFrom(from, to, encryptedAmount);

// Transfer with callback to receiving contract
token.confidentialTransferAndCall(to, encryptedAmount, data);

Security Considerations

FHE-Specific Security

1. Balance Indicators Are Public: The indicator values (0.0000-0.9999) reveal transfer activity but not amounts
2. Operator Model: Operators have full transfer authority during their approval period - use short deadlines
3. Decryption Delays: Unwrapping operations require waiting for FHE decryption to complete

Smart Contract Security

1. Reentrancy: confidentialTransferAndCall includes callback functionality - receiving contracts should follow checks-effects-interactions
2. Integer Operations: FHE operations have different overflow behavior than standard Solidity

Audit Status

Warning: These contracts have not been audited. A security audit is planned before v1.0.0 release.

Reporting Vulnerabilities

Please report security vulnerabilities through our Security Policy.

Dependencies

• @openzeppelin/contracts ^5.2.0
• @fhenixprotocol/cofhe-contracts 0.0.13

Development

# Install dependencies
pnpm install

# Compile contracts
pnpm compile

# Run tests
pnpm test

# Run tests with gas reporting
pnpm gas

# Format code
pnpm format

# Lint
pnpm lint

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a Pull Request.

License

Released under the MIT License.