tornado-core/README.md

85 lines
4.9 KiB
Markdown
Raw Normal View History

2019-07-19 04:50:54 +02:00
# Tornado mixer [![Build Status](https://travis-ci.org/peppersec/tornado-mixer.svg?branch=master)](https://travis-ci.org/peppersec/tornado-mixer)
2019-07-13 17:00:41 +02:00
Tornado is a non-custodial Ethereum and ERC20 mixer based on zkSNARKs. It improves transaction privacy by breaking the on-chain link between recipient and destination addresses. It uses a smart contract that accepts ETH deposits that can be withdrawn by a different address. Whenever ETH is withdrawn by the new address, there is no way to link the withdrawal to the deposit, ensuring complete privacy.
2019-10-16 03:45:14 +02:00
To make a deposit user generates a secret and sends its hash (called a commitment) along with the deposit amount to the Tornado smart contract. The contract accepts the deposit and adds the commitment to its list of deposits.
2019-10-16 03:45:14 +02:00
Later, the user decides to make a withdrawal. In order to do that, the user should provide a proof that he or she possesses a secret to an unspent commitment from the smart contracts list of deposits. zkSnark technology allows that to happen without revealing which exact deposit corresponds to this secret. The smart contract will check the proof, and transfer deposited funds to the address specified for withdrawal. An external observer will be unable to determine which deposit this withdrawal came from.
You can read more about it in [this medium article](https://medium.com/@tornado.cash.mixer/introducing-private-transactions-on-ethereum-now-42ee915babe0)
2019-07-12 23:56:17 +02:00
2019-07-17 13:12:57 +02:00
## Specs
- Deposit gas const: 888054 (43381 + 50859 * tree_depth)
2019-07-17 13:12:57 +02:00
- Withdraw gas cost: 692133
- Circuit Constraints = 22617 (1869 + 1325 * tree_depth)
- Circuit Proof time = 6116ms (1071 + 347 * tree_depth)
2019-07-17 13:12:57 +02:00
- Serverless
2019-07-13 00:38:25 +02:00
![mixer image](./mixer.png)
2019-07-17 13:12:57 +02:00
## Security risks
2019-10-16 03:45:14 +02:00
* Cryptographic tools used by mixer (zkSNARKS, Pedersen commitment, MiMC hash) are yet NOT extensively audited by cryptographic experts and may be vulnerable
* Note: we use MiMC hash only for merkle tree, so even if a preimage attack on MiMC is discovered, it will not allow to deanonymize users. To drain funds attacker needs to be able to generate arbitrary hash collisions, which is a pretty strong assumption.
* Bugs in contract. Even though we have an extensive experience in smart contract security audits, we can still make mistakes. An external audit is needed to reduce probablility of bugs. Our mixer is currently being audited, stay tuned.
2019-07-13 00:38:25 +02:00
* Relayer is frontrunnable. When relayer submits a transaction someone can see it in tx pool and frontrun it with higher gas price to get the fee and drain relayer funds.
* Workaround: we can set high gas price so that (almost) all fee is used on gas
* Second workaround: allow only single hardcoded relayer, we use this approach for now
2019-07-25 20:29:09 +02:00
* ~~Nullifier griefing. when you submit a withdraw transaction you reveal the nullifier for your note. If someone manages to
2019-07-15 21:19:34 +02:00
make a deposit with the same nullifier and withdraw it while your transaction is still in tx pool, your note will be considered
2019-07-25 20:29:09 +02:00
spent since it has the same nullifier and it will prevent you from withdrawing your funds~~
* Fixed by sending nullifier hash instead of plain nullifier
2019-07-12 11:53:44 +02:00
2019-07-17 13:12:57 +02:00
## Requirements
1. `node v11.15.0`
2. `npm install -g npx`
## Usage
You can see example usage in cli.js, it works both in console and in browser.
1. `npm install`
2019-07-17 13:12:57 +02:00
1. `cp .env.example .env`
1. `npm run build` - this may take 10 minutes or more
2019-07-17 13:12:57 +02:00
1. `npx ganache-cli`
2019-10-16 03:45:14 +02:00
1. `npm run test` - optionally runs tests. It may fail on the first try, just run it again.
Use browser version on Kovan:
2019-07-17 13:12:57 +02:00
1. `vi .env` - add your Kovan private key to deploy contracts
1. `npm run migrate`
1. `npx http-server` - serve current dir, you can use any other static http server
2019-07-17 13:12:57 +02:00
1. Open `localhost:8080`
2019-09-14 20:21:53 +02:00
Use with command line version with Ganache:
### ETHMixer
2019-07-17 13:12:57 +02:00
1. `npm run migrate:dev`
1. `./cli.js deposit`
1. `./cli.js withdraw <note from previous step> <destination eth address>`
1. `./cli.js balance <destination eth address>`
2019-09-14 20:21:53 +02:00
### ERC20Mixer
1. `npm run migrate:dev`
1. `./cli.js depositErc20`
2019-09-16 13:14:49 +02:00
1. `./cli.js withdrawErc20 <note from previous step> <destination eth address> <relayer eth address>`
2019-09-14 20:21:53 +02:00
1. `./cli.js balanceErc20 <destination eth address> <relayer eth address>`
2019-10-16 03:45:14 +02:00
If you want, you can point the app to existing tornado contracts on Mainnet or Kovan. It should work without any problems
2019-07-17 13:12:57 +02:00
2019-08-27 22:42:24 +02:00
## Deploy ETH Tornado Cash
1. `cp .env.example .env`
1. Tune all necessary params
2019-09-16 12:07:14 +02:00
1. `npx truffle migrate --network kovan --reset --f 2 --to 4`
2019-08-27 22:42:24 +02:00
## Deploy ERC20 Tornado Cash
1. `cp .env.example .env`
1. Tune all necessary params
2019-09-16 12:07:14 +02:00
1. `npx truffle migrate --network kovan --reset --f 2 --to 3`
1. `npx truffle migrate --network kovan --reset --f 5`
2019-08-27 22:42:24 +02:00
**Note**. If you want to reuse the same verifier for all the mixers, then after you deployed one of the mixers you should only run 4th or 5th migration for ETH or ERC20 mixers respectively (`--f 4 --to 4` or `--f 5`).
2019-07-17 13:12:57 +02:00
## Credits
2019-07-12 11:53:44 +02:00
2019-07-24 16:09:37 +02:00
Special thanks to @barryWhiteHat and @kobigurk for valuable input,
2019-07-17 13:12:57 +02:00
and to @jbaylina for awesome [Circom](https://github.com/iden3/circom) & [Websnark](https://github.com/iden3/websnark) framework