# Introduction

Welcome to the fhEVM Examples library. These examples span multiple categories and are designed to help you learn privacy-preserving smart contract patterns step by step.

## Start here

* [**FHE 101 (Plain Language)**](https://sun-labs.gitbook.io/fhevm-hub/fhe-101)
* [**Start Here**](https://sun-labs.gitbook.io/fhevm-hub/start-here)
* [**Common Pitfalls**](https://sun-labs.gitbook.io/fhevm-hub/pitfalls)
* [**Learning Paths**](https://sun-labs.gitbook.io/fhevm-hub/learning-paths)
* Want to browse by topic? See [**Chapters**](https://sun-labs.gitbook.io/fhevm-hub/chapters).

## Example map

### Auctions

| Example                                                                     | Concept                                                   | Difficulty   |
| --------------------------------------------------------------------------- | --------------------------------------------------------- | ------------ |
| [BlindAuction](https://sun-labs.gitbook.io/fhevm-hub/auctions/blindauction) | Sealed-bid auction with encrypted bids and public reveal  | Advanced     |
| [DutchAuction](https://sun-labs.gitbook.io/fhevm-hub/auctions/dutchauction) | Dutch auction with descending price and encrypted reserve | Intermediate |

### Basic

| Example                                                                                                | Concept                                                                            | Difficulty   |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------ |
| [AntiPatternMissingAllowThis](https://sun-labs.gitbook.io/fhevm-hub/basic/antipatternmissingallowthis) | Missing FHE.allowThis breaks reuse of stored handles                               | Intermediate |
| [AntiPatternMissingUserAllow](https://sun-labs.gitbook.io/fhevm-hub/basic/antipatternmissinguserallow) | Missing FHE.allow(user) blocks user decryption                                     | Intermediate |
| [AntiPatternViewOnEncrypted](https://sun-labs.gitbook.io/fhevm-hub/basic/antipatternviewonencrypted)   | View functions return encrypted handles, not plaintext                             | Intermediate |
| [EncryptMultipleValues](https://sun-labs.gitbook.io/fhevm-hub/basic/encryptmultiplevalues)             | Store multiple encrypted values with a single proof                                | Beginner     |
| [EncryptSingleValue](https://sun-labs.gitbook.io/fhevm-hub/basic/encryptsinglevalue)                   | Store one encrypted value and grant permissions                                    | Beginner     |
| [FHEAdd](https://sun-labs.gitbook.io/fhevm-hub/basic/fheadd)                                           | Add two encrypted values with FHE.add                                              | Beginner     |
| [FHECounter](https://sun-labs.gitbook.io/fhevm-hub/basic/fhecounter)                                   | Encrypted counter using FHE.add and FHE.sub                                        | Beginner     |
| [FHEEq](https://sun-labs.gitbook.io/fhevm-hub/basic/fheeq)                                             | Compare two encrypted values using FHE.eq                                          | Beginner     |
| [FHEIfThenElse](https://sun-labs.gitbook.io/fhevm-hub/basic/fheifthenelse)                             | Conditional selection on encrypted values using FHE.select                         | Beginner     |
| [FHESub](https://sun-labs.gitbook.io/fhevm-hub/basic/fhesub)                                           | Subtract two encrypted values with FHE.sub                                         | Beginner     |
| [HandleGeneration](https://sun-labs.gitbook.io/fhevm-hub/basic/handlegeneration)                       | Handles are opaque references; FHE ops create derived handles (symbolic execution) | Intermediate |
| [HandleLifecycle](https://sun-labs.gitbook.io/fhevm-hub/basic/handlelifecycle)                         | Store encrypted handles and reuse them across calls                                | Intermediate |
| [InputProofsExplained](https://sun-labs.gitbook.io/fhevm-hub/basic/inputproofsexplained)               | Input proofs bind encrypted inputs to a contract and sender                        | Intermediate |
| [PublicDecryptMultipleValues](https://sun-labs.gitbook.io/fhevm-hub/basic/publicdecryptmultiplevalues) | Public decryption flow for multiple encrypted values                               | Intermediate |
| [PublicDecryptSingleValue](https://sun-labs.gitbook.io/fhevm-hub/basic/publicdecryptsinglevalue)       | Public decryption flow for a single encrypted value                                | Intermediate |
| [UserDecryptMultipleValues](https://sun-labs.gitbook.io/fhevm-hub/basic/userdecryptmultiplevalues)     | User decryption flow for multiple encrypted results                                | Beginner     |
| [UserDecryptSingleValue](https://sun-labs.gitbook.io/fhevm-hub/basic/userdecryptsinglevalue)           | User decryption flow for a single encrypted result                                 | Beginner     |

### Games

| Example                                                            | Concept                                               | Difficulty   |
| ------------------------------------------------------------------ | ----------------------------------------------------- | ------------ |
| [FHEWordle](https://sun-labs.gitbook.io/fhevm-hub/games/fhewordle) | Encrypted letter comparison with branch-free feedback | Intermediate |

### Identity

| Example                                                                                                             | Concept                                                                                | Difficulty   |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------ |
| [AccessControlGrants](https://sun-labs.gitbook.io/fhevm-hub/identity/accesscontrolgrants)                           | User-controlled FHE.allow() permissions                                                | Intermediate |
| [ComplianceRules](https://sun-labs.gitbook.io/fhevm-hub/identity/compliancerules)                                   | Combining encrypted compliance checks with FHE.and()                                   | Intermediate |
| [CompliantERC20](https://sun-labs.gitbook.io/fhevm-hub/identity/complianterc20)                                     | FHE.select() for branch-free compliant transfers                                       | Advanced     |
| [EncryptedAgeVerification](https://sun-labs.gitbook.io/fhevm-hub/identity/encryptedageverification)                 | FHE comparison (le, ge) for threshold checks without revealing values                  | Beginner     |
| [ERC7984ERC20WrapperExample](https://sun-labs.gitbook.io/fhevm-hub/identity/erc7984erc20wrapperexample)             | ERC7984ERC20Wrapper (ERC20 ↔ ERC7984) + KYC-gated wrap/unwrap                          | Advanced     |
| [ERC7984Example](https://sun-labs.gitbook.io/fhevm-hub/identity/erc7984example)                                     | Minimal ERC7984 token with confidential mint + transfer                                | Beginner     |
| [ERC7984KycRestricted](https://sun-labs.gitbook.io/fhevm-hub/identity/erc7984kycrestricted)                         | OpenZeppelin ERC7984Restricted + public KYC allowlist (revert-based compliance)        | Intermediate |
| [ERC7984ObserverAccessExample](https://sun-labs.gitbook.io/fhevm-hub/identity/erc7984observeraccessexample)         | ERC7984ObserverAccess for opt-in audit / compliance observers                          | Intermediate |
| [IdentityRegistry](https://sun-labs.gitbook.io/fhevm-hub/identity/identityregistry)                                 | Storing encrypted identity attributes (euint8, euint16, ebool)                         | Intermediate |
| [SwapERC7984ToERC20](https://sun-labs.gitbook.io/fhevm-hub/identity/swaperc7984toerc20)                             | ERC7984 → ERC20 swap using public decryption + FHE.checkSignatures (KYC is public)     | Advanced     |
| [SwapERC7984ToERC7984](https://sun-labs.gitbook.io/fhevm-hub/identity/swaperc7984toerc7984)                         | ERC7984 → ERC7984 swap using FHE.allowTransient across token contracts (KYC is public) | Intermediate |
| [TransientAccessControl](https://sun-labs.gitbook.io/fhevm-hub/identity/transientaccesscontrol)                     | FHE.allowTransient() for one-transaction permissions between contracts                 | Intermediate |
| [VestingWalletConfidentialExample](https://sun-labs.gitbook.io/fhevm-hub/identity/vestingwalletconfidentialexample) | Confidential vesting (ERC7984) + public KYC gating + factory/clones                    | Advanced     |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sun-labs.gitbook.io/fhevm-hub/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.