{"id":13456266,"url":"https://github.com/tornadocash/tornado-core","last_synced_at":"2025-03-24T09:31:52.765Z","repository":{"id":60262999,"uuid":"196010807","full_name":"tornadocash/tornado-core","owner":"tornadocash","description":"Tornado cash. Non-custodial private transactions on Ethereum. ","archived":true,"fork":false,"pushed_at":"2022-07-16T04:47:11.000Z","size":1684,"stargazers_count":1470,"open_issues_count":22,"forks_count":554,"subscribers_count":44,"default_branch":"master","last_synced_at":"2024-10-28T23:33:58.715Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tornado.cash","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tornadocash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-09T13:07:46.000Z","updated_at":"2024-10-25T23:12:25.000Z","dependencies_parsed_at":"2022-09-27T10:50:19.231Z","dependency_job_id":null,"html_url":"https://github.com/tornadocash/tornado-core","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornadocash%2Ftornado-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornadocash%2Ftornado-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornadocash%2Ftornado-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornadocash%2Ftornado-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tornadocash","download_url":"https://codeload.github.com/tornadocash/tornado-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245243382,"owners_count":20583614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:01:18.944Z","updated_at":"2025-03-24T09:31:52.257Z","avatar_url":"https://github.com/tornadocash.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Projects and Implementations","Projects using Circom"],"sub_categories":["Cryptographic primitives in other languages"],"readme":"# Tornado Cash Privacy Solution [![build status](https://github.com/tornadocash/tornado-core/actions/workflows/build.yml/badge.svg)](https://github.com/tornadocash/tornado-core/actions/workflows/build.yml) [![Coverage Status](https://coveralls.io/repos/github/tornadocash/tornado-core/badge.svg?branch=master)](https://coveralls.io/github/tornadocash/tornado-core?branch=master)\n\nTornado Cash is a non-custodial Ethereum and ERC20 privacy solution based on zkSNARKs. It improves transaction privacy by breaking the on-chain link between the 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.\n\nTo 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.\n\nLater, the user decides to make a withdrawal. To do that, the user should provide a proof that he or she possesses a secret to an unspent commitment from the smart contract’s 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.\n\nYou can read more about it in [this Medium article](https://medium.com/@tornado.cash/introducing-private-transactions-on-ethereum-now-42ee915babe0)\n\n## Specs\n\n- Deposit gas cost: 1088354 (43381 + 50859 \\* tree_depth)\n- Withdraw gas cost: 301233\n- Circuit Constraints = 28271 (1869 + 1325 \\* tree_depth)\n- Circuit Proof time = 10213ms (1071 + 347 \\* tree_depth)\n- Serverless\n\n![image](docs/diagram.png)\n\n## Whitepaper\n\n**[TornadoCash_whitepaper_v1.4.pdf](https://tornado.cash/audits/TornadoCash_whitepaper_v1.4.pdf)**\n\n## Was it audited?\n\nTornado.cash protocols, circuits, and smart contracts were audited by a group of experts from [ABDK Consulting](https://www.abdk.consulting), specializing in zero-knowledge, cryptography, and smart contracts.\n\nDuring the audit, no critical issues were found and all outstanding issues were fixed. The results can be found here:\n\n- Cryptographic review https://tornado.cash/audits/TornadoCash_cryptographic_review_ABDK.pdf\n- Smart contract audit https://tornado.cash/audits/TornadoCash_contract_audit_ABDK.pdf\n- Zk-SNARK circuits audit https://tornado.cash/audits/TornadoCash_circuit_audit_ABDK.pdf\n\nUnderlying circomlib dependency is currently being audited, and the team already published most of the fixes for found issues\n\n## Requirements\n\n1. `node v11.15.0`\n2. `npm install -g npx`\n\n## Usage\n\nYou can see example usage in cli.js, it works both in the console and in the browser.\n\n1. `npm install`\n1. `cp .env.example .env`\n1. `npm run build` - this may take 10 minutes or more\n1. `npx ganache-cli`\n1. `npm run test` - optionally runs tests. It may fail on the first try, just run it again.\n\nUse browser version on Kovan:\n\n1. `vi .env` - add your Kovan private key to deploy contracts\n1. `npm run migrate`\n1. `npx http-server` - serve current dir, you can use any other static http server\n1. Open `localhost:8080`\n\nUse the command-line version. Works for Ganache, Kovan, and Mainnet:\n\n### Initialization\n\n1. `cp .env.example .env`\n1. `npm run download`\n1. `npm run build:contract`\n\n### Ganache\n\n1. make sure you complete steps from Initialization\n1. `ganache-cli -i 1337`\n1. `npm run migrate:dev`\n1. `./cli.js test`\n1. `./cli.js --help`\n\n### Kovan, Mainnet\n\n1. Please use https://github.com/tornadocash/tornado-cli\n   Reason: because tornado-core uses websnark `2041cfa5fa0b71cd5cca9022a4eeea4afe28c9f7` commit hash in order to work with local trusted setup. Tornado-cli uses `4c0af6a8b65aabea3c09f377f63c44e7a58afa6d` commit with production trusted setup of tornadoCash\n\nExample:\n\n```bash\n./cli.js deposit ETH 0.1 --rpc https://kovan.infura.io/v3/27a9649f826b4e31a83e07ae09a87448\n```\n\n\u003e Your note: tornado-eth-0.1-42-0xf73dd6833ccbcc046c44228c8e2aa312bf49e08389dadc7c65e6a73239867b7ef49c705c4db227e2fadd8489a494b6880bdcb6016047e019d1abec1c7652\n\u003e Tornado ETH balance is 8.9\n\u003e Sender account ETH balance is 1004873.470619891361352542\n\u003e Submitting deposit transaction\n\u003e Tornado ETH balance is 9\n\u003e Sender account ETH balance is 1004873.361652048361352542\n\n```bash\n./cli.js withdraw tornado-eth-0.1-42-0xf73dd6833ccbcc046c44228c8e2aa312bf49e08389dadc7c65e6a73239867b7ef49c705c4db227e2fadd8489a494b6880bdcb6016047e019d1abec1c7652 0x8589427373D6D84E98730D7795D8f6f8731FDA16 --rpc https://kovan.infura.io/v3/27a9649f826b4e31a83e07ae09a87448 --relayer https://kovan-frelay.duckdns.org\n```\n\n\u003e Relay address: 0x6A31736e7490AbE5D5676be059DFf064AB4aC754\n\u003e Getting current state from tornado contract\n\u003e Generating SNARK proof\n\u003e Proof time: 9117.051ms\n\u003e Sending withdraw transaction through the relay\n\u003e Transaction submitted through the relay. View transaction on etherscan https://kovan.etherscan.io/tx/0xcb21ae8cad723818c6bc7273e83e00c8393fcdbe74802ce5d562acad691a2a7b\n\u003e Transaction mined in block 17036120\n\u003e Done\n\n## Deploy ETH Tornado Cash\n\n1. `cp .env.example .env`\n1. Tune all necessary params\n1. `npx truffle migrate --network kovan --reset --f 2 --to 4`\n\n## Deploy ERC20 Tornado Cash\n\n1. `cp .env.example .env`\n1. Tune all necessary params\n1. `npx truffle migrate --network kovan --reset --f 2 --to 3`\n1. `npx truffle migrate --network kovan --reset --f 5`\n\n**Note**. If you want to reuse the same verifier for all the instances, then after you deployed one of the instances you should only run the 4th or 5th migration for ETH or ERC20 contracts respectively (`--f 4 --to 4` or `--f 5`).\n\n## How to resolve ENS name to DNS name for a relayer\n\n1. Visit https://etherscan.io/enslookup and put relayer ENS name to the form.\n2. Copy the namehash (1) and click on the `Resolver` link (2)\n   ![enslookup](docs/enslookup.png)\n3. Go to the `Contract` tab. Click on `Read Contract` and scroll down to the `5. text` method.\n4. Put the values:\n   ![resolver](docs/resolver.png)\n5. Click `Query` and you will get the DNS name. Just add `https://` to it and use it as `relayer url`\n\n## Credits\n\nSpecial thanks to @barryWhiteHat and @kobigurk for valuable input,\nand @jbaylina for awesome [Circom](https://github.com/iden3/circom) \u0026 [Websnark](https://github.com/iden3/websnark) framework\n\n## Minimal demo example\n\n1. `npm i`\n1. `ganache-cli -d`\n1. `npm run download`\n1. `npm run build:contract`\n1. `cp .env.example .env`\n1. `npm run migrate:dev`\n1. `node minimal-demo.js`\n\n## Run tests/coverage\n\nPrepare test environment:\n\n```\n   yarn install\n   yarn download\n   cp .env.example .env\n   npx ganache-cli \u003e /dev/null \u0026\n   npm run migrate:dev\n```\n\nRun tests:\n\n```\n   yarn test\n```\n\nRun coverage:\n\n```\n   yarn coverage\n```\n\n## Emulate MPC trusted setup ceremony\n\n```bash\ncargo install zkutil\nnpx circom circuits/withdraw.circom -o build/circuits/withdraw.json\nzkutil setup -c build/circuits/withdraw.json -p build/circuits/withdraw.params\nzkutil export-keys -c build/circuits/withdraw.json -p build/circuits/withdraw.params -r build/circuits/withdraw_proving_key.json -v build/circuits/withdraw_verification_key.json\nzkutil generate-verifier -p build/circuits/withdraw.params -v build/circuits/Verifier.sol\nsed -i -e 's/pragma solidity \\^0.6.0/pragma solidity 0.5.17/g' ./build/circuits/Verifier.sol\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftornadocash%2Ftornado-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftornadocash%2Ftornado-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftornadocash%2Ftornado-core/lists"}