docs(common): regroup files (#353)

Author: yuxizama

docs/examples/SUMMARY.md

@@ -1,14 +1,16 @@
 - [Overview](example-overview.md)
 
-## Dapps Examples
+## Smart contract examples
+- Function examples
+    - [FHEAdd](fheadd.md)
+    - [FHEIfThenElse](fheifthenelse.md)
+    - [FHEEncryptSingleValue](fhe-encrypt-single-value.md)
+    - [FHEEncryptMultipleValue](fhe-encrypt-multiple-value.md)
+    - [FHEDecryptSingleValue](fhe-decrypt-single-value.md)
 
-- Deberry
-- Confidential Token Portfolio
+- Use case examples
+    - [FHE Counter](fhe-counter.md)
+    - [Confidential ERC20 Wrapper](erc20-wrapper.md)
 
-## Smart Contract Templates
-
-- Finance
-- Governance
-- ERC20
-- Utilities
-- [See all tutorials](see-all-tutorials.md)
+## dApp examples
+- Coming Soon

docs/examples/erc20-wrapper.md

@@ -0,0 +1,258 @@
+This example demonstrate how to build an confidential counter using FHEVM, in comparison to a simple counter.
+
+{% hint style="info" %}
+To run this example correctly, make sure the files are placed in the following directories:
+- `.sol`  file → `<your-project-root-dir>/contracts/`
+- `.ts` file → `<your-project-root-dir>/test/`
+
+This ensures Hardhat can compile and test your contracts as expected.
+{% endhint %}
+
+## A simple counter
+{% tabs %}
+
+{% tab title="counter.sol" %} 
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/// @title A simple counter contract
+contract Counter {
+    uint32 private _count;
+
+    /// @notice Returns the current count
+    function getCount() external view returns (uint32) {
+        return _count;
+    }
+
+    /// @notice Increments the counter by 1
+    function increment(uint32 value) external {
+        _count += value;
+    }
+
+    /// @notice Decrements the counter by 1
+    function decrement(uint32 value) external {
+        require(_count > value, "Counter: cannot decrement below zero");
+        _count -= value;
+    }
+}
+```
+{% endtab %}
+
+{% tab title="counter.ts" %} 
+```ts
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { ethers } from "hardhat";
+import { Counter, Counter__factory } from "../types";
+import { expect } from "chai";
+
+type Signers = {
+  deployer: HardhatEthersSigner;
+  alice: HardhatEthersSigner;
+  bob: HardhatEthersSigner;
+};
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory("Counter")) as Counter__factory;
+  const counterContract = (await factory.deploy()) as Counter;
+  const counterContractAddress = await counterContract.getAddress();
+
+  return { counterContract, counterContractAddress };
+}
+
+describe("Counter", function () {
+  let signers: Signers;
+  let counterContract: Counter;
+
+  before(async function () {
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { deployer: ethSigners[0], alice: ethSigners[1], bob: ethSigners[2] };
+  });
+
+  beforeEach(async () => {
+    ({ counterContract } = await deployFixture());
+  });
+
+  it("count should be zero after deployment", async function () {
+    const count = await counterContract.getCount();
+    console.log(`Counter.getCount() === ${count}`);
+    // Expect initial count to be 0 after deployment
+    expect(count).to.eq(0);
+  });
+
+  it("increment the counter by 1", async function () {
+    const countBeforeInc = await counterContract.getCount();
+    const tx = await counterContract.connect(signers.alice).increment(1);
+    await tx.wait();
+    const countAfterInc = await counterContract.getCount();
+    expect(countAfterInc).to.eq(countBeforeInc + 1n);
+  });
+
+  it("decrement the counter by 1", async function () {
+    // First increment, count becomes 1
+    let tx = await counterContract.connect(signers.alice).increment();
+    await tx.wait();
+    // Then decrement, count goes back to 0
+    tx = await counterContract.connect(signers.alice).decrement(1);
+    await tx.wait();
+    const count = await counterContract.getCount();
+    expect(count).to.eq(0);
+  });
+});
+```
+{% endtab %}
+
+{% endtabs %}
+
+## An FHE counter
+
+{% tabs %}
+
+{% tab title="FHECounter.sol" %} 
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {FHE, euint32, externalEuint32} from "@fhevm/solidity/lib/FHE.sol";
+import {SepoliaConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+
+/// @title A simple FHE counter contract
+contract FHECounter is SepoliaConfig {
+    euint32 private _count;
+
+    /// @notice Returns the current count
+    function getCount() external view returns (euint32) {
+        return _count;
+    }
+
+    /// @notice Increments the counter by a specified encrypted value.
+    /// @dev This example omits overflow/underflow checks for simplicity and readability.
+    /// In a production contract, proper range checks should be implemented.
+    function increment(externalEuint32 inputEuint32, bytes calldata inputProof) external {
+        euint32 encryptedEuint32 = FHE.fromExternal(inputEuint32, inputProof);
+
+        _count = FHE.add(_count, encryptedEuint32);
+
+        FHE.allowThis(_count);
+        FHE.allow(_count, msg.sender);
+    }
+
+    /// @notice Decrements the counter by a specified encrypted value.
+    /// @dev This example omits overflow/underflow checks for simplicity and readability.
+    /// In a production contract, proper range checks should be implemented.
+    function decrement(externalEuint32 inputEuint32, bytes calldata inputProof) external {
+        euint32 encryptedEuint32 = FHE.fromExternal(inputEuint32, inputProof);
+
+        _count = FHE.sub(_count, encryptedEuint32);
+
+        FHE.allowThis(_count);
+        FHE.allow(_count, msg.sender);
+    }
+}
+```
+{% endtab %}
+
+{% tab title="FHECounter.ts" %} 
+```ts
+import { HardhatEthersSigner } from "@nomicfoundation/hardhat-ethers/signers";
+import { ethers, fhevm } from "hardhat";
+import { FHECounter, FHECounter__factory } from "../types";
+import { expect } from "chai";
+import { FhevmType } from "@fhevm/hardhat-plugin";
+
+type Signers = {
+  deployer: HardhatEthersSigner;
+  alice: HardhatEthersSigner;
+  bob: HardhatEthersSigner;
+};
+
+async function deployFixture() {
+  const factory = (await ethers.getContractFactory("FHECounter")) as FHECounter__factory;
+  const fheCounterContract = (await factory.deploy()) as FHECounter;
+  const fheCounterContractAddress = await fheCounterContract.getAddress();
+
+  return { fheCounterContract, fheCounterContractAddress };
+}
+
+describe("FHECounter", function () {
+  let signers: Signers;
+  let fheCounterContract: FHECounter;
+  let fheCounterContractAddress: string;
+
+  before(async function () {
+    const ethSigners: HardhatEthersSigner[] = await ethers.getSigners();
+    signers = { deployer: ethSigners[0], alice: ethSigners[1], bob: ethSigners[2] };
+  });
+
+  beforeEach(async () => {
+    ({ fheCounterContract, fheCounterContractAddress } = await deployFixture());
+  });
+
+  it("encrypted count should be uninitialized after deployment", async function () {
+    const encryptedCount = await fheCounterContract.getCount();
+    // Expect initial count to be bytes32(0) after deployment,
+    // (meaning the encrypted count value is uninitialized)
+    expect(encryptedCount).to.eq(ethers.ZeroHash);
+  });
+
+  it("increment the counter by 1", async function () {
+    const encryptedCountBeforeInc = await fheCounterContract.getCount();
+    expect(encryptedCountBeforeInc).to.eq(ethers.ZeroHash);
+    const clearCountBeforeInc = 0;
+
+    // Encrypt constant 1 as a euint32
+    const clearOne = 1;
+    const encryptedOne = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(clearOne)
+      .encrypt();
+
+    const tx = await fheCounterContract
+      .connect(signers.alice)
+      .increment(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    const encryptedCountAfterInc = await fheCounterContract.getCount();
+    const clearCountAfterInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountAfterInc,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+
+    expect(clearCountAfterInc).to.eq(clearCountBeforeInc + clearOne);
+  });
+
+  it("decrement the counter by 1", async function () {
+    // Encrypt constant 1 as a euint32
+    const clearOne = 1;
+    const encryptedOne = await fhevm
+      .createEncryptedInput(fheCounterContractAddress, signers.alice.address)
+      .add32(clearOne)
+      .encrypt();
+
+    // First increment by 1, count becomes 1
+    let tx = await fheCounterContract
+      .connect(signers.alice)
+      .increment(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    // Then decrement by 1, count goes back to 0
+    tx = await fheCounterContract.connect(signers.alice).decrement(encryptedOne.handles[0], encryptedOne.inputProof);
+    await tx.wait();
+
+    const encryptedCountAfterDec = await fheCounterContract.getCount();
+    const clearCountAfterInc = await fhevm.userDecryptEuint(
+      FhevmType.euint32,
+      encryptedCountAfterDec,
+      fheCounterContractAddress,
+      signers.alice,
+    );
+
+    expect(clearCountAfterInc).to.eq(0);
+  });
+});
+```
+{% endtab %}
+
+{% endtabs %}