Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update README #31

Merged
merged 2 commits into from
Mar 13, 2024
Merged

chore: update README #31

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e8afe2
chore: update README
immortal-tofu Mar 13, 2024
446459f
chore: update README
immortal-tofu Mar 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 73 additions & 222 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,259 +1,110 @@
# Hardhat Template [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Hardhat][hardhat-badge]][hardhat] [![License: MIT][license-badge]][license]

[gitpod]: https://gitpod.io/#https://github.com/zama-ai/fhevm-hardhat-template
[gitpod-badge]: https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-FFB45B?logo=gitpod
[gha]: https://github.com/zama-ai/fhevm-hardhat-template/actions
[gha-badge]: https://github.com/zama-ai/fhevm-hardhat-template/actions/workflows/ci.yml/badge.svg
[hardhat]: https://hardhat.org/
[hardhat-badge]: https://img.shields.io/badge/Built%20with-Hardhat-FFDB1C.svg
[license]: https://opensource.org/licenses/MIT
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg

A Hardhat-based template for developing Solidity smart contracts, with sensible defaults.

- [Hardhat](https://github.com/nomiclabs/hardhat): compile, run and test smart contracts
- [TypeChain](https://github.com/ethereum-ts/TypeChain): generate TypeScript bindings for smart contracts
- [Ethers](https://github.com/ethers-io/ethers.js/): renowned Ethereum library and wallet implementation
- [Solhint](https://github.com/protofire/solhint): code linter
- [Solcover](https://github.com/sc-forks/solidity-coverage): code coverage
- [Prettier Plugin Solidity](https://github.com/prettier-solidity/prettier-plugin-solidity): code formatter
# fhEVM Contracts

## Getting Started

Click the [`Use this template`](https://github.com/zama-ai/fhevm-hardhat-template/generate) button at the top of the
page to create a new repository with this repo as the initial state.

## Features

This template builds upon the frameworks and libraries mentioned above, so for details about their specific features,
please consult their respective documentations.

For example, for Hardhat, you can refer to the [Hardhat Tutorial](https://hardhat.org/tutorial) and the
[Hardhat Docs](https://hardhat.org/docs). You might be in particular interested in reading the
[Testing Contracts](https://hardhat.org/tutorial/testing-contracts) section.

### Sensible Defaults

This template comes with sensible default configurations in the following files:

```text
├── .editorconfig
├── .eslintignore
├── .eslintrc.yml
├── .gitignore
├── .prettierignore
├── .prettierrc.yml
├── .solcover.js
├── .solhint.json
└── hardhat.config.ts
```

### VSCode Integration

This template is IDE agnostic, but for the best user experience, you may want to use it in VSCode alongside Nomic
Foundation's [Solidity extension](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity).

### GitHub Actions

This template comes with GitHub Actions pre-configured. Your contracts will be linted and tested on every push and pull
request made to the `main` branch.

Note though that to make this work, you must use your `INFURA_API_KEY` and your `MNEMONIC` as GitHub secrets.

You can edit the CI script in [.github/workflows/ci.yml](./.github/workflows/ci.yml).

## Usage

### Pre Requisites

Install [docker](https://docs.docker.com/engine/install/)
<p align="center">
<a href="./fhevm-whitepaper.pdf"> 📃 Read white paper</a> |<a href="https://docs.zama.ai/fhevm"> 📒 Documentation</a> | <a href="https://zama.ai/community"> 💛 Community support</a> | <a href="https://github.com/zama-ai/awesome-zama"> 📚 FHE resources by Zama</a>
</p>

Install [pnpm](https://pnpm.io/installation)

Before being able to run any command, you need to create a `.env` file and set a BIP-39 compatible mnemonic as an
environment variable. You can follow the example in `.env.example`. If you don't already have a mnemonic, you can use
this [website](https://iancoleman.io/bip39/) to generate one.

Then, proceed with installing dependencies:

```sh
pnpm install
```

### Start fhevm

Start a local fhevm docker container that inlcudes everything needed to deploy FHE encrypted smart contracts

```sh
# In one terminal, keep it opened
# The node logs are printed
pnpm fhevm:start
```

To stop:

```sh
pnpm fhevm:stop
```

### Compile

Compile the smart contracts with Hardhat:

```sh
pnpm compile
```

### TypeChain

Compile the smart contracts and generate TypeChain bindings:

```sh
pnpm typechain
```
<p align="center">
<a href="https://github.com/zama-ai/fhevm/releases"><img src="https://img.shields.io/github/v/release/zama-ai/fhevm?style=flat-square"></a>
<a href="license"><img src="https://img.shields.io/badge/License-BSD--3--Clause--Clear-%23ffb243?style=flat-square"></a>
<a href="https://github.com/zama-ai/bounty-program"><img src="https://img.shields.io/badge/Contribute-Zama%20Bounty%20Program-%23ffd208?style=flat-square"></a>
</p>

### List accounts
fhEVM contracts is a library for encrypted smart contract development on fhEVM.

From the mnemonic in .env file, list all the derived Ethereum adresses:

```sh
pnpm task:accounts
```

### Get some native coins

In order to interact with the blockchain, one need some coins. This command will give coins to the first address derived
from the mnemonic in .env file.

```sh
pnpm fhevm:faucet
```

<br />
<details>
<summary>To get the first derived address from mnemonic</summary>
<br />

```sh
pnpm task:getEthereumAddress
```

</details>
<br />

### Deploy

Deploy the ERC20 to local network:

```sh
pnpm deploy:contracts
```

Notes: <br />

<details>
<summary>Error: cannot get the transaction for EncryptedERC20's previous deployment</summary>
## Getting Started

One can delete the local folder in deployments:
### Installation

```bash
rm -r deployments/local/
```

</details>
# Using npm
npm install fhevm-contracts

<details>
<summary>Info: by default, the local network is used</summary>
# Using Yarn
yarn add fhevm-contracts

One can change the network, check [hardhat config file](./hardhat.config.ts).

</details>
<br />

#### Mint

Run the `mint` task on the local network:

```sh
pnpm task:mint --network local --mint 1000 --account alice
# Using pnpm
pnpm add fhevm-contracts
```

### Test
### A Simple Example

Run the tests with Hardhat:
```solidity
// SPDX-License-Identifier: BSD-3-Clause-Clear

```sh
pnpm test
```

### Lint Solidity

Lint the Solidity code:

```sh
pnpm lint:sol
```
pragma solidity ^0.8.20;

### Lint TypeScript
import "fhevm/lib/TFHE.sol";
import "fhevm-contracts/contracts/token/ERC20/EncryptedERC20.sol";

Lint the TypeScript code:
contract MyERC20 is EncryptedERC20 {
function _transfer(address from, address to, uint256 amount) internal virtual override {
immortal-tofu marked this conversation as resolved.
Show resolved Hide resolved
require(_validRecipient(to), "ERC20WithSafeTransfer: invalid recipient");
super._transfer(from, to, amount);
}

```sh
pnpm lint:ts
function _validRecipient(address to) private view returns (bool) {
...
}
}
```

### Coverage
## Resources

Generate the code coverage report:
### Documentation

```sh
pnpm coverage
```
Full, comprehensive documentation is available here: [https://docs.zama.ai/fhevm](https://docs.zama.ai/fhevm).

### Report Gas
### Citations

See the gas usage per unit test and average gas per method call:
To cite fhEVM or the whitepaper in academic papers, please use the following entries:

```sh
REPORT_GAS=true pnpm test
```text
@Misc{fhEVM,
title={{Private smart contracts on the EVM using homomorphic encryption}},
author={Zama},
year={2023},
note={\url{https://github.com/zama-ai/fhevm}},
}
```

### Clean

Delete the smart contract artifacts, the coverage reports and the Hardhat cache:

```sh
pnpm clean
```text
@techreport{fhEVM,
author = "Morten Dahl, Clément Danjou, Daniel Demmler, Tore Frederiksen, Petar Ivanov,
Marc Joye, Dragos Rotaru, Nigel Smart, Louis Tremblay Thibault
",
title = "Confidential EVM Smart Contracts using Fully Homomorphic Encryption",
institution = "Zama",
year = "2023"
}
```

### Tasks

#### Deploy EncryptedERC20

Deploy a new instance of the EncryptedERC20 contract via a task:

```sh
pnpm task:deployERC20
```
### Contributing

## Tips
There are two ways to contribute to the Zama fhEVM contracts:

### Syntax Highlighting
- [Open issues](https://github.com/zama-ai/fhevm-contracts/issues/new/choose) to report bugs and typos, or to suggest new ideas
- Request to become an official contributor by emailing [email protected].

If you use VSCode, you can get Solidity syntax highlighting with the
[hardhat-solidity](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity) extension.
Becoming an approved contributor involves signing our Contributor License Agreement (CLA)). Only approved contributors can send pull requests, so please make sure to get in touch before you do!
<br></br>

## Using GitPod
### License

[GitPod](https://www.gitpod.io/) is an open-source developer platform for remote development.
This software is distributed under the **BSD-3-Clause-Clear** license. If you have any questions, please contact us at [email protected].

To view the coverage report generated by `pnpm coverage`, just click `Go Live` from the status bar to turn the server
on/off.
<p align="right">
<a href="#table-of-contents" > ↑ Back to top </a>
</p>

## Local development with Docker
## Support

Please check Evmos repository to be able to build FhEVM from sources.
<a target="_blank" href="https://community.zama.ai">
<img src="https://github.com/zama-ai/fhevm/assets/157474013/4e75e34e-df3f-4e9e-8a22-12b1d4013578">
</a>

## License
🌟 If you find this project helpful or interesting, please consider giving it a star on GitHub! Your support helps to grow the community and motivates further development.

This project is licensed under MIT.
<p align="right">
<a href="#about" > ↑ Back to top </a>
</p>
Loading