Note that Nightfall is no longer being updated. Please see Nightfall_3 instead
Nightfall integrates a set of smart contracts and microservices, and the ZoKrates zk-snark toolkit, to enable standard ERC-20 and ERC-721 tokens to be transacted on the Ethereum blockchain with complete privacy. It is an experimental solution and still being actively developed. We decided to share our research work in the belief that this will speed adoption of public blockchains. This is not intended to be a production-ready application and we do not recommend that you use it as such. If it accelerates your own work, then we are pleased to have helped. We hope that people will feel motivated to contribute their own ideas and improvements.
Note that this code has not yet completed a security review and therefore we strongly recommend that you do not use it in production or to transfer items of material value. We take no responsibility for any loss you may incur through the use of this code.
As well as this file, please be sure to check out:
- The Whitepaper for technical details on the protocols and their application herein.
- contributions.md to find out how to contribute code.
- limitations.md to understand the limitations of the current code.
- license.md to understand how we have placed this code completely in the public domain, without restrictions (but note that Nightfall makes use of other open source code which does apply licence conditions).
- UI.md to learn how to drive the demonstration UI and make transactions.
- SECURITY.md to learn about how we handle security issues.
Critical security updates will be listed here. If you had previously installed Nightfall prior to one of these security updates, please pull the latest code, and follow the extra re-installation steps.
These instructions give the most direct path to a working Nightfall setup. The application is compute-intensive and so a high-end processor is preferred. Depending on your machine, setup can take one to several hours.
Mac and Linux machines with at least 16GB of memory and 10GB of disk space are supported.
The Nightfall demonstration requires the following software to run:
- Docker
- Launch Docker Desktop (on Mac, it is on the menu bar) and set memory to 12GB with 4GB of swap space (minimum - 16GB memory is better). The default values for Docker Desktop will NOT work. No, they really won't.
- Python
- Be sure npm is setup to use v2.7 of python, not python3. To check the python version, run
python --version
- You may need to run
npm config set python /usr/bin/python2.7
(or wherever your python 2 location is)
- Be sure npm is setup to use v2.7 of python, not python3. To check the python version, run
- Node (tested with node 14.15.0) with npm and node-gyp.
- Will not work with node v15. To check the node version, run
node --version
- If using mac/brew, then you may need to run
brew install node@14
andbrew link --overwrite node@14 --force
- Will not work with node v15. To check the node version, run
- Xcode Command line tools:
- If running macOS, install Xcode then run
xcode-select --install
to install command line tools.
- If running macOS, install Xcode then run
Start Docker:
- On Mac, open Docker.app.
Clone the Nightfall repository:
git clone git@github.com:EYBlockchain/nightfall.git
or:
git clone https://github.com/EYBlockchain/nightfall.git
Enter the directory:
cd <path/to/nightfall>
For Linux users:
-
Change permission for the directory
sudo chmod 777 -R zkp/code/
-
Add the Linux user to docker group to run Docker commands without sudo (read more). Then log out and enter again.
sudo groupadd docker sudo usermod --append --groups docker $USER
For Mac & Linux users:
Next set a environment variable NPM_TOKEN, value should be a github
personal access token with :repo
and :read-package
permission granted.
export NPM_TOKEN=XXXXX
Next pull a compatible Docker image of ZoKrates
docker pull zokrates/zokrates:0.5.1
Next we have to generate the keys and constraint files for Zero Knowledge Proofs (read more), this is about 7GB and depends on randomness for security. This step can take a while, depending on your hardware. Before you start, check once more that you have provisioned enough memory for Docker, as described above:
./nightfall-generate-trusted-setup
Note that this is an automated run. For an initial installation, select the option to generate all files. For more information on the MiMC hashing option and further documentation on the setup process, see the zkp module documentation.
Please be patient - you can check progress in the terminal window and by using docker stats
in
another terminal.
You just created all the files needed to generate zk-SNARKs. The proving keys, verifying keys and constraint files will allow you to create hidden tokens, move them under zero knowledge and then recover them — both for fungible (ERC-20) and non-fungible (ERC-721) tokens.
If this isn't your first time running Nightfall, but you have just pulled new changes from the repo, then you might need to 're-install' certain features due to code changes. First run:
docker-compose -f docker-compose.yml build
It's important to re-run the trusted setup if any of the .zok
files have been modified since your
last pull of the repo. You can check by comparing the latest version of Nightlite (where the .zok
files are stored):
npm info @eyblockchain/nightlite version
with the version you are using:
cd zkp
npm list @eyblockchain/nightlite
If this shows that your version is behind, then you may need to re-install, as above, then re-run:
./nightfall-generate-trusted-setup
(If only one or a few of the .zok
files have been changed, then it will be faster for you to
consult the zkp module documentation for details on selecting individual files for
trusted setup).
🌃 We're ready to go! Be sure to be in the main directory and run the demo:
./nightfall
and wait until you see the message Compiled successfully
in the console.
This brings up each microservice using docker-compose and finally builds a UI running on a local Angular server.
Navigate your web browser to http://localhost:8000 to start using Nightfall (give everything enough time to start up). There are instructions on how to use the application in the UI.md file.
Note that ./nightfall has deployed an ERC-20 and ERC-721 contract for you (specifically FToken.sol and NFTokenMetada.sol). These are designed to allow anyone to mint tokens for demonstration purposes. You will probably want to curtail this behaviour in anything but a demonstration.
The UI pulls token names from the contracts you deploy. In the present case, the tokens are called EY OpsCoin for the ERC-20 and EY Token for ERC-721.
Note that it can take up to 10 mins to compute a transfer proof (depending on your machine) and the
demonstration UI is intentionally modal while this happens (even though the action returns a
promise). You can see what's happening if you look at the terminal where you ran ./nightfall
.
If you want to close the application, make sure to stop containers and remove containers, networks, volumes, and images created by up, using:
docker-compose down -v
See the zkp module documentation, "run zkp unit tests".
Be sure to be in the main directory and then open terminal and run
./nightfall-test
- Mac
- Test suites will open a terminal, where you can see test container's log. This terminal will close automatically.
- configure
Terminal.app
to close window when shell exitsexit
.
For details, see the zkp readme. The compliance version requires you to have selected the correct trusted setup when you ran
./nightfall-generate-trusted-setup
After that, you can start it with
./nightfall compliance
Nightfall will inject test keys into the underlying Nightfall library, warning you that it has done
so. To log in as a compliance administrator, use username admin
, password admin
. This is only
for demonstration of course. You should use an appropriate access control system for any other
purpose.
Nightfall will operate with any ERC-20 and ERC-721 compliant contract. The contracts' addresses are fed into FTokenShield.sol and NFTokenShield.sol respectively during the Truffle migration and cannot be changed subsequently.
If you wish to use pre-existing ERC-20 and ERC-721 contracts then edit 2_Shield_migration.js
so
that the address of the pre-existing ERC-20 contract is passed to FTokenShield and the address of
the pre-existing ERC-721 contract is passed to NFTokenShield i.e. replace FToken.address
and
NFTokenMetadata.address
.
This can also be done from UI, by clicking on the user to go to settings, then clicking on contracts option in this page. A new shield contract address that has been deployed separately can be provided here. This new contract will be a replacement for NFTokenShield.sol or FTokenShield.sol. Each of these contracts currently shields the tokens of an ER721 or ERC20 contract instance respectively.
The demo mode uses Ganache-cli as a blockchain emulator. This is easier than using a true blockchain
client but has the disadvantage that Ganache-cli doesn't currently support the Whisper protocol,
which Nightfall uses for exchanging secrets between sender and receiver. Accordingly we've written a
Whisper stub, which will emulate whisper for participants who are all on the same node server. If
you want to run across multiple blockchain nodes and server instances then replace all occurrences
of the words whisper-controller-stub
with whisper-controller
in the code — but you will need to
use Geth rather than Ganache-cli and construct an appropriate Docker container to replace the
Ganache one we provide.
Team Nightfall thanks those who have indirectly contributed to it, with the ideas and tools that they have shared with the community: