Skip to content

Latest commit

 

History

History
286 lines (208 loc) · 12 KB

README.md

File metadata and controls

286 lines (208 loc) · 12 KB
Raw

Zeth - Zerocash on Ethereum

macOS build ubuntu build

WARNING This project is a Proof of Concept. It is highly inefficient and has not been thoroughly reviewed. Please do not use in production!

Disclaimer: This work is inspired from babyzoe, Miximus. It follows and extends the design presented in zerocash-ethereum by adapting some code initially written by Zcash.

It is not intended for handling real value or for use on public networks. The authors have not created any such deployment, and assume no responsibility for any fork of the code or deployment created by other parties.

Check our paper, and the protocol specifications for more information about Zeth.

Collaboration is welcome. Consider opening an issue or a pull-request targeting this repository, or writing a Zeth Protocol Improvement Proposal (ZPIP).

Building and running the project:

Warning This project primarily targets x86_64 Linux and macOS platforms.

Environment

In order to follow the README below, you will need:

  • Docker
  • Npm (at least version 6.9.0)
  • Node (recommended version v10 to be able to build and use the custom ganache-cli)
  • Python3 (at least version 3.7)
  • Pip (at least version 19.0.2)

Additionally, several tools from the GCC and LLVM tools suite are used to improve code quality and generate the documentation of the project. These are required in order to compile the project with all options enabled:

To use the Zeth functionality, 3 components are required:

  • An Ethereum network (the commands below use a local testnet) to host the Zeth contracts and handle transactions.
  • A running prover-server process, used by Zeth clients to generate proofs.
  • Client tools, which generate all inputs required for a Zeth operations, request proofs from the prover-server, and transmit transactions to the Ethereum network holding the Zeth contract.

We use 3 terminals, one for each of the above components.

Note: Mac users should increase docker runtime memory from 2GB to 4GB to allow Terminal 1 to complete successfully.

Terminal 1:

We propose 2 alternatives to run the prover-server below.

Fetch the prover-server image (recommended)
docker pull ghcr.io/clearmatics/zeth:latest-prover
docker run -ti -p 50051:50051 --name prover ghcr.io/clearmatics/zeth:latest-prover prover-server
Build and run the prover-server in the development container
# Clone this repository:
git clone [email protected]:clearmatics/zeth.git
cd zeth

# Build the zeth-dev image
docker build -f Dockerfile-dev -t zeth-dev .
# Start the zeth development container
docker run -ti -p 50051:50051 --name zeth zeth-dev:latest

# All the commands below are run in the docker container
# Configure your environment
. ./setup_env.sh

# Compile the proving server
mkdir build
cd build
cmake .. [<flags (see below)>]
# Compile all libraries and tools, including the prover-server
make
# (optional) Run the unit tests
make test
# (optional) Run the all tests (unit tests, syntax checks, etc)
make check

# Start the prover-server process
prover-server

Note: By default, prover-server generates a key at startup. Flags can be used to force the server to load and/or save keys. Run prover-server --help for more details.

Build Options

Some flags to the cmake command can control the build configuration. -DCMAKE_BUILD_TYPE=Release or -DCMAKE_BUILD_TYPE=Debug can be used to force a release or debug build.

By default, zeth makes use of the GROTH16 zk-snark. To chose a different zksnark run the following: cmake -DZETH_SNARK=$ZKSNARK .. where $ZETH_SNARK is PGHR13 (see https://eprint.iacr.org/2013/279, http://eprint.iacr.org/2013/879) or GROTH16(see https://eprint.iacr.org/2016/260).

Terminal 2: Ethereum testnet

scripts/ganache-start

Terminal 3: Python client

# Configure your environment
. ./setup_env.sh

cd client

Follow the steps described in the client README to run tests or invoke the zeth tools.

Secure Multi Party Computation for the Groth16 SRS generation

See MPC for SRS generation documentation

Development dependencies (for building outside of the Docker container)

Immediate dependencies are provided as submodules and compiled during the Zeth build. Ensure submodules are synced.

The following libraries are also required to build:

  • grpc
  • gmp
  • boost
  • openssl

Generate the Doxygen documentation

To generate the documentation of Zeth:

cd build
cmake .. -DGEN_DOC=ON && make docs

Compile the project using 'sanitizers'

You can select the sanitizer of your choice (one of the sanitizers listed here) by passing the flag -DSANITIZER=<sanitizer> to cmake.

Example:

cd build
cmake -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DSANITIZER=Address -DCMAKE_BUILD_TYPE=Debug ..
make check

Docker images

Docker files Image Tags Description
./Dockerfile-prover ghcr.io/clearmatics/zeth:latest-prover latest-prover, X.Y.Z-prover - Release of zeth, git-%HASH%-prover - developers build by git-commit Zeth Prover Server. Image use zeth-base for building
./Dockerfile-client ghcr.io/clearmatics/zeth:latest-client latest-client, X.Y.Z-client - Release of zeth, git-%HASH%-client - developers build by git-commit Python client to interact with the prover
./Dockerfile-mpc ghcr.io/clearmatics/zeth:latest-mpc latest-mpc, X.Y.Z-mpc - Release of zeth, git-%HASH%-mpc - developers build by git-commit Tools for Multi-Party Computation. Image use zeth-base for building
./Dockerfile-base ghcr.io/clearmatics/zeth:latest-base latest-base, A.B.C-base - Release of zeth-base Base image for building other containers

Run analysis tools on the code

Several tools can be ran on the code. These can be enabled via a set of compilation options.

Note: The clang-tidy target runs a clang-tidy python script that should be fetched from here. To do so, run: cd build && wget https://raw.githubusercontent.com/llvm/llvm-project/master/clang-tools-extra/clang-tidy/tool/run-clang-tidy.py

Example:

# run-clang-tidy.py needs to be in the PATH to be found
PATH=$PATH:${PWD}
chmod +x run-clang-tidy.py

cmake -DUSE_CLANG_FORMAT=ON -DUSE_CPP_CHECK=ON -DUSE_CLANG_TIDY=ON ..
make cppcheck
make clang-format
make clang-tidy

Generate code coverage report

  1. Make sure to enable the CODE_COVERAGE option in the CMake configuration.
  2. Compile the tests
cd build && cmake -DCODE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug .. && make check
  1. Generate the coverage report:
make coverage

Note: In order to generate the coverage reports, you will need lcov, along with genhtml and xdg-open.

References and useful links

License notices:

Zcash

Copyright (c) 2016-2018 The Zcash developers
Copyright (c) 2009-2018 The Bitcoin Core developers
Copyright (c) 2009-2018 Bitcoin Developers

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


The MIT software license (http://www.opensource.org/licenses/mit-license.php)
above applies to the code directly included in this source distribution.
Dependencies downloaded as part of the build process may be covered by other
open-source licenses. For further details see 'contrib/debian/copyright'.


This product includes software developed by the OpenSSL Project for use in the
OpenSSL Toolkit (https://www.openssl.org/). This product includes cryptographic
software written by Eric Young ([email protected]).


Although almost all of the Zcash code is licensed under "permissive" open source
licenses, users and distributors should note that when built using the default
build options, Zcash depends on Oracle Berkeley DB 6.2.x, which is licensed
under the GNU Affero General Public License.

Libsnark

The libsnark library is developed by SCIPR Lab (http://scipr-lab.org)
and contributors.

Copyright (c) 2012-2014 SCIPR Lab and contributors (see AUTHORS file).

All files, with the exceptions below, are released under the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Miximus

barryWhiteHat/miximus GNU General Public License v3.0