Skip to content

Commit

Permalink
Refactor README.md and add more development docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@popzxc
popzxc committed Sep 8, 2020
1 parent 4dd9fba commit f0182d6
Show file tree
Hide file tree
Showing 5 changed files with 344 additions and 240 deletions.
254 changes: 14 additions & 240 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
# zkSync: scaling and privacy engine for Ethereum

zkSync io [Live on Mainnet!](https://wallet.zksync.io).
[![Logo](zkSyncLogo.svg)](https://zksync.io/)

[![Live on Mainnet](https://img.shields.io/badge/wallet-Live%20on%20Mainnet-blue)](https://wallet.zksync.io)
[![Live on Rinkeby](https://img.shields.io/badge/wallet-Live%20on%20Rinkeby-blue)](https://rinkeby.zksync.io)
[![Join the technical discussion chat at https://gitter.im/matter-labs/zksync](https://badges.gitter.im/matter-labs/zksync.svg)](https://gitter.im/matter-labs/zksync?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

zkSync is a scaling and privacy engine for Ethereum. Its current functionality scope includes low gas transfers of ETH and ERC20 tokens in the Ethereum network. This document is a description of the JS library that can be used to interact with zkSync.

zkSync is a scaling and privacy engine for Ethereum. Its current functionality scope includes low gas transfers of ETH and ERC20 tokens in the Ethereum network.

## Description

zkSync is built on ZK Rollup architecture. ZK Rollup is an L2 scaling solution in which all funds are held by a smart contract on the mainchain, while computation and storage are performed off-chain. For every Rollup block, a state transition zero-knowledge proof (SNARK) is generated and verified by the mainchain contract. This SNARK includes the proof of the validity of every single transaction in the Rollup block. Additionally, the public data update for every block is published over the mainchain network in the cheap calldata.

Expand All @@ -18,247 +23,16 @@ In other words, ZK Rollup strictly inherits the security guarantees of the under

To learn how to use zkSync, please refer to the [zkSync SDK documentation](https://zksync.io).

## Prerequisites

Prepare dev environment prerequisites: see [docs/setup-dev.md](docs/setup-dev.md)

## Setup local dev environment

Setup:

```sh
zksync init
```

During the first initialization you have to download around 8 GB of setup files, this should be done once.
If you have a problem on this step of the initialization, see help for the `zksync plonk-setup` command.

To completely reset the dev environment:

- Stop services:
```sh
zksync dev-down
```
- Repeat the setup procedure above

# (Re)deploy db and contraсts:

```sh
zksync redeploy
```

## Environment configurations

Env config files are held in `etc/env/`

List configurations:

```sh
zksync env
```

Switch between configurations:

```sh
zksync env <ENV_NAME>
```

## Build and run server + prover locally for development:

Run server:

```sh
zksync server
```

Server is configured using env files in `./etc/env` directory.
After the first initialization, file `./etc/env/dev.env` will be created. By default, this file is copied from the `./etc/env/dev.env.example` template.

Server can produce block of different sizes, the list of available sizes is determined by the `SUPPORTED_BLOCK_CHUNKS_SIZES` environment variable.
Block sizes which will actually be produced by the server can be configured using the `BLOCK_CHUNK_SIZES` environment variable.

Note: for proof generation for large blocks requires a lot of resources and an average user machine
is only capable of creating proofs for the smallest block sizes.

After that you may need to invalidate `cargo` cache by touching the files of `models`:

```sh
touch core/models/**/*.rs
```

This is required, because `models` take the environment variable value at the compile time, and
we have to recompile this module to set correct values.

If you use additional caching systems (like `sccache`), you may have to remove their cache as well.

Run prover:

```sh
zksync prover
```

Run client

```sh
zksync client
```

Client UI will be available at http://localhost:8080.
Make sure you have environment variables set right, you can check it by running:
`zksync env`. You should see `* dev` in output.

## Build and push images to dockerhub:

```sh
zksync dockerhub-push
```

# Development

## Committing changes

`zksync` uses pre-commit git hooks for basic code integrity checks. Hooks are set up automatically
within the workspace initialization process. These hooks will not allow to commit the code which does
not pass several checks.

Currently the following criteria are checked:

- Code should always be formatted via `cargo fmt`.
- Dummy Prover should not be staged for commit (see below for the explanation).

## Database migrations

-
```sh
cd core/storage
```
- Add diesel migration
- Rename `core/storage/schema.rs.generated` to `schema.rs`
- Run tests:
```sh
zksync db-tests
```

## Testing

- Running all the `rust` tests:

```sh
f cargo test
```

- Running the database tests:

```sh
zksync db-tests
```
- Running the integration test:

```sh
zksync server # Has to be run in the 1st terminal
zksync prover # Has to be run in the 2nd terminal
zksync integration-simple # Has to be run in the 3rd terminal
```

- Running the full integration tests (similar to `integration-simple`, but performs different full exits)

```sh
zksync server # Has to be run in the 1st terminal
zksync prover # Has to be run in the 2nd terminal
zksync integration-full-exit # Has to be run in the 3rd terminal
```

- Running the circuit tests:

```sh
zksync circuit-tests
```

- Running the prover tests:

```sh
zksync prover-tests
```

- Running the benchmarks:

```sh
f cargo bench
```

- Running the loadtest:

```sh
zksync server # Has to be run in the 1st terminal
zksync prover # Has to be run in the 2nd terminal
zksync loadtest # Has to be run in the 3rd terminal
```

## Using Dummy Prover

Using the real prover for the development can be not really handy, since it's pretty slow and resource consuming.

Instead, one may want to use the Dummy Prover: lightweight version of prover, which does not actually proves anything,
but acts like it does.

To enable the dummy prover, run:

```sh
zksync dummy-prover enable
```

And after that you will be able to use the dummy prover instead of actual prover:

```sh
zksync dummy-prover # Instead of `zksync prover`
```

**Warning:** `setup-dummy-prover` subcommand changes the `Verifier.sol` contract, which is a part of `git` repository.
Be sure not to commit these changes when using the dummy prover!

If one will need to switch back to the real prover, a following command is required:

```sh
zksync dummy-prover disable
```

This command will revert changes in the contract and redeploy it, so the actual prover will be usable again.

Also you can always check the current status of the dummy verifier:

```sh
$ zksync dummy-prover status
Dummy Verifier status: disabled
```


## Developing circuit

* To generate proofs one must have the universal setup files (which are downloaded during the first initialization).
* To verify generated proofs one must have verification keys. Verification keys are generated for specific circuit & Verifier.sol contract; without these keys it is impossible to verify proofs on the Ethereum network.

Steps to do after updating circuit:
1. Update circuit version by updating `KEY_DIR` in your env file (don't forget to place it to `dev.env.example`)
(last parts of this variable usually means last commit where you updated circuit).
2. Regenerate verification keys and Verifier contract using `zksync verify-keys gen` command.
3. Pack generated verification keys using `zksync verify-keys pack` command and commit resulting file to repo.


## Contracts

### Re-build contracts:

```sh
zksync build-contracts
```
## Development Documentation

### Publish source code on etherscan
The following guides for developers are available:

```sh
zksync publish-source
```
- Installing development dependencies: [docs/setup-dev.md](docs/setup-dev.md).
- Launching zkSync locally: [docs/launch.md](docs/launch.md).
- Development guide: [docs/development.md](docs/development.md).
- Repository architecture overview: [docs/architecture.md](docs/architecture.md).

# License
## License

zkSync is distributed under the terms of both the MIT license
and the Apache License (Version 2.0).
Expand Down
73 changes: 73 additions & 0 deletions docs/architecture.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# zkSync project architecture

This document covers the structure of this repository.

## High-Level Overview

zkSync repository consists of several applications:

- zkSync smart contract: a Solidity smart contract deployed on the Ethereum blockchain,
which manages users' balances and verifies the correctness of operations performed within
zkSync network.
- Prover application: a worker application that creates a proof for an executed block.
Prover applications poll Server application for available jobs, and once there is a new
block, server provides a witness (input data to generate a proof), and prover starts working.
Once proof is generated, it is reported to the Server application, and Server publishes the
proof to the smart contract.
Prover application is considered an on-demand worker, thus it is OK to have many provers (if
server load is high) or no provers at all (if there are no incoming transactions).
Generating a proof is a very resource consuming work, thus machines that run a prover application
must have a modern CPU and a lot of RAM.
- Server application: a node running the zkSync network. It is capable of following things:
- Monitoring the smart contract for the onchain operations (such as deposits).
- Accepting transactions.
- Generating zkSync chain blocks.
- Requesting proofs for executed blocks.
- Publishing data to the smart contract.
- Explorer: zkSync network explorer. A web application that receives data from the Server API
and renders it to the convenient blockchain explorer interface.

Thus, in order to get a local zkSync setup running, the following has to be done:

- zkSync smart contract is compiled and deployed to the Ethereum.
- zkSync server is launched.
- At least one prover is launched and connected to the Server application.


## Low-Level Overview

This section provides an overview on folders / sub-projects that exist in this repository.

- `/bin`: Infrastructure scripts which help to work with zkSync applications.
- `/contracts`: Everything related to zkSync smart-contract.
- `/contracts`: Smart contracts code
- `/scripts` && `/src.ts`: TypeScript scripts for smart contracts management.
- `/core`: Code of the sub-projects that implement zkSync network.
- `/bin`: Applications mandatory for zkSync network to operate.
- `/server`: zkSync server application.
- `/prover`: zkSync prover application.
- `/data_restore`: Utility to restore a state of the zkSync network from a smart contract.
- `/key_generator`: Utility to generate verification keys for network.
- `/lib`: Dependencies of the binaries above.
- `/circuit`: Cryptographic environment enforsing the correctness of executed transactions in the zkSync network.
- `/crypto_exports`: Re-exports for used external cryptographic libraries.
- `/eth_client`: Module providing an interface to interact with an Ethereum node.
- `/models`: Various types declarations and primitive functions using throughout zkSync crates.
- `/plasma`: A fast pre-circuit executor for zkSync transactions used on the Server level to generate blocks.
- `/storage`: An encapsulated database interface.
- `/vlog`: An utility library for verbose logging.
- `/tests`: Testing infrastructure for zkSync network.
- `/loadtest`: An application for highload testing of zkSync server.
- `/testkit`: A relatively low-level testing library and test suite for zkSync.
- `/ts-test`: Integration tests set implemented in TypeScript. Requires a running Server and Prover applications to operate.
- `/docker`: Dockerfiles used for development of zkSync and for packaging zkSync for a production environment.
- `/etc`: Configration files.
- `/env`: `.env` files that contain environment variables for different configuration of zkSync Server / Prover.
- `/js`: Configuration files for JavaScript applications (such as Explorer).
- `/tesseracts`: Configuration for `tesseracts` minimalistic blockchain explorer (used for development).
- `/tokens`: Configuration of supported Ethereum ERC-20 tokens.
- `/explorer`: A blockchain explorer for zkSync network.
- `/keys`: Verification keys for `circuit` module.
- `/sdk`: Implementation of client libraries for zkSync network in different programming languages.
- `/zksync-crypto`: zkSync network cryptographic primitives, which can be compiled to WASM.
- `/zksync.js`: A JavaScript / TypeScript client library for zkSync.
Loading

0 comments on commit f0182d6

Please sign in to comment.