Our library compiles seamlessly with the traditional Solidity compiler and is generally compatible with traditional Solidity tools. However, it's important to note that the execution is designed to function exclusively on a fhEVM. As a result, this library is not intended for deployment on a classic EVM, such as Goerli or Ganache.
To get started with fhEVM Solidity Library, you need to install it as a dependency in your JavaScript project. You can do this using npm (Node Package Manager) or Yarn. Open your terminal and navigate to your project's directory, then run one of the following commands:
This will download and install the fhEVM Solidity Library and its dependencies into your project.
1/ For quick prototyping of a specific feature, use the Zama version of the Remix IDE. This will let you quickly deploy a contract on the devnet via Metamask, and interact easily with it through the Remix UI. Otherwise, for a bigger project, you should use our custom fhevm-hardhat-template repository. Hardhat is a popular development environment for Solidity developers and will let you test and deploy your contracts to the fhEVM using TypeScript.
2/ A good first step is to start with an unencrypted version of the contract you want to implement, as you would usually do on a regular EVM chain. It is easier to reason first on cleartext variables, before thinking on how to add confidentialy.
3/ When you're ready, you can start to add confidentiality by using the TFHE solidity library. Typically, this would involve converting some uintX types to euintX, as well as following all the detailed advices that we gave in the pitfalls to avoid and best practises section of the documentation. For inspiration, you can take a look at the examples inside the fhevm repository. If you're using the Hardhat template, read the advices that we gave in the Hardhat section.
The fhEVM does not work with Foundry as Foundry employs its own EVM, preventing us from incorporating a mock for our precompiled contract. An ongoing discussion is exploring the possibility of incorporating a plugin system for precompiles, which could potentially pave the way for the utilization of Foundry at a later stage.
However, you could still use Foundry with the mocked version of the fhEVM, but please be aware that this approach is NOT recommended, since the mocked version is not fully equivalent to the real fhEVM node's implementation (see warning in hardhat). In order to do this, you will need to rename your TFHE.sol imports from fhevm/lib/TFHE.sol to fhevm/mocks/TFHE.sol in your solidity source files.
The best way to start writing smart contracts with fhEVM is to use our Hardhat template.
It allows you to start a fhEVM docker image and run your smart contract on it. Read the README for more information.
When developing confidential contracts, we recommend to use first the mocked version of fhEVM for faster testing with pnpm test:mock and coverage computation via pnpm coverage:mock, this will lead to a better developer experience. However, keep in mind that the mocked fhEVM has some limitations and discrepencies compared to the real fhEVM node, as explained in the warning section at the end of this section.
It's essential to run tests of the final contract version using the real fhEVM. You can do this by running pnpm test before deployment.
For faster testing iterations, instead of launching all the tests on the local fhEVM node via pnpm testor npx hardhat test which could last several minutes, you could use instead a mocked version of the TFHE.sol library. The same tests should (almost always) pass, as is, without any modification: neither the javascript files neither the solidity files need to be changed between the mocked and the real version. The mocked mode does not actually use encryption for encrypted types and runs the tests on a local hardhat node which is implementing the original EVM (i.e non-fhEVM).
To run the mocked tests use either:
Or equivalently:
In mocked mode, all tests should pass in few seconds instead of few minutes, allowing a better developer experience.
Furthermore, getting the coverage of tests is only possible in mocked mode. Just use the following command:
Or equivalently:
Then open the file coverage/index.html. This will allow increased security by pointing out missing branches not covered yet by the current test suite.
⚠️ Warning : Notice that, due to intrinsic limitations of the original EVM, the mocked version differ in few corner cases from the real fhEVM, the most important change is the TFHE.isInitialized method which will always return true in the mocked version. Another big difference in mocked mode, compared to the real fhEVM implementation, is that there is no ciphertext verification neither checking that a ciphertext has been honestly obtained in the mocked version (see section 4 of the whitepaper). This means that before deploying to production, developers still need to run the tests with the original fhEVM node, as a final check in non-mocked mode, with pnpm test or npx hardhat test.
You can use Remix to interact with a blockchain using fhEVM. If you want to send an encrypted input, you need to encrypt it with fhevmjs CLI tool for example. It becomes more complex if you want to reencrypt a value directly in Remix.
To avoid this problem, we developed a version of Remix IDE with these two missing features:
Encryption of input
Generation of public key and signature for reencryption and decryption.
You can use it on https://remix.zama.ai.
To import TFHE library, simply import it at the top of your contract.
import "fhevm/lib/TFHE.sol";
Be sure to be on the correct network before deploying your contract
````
