diff --git a/docs/.gitbook/assets/image (1).png b/docs/.gitbook/assets/image (1).png new file mode 100644 index 00000000..8db83ee5 Binary files /dev/null and b/docs/.gitbook/assets/image (1).png differ diff --git a/docs/.gitbook/assets/image.png b/docs/.gitbook/assets/image.png new file mode 100644 index 00000000..8db83ee5 Binary files /dev/null and b/docs/.gitbook/assets/image.png differ diff --git a/docs/README.md b/docs/README.md index 76c0ec20..e3a4d8f0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,18 +21,27 @@ layout: Learn the basics of fhEVM, set it up, and make it run with ease. -
OverviewUnderstand the basic concepts of fhEVM library.start1.pngkey_concepts.md
Quick startDeploy your first fhEVM smart contract.start4.pngquick_start.md
Get started with HardhatLearn how to deploy and write confidential smart contracts with Hardhatstart5.pnghardhat.md
+
OverviewExplore the suite of fhEVM protocol.start1.pngoverview.md
Quick start with RemixLearn and prototype in the in-browser IDE.start4.pngoverview.md
Get started with HardhatDevelop in production-ready envrionment.start5.pnghardhat.md
## Develop a fhEVM smart contract Start developing fhEVM smart contracts in Solidity by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials. -
FundamentalsExplore core features.build1.png
GuidesLearn more about fhEVM implementation.build2.png
TutorialsBuild quickly with tutorials.build3.png
+
Smart contractLearn core Solidity library.build1.png
FrontendWrite a dAPP frontend.build2.png
TutorialsBuild quickly with tutorials.build3.png
## Explore more Access to additional resources and join the Zama community. +### Explanations + +Explore the technical architecture of the fhEVM protocol and the underlying cryptographic principles that power it. + +- [Architecture overview](smart_contracts/architecture_overview.md) +- [FHE on blockchain](smart_contracts/architecture_overview/fhe-on-blockchain.md) +- [fhEVM components](smart_contracts/architecture_overview/fhevm-components.md) +- [Encryption, decryption re-encryption and computation](smart_contracts/d_re_ecrypt_compute.md) + ### References Refer to the API and access additional resources for in-depth explanations while working with fhEVM. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4448cbba..d5dabef5 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,20 +1,27 @@ # Table of contents - [Welcome to fhEVM](README.md) -- [Whitepaper](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper-v2.pdf) +- [White paper](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper-v2.pdf) ## Getting Started -- [Overview](getting_started/overview.md) -- [Quick start](getting_started/quick_start/overview.md) - - [1. Setting up Remix](getting_started/quick_start/remix.md) - - [2. Connect your wallet to Remix](getting_started/quick_start/connect_wallet.md) - - [3. Deploying ConfidentialERC20](getting_started/quick_start/deploying_cerc20.md) - - [4. Interacting with the contract](getting_started/quick_start/interact.md) +- [Overview](getting-started/overview.md) +- [Quick Start](getting-started/overview-1/overview.md) + - [Remix](getting-started/overview-1/remix/README.md) + - [1. Setting up Remix](getting-started/overview-1/remix/remix.md) + - [2. Connect your wallet to Remix](getting-started/overview-1/remix/connect_wallet.md) + - [3. Deploying ConfidentialERC20](getting-started/overview-1/remix/deploying_cerc20.md) + - [4. Interacting with the contract](getting-started/overview-1/remix/interact.md) + - [Hardhat](getting-started/overview-1/hardhat/README.md) + - [Prerequisites](getting-started/overview-1/hardhat/prerequisites.md) + - [1. Setting up Hardhat](getting-started/overview-1/hardhat/1.-setting-up-hardhat.md) + - [2. Writing contracts](getting-started/overview-1/hardhat/2.-writing-contracts.md) + - [3. Testing in mocked mode](getting-started/overview-1/hardhat/3.-testing-in-mocked-mode.md) + - [4. Deploying the contract](getting-started/overview-1/hardhat/4.-deploying-the-contract.md) + - [5. Interacting with the contract](getting-started/overview-1/hardhat/5.-interacting-with-the-contract.md) ## Tutorials -- [Tutorial: Setting up Hardhat](tutorials/hardhat.md) - [See all tutorials](tutorials/see-all-tutorials.md) ## Smart contract @@ -31,7 +38,7 @@ - [Decryption](smart_contracts/decryption/decrypt.md) - [Decryption in depth](smart_contracts/decryption/decrypt_details.md) - [Re-encryption](smart_contracts/decryption/reencryption.md) -- [If sentances](smart_contracts/loop.md) +- [If sentences](smart_contracts/loop.md) - [Branching in FHE](smart_contracts/conditions.md) - [AsEbool, asEuintXX, asEaddress and asEbytesXX operations](smart_contracts/asEXXoperators.md) - [Generate random numbers](smart_contracts/random.md) diff --git a/docs/getting-started/overview-1/hardhat/1.-setting-up-hardhat.md b/docs/getting-started/overview-1/hardhat/1.-setting-up-hardhat.md new file mode 100644 index 00000000..69015c8e --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/1.-setting-up-hardhat.md @@ -0,0 +1,55 @@ +# 1. Setting up Hardhat + +This guide walks you through setting up your Hardhat environment using Zama's fhEVM Hardhat template. + +## Step 1: Clone the Hardhat template + +1. Open the repository: [Zama fhEVM Hardhat Template](https://github.com/zama-ai/fhevm-hardhat-template) +2. Click "Use this template" to create a new repository under your GitHub account. +3. Clone the repository you have created to your local environment +4. Copy the repository URL of your newly created repository. +5. Open a terminal and run: + +```sh +git clone +cd +``` + +{% embed url="https://scribehow.com/embed/Step_1__M1Gjr6SAQuOsPyT7luekmw?removeLogo=true&skipIntro=true" %} + +## Step 2: Configure the environment + +1. Copy the environment configuration template: + + ```sh + cp .env.example .env + ``` + +2. Install project dependencies: Depending on your package manager, run one of the following: + + ```sh + # Using npm + npm install + + # Using yarn + yarn install + + # Using pnpm + pnpm install + ``` + +{% embed url="https://scribehow.com/embed/Step_2_Copy__dIIvxIkrTPWTMD-A9s3Twg?removeLogo=true&skipIntro=true" %} + +## Project structure overview + +- **`contracts/`**: Write your Solidity smart contracts here. +- **`test/`**: Place your test scripts for smart contract testing. +- **`deploy/`**: Deployment scripts for deploying your contracts. +- **`hardhat.config.js`**: The pre-configured Hardhat setup file for deploying on Sepolia. +- **`.env`:** The environment file that stores sensitive or environment-specific variables such as private keys and API keys. + +To learn more about Hardhat, refer to the [official Hardhat documentation](https://hardhat.org/hardhat-runner/docs/getting-started#overview). + +--- + +You are now ready to start building your confidential smart contracts with fhEVM! diff --git a/docs/getting-started/overview-1/hardhat/2.-writing-contracts.md b/docs/getting-started/overview-1/hardhat/2.-writing-contracts.md new file mode 100644 index 00000000..8f172ced --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/2.-writing-contracts.md @@ -0,0 +1,70 @@ +# 2. Writing contracts + +This document explains how to write confidential smart contract using fhEVM in Hardhat projects. + +## Prerequisites + +Before proceeding, ensure you have: + +- A working Hardhat environment set up (see [previous section](1.-setting-up-hardhat.md)). +- Basic knowledge of Solidity. +- An understanding of ERC20 tokens. + +## Understanding the example contract + +The Hardhat template includes an example contract in the `contracts/` folder - `MyConfidentialERC20.sol`. This contract enables: + +- Private ERC20 token transfers. +- Encrypted balances. +- Minting functionality for authorized addresses. + +Let's break down the contract. + +{% embed url="https://scribehow.com/embed/Contract__WHzYcFfeQp-wamyKwJVDhw?removeLogo=true&skipIntro=true" %} + +### Step 1. Importing required libraries and contracts. + +```solidity +pragma solidity ^0.8.24; + +import "fhevm/lib/TFHE.sol"; +import "fhevm/config/ZamaFHEVMConfig.sol"; +import "fhevm-contracts/contracts/token/ERC20/extensions/ConfidentialERC20Mintable.sol"; +``` + +- **`TFHE.sol`**: The core Solidity library of Zama's fhEVM. It enables encrypted data type like `euint64`, secures encrypted operations, such as addition and comparison and allows access control. +- **`SepoliaZamaFHEVMConfig`**: A configuration contract that automatically sets up the required configurations for real-time encrypted operations on the Sepolia testnet. +- **`ConfidentialERC20Mintable.sol`** : The confidential smart contract that allows for full ERC20 compatibility with FHE encryption. + +### Step 2. Contract construction + +```solidity +contract MyConfidentialERC20 is SepoliaZamaFHEVMConfig, ConfidentialERC20Mintable { + constructor(string memory name_, string memory symbol_) ConfidentialERC20Mintable(name_, symbol_, msg.sender) {} +} +``` + +- This contract inherits `SepoliaZamaFHEVMConfig` and `ConfidentialERC20Mintable`. +- The constructor initializes the ERC20 token with a name and symbol, setting the deployer as the initial owner. + +## Going further + +This is a simple basic contract that we will deploy and use in this tutorial. To write more complex confidential smart contracts or customize your own functions: + +- Explore the full range of fhEVM capabilities in the [**Smart Contract**](../../../smart_contracts/key_concepts.md) section. +- Use the **`fhevm-contracts`** library and extend from the basic contract templates. + +{% hint style="info" %} +The **fhevm-contracts** is a Solidity library designed for developers to easily develop confidential smart contracts using fhEVM. It provides: + +- **Ready-to-use confidential contracts**: Pre-built implementations of common token standards with FHE capabilities +- **Base contracts**: Foundational building blocks for creating custom confidential smart contracts +- **Extensions**: Additional features and utilities that can be added to base contracts +- **Testing utilities**: Tools to help test FHE-enabled smart contracts + +See more details in [the fhEVM-contracts documentation](../../../smart_contracts/contracts.md). +{% endhint %} + +--- + +Your contract is ready! Let's move on to testing and deployment. diff --git a/docs/getting-started/overview-1/hardhat/3.-testing-in-mocked-mode.md b/docs/getting-started/overview-1/hardhat/3.-testing-in-mocked-mode.md new file mode 100644 index 00000000..44d49b96 --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/3.-testing-in-mocked-mode.md @@ -0,0 +1,44 @@ +# 3. Testing in mocked mode + +This tutorial walks you through performing tests in the **mocked** mode provided by the fhEVM Hardhat template. + +## Prerequisites + +Before proceeding, ensure you have: + +- A configured Hardhat project using the fhEVM Hardhat template. (See the [previous section](1.-setting-up-hardhat.md)) +- Basic knowledge of Solidity and Hardhat testing. (See the [Hardhat testing documentation](https://hardhat.org/hardhat-runner/docs/guides/test-contracts)) + +{% hint style="info" %} +fhEVM provides a **mocked mode** in Hardhat that allows for: + +- Faster testing on a local Hardhat network. +- The ability to analyze code coverage. +- A simulated version of encrypted types (they are not truly encrypted). +- Access to Hardhat features such as snapshots (`evm_snapshot`), time manipulation (`evm_increaseTime`), and debugging (`console.log`). + +To learn more about the fhEVM **mocked** mode, refer to the README in the [fhEVM Hardhat template repository](https://github.com/zama-ai/fhevm-hardhat-template). +{% endhint %} + +## Running your tests + +To run tests in **mocked mode**, open a terminal in your project's root directory and execute: + +``` +# Using npm +npm run test + +# Using yarn +yarn test + +# Using pnpm +pnpm test +``` + +This command runs all tests locally in mocked mode. You should see the test results in your console. + +{% embed url="https://scribehow.com/embed/Test__GPNkyWV-T3Kz3wOu14xWQA?removeLogo=true&skipIntro=true" %} + +## Next steps + +For most development and demonstration scenarios, mocked mode is sufficient. However, for production-ready development and a real testing environment, you need to run your tests on a real network where the coprocessor is deployed for example Sepolia. Refer to the [next section](4.-deploying-the-contract.md) on how to deploy your contract on Sepolia test network. diff --git a/docs/getting-started/overview-1/hardhat/4.-deploying-the-contract.md b/docs/getting-started/overview-1/hardhat/4.-deploying-the-contract.md new file mode 100644 index 00000000..b7d9782e --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/4.-deploying-the-contract.md @@ -0,0 +1,78 @@ +# 4. Deploying the contract + +This guide walks you through deploying your Confidential ERC20 smart contract on the Sepolia test network. + +## Prerequisites + +Before proceeding, ensure you have: + +- A configured Hardhat project using the fhEVM Hardhat Template (see previous sections). +- A crypto wallet installed (e.g., Metamask). +- Some Sepolia ETH available for testing. If you don’t have enough ETH, use a Sepolia faucet to request free SepoliaETH for testing: + - [Alchemy Faucet](https://www.alchemy.com/faucets/ethereum-sepolia) + - [QuickNode Faucet](https://faucet.quicknode.com/ethereum/sepolia) + +## Step 1. Preparing for deployment + +1. Generate a mnemonic seed for accounts using `cast`: + - (`cast` is a Foundry function. If you don't have Foundry installed, run `curl -L https://foundry.paradigm.xyz | bash` first): + +``` +cast wallet new-mnemonic +``` + +2. Obtain a Sepolia RPC URL: + - Sign up for a node provider such as Alchemy - `https://www.alchemy.com/` or Infura - `https://infura.io/`. Copy your Sepolia RPC URL. +3. Open the `.env` file: + - Past your mnemonic in the code: + - MNEMONIC=`` + - Paste a Sepolia RPC URL: + - SEPOLIA_RPC_URL=`` +4. Verify generated accounts: + +```sh +npx hardhat get-accounts --num-accounts 5 +``` + +{% embed url="https://scribehow.com/embed/Step_3_Copy__EGYS53LkSP-Pr2WB7yQ1vw?removeLogo=true&skipIntro=true" %} + +## Step 2. Funding your wallet + +1. Open your wallet (e.g, MetaMask) +2. Import the first 2 accounts (e.g., Alice and Bob) into your wallet with their private keys. +3. Fund these 2 accounts with some Sepolia ETH. + +{% embed url="https://scribehow.com/embed/Step_3__2__Hbg4nSgdR3KMcCkB4aw8Jw?removeLogo=true&skipIntro=true" %} + +## Step 3. Deploying the contract + +In the `deploy/` directory, there is a preconfigured `deploy.ts` file that handles the deployment process. You can customize it or add your own scripts. + +To deploy the contracts to Sepolia, run: + +```sh +# Using npm +npm run deploy-sepolia + +# Using yarn +yarn deploy-sepolia + +# Using pnpm +pnpm deploy-sepolia +``` + +## Step 4. Verify the deployment + +Once deployment is successful, you should see a console output that includes the contract address such as: + +``` +MyConfidentialERC20: 0x1234........ABCD +``` + +You can verify this contract on [Sepolia Etherscan](https://sepolia.etherscan.io/) by searching for the deployed address. + +{% embed url="https://scribehow.com/embed/Step_4__b3lGkybMS3ihZa8FklQo5A?removeLogo=true&skipIntro=true" %} + +--- + +Congratulations! 🎉 You have deployed your first confidential ERC20 smart contract. Let's mint a few tokens and perform some encrypted transactions! diff --git a/docs/getting-started/overview-1/hardhat/5.-interacting-with-the-contract.md b/docs/getting-started/overview-1/hardhat/5.-interacting-with-the-contract.md new file mode 100644 index 00000000..9c894dd7 --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/5.-interacting-with-the-contract.md @@ -0,0 +1,173 @@ +# 5. Interacting with the contract + +After deploying your first **fhEVM** contract using **Hardhat**, this guide shows you how to interact with it using Hardhat tasks. + +## Prerequisites + +Before interacting with your deployed contract, ensure the following: + +- **Deployment completed**: You have successfully deployed the `MyConfidentialERC20` contract (see previous section) +- **Contract address**: You have saved the deployed contract address +- **Sepolia ETH**: You have some Sepolia ETH in your wallet for transaction fees +- **Environment setup**: Your `.env` file is properly configured with your private key + +## Step 1: Mint tokens to your account + +First, let's mint some confidential tokens to your account: + +```sh +# Mint 1000 tokens to your account by replacing recipient-address with your address +npx hardhat mint --to --amount 1000 --network sepolia +``` + +Once successful, you'll see a transaction confirmation in the terminal that looks like this: + +``` +Starting mint process... +Contract address: 0x1...26 +Minting 1000 tokens to address: 0x1...26 +Transaction submitted, waiting for confirmation... +✅ Mint transaction successful! +Transaction hash: 0x1...26 +1000 tokens were minted to 0x1....26 +``` + +## Step 2: Verify total supply + +You can check the total supply of tokens to confirm your mint was successful: + +```sh +# Check the total supply +npx hardhat totalSupply --network sepolia +``` + +Once successful, you'll see a transaction confirmation in the terminal: + +``` +✅ Retrieved total supply successfully +---------------------------------------- +Total Supply: 1000 tokens +---------------------------------------- +``` + +## Step 3: Check your balance + +To verify your account balance: + +```sh +# Check your encrypted balance by replacing with the private key of the account you want to check +# You can get the private key by running 'npx hardhat get-accounts --num-accounts 5' +npx hardhat balance --privatekey --network sepolia +``` + +Note to remind yourself what was are the private keys of the accounts of the MNEMONIC SEED you can always check it by running: + +```sh +npx hardhat get-accounts --num-accounts 5 +``` + +Once successful, you'll see a transaction confirmation in the terminal. + +``` +✅ Retrieved balance handle successfully +---------------------------------------- +Address: 0x1..59 +Balance: 1000 tokens +---------------------------------------- +``` + +## Step 4: Transfer tokens + +To transfer confidential tokens to another account: + +```sh +# Transfer tokens from your account to another address +# Replace with the private key of the sending account +# Replace with the destination wallet address +# Adjust the amount (100) as needed +npx hardhat transfer --privatekey --to --amount 100 --network sepolia +``` + +Once successful, you'll see a transaction confirmation in the terminal. + +``` +Starting transfer process... +Contract address: 0x1...26 +From: 0x1...59 +To: 0xA...4D +Amount: 100 tokens +Encrypting and proving in 9.4s +Verifying in 8.7s +Submitting transfer transaction... +Waiting for confirmation... +---------------------------------------- +✅ Transfer successful! +Transaction hash: 0xc..13 +Transferred 100 tokens to 0xA..4D +``` + +## Step 5: Verify updated balances + +After the transfer, you can check both accounts balances: + +```sh +# Check sender's updated balance after transfer +# Replace with the private key of the senders account +npx hardhat balance --privatekey --network sepolia + +# Check recipient's updated balance after receiving transfer +# Replace with the private key of the recipient account +npx hardhat balance --privatekey --network sepolia +``` + +If both balances have changed accordingly the transaction was successful. + +## Available Tasks + +Here's a complete list of available Hardhat tasks for interacting with your contract: + +- `mint`: Mint new encrypted tokens +- `transfer`: Transfer encrypted tokens to another address +- `balance`: Check encrypted balance of an account +- `totalSupply`: Get the total token supply + +For detailed help on any task, run: + +```sh +npx hardhat help +``` + +## Next steps + +🎉 **Congratulations on completing this tutorial!** You’ve taken the first step in building confidential smart contracts using **fhEVM**. It's time now to take the next step and build your own confidential dApps! + +### 1. Resources + +To continue your journey and deepen your knowledge, explore the resources below. + +- [**Read the white paper**](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper-v2.pdf): Understand the core technology behind fhEVM, including its cryptographic foundations and use cases. +- [**See more demos and tutorials**](../../../tutorials/see-all-tutorials.md): Expand your skills with hands-on demos and tutorials crafted to guide you through various real-world scenarios. +- [**Try out AI coding assistant**](https://chatgpt.com/g/g-67518aee3c708191b9f08d077a7d6fa1-zama-solidity-developer): If you have a ChatGPT plus account, try out our custom ChatGPT model tailored for Solidity and fhEVM developers. + +### 2. Tools + +Use out-of-box templates and frameworks designed for developers to build confidential dApps easily. + +**Smart contract development** + +- [**Hardhat Template**](https://github.com/zama-ai/fhevm-hardhat-template): A developer-friendly starting point for building and testing smart contracts on fhEVM. +- [**fhEVM Contracts Library**](https://github.com/zama-ai/fhevm-contracts): Access standardized contracts for encrypted operations. + +**Frontend development** + +- [**React.js Template**](https://github.com/zama-ai/fhevm-react-template): Quickly develop FHE-compatible dApps using a clean React.js setup. +- [**Next.js Template**](https://github.com/zama-ai/fhevm-next-template): Build scalable, server-rendered dApps with FHE integration. +- [**Vue.js Template**](https://github.com/zama-ai/fhevm-vue-template): Develop responsive and modular dApps with FHE support in Vue.js. + +### 3. Community + +Join the community to shape the future of blockchain together with us. + +- [**Discord**](https://discord.gg/zama-ai): Join the community to get the latest update, have live discussion with fellow developers and Zama team. +- [**Community Forum**](https://community.zama.ai/): Get support on all technical questions related to fhEVM +- [**Zama Bounty Program**](https://github.com/zama-ai/bounty-program): Participate to tackle challenges and earn rewards in cash. diff --git a/docs/getting-started/overview-1/hardhat/README.md b/docs/getting-started/overview-1/hardhat/README.md new file mode 100644 index 00000000..43f10c1b --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/README.md @@ -0,0 +1,15 @@ +# Hardhat + +This tutorial covers the essential steps to quickly write and deploy a confidential ERC20 smart contract using the [fhEVM Hardhat template](https://github.com/zama-ai/fhevm-hardhat-template). + +Hardhat is a flexible, extensible development environment for Ethereum, providing a robust toolkit for compiling, testing, and deploying smart contracts. With Zama’s fhEVM integration, you can develop confidential ERC20 contracts locally and then seamlessly deploy them to a real fhEVM node. + +**In this tutorial, you will learn to:** + +1. Set up a Hardhat project with the [**fhEVM Hardhat Template**](https://github.com/zama-ai/fhevm-hardhat-template). +2. Write confidential contracts utilizing encrypted data types. +3. Test your contracts in **mocked mode** (for rapid feedback and coverage). +4. Deploy your confidential ERC20 contract to the Sepolia test network. +5. Interact with your deployed contract, including performing encrypted transfers. + +By following these steps, you’ll get familiar with the complete development workflow using Hardhat, and be able to build, test and deploy confidential ERC20 smart contracts on Sepolia testnet. diff --git a/docs/getting-started/overview-1/hardhat/prerequisites.md b/docs/getting-started/overview-1/hardhat/prerequisites.md new file mode 100644 index 00000000..03165ba8 --- /dev/null +++ b/docs/getting-started/overview-1/hardhat/prerequisites.md @@ -0,0 +1,91 @@ +# Prerequisites + +This guide will walk you through installing all necessary dependencies from scratch, preparing you for developing and deploying fhEVM smart contracts using Hardhat. + +To use Hardhat to build and deploy confidential smart contract, you need to have the following: + +- **Node.js (v20 or later)** +- **A package manager**: `npm`, `yarn`, or `pnpm` +- **Git** for version control +- **Foundry** for using the command `cast` + +If you already have these installed, skip ahead to [1. Setting Up Hardhat.](1.-setting-up-hardhat.md) + +--- + +## Step 1: Open your terminal + +To run the installation commands, open a terminal: + +- Use your system's built-in terminal (e.g., Terminal on macOS, Command Prompt or PowerShell on Windows, or a Linux shell). +- Alternatively, use the integrated terminal in a IDE such as [Visual Studio Code (VS Code)](https://code.visualstudio.com/). + +{% hint style="info" %} +VS code provide the official [Hardhat extension](https://hardhat.org/hardhat-vscode) for an enhanced development experience with Hardhat. +{% endhint %} + +## Step 2. Install Node.js and a package manager + +Instead of installing Node.js directly, we recommend using Node Version Manager (`nvm`), which allows you to manage multiple versions of Node.js: + +1. **Install `nvm`** following the recommended tutorials: + - [Linux](https://tecadmin.net/how-to-install-nvm-on-ubuntu-20-04/) + - [Windows ](https://github.com/coreybutler/nvm-windows/blob/master/README.md#installation--upgrades) + - [Mac OS](https://tecadmin.net/install-nvm-macos-with-homebrew/) +2. **Install Node.js** using nvm. This installs the latest version of Node.js: + +``` +nvm install node +``` + +3. **Install pnpm** (optional but recommended for better speed and efficiency). After installing Node.js, you automatically have npm, so run: + +``` +npm install -g pnpm +``` + + Alternatively, you can continue using `npm` or `yarn` if you prefer. + +## Step 3. Install Git + +Git is required for managing source code, cloning repositories, and handling version control. Install Git based on your operating system: + +- **Linux**: Use your distribution's package manager (e.g., `sudo apt-get install git` on Ubuntu/Debian). +- **Windows**: [Download Git for Windows](https://git-scm.com/download/win). +- **macOS**: Install via [Homebrew](https://brew.sh/) with `brew install git` or [download Git](https://git-scm.com/download/mac). + +## Step 4. Install Foundry + +We will need the command `cast` in our tutorial. This command is available with installing Foundry. + +1. **Install Foundry** using the official installer: + +```bash +curl -L https://foundry.paradigm.xyz | bash +``` + +2. **Reload your terminal configuration**: + +```bash +source ~/.bashrc # Linux/WSL +# or +source ~/.zshrc # macOS/zsh +``` + +3. **Run the Foundry installer**: + +```bash +foundryup +``` + +This will install all Foundry components, including `cast`, `forge`, `anvil`, and `chisel`. + +To verify the installation, run: + +```bash +cast --version +``` + +## Next Steps + +You now have all the necessary dependencies installed. Continue to [**1. Setting Up Hardhat**](1.-setting-up-hardhat.md) to begin creating and deploying your FHE smart contracts! diff --git a/docs/getting-started/overview-1/overview.md b/docs/getting-started/overview-1/overview.md new file mode 100644 index 00000000..3f642d4a --- /dev/null +++ b/docs/getting-started/overview-1/overview.md @@ -0,0 +1,51 @@ +# Quick Start + +This tutorial guides you to start quickly with Zama’s **Fully Homomorphic Encryption (FHE)** technology for building confidential smart contracts. + +## What You’ll Learn + +In about 20 minutes, you will: + +- Build your first **confidential ERC20** contract that leverages FHE. +- Deploy the contract on the **Sepolia** Network. +- **Mint tokens** and **perform transactions** in FHE. +- Build a **frontend application** for your contract. + +## Prerequisite + +- A basic understanding of **Solidity** library and **Ethereum**. +- A certain amount of **Sepolia ETH** available. + - If you don’t have enough ETH, use a Sepolia faucet to request free SepoliaETH for testing such as [Alchemy Faucet](https://www.alchemy.com/faucets/ethereum-sepolia) or [QuickNode Faucet](https://faucet.quicknode.com/ethereum/sepolia). + +## What is Confidenetial ERC20 + +The contract that you will build with this tutorial is called `ConfidentialERC20Mintable` — a privacy-preserving ERC20 implementation that leverages **FHE** to keep balances and transactions confidential. To understand this contract, let’s first introduce the foundational concepts. + +**RC20** + +ERC20 is a widely used token standard on Ethereum that defines a set of rules for creating and managing fungible tokens. These tokens are efficient but lack privacy — balances and transactions are visible to anyone on the blockchain. + +**Confidential ERC20** + +Zama’s `ConfidentialERC20` introduces privacy to ERC20 tokens by storing balances and transactions in an encrypted format using FHE. + +The `ConfidentialERC20` contract still supports standard ERC20 functions such as `transfer`, `approve`, `transferFrom`, `balanceOf`, and `totalSupply` but ensures these operations are processed securely with encrypted data. + +To explore the implementation details of ConfidentialERC20, check out the [Zama blog post](https://www.zama.ai/post/confidential-erc-20-tokens-using-homomorphic-encryption). + +**Confidential ERC-20 Mintable** + +The contract that we will build in this tutorial is `ConfidentialERC20Mintable` . It's built on top of `ConfidentialERC20` by adding secure minting capabilities. This allows authorized accounts to create new tokens, while maintaining the privacy guarantees of encrypted balances and transactions. + +The `ConfidentialERC20Mintable` contract ensures: + +- **Enhanced privacy**: Balances are stored as encrypted values (`euint64`), preventing public inspection of account balances. +- **Secure transactions**: Token transfers are processed securely, maintaining confidentiality of amounts. +- **Owner visibility**: Only account owners can decrypt and view their balances. + +## Next steps + +Choose your path and get started: + +- [**Remix Guide**](remix) – Rapid in‐browser setup, great for **learning** and fast **prototyping**. +- [**Hardhat Guide**](hardhat) – Full-fledged development environment, suitable for **production**. diff --git a/docs/getting-started/overview-1/remix/README.md b/docs/getting-started/overview-1/remix/README.md new file mode 100644 index 00000000..3c4f9c79 --- /dev/null +++ b/docs/getting-started/overview-1/remix/README.md @@ -0,0 +1,14 @@ +# Remix + +This tutorial covers the essentials steps to quickly write and deploy confidential ERC20 smart contract using the Zama Plug in. + +Remix is a powerful in-browser IDE for Ethereum smart contract development. It offers a fast, intuitive way to write and deploy confidential ERC20 contracts using Zama’s fhEVM plugin—no local setup required. + +**In this tutorial, you will learn to:** + +1. Set up Remix for fhEVM development. +2. Connect your wallet (e.g., MetaMask) to Remix. +3. Deploy a **ConfidentialERC20** contract. +4. Interact with your deployed contract directly in the Remix interface. + +By the end, you’ll have a working confidential ERC20 token on Sepolia network and know how to perform encrypted transactions. diff --git a/docs/getting_started/quick_start/connect_wallet.md b/docs/getting-started/overview-1/remix/connect_wallet.md similarity index 100% rename from docs/getting_started/quick_start/connect_wallet.md rename to docs/getting-started/overview-1/remix/connect_wallet.md diff --git a/docs/getting_started/quick_start/deploying_cerc20.md b/docs/getting-started/overview-1/remix/deploying_cerc20.md similarity index 98% rename from docs/getting_started/quick_start/deploying_cerc20.md rename to docs/getting-started/overview-1/remix/deploying_cerc20.md index b78973ba..b54fcd0e 100644 --- a/docs/getting_started/quick_start/deploying_cerc20.md +++ b/docs/getting-started/overview-1/remix/deploying_cerc20.md @@ -60,7 +60,7 @@ The **fhevm-contracts** is a Solidity library designed for developers to easily - **Extensions**: Additional features and utilities that can be added to base contracts - **Testing utilities**: Tools to help test FHE-enabled smart contracts -See more details in [the fhEVM-contracts documentation](../../smart_contracts/contracts.md). +See more details in [the fhEVM-contracts documentation](../../../smart_contracts/contracts.md). {% endhint %} The `fhevm-contracts` library includes the `ConfidentialERC20Mintable` contract, which is an extention of `ConfidentialERC20` with minting capabilities, providing: diff --git a/docs/getting_started/quick_start/interact.md b/docs/getting-started/overview-1/remix/interact.md similarity index 96% rename from docs/getting_started/quick_start/interact.md rename to docs/getting-started/overview-1/remix/interact.md index 87ebc7b8..d5ee51cd 100644 --- a/docs/getting_started/quick_start/interact.md +++ b/docs/getting-started/overview-1/remix/interact.md @@ -20,7 +20,7 @@ To perform transactions directly in Remix, your contract needs to be connected t 4. Paste the contract address into the **"At address"** field under the **Deploy** section. 5. Click **At address**. -If the address was entered correctly, the `MyConfidentialERC20.sol` contract will be displayed in the "**Deployed Contract**" inside the **Zama Plugin**. +If the address was entered correctly, the `MyConfidentialERC20.sol` contract will be displayed in the "**Deployed Contract**" inside the **Zama Plugin**. {% embed url="https://scribehow.com/embed/Load_MyConfidentialERC20_Contract_in_Remix__tJ1PmbA4TuGQ2fj6kMdMtQ?removeLogo=true&skipIntro=true" %} @@ -40,7 +40,7 @@ From here, you can mint confidential ERC20 token to your account: 2. Inside **Zama Plugin,** click to expand the **mint** function of your contract. 3. Enter your wallet address and the amount of tokens to mint (e.g., `1000`). 4. Click `Submit`. -5. Confirm the transaction in **MetaMask**. +5. Confirm the transaction in **MetaMask**. Once sccussful, you should see the message in the terminal. @@ -111,7 +111,7 @@ Always re-encrypt to validate ciphertext transformations and confirm operations. To continue your journey and deepen your knowledge, explore the resources below. - [**Read the Whitepaper**](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper-v2.pdf): Understand the core technology behind fhEVM, including its cryptographic foundations and use cases. -- [**See more demos and tutorials**](../../tutorials/see-all-tutorials.md): Expand your skills with hands-on demos and tutorials crafted to guide you through various real-world scenarios. +- [**See more demos and tutorials**](../../../tutorials/see-all-tutorials.md): Expand your skills with hands-on demos and tutorials crafted to guide you through various real-world scenarios. - [**Try out AI coding assistant**](https://chatgpt.com/g/g-67518aee3c708191b9f08d077a7d6fa1-zama-solidity-developer): If you have a chatGPT plus account, try out our custom ChatGPT model tailored for Solidity and fhEVM developers. ### 2. Tools diff --git a/docs/getting_started/quick_start/remix.md b/docs/getting-started/overview-1/remix/remix.md similarity index 100% rename from docs/getting_started/quick_start/remix.md rename to docs/getting-started/overview-1/remix/remix.md diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md new file mode 100644 index 00000000..0c3a2e35 --- /dev/null +++ b/docs/getting-started/overview.md @@ -0,0 +1,27 @@ +# Overview + +
+ +fhEVM is a suite of solutions that enables confidential smart contracts on the EVM using **Fully Homomorphic Encryption (FHE)**. This document provides a high-level overview of the fhEVM suite along with onboarding guidance tailored to specific audiences. + +### For dApp developers + +The fhEVM Protocol provides a **`TFHE` Solidity library** for building confidential smart contracts, a **`fhevm.js` Javascript library** to enable front‐end FHE interactions, and a range of developer tools, examples, and templates to streamline the usage for developers. + +#### Smart contract development + +
RepositoryDescription
fhevmSolidity library for FHE operations (e.g., encryption/decryption, arithmetic) within smart contracts.
fhevm-hardhat-templateHardhat template with scripts for compiling, deploying, and testing FHE‐enabled contracts.
fhevm-foundry-template - coming soonFoundry template for building FHE smart contracts.
fhevm-contractsReady‐to‐use FHE smart contract example covering finance, governance, and ERC‐20 tokens use cases.
+ +#### Frontend development + +
RepositoryDescription
fhevmjsJavaScript library for client‐side FHE, enabling encryption, decryption, and data handling.
fhevm-react-templateReact.js template to quickly spin up FHE‐enabled dApps.
fhevm-next-templateNext.js template for integrating FHE in server‐side rendered or hybrid web apps.
fhevm-vue-templateVue.js template for creating privacy‐preserving dApps with encrypted data
+ +#### Examples & Resources + +
RepositoryDescription
dappsSample decentralized applications demonstrating FHE with real‐world code.
Zama Bounty ProgramExplore open challenges and submit contributions to earn rewards.
Awesome Zama A curated list by the team at Zama of blog posts, libraries, research papers, and tutorials on Fully Homomorphic Encryption (FHE).
+ +### For network builders + +To **integrate FHE at the protocol level** or operate an **FHE‐enabled network**, fhEVM offers the fhevm backend modules. These repositories include the foundational implementations that enables FHE in blockchain systems, ensuring that privacy remains at the core of your network architecture. + +
RepositoryDescription
fhevm-backendRust backend & Go‐Ethereum modules, enabling native or coprocessor‐based FHE.
fhevm-goGo implementation of the FHE Virtual Machine
zbc-go-ethereumModified go-ethereum with enhanced FHE support
diff --git a/docs/getting_started/overview.md b/docs/getting_started/overview.md deleted file mode 100644 index 2a710ab6..00000000 --- a/docs/getting_started/overview.md +++ /dev/null @@ -1,68 +0,0 @@ -# What is fhEVM - -
- -## Introduction - -There used to be a dilemma in blockchain: keep your application and user data on-chain, allowing everyone to see it, or keep it privately off-chain and lose contract composability. - -**fhEVM** is a technology that enables confidential smart contracts on the EVM using Fully Homomorphic Encryption (FHE). - -Thanks to a breakthrough in FHE, Zama’s fhEVM makes it possible to run confidential smart contracts on encrypted data, guaranteeing both confidentiality and composability with: - -- **End-to-end encryption of transactions and state**: Data included in transactions is encrypted and never visible to anyone. -- **Composability and data availability on-chain**: States are updated while remaining encrypted at all times. -- **No impact on existing dapps and state**: Encrypted state co-exists alongside public one, and doesn't impact existing dapps. - -## Use cases - -fhEVM enables powerful privacy-preserving applications across key blockchain sectors: - -### 1. Decentralized Finance (DeFi) - -- **Private Trading & AMMs** - - Execute trades without revealing amounts or strategies - - Prevent front-running and MEV exploitation - - Create dark pools with hidden order books -- **Confidential Lending** - - Keep collateral amounts and positions private - - Protect borrowing history and credit scores - - Enable private under-collateralized lending -- **Example**: [Confidential ERC20 tutorial](../getting_started/quick_start/overview.md) - -### 2. Identity & Governance - -- **Decentralized Identity** - - Store encrypted credentials on-chain - - Issue private attestations - - Verify membership without revealing identity -- **Private Voting** - - Cast encrypted votes without revealing choices - - Prevent voter coercion and vote buying - - Enable quadratic voting with private token balances -- **Example**: [Decentralized identity](https://github.com/zama-ai/dapps/tree/main/hardhat/contracts/decIdentity) - -### 3. Enterprise Solutions - -- **Supply Chain** - - Track sensitive business metrics privately - - Share data selectively with partners - - Maintain competitive advantages on-chain -- **Data Markets** - - Trade data while preserving confidentiality - - Enable private computation services - - Create subscription-based data access - -### 4. Gaming & NFTs - -- **Strategy Games** - - Hide player moves and game state - - Enable private bidding and trading of in-game assets - - Implement truly random number generation -- **NFT Privacy** - - Conceal ownership and transfer history - - Keep metadata and attributes private - - Enable sealed-bid NFT auctions -- **Example**: [FHE Wordle](https://github.com/zama-ai/dapps/tree/main/hardhat/contracts/fheWordle) - -These applications showcase how fhEVM uniquely combines the transparency and composability of blockchain with the privacy guarantees of FHE, enabling a new generation of confidential smart contracts. diff --git a/docs/getting_started/quick_start/overview.md b/docs/getting_started/quick_start/overview.md deleted file mode 100644 index 48639eea..00000000 --- a/docs/getting_started/quick_start/overview.md +++ /dev/null @@ -1,46 +0,0 @@ -# Quick Start - -This tutorial guides you to start quickly with Zama’s **Fully Homomorphic Encryption (FHE)** technology for building confidential smart contracts. - -## What you'll learn - -In around 20 minutes, you will build and deploy your first confidential ERC20 contract, mint tokens and perform transactions on it. - -This tutorial will cover: - -1. **Set up Remix** development environment using the Zama Plugin. -2. **Connect your wallet** for deployment and interaction. -3. **Write and deploy** `ConfidentialERC20Mintable` contract on the Sepolia testnet -4. **Interact with your contract** to mint, transfer, and manage confidential tokens. - -## What you'll build - -The contract that you will build with this tutorial is called `ConfidentialERC20Mintable` — a privacy-preserving ERC20 implementation that leverages **FHE** to keep balances and transactions confidential. To understand this contract, let’s first introduce the foundational concepts. - -{% hint style="info" %} Feel free to skip this part if you already have a basic knowledge of confidential ERC20 tokens.{% endhint %} - -**ERC20** - -ERC20 is a widely used token standard on Ethereum that defines a set of rules for creating and managing fungible tokens. - -These tokens are efficient but lack privacy — balances and transactions are visible to anyone on the blockchain. - -**Confidential ERC20** - -Zama’s `ConfidentialERC20` introduces privacy to ERC20 tokens by storing balances and transactions in an encrypted format using FHE. - -The `ConfidentialERC20` contract still supports standard ERC20 functions such as `transfer`, `approve`, `transferFrom`, `balanceOf`, and `totalSupply` but ensures these operations are processed securely with encrypted data. - -To explore the implementation details of ConfidentialERC20, check out the [Zama blog post](https://www.zama.ai/post/confidential-erc-20-tokens-using-homomorphic-encryption). - -**Confidential ERC-20 Mintable** - -The contract that we will build in this tutorial is  `ConfidentialERC20Mintable` . It's built on top of `ConfidentialERC20` by adding secure minting capabilities. This allows authorized accounts to create new tokens, while maintaining the privacy guarantees of encrypted balances and transactions. - -The `ConfidentialERC20Mintable` contract ensures: - -- **Enhanced privacy**: Balances are stored as encrypted values (`euint64`), preventing public inspection of account balances. -- **Secure transactions**: Token transfers are processed securely, maintaining confidentiality of amounts. -- **Owner visibility**: Only account owners can decrypt and view their balances. - -Let’s get started on your journey to building confidential blockchain applications!  diff --git a/docs/tutorials/hardhat.md b/docs/tutorials/hardhat.md deleted file mode 100644 index 27bf6e07..00000000 --- a/docs/tutorials/hardhat.md +++ /dev/null @@ -1,129 +0,0 @@ -# Step 1: Setting Up Hardhat - -This guide walks you through setting up a development environment for creating **privacy-preserving smart contracts** using the Fully Homomorphic Encryption Virtual Machine (**FHEVM**) with Hardhat. - ---- - -## Prerequisites - -Before you begin, ensure you have the following installed on your system: - -- **Node.js** (v20 or later) -- A package manager: `npm`, `yarn`, or `pnpm` -- **Git** - ---- - -## Getting Started - -Learn how to configure your Hardhat project for developing and deploying fhEVM-specific smart contracts. - -### 1. Clone the Hardhat Template - -1. Go to the [FHEVM Hardhat Template Repository](https://github.com/zama-ai/fhevm-hardhat-template). -2. Create a new repository by clicking "Use this template." -3. Clone the repository you created: - - ```bash - git clone - cd - ``` - -{% embed url="https://scribehow.com/embed/Step_1__M1Gjr6SAQuOsPyT7luekmw?skipIntro=true&removeLogo=true" %} - ---- - -### 2. Configure Your Environment - -1. Copy the environment configuration template: - - ```bash - cp .env.example .env - ``` - -2. Install project dependencies: - - ```bash - # Using npm - npm install - - # Using yarn - yarn install - - # Using pnpm - pnpm install - ``` - ---- - -### Development Workflow - -- Write your **smart contracts** in the `contracts/` directory. -- Write your **tests** in the `tests/` directory. - ---- - -### 3. Testing your contracts - -Run the test suite using: - -```bash -pnpm test -``` - -{% embed url="https://scribehow.com/embed/Step_2__X1NmSAwhRiSiToABTDD31Q?skipIntro=true&removeLogo=true" %} - ---- - -## Deployment - -### 1. Prepare for Deployment - -1. Generate a mnemonic seed for accounts: - - ```bash - cast wallet new-mnemonic - ``` - - Copy the mnemonic and paste it into the `.env` file under `MNEMONIC`. - -2. Add a **Sepolia RPC URL** from a node provider (e.g., Alchemy or Infura). - - Update your `.env` file with the RPC URL: - - - **SEPOLIA_RPC_URL**: `` - -3. Verify generated accounts: - - ```bash - npx hardhat get-accounts --num-accounts 5 - ``` - -4. Import the first two accounts (e.g., Alice and Bob) into your wallet and fund them with Sepolia ETH. - - {% embed url="https://scribehow.com/embed/Step_3__Hbg4nSgdR3KMcCkB4aw8Jw?skipIntro=true&removeLogo=true" %} - ---- - -### 2. Deploy the Contracts - -1. Write your **deployments** under the `deploy/` directory. - -2. Deploy the contracts to Sepolia: - - ```bash - pnpm deploy-sepolia - ``` - ---- - -### 3. Verify Deployment - -1. After deploying, locate the deployed contract on Sepolia Etherscan: - - - {% embed url="https://scribehow.com/embed/Step_4__b3lGkybMS3ihZa8FklQo5A?skipIntro=true&removeLogo=true" %} - ---- - -With this setup, you’re ready to develop, test, and deploy privacy-preserving smart contracts using fhEVM and Hardhat. Happy coding! 🚀