Skip to content

Commit

Permalink
Merge pull request #31 from zama-ai/packaging
Browse files Browse the repository at this point in the history 
chore: update README
  • Loading branch information
@jatZama
jatZama authored Mar 13, 2024
2 parents 2bdbeab + 446459f commit 33b13b5
Showing 1 changed file with 71 additions and 222 deletions.
293 changes: 71 additions & 222 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,259 +1,108 @@
# Hardhat Template [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Hardhat][hardhat-badge]][hardhat] [![License: MIT][license-badge]][license]
# fhEVM Contracts

[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
<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>

A Hardhat-based template for developing Solidity smart contracts, with sensible defaults.
<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>

- [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 is a library for encrypted smart contract development on fhEVM.

## 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/)

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
```

### List accounts

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>

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

Run the tests with Hardhat:
### A Simple Example

```sh
pnpm test
```
```solidity
// SPDX-License-Identifier: BSD-3-Clause-Clear
### Lint Solidity
pragma solidity ^0.8.20;
Lint the Solidity code:
import "fhevm/lib/TFHE.sol";
import "fhevm-contracts/contracts/token/ERC20/EncryptedERC20.sol";
```sh
pnpm lint:sol
contract MyERC20 is EncryptedERC20 {
constructor() EncryptedERC20("MyToken", "MYTOKEN") {
_mint(1000000, msg.sender);
}
}
```

### Lint TypeScript

Lint the TypeScript code:
## Resources

```sh
pnpm lint:ts
```
### Documentation

### Coverage
Full, comprehensive documentation is available here: [https://docs.zama.ai/fhevm](https://docs.zama.ai/fhevm).

Generate the code coverage report:

```sh
pnpm coverage
```
### Citations

### Report Gas
To cite fhEVM or the whitepaper in academic papers, please use the following entries:

See the gas usage per unit test and average gas per method call:

```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>

0 comments on commit 33b13b5

Please sign in to comment.