tornadocash/ docs
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation and make it more accurate 

Signed-off-by: AlienTornadosaurusHex <>
This commit is contained in:
AlienTornadosaurusHex 2023-06-08 16:16:38 +00:00
parent fff16d3063
commit cab2d0c3f1
8 changed files with 62 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -48,7 +48,7 @@ _See sections_ [_Anonymity mining_](tornado-cash-classic/anonymity-mining.md) _a
**The protocol's native governance token, TORN, allows open and decentralized collaboration to shape the direction of the protocol through voting.**. The community has a strong influence over the evolution of Tornado Cash, it's development and management of the protocol's treasury.
Anonymity pools operate **under the principle of fixed-amount deposits and withdrawals**. Meaing that each supported asset has multiple pools which make up an "anonymity set", each pool restricts transactions to be a fixed amount _(e.g. ETH has four different pools, one for each of these amounts: 0.1, 1, 10 and 100 ETH)_.
Anonymity pools operate **under the principle of fixed-amount deposits and withdrawals**. Meaning that each supported asset has multiple pools which make up an "anonymity set", each pool restricts transactions to be a fixed amount _(e.g. ETH has four different pools, one for each of these amounts: 0.1, 1, 10 and 100 ETH)_.
### Tornado Cash Nova
@ -64,8 +64,8 @@ Tornado Cash is represented by it's community, collaboration is facilitated thro
All protocol related code is open-source and is published to two independent git instances:
* [Community git](https://development.tornadocash.community): store of the latest community maintained repositories
* [Github](https://github.com/tornadocash): public archive after the OFAC sanctions
* [Community git](https://git.tornado.ws): store of the latest community maintained repositories
* [Sanctioned Github](https://github.com/tornadocash): public archive after the OFAC sanctions
The existence of zero knowledge in the protocol was based **on open-source research authored by ZCash**. To implement a zero knowledge scheme, [a trusted setup is required](https://tornado-cash.medium.com/tornado-cash-trusted-setup-ceremony-b846e1e00be1), which is essentially a store of random data from various sources defining robustness in generation of proving and verifying keys. Which successfully occured for the protocol on [May 2020 with 1114 contributions](https://tornado-cash.medium.com/the-biggest-trusted-setup-ceremony-in-the-world-3c6ab9c8fffa). This significant number of contributors makes it implausible to compromise the protocol by faking zero-knowledge proofs.

4
general/community/governance.md
View File

@ -4,7 +4,7 @@ _Tornado Cash Classic anonymity pools are not under the control of governance, t
### How to create a proposal?
In order to participate in Tornado Cash governance, users first need to lock tokens in the governance contract to obtain a voting balance. **If a user votes or creates a proposal, the tokens cannot are time-locked until the proposal execution period (8.25 days from proposal creation).** Individuals can also be delegated voting weight which additionally timelocks the allocated tokens if used in either context.
In order to participate in Tornado Cash governance, users first need to lock tokens in the governance contract to obtain a voting balance. **If a user votes or creates a proposal, the tokens are time-locked until the proposal execution period (8.25 days from proposal creation).** Individuals can also be delegated voting weight which additionally timelocks the allocated tokens if used in either context.
To create a proposal, a user needs the proposal threshold of at least `1,000 TORN`. Proposal format follows an independent deployed contract with verified bytecode that can be executed from the [governance contract](https://etherscan.io/address/0x5efda50f22d34F262c29268506C5Fa42cB56A1Ce)(using `delegatecall`). Individuals are suggested to create an open source repositories for their proposals, alongside simulating execution for sufficient security practices.
@ -34,7 +34,7 @@ Approve the locked amount for the governance contract to transfer your tokens by
![](../../.gitbook/assets/c05e5a1813edad280544b627b24002dc8d5adcf2.png)
Individuals should take time to review the matters they are voting on, as given the open nature of the organisation - **the code execution could be malcious** - or may just simply be against their opinion. Proposals are encouraged to be discussed on the forums before being deployed. Review the discription, subject matter and forum thread before voting.
Individuals should take time to review the matters they are voting on, as given the open nature of the organisation - **the code execution could be malicious** - or may just simply be against their opinion. Proposals are encouraged to be discussed on the forums before being deployed. Review the discription, subject matter and forum thread before voting.
To allow easy auditing of the proposals execution and ensure the highest possibility for your proposal to win consensus, bytecode should be verified on Etherscan using the contract source code.

11
general/deployments.md
View File

@ -138,9 +138,9 @@ The following addresses are deployments of the [source code of Tornado Cash smar
| Proxy of feeManagerContract | [0x5f6c97C6AD7bdd0AE7E0Dd4ca33A4ED3fDabD4D7](https://etherscan.io/address/0x5f6c97C6AD7bdd0AE7E0Dd4ca33A4ED3fDabD4D7) |
| FeeManager | [0xf4B067dD14e95Bab89Be928c07Cb22E3c94E0DAA](https://etherscan.io/address/0xf4B067dD14e95Bab89Be928c07Cb22E3c94E0DAA) |
| Proxy of relayerRegistryContract | [0x58E8dCC13BE9780fC42E8723D8EaD4CF46943dF2](https://etherscan.io/address/0x58E8dCC13BE9780fC42E8723D8EaD4CF46943dF2) |
| RelayerRegistry | [0x01e2919679362dFBC9ee1644Ba9C6da6D6245BB1](https://etherscan.io/address/0x01e2919679362dFBC9ee1644Ba9C6da6D6245BB1) |
| Proxy of stakingContract | [0x2FC93484614a34f26F7970CBB94615bA109BB4bf](https://etherscan.io/address/0x2FC93484614a34f26F7970CBB94615bA109BB4bf) |
| TornadoStakingRewards | [0x26903a5a198D571422b2b4EA08b56a37cbD68c89](https://etherscan.io/address/0x26903a5a198D571422b2b4EA08b56a37cbD68c89) |
| RelayerRegistry | [0xe27b91724c55e950f68b394f33fa3b86693179c0](https://etherscan.io/address/0xe27b91724c55e950f68b394f33fa3b86693179c0) |
| Proxy of stakingContract | [0x5b3f656c80e8ddb9ec01dd9018815576e9238c29](https://etherscan.io/address/0x5b3f656c80e8ddb9ec01dd9018815576e9238c29) |
| TornadoStakingRewards | [0xefbea4ec481c2467a1a94d94bc54f111f6a7345f](https://etherscan.io/address/0xefbea4ec481c2467a1a94d94bc54f111f6a7345f) |
| Proxy of instanceRegistryContract | [0xB20c66C4DE72433F3cE747b58B86830c459CA911](https://etherscan.io/address/0xB20c66C4DE72433F3cE747b58B86830c459CA911) |
| InstanceRegistry | [0x2573BAc39EBe2901B4389CD468F2872cF7767FAF](https://etherscan.io/address/0x2573BAc39EBe2901B4389CD468F2872cF7767FAF) |
@ -148,6 +148,8 @@ The following addresses are deployments of the [source code of Tornado Cash smar
| Contract | Address |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Original Verifier | [0xce172ce1F20EC0B3728c9965470eaf994A03557A](https://etherscan.io/address/0xce172ce1F20EC0B3728c9965470eaf994A03557A) |
| MinimalInstanceFactory | [0x9d00007c0f5037157b5be8bff174b194a99118d0](https://etherscan.io/address/0x9d00007c0f5037157b5be8bff174b194a99118d0) |
| Tornado.Cash Trees | [0x527653ea119f3e6a1f5bd18fbf4714081d7b31ce](https://etherscan.io/address/0x527653ea119f3e6a1f5bd18fbf4714081d7b31ce) |
| Tree Update Verifier | [0x653477c392c16b0765603074f157314cc4f40c32](https://etherscan.io/address/0x653477c392c16b0765603074f157314cc4f40c32) |
| Reward Verifier | [0x88fd245fedec4a936e700f9173454d1931b4c307](https://etherscan.io/address/0x88fd245fedec4a936e700f9173454d1931b4c307) |
@ -159,5 +161,4 @@ The following addresses are deployments of the [source code of Tornado Cash smar
| Mixer 2 | [0xb541fc07bc7619fd4062a54d96268525cbc6ffef](https://etherscan.io/address/0xb541fc07bc7619fd4062a54d96268525cbc6ffef) |
| Poseidon 2 | [0x94c92f096437ab9958fc0a37f09348f30389ae79](https://etherscan.io/address/0x94c92f096437ab9958fc0a37f09348f30389ae79) |
| Poseidon 3 | [0xd82ed8786d7c69dc7e052f7a542ab047971e73d2](https://etherscan.io/address/0xd82ed8786d7c69dc7e052f7a542ab047971e73d2) |
| Gitcoin Grants | [0xdd4c48c0b24039969fc16d1cdf626eab821d3384](https://etherscan.io/address/0xdd4c48c0b24039969fc16d1cdf626eab821d3384) |
| Gitcoin Grants | [0xdd4c48c0b24039969fc16d1cdf626eab821d3384](https://etherscan.io/address/0xdd4c48c0b24039969fc16d1cdf626eab821d3384) |

4
general/guides/local-ui.md
View File

@ -10,8 +10,8 @@ _If you have privacy concerns about using this extension in this tutorial, you [
### Step #1: Download the static source
For this part you'll need to be able to open .zip files, most operating systems allow this. Head to either the Nova or Classic release page on the community git to download the static files.
Nova: https://development.tornadocash.community/tornadocash/nova-ui-minified/releases
Classic: https://development.tornadocash.community/tornadocash/classic-ui/releases
Nova: https://git.tornado.ws/tornadocash/nova-ui-minified/releases
Classic: https://git.tornado.ws/tornadocash/classic-ui/releases
Click the version named zip file download option to download the zip file, as seen below. It should download locally to your machine.

20
general/guides/relayer.md
View File

@ -3,16 +3,16 @@
Following the execution of [proposal #10](https://etherscan.io/address/0xEC2412368be52107Fa549c3fb78DE1e3e6bF18EB#code), anyone can become a relayer for Tornado Cash users.
{% hint style="success" %}
The only condition to be included on the Tornado Cash UI is to lock a min. of `300 TORN`\*. To remain listed, it is needed to keep enough TORN locked (\~`40 TORN` at the moment in April 2022) to be able to pay back the transaction fee to the staking contract.
The first condition to be included on the Tornado Cash UI is to lock a min. of `2000 TORN`\*. To remain listed, it is needed to keep enough TORN locked to be able to pay back the transaction fee to the staking contract.
{% endhint %}
\*_This minimum stake can be changed by a governance vote at any time._
Relayers form an essential & necessary part of the Tornado Cash ecosystem. Their use guarantees privacy as they solve the infamous “fee payment dilemma” : how to pay fees for token withdrawals from a pool while maintaining anonymity?
Relayers form an essential & necessary part of the Tornado Cash ecosystem. Their use guarantees privacy as they solve the “fee payment dilemma” : how to pay fees for token withdrawals from a pool while maintaining anonymity?
Therefore, relayers act as third parties and manage the entire withdrawal. They pay for transaction fees by deducting them directly from the transferred amount. They also charge an additional fee for their services.
Since the implementation of the [relayer registry proposal](https://etherscan.io/address/0xEC2412368be52107Fa549c3fb78DE1e3e6bF18EB#code), the protocol collects a fee directly from the relayer’s staked balance through the `StakingReward` contract for each withdrawal. This fee percentage may vary from one pool to another and is also subject to change through on-chain governance.
Since the implementation of the [relayer registry proposal](https://etherscan.io/address/0xEC2412368be52107Fa549c3fb78DE1e3e6bF18EB#code), lockers in the Governance contract collect a fee directly from the relayer’s staked balance through the `TornadoStakingRewards` contract for each withdrawal. This fee percentage may vary from one pool to another and is also subject to change through on-chain governance.
Currently, it is fixed at `0.3%` . Some pools remain without fees, either because the instance is too small to assign a fee (0.1 ETH, 100 DAI/USDT, 1000 DAI/USDT), or because there is not enough liquidity on Uni v3 (all cDAI instances).
@ -22,9 +22,9 @@ Anyone can become a relayer for the protocol in **6 simple steps** through the r
### 1. Disclaimer
Before you commit to sharing part of your journey with Tornado Cash users as a relayer, you need to understand & accept all potential risks of being a relayer for the protocol.
Before you commit to sharing part of your journey with Tornado Cash users as a relayer, you need to understand & accept all potential risks of being a relayer for the protocol (see section 6).
#### How a relayer is chosen by the user interface
#### 1. The `relayer-selection system` (how a relayer is chosen by frontends)
The formula for designating a relayer is as follows:
@ -34,7 +34,7 @@ The formula for designating a relayer is as follows:
### 2. Set up relayer
The first concrete step is to run the Tornado Cash Relayer software for Ethereum Mainnet on your computer. All steps are outlined in the protocol's github. To complete this task successfully, you will have to carefully follow [these instructions](https://development.tornadocash.community/tornadocash/classic-relayer).
The first concrete step is to run the Tornado Cash Relayer software for Ethereum Mainnet on your computer. All steps are outlined in the protocol's github. To complete this task successfully, you will have to carefully follow [these instructions](https://git.tornado.ws/tornadocash/classic-relayer).
Once completed, you will need to insert your url in the input box.
@ -108,7 +108,13 @@ Your staked TORN amount is not claimable, and it is non-refundable
![](../../.gitbook/assets/5.png)
### 6. Final verification and registration
### 6. Slashing (nullification risk)
Similarly to how Ethereum validators are slashed if they behave in a way which Ethereum defines as malicious behaviour, so too are relayers slashed (nullified) if they attempt to game the `relayer-selection system`.
In future, the selection mechanism will be redesigned to remove the need for nullifications.
### 7. Final verification and registration
Last but not least, we advise you to **double-check all information** displayed in the summary before registering.

2
general/resources/compliance-tool.md
View File

@ -1,6 +1,6 @@
# Compliance tool
By design, everything is public on the blockchain, which can deprive users from their right to privacy. Anyone can have view everyone elses entire financial history. Tornado Cash breaks the on-chain link between the source and destination address, although not at expense of non-compliance. The right of privacy lies in the ability to have control over the information we provide and to whom we provide it.
By design, everything is public on the blockchain, which can deprive users from their right to privacy. Anyone can have view everyone elses entire financial history. The right of privacy lies in the ability to have control over the information we provide and to whom we provide it.
To this extent, **the compliance tool enables users to prove the origin of their funds through selective disclourse.** Each note translates to a unique deposit, **this tool will issue a cryptographic proof of a deposit** allowing a third party to authethicate one's transactional profile.

35
general/token/locking.md Normal file
View File

@ -0,0 +1,35 @@
# Locking in Governance
All Governance systems converge towards the same pattern of consensus systems based on some form of pluralism-based voting. This is for the reason, that large-scale coordination problems can only be resolved by giving "users" or "nodes" or "validators" (however you want to call it) an incentive to cooperate, and then bind that incentive within a ruleset which ultimately the "users/nodes/validators" will prefer because it encourages the stability of the system which actually supplies them the incentives, meaning that it economically guarantees them future income.
For this reason, since the prime directive of the Governance "community" surrounding Tornado Cash is ensuring protocol and service stability, mechanisms must exist by which Governance can incentivize "users/validators/nodes" to configure a system around the core protocol contracts, which must act as a bridge between them and users wanting to interface with the protocol. Specifically, this is necessary due to the fee dilemma which has been mentioned in the guide for relayers, which states that a third party must be providing ether on the withdrawal side of a run through Tornado.
Since the execution of [Proposal #10](https://etherscan.io/address/0xEC2412368be52107Fa549c3fb78DE1e3e6bF18EB#code), the TORN token has gained the ability to offer such an incentive, albeit in a primitive form. Essentially, all frontends include the possibility of selecting relayers which have decided to sign up for a registry. Similarly to validators, relayers must stake TORN (irretrievably) if they would like to be registered in this registry, and this grants them the benefit of appearing on the implementing frontends independent of the person hosting the service.
The entire reason why this is done is most importantly the IPFS deployment, which is expected to be the fully censorship resistant, decentralized frontend which should survive in worst case scenarios. In the combination with the former system, the IPFS deployment should not run into relayer sybil issues.
The fee mechanism functions by relayers locking a listing amount (currently `2000 TORN`). Everytime a withdrawal is processed the registry fee (currently `0.3%` of the relayer's arbitary fee) is deducted from their locked balance. This fee is then distributed proportionally to tokenholders locked in the user vault contract (through Governance). Relayers must keep a locked balance greater than the minimum balance (`500 TORN` currently) to be marked as an active relayer and be recommended on the frontend.
The listing amount, registry fee and minimum balance are all configurable by Governance.
### How to lock?
First, [connect your wallet to Tornado Cash](../../tornado-cash-classic/how-to-connect-your-wallet.md).
As mentioned above, the process to lock TORN tokens has remained unchanged.
* To do that click the **`Voting`** button on the navigation bar at the top of the page to be directed to the governance route of the application
* The governance contract need to be approved in order to allow the transfer of your tokens to the smart contract. To do so, you need to click on the **`Approve`** button
* Once the approval is confirmed, you can chose the amount of token to lock, then click on **`Lock`**
* All you have to do after that is to confirm the transaction in your wallet & wait for the confirmation to come through
![](../../.gitbook/assets/c05e5a1813edad280544b627b24002dc8d5adcf2.png)
### How to claim your locking reward?
To do that click the **`Voting`** button on the navigation bar at the top of the page to be directed to the governance route of the application. As soon as you connect your wallet, you will be able to see your staking reward at the top if you have a balance.
![](../../.gitbook/assets/head.png)
* Click **`Manage`** -> **`Claim`** tab -> **`Claim`** _button._

29
general/token/staking.md
View File

@ -1,29 +0,0 @@
# Staking
Since the execution of [proposal #10](https://etherscan.io/address/0xEC2412368be52107Fa549c3fb78DE1e3e6bF18EB#code), an additional utility was enabled for TORN aside from governance. Through the deployment of the relayer registry, which acts as a official store of active relayers. Which grants the access to referencing on the frontend through querying the registry contract. Relayers pay a percent of withdrawal fees to governance to have an active registration in the registry.
The fee mechanisim functions by relayers locking a listing amount (currently `300 TORN`) and everytime a withdrawal is processed the registry fee (currently `0.3%` of the relayer's arbitary fee) is deducted from their locked balance. This fee is then distributed proportionally to tokenholders locked into the governance contract. Relayers must keep a locked balance greater than the minimum balance (currently `40 TORN`) to be marked as an active relayer and be recommended on the frontend.
The listing amount, registry fee and minimum balance are all configurable by governance.
### How to stake?
First, [connect your wallet to Tornado Cash](../../tornado-cash-classic/how-to-connect-your-wallet.md).
As mentioned above, the process to lock TORN tokens has remained unchanged.
* To do that click the **`Voting`** button on the navigation bar at the top of the page to be directed to the governance route of the application
* The governance contract need to be approved in order to allow the transfer of your tokens to the smart contract. To do so, you need to click on the **`Approve`** button
* Once the approval is confirmed, you can chose the amount of token to lock, then click on **`Lock`**
* All you have to do after that is to confirm the transaction in your wallet & wait for the confirmation to come through
![](../../.gitbook/assets/c05e5a1813edad280544b627b24002dc8d5adcf2.png)
### How to claim your staking reward?
To do that click the **`Voting`** button on the navigation bar at the top of the page to be directed to the governance route of the application. As soon as you connect your wallet, you will be able to see your staking reward at the top if you have a balance.
![](../../.gitbook/assets/head.png)
* Click **`Manage`** -> **`Claim`** tab -> **`Claim`** _button._