> ## Documentation Index
> Fetch the complete documentation index at: https://cofhe-docs.fhenix.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# FHERC20 Overview

> Introduction to the FHERC20 confidential token standard (ERC-7984)

## What is FHERC20?

FHERC20 is a Fully Homomorphic Encryption (FHE) enabled token standard that provides **complete confidentiality** for token balances while maintaining compatibility with existing ERC20 infrastructure. Built on the Fhenix CoFHE protocol and implementing the [ERC-7984](https://eips.ethereum.org/EIPS/eip-7984) standard, FHERC20 allows users to transfer and manage tokens without revealing their balances or transaction amounts to anyone—not even other participants in the same smart contract.

<CardGroup cols={2}>
  <Card title="Private by Default" icon="lock">
    All balances and transfer amounts are encrypted using FHE, ensuring complete financial privacy on a public blockchain.
  </Card>

  <Card title="ERC20 Compatible" icon="plug">
    Maintains compatibility with existing wallets and block explorers through an indicator system, while confidential operations use specialized functions.
  </Card>

  <Card title="Secure Operations" icon="shield">
    Perform computations on encrypted data without decryption, using homomorphic properties and FHESafeMath to maintain security throughout all operations.
  </Card>

  <Card title="Flexible Permissions" icon="key">
    Modern operator system with time-based expiration for granular access control.
  </Card>
</CardGroup>

***

## Key Features

### 1. Encrypted Balances

Unlike standard ERC20 tokens where balances are visible to everyone, FHERC20 stores all balances as encrypted values using `euint64` types:

```solidity theme={null}
// In FHERC20.sol
mapping(address account => euint64) private _confidentialBalances;
```

These encrypted balances:

* Cannot be read by anyone (including the contract)
* Can be operated on using FHE operations
* Maintain their encrypted state throughout all computations
* Are only revealed when explicitly disclosed with a valid proof

### 2. Confidential Transfers

All token movements use encrypted amounts:

```solidity theme={null}
// Transfer with encrypted input
function confidentialTransfer(address to, InEuint64 memory encryptedAmount)
    external returns (euint64 transferred);

// Transfer with already-encrypted value
function confidentialTransfer(address to, euint64 amount)
    external returns (euint64 transferred);
```

<Note>
  FHERC20 provides two overloads for most functions: one accepting `InEuint64` (encrypted input from users) and one accepting `euint64` (already-encrypted values for contract-to-contract calls).
</Note>

### 3. Operator System

Instead of traditional ERC20 allowances (which leak information about approved amounts), FHERC20 uses a time-based operator system:

```solidity theme={null}
// Grant operator permission until a specific timestamp
function setOperator(address operator, uint48 until) external;

// Check if an address is an authorized operator
function isOperator(address holder, address spender)
    external view returns (bool);
```

Operators have **full access** to move tokens on behalf of the holder until the expiration time, without revealing specific amounts.

### 4. Transfer Callbacks

FHERC20 supports safe transfers with callbacks:

```solidity theme={null}
function confidentialTransferAndCall(
    address to,
    InEuint64 memory encryptedAmount,
    bytes calldata data
) external returns (euint64 transferred);
```

Recipients must implement the `IERC7984Receiver` interface to accept these transfers, enabling atomic token transfers with contract interactions.

### 5. Amount Disclosure

FHERC20 supports optional disclosure of encrypted amounts for transparency when needed:

```solidity theme={null}
function requestDiscloseEncryptedAmount(euint64 amount) external;
function discloseEncryptedAmount(euint64 amount, uint64 cleartext, bytes memory proof) external;
```

This emits an `AmountDisclosed` event, allowing accounts with access to an encrypted amount to voluntarily reveal it on-chain.

***

## Architecture

<Steps>
  <Step title="Client-Side Encryption">
    Users encrypt their transaction data (amounts, recipients) off-chain using the Client SDK (`@cofhe/sdk`) before submitting to the blockchain.
  </Step>

  <Step title="On-Chain FHE Operations">
    The FHERC20 contract performs all operations (additions, subtractions, comparisons) on encrypted data without ever decrypting it.
  </Step>

  <Step title="Access Control">
    The contract manages permissions for who can access encrypted balances, using FHE access control mechanisms.
  </Step>

  <Step title="Indicator System">
    For compatibility with standard wallets, FHERC20 maintains non-confidential "indicators" that show activity without revealing amounts.
  </Step>
</Steps>

***

## The Indicator System

To maintain compatibility with existing ERC20 infrastructure (wallets, block explorers), FHERC20 implements an **indicator system**:

<Accordion title="What are Indicators?" icon="gauge" defaultOpen>
  Indicators are small, non-confidential numbers that represent account activity without revealing actual balances:

  * Range from `0.0000` to `0.9999` (stored as `0-9999`)
  * Start at `0` for accounts that have never interacted
  * Initialize at `0.7984` upon first interaction (referencing the ERC-7984 standard)
  * Increment by `0.0001` for each received transaction
  * Decrement by `0.0001` for each sent transaction

  **Example:**

  ```solidity theme={null}
  // Alice's indicator: 0.7990
  // Bob's indicator: 0.7980
  // These numbers provide visual feedback in wallets but reveal no actual balance info
  ```
</Accordion>

<Accordion title="Why Indicators?" icon="question" defaultOpen>
  Standard ERC20 functions like `balanceOf()` must return a `uint256`. For confidential tokens, we can't return the real balance, so we return the indicator instead.

  The `balanceOfIsIndicator()` function returns `true`, signalling to wallets and block explorers that `balanceOf` returns an indicator, not a real balance.

  This allows:

  * ✅ Wallets to display "activity" for the token
  * ✅ Block explorers to show transactions occurred
  * ✅ Basic compatibility with existing infrastructure
  * ❌ But doesn't reveal actual token amounts

  Users can opt out by calling `resetIndicatedBalance()` to set their indicator back to zero.
</Accordion>

<Accordion title="Indicator Tick" icon="ruler" defaultOpen>
  The `indicatorTick` is the base unit for indicator increments:

  ```solidity theme={null}
  uint256 indicatorTick = 10^(decimals - 4);

  // For a token with 6 decimals (recommended):
  // indicatorTick = 10^2 = 100
  ```

  This value is returned in `Transfer` events to maintain ERC20 compatibility while hiding real amounts.
</Accordion>

***

## Comparison with Standard ERC20

| Feature                | Standard ERC20            | FHERC20                                     |
| ---------------------- | ------------------------- | ------------------------------------------- |
| **Balance Visibility** | Public, anyone can see    | Encrypted, private                          |
| **Transfer Amounts**   | Public, visible in events | Encrypted                                   |
| **Allowances**         | Specific amounts approved | Time-based operator system                  |
| **Transfer Function**  | `transfer(to, amount)`    | `confidentialTransfer(to, encryptedAmount)` |
| **Balance Query**      | Returns actual balance    | Returns indicator                           |
| **Compatibility**      | Native ERC20              | Indicator system for wallets                |
| **Privacy**            | None                      | Complete                                    |
| **Standard**           | ERC-20                    | ERC-7984 + ERC-20 compatibility             |

***

## Contract Variants

The FHERC20 ecosystem includes several specialized contracts:

<CardGroup cols={2}>
  <Card title="FHERC20" icon="coins" href="/fhe-library/confidential-contracts/fherc20/core-features">
    **Base Implementation**

    Core confidential token with encrypted balances, confidential transfers, and operator system.
  </Card>

  <Card title="FHERC20ERC20Wrapper" icon="gift" href="/fhe-library/confidential-contracts/fherc20/fherc20-wrapper">
    **ERC20 Wrapper**

    Shields standard ERC20 tokens into confidential FHERC20 tokens with rate-based decimal conversion and handles unshielding with a claim system.
  </Card>

  <Card title="FHERC20NativeWrapper" icon="ethereum" href="/fhe-library/confidential-contracts/fherc20/fherc20-wrapper">
    **Native Token Wrapper**

    Shields native tokens (e.g., ETH) or WETH into confidential FHERC20 tokens.
  </Card>

  <Card title="FHERC20WrapperClaimHelper" icon="hand-holding-dollar">
    **Claim Management**

    Abstract contract providing claim lifecycle management for unshield operations and decryption verification.
  </Card>
</CardGroup>

***

## Quick Start Example

Here's a minimal example showing FHERC20 in action:

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.25;

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

contract MyConfidentialToken is FHERC20 {
    constructor() FHERC20("My Confidential Token", "MCT", 6) {}

    // Mint confidential tokens
    function mint(address to, uint64 amount) external {
        _mint(to, amount);
    }
}
```

<Note>
  The recommended number of decimals for FHERC20 tokens is **6**. This ensures compatibility with the wrapper contracts and avoids overflow issues with the `euint64` type.
</Note>

Using the token:

```solidity theme={null}
// User encrypts amount off-chain, then submits
InEuint64 memory encryptedAmount = cofhe.encrypt(100);
token.confidentialTransfer(recipient, encryptedAmount);

// Check indicator (not real balance!)
uint256 indicator = token.balanceOf(user); // Returns indicator value

// Check real encrypted balance (only accessible to user)
euint64 encBalance = token.confidentialBalanceOf(user);
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Features" icon="star" href="/fhe-library/confidential-contracts/fherc20/core-features">
    Learn about encrypted balances, transfers, and the indicator system in detail.
  </Card>

  <Card title="Operators" icon="users" href="/fhe-library/confidential-contracts/fherc20/operators">
    Understand the operator permission system and how it replaces traditional allowances.
  </Card>

  <Card title="Transfer Callbacks" icon="phone-arrow-down-left" href="/fhe-library/confidential-contracts/fherc20/transfer-callbacks">
    Implement safe transfers with callbacks using the IERC7984Receiver interface.
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/fhe-library/confidential-contracts/fherc20/best-practices">
    Security considerations, gas optimization, and recommended patterns.
  </Card>
</CardGroup>

***

## Related Topics

* Learn about FHE operations in [Encrypted Operations](/fhe-library/core-concepts/encrypted-operations)
* Understand access control in [Access Control](/fhe-library/core-concepts/access-control)
* Explore encryption with the [Client SDK](/client-sdk/introduction/overview)