Skip to content
Branch: master
Find file History
Brechtpd [Protocol3] Added check for new Merkle root value (#451)
* [Protocol3] Added extra checks that the Merkle roots fit into the field

* [Protocol3] Added test for invalid new Merkle root value
Latest commit 1efa91a Aug 22, 2019
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
circuit [Protocol3] Added circuit testing support + small improvements (#396) Aug 12, 2019
contracts [Protocol3] Added check for new Merkle root value (#451) Aug 22, 2019
docker [Protocol3] Add contracts dump file to gitignore (#346) (#347) Aug 4, 2019
ethsnarks @ f515916 [Protocol3] Added circuit testing support + small improvements (#396) Aug 12, 2019
migrations [Protocol3] Reimplement protocol and exchange registry (#445) Aug 18, 2019
operator [Protocol3] Fixed failing tests + Minor misc improvements (#431) Aug 14, 2019
test [Protocol3] Added check for new Merkle root value (#451) Aug 22, 2019
util [Protocol3] Reimplement protocol and exchange registry (#445) Aug 18, 2019
.eslintrc.js [Protocol3] replace tslint with eslint and fix some solium issues (#279) Jul 19, 2019
.gitignore [Loopring3] refactor deployment process to support upgradability (#384) Aug 12, 2019
.soliumignore [Protocol3] Batched proof verification (#283) Jul 25, 2019
.soliumrc.json Protocol3: split exchange code into multiple small libraries. (#58) Mar 29, 2019
.travis.yml remove Errors.sol (#26) Mar 23, 2019
BACKEND.md [Protocol3] Backend docs update (#416) Aug 13, 2019
CMakeLists.txt move packages to packages dir Mar 18, 2019
DESIGN.md [Protocol3] Revert design updates Jun 5, 2019
LICENSE move packages to packages dir Mar 18, 2019
Makefile Update Makefile to use release on Mac (#406) Aug 12, 2019
README.md [Protocol3] install truffle-flattener (#435) Aug 16, 2019
ganache.sh [Loopring3] refactor deployment process to support upgradability (#384) Aug 12, 2019
genAbi.sh [Loopring3] refactor deployment process to support upgradability (#384) Aug 12, 2019
globals.d.ts [Protocol3] WIP: signing in JS May 30, 2019
install [Protocol3] Update README.md and package.json (#371) Aug 8, 2019
package-lock.json [Protocol3] install truffle-flattener (#435) Aug 16, 2019
package.json [Protocol3] Reimplement protocol and exchange registry (#445) Aug 18, 2019
truffle.js [Protocol3] Try to fix out-of-gas issue when deploying on mainnet - n… Aug 13, 2019
tsconfig.json [Protocol3] Calldata compression (#221) Jun 25, 2019

README.md

Loopring Protocol (V3) using zkSNARKs

About

This is a very early version of Loopring's order-based DEX protocol (version 3.0). The code base is still being tested and is not production ready.

To understand several concepts introduced by the Loopring Protocol, such as order-ring, ring-matching, dual-authoring, free-burning, please read our whitepaper for Loopring Protocol 2.x.

To understand the overall design for Loopring 3.0, including Ethereum smart contracts and zkSNARKs circuits, please refer to the DESIGN doc. The design of the backend relayer system is and will not be covered by this document. We welcome any feedback regarding the design and our implementation, feel free to email us or submit pull requests.

Performance

Loopring 2.x Loopring 3.0
(w/ Data Availability)
Loopring 3.0
(w/o Data Availability)
Trades per Ethereum Block 26 5350 92000
Trades per Second ~2 350 6150
Cost per Trade ~300,000 gas 1500 gas 87 gas

After Istanbul:

Loopring 2.x Loopring 3.0
(w/ Data Availability)
Loopring 3.0
(w/o Data Availability)
Trades per Ethereum Block 26 20800 140000
Trades per Second ~2 1400 9350
Cost per Trade ~300,000 gas 385 gas 57 gas
  • Cost in USD per Trade in the table does not cover off-chain proof generation.

Top Features

  • Onchain data-availability (DEXes can opt out for even greater throughput & lower cost)
  • All ERC20 tokens and Ether are supported by default
  • Multiple on-chain DEX instances with isolated state and dedicated event stream (different from 2.0)
  • Onchain deposit + on-chain & offchain withdrawal support
  • Support offchain order cancellation and order time-to-live settings (inherited from 2.0)
  • Allow partial order matching (aka partial fill) and offchain order-scaling (inherited from 2.0)
  • Multiple circuit permutations for different request batch sizes
  • Use tokens/ether traded as trading fee
  • A built-in mechanism to force DEX operators to fulfill duties in time (especially for handling deposits and withdrawals)
  • Support DEX operators to stake tokens to lower down protocol fees
  • Support a "maintenance mode" for DEX operators to upgrade backends within a time window
  • Support a unique feature called Order Aliasing (new to 3.0)
  • 100% secure for end users, even when DEX operators are evil (same as 2.0)
  • whitelist support through customizable sub-contract
  • and more...

Challenges

  • SNARKs require trusted setups

Build

npm run build // first time or npm run compile or npm run watch.

Circuits

The code of our circuits is currently not open source. If you have access to the private repo protocol3-circuits please clone it and update the circuit_src_folder variable in circuit/CMakeLists.txt so it points to the correct folder.

make

The circuit tests can be run with npm run build && npm run testc. A single test can be run with npm run test-circuits <test_name>.

Run Unit Tests

  • please clone the circuits repository https://github.com/Loopring/protocol3-circuits.git to the same directory as this project.
  • please make sure you run npm run build for the first time.
  • run npm run ganache from project's root directory in terminal.
  • run npm run test from project's root directory in another terminal window.
  • run single test: npm run test -- transpiled/test/xxx.js
  • print info logs in tests: npm run test -- -i
  • print more detailed debug logs in tests: npm run test -- -x

Running all tests takes around 3 hours on a modern PC with a CPU with 4 cores. Creating proofs is computationaly heavy and takes time even when multi-threading is used. Run individual tests when you can.

Verifier/Prover keys are cached in the keys folder. When updating the circuits make sure to delete the keys of older circuit versions because this is not automatically detected.

Contract Deployment

  • development network: npm run migrate-dev
  • ropsten network: npm run migrate-ropsten
  • main network: npm run migrate

If you have installed truffle globally, you can run:

npm run transpile && truffle migrate --network <network> --reset --dry-run

Replace network with development, live, ropsten, koven, etc.

Etherscan.io Code Verification

You can run truffle-flattener <solidity-files> to flatten a file. For contracts with constructor arguments, use https://abi.hashex.org/ to generated the argument string. To verify on etherscan.io, you also need to learn which libraries are linked to each contract from the migration scripts.

You can’t perform that action at this time.