mirror of https://github.com/tornadocash/docs
GitBook: [#11] Restructure Tornado Trees as a subpage
This commit is contained in:
Justin Martin
gitbook-bot
parent
1e513d9f27
commit
0afd5b4387
|
|
@ -11,4 +11,5 @@
|
|||
* [Compliance Tool](compliance-tool.md)
|
||||
* [Circuits](circuits/README.md)
|
||||
* [Core Deposit Circuit](circuits/core-deposit-circuit.md)
|
||||
* [Anonymity Mining](circuits/anonymity-mining.md)
|
||||
* [Anonymity Mining](circuits/anonymity-mining/README.md)
|
||||
* [Tornado Trees](circuits/anonymity-mining/tornado-trees.md)
|
||||
|
|
|
|||
|
|
@ -66,6 +66,6 @@ The core deposit circuit is what most users interact with, proving that a user h
|
|||
|
||||
The anonymity mining circuits form the basis for the Anonymity Mining program, which incentivizes users to leave their deposits in the contract for longer periods of time, so as to ensure that the Tornado.cash deposit pools maintain a large number of active deposits (thus increasing [k-anonymity](https://en.wikipedia.org/wiki/K-anonymity) for other users).
|
||||
|
||||
{% content-ref url="anonymity-mining.md" %}
|
||||
[anonymity-mining.md](anonymity-mining.md)
|
||||
{% content-ref url="anonymity-mining/" %}
|
||||
[anonymity-mining](anonymity-mining/)
|
||||
{% endcontent-ref %}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
# Anonymity Mining
|
||||
|
||||
The anonymity mining protocol underpins the [Anonymity Mining Program](../../anonymity-mining.md), which rewards users according to the block duration that they wait before withdrawing their deposits.
|
||||
|
||||
Anonymity Mining uses a Tornado Trees contract as a ZK-efficient register of deposit and withdrawal transactions, which enables users to make efficient proofs regarding their usage.
|
||||
|
||||
{% content-ref url="tornado-trees.md" %}
|
||||
[tornado-trees.md](tornado-trees.md)
|
||||
{% endcontent-ref %}
|
||||
|
||||
|
|
@ -1,12 +1,13 @@
|
|||
# Anonymity Mining
|
||||
---
|
||||
description: >-
|
||||
The Tornado Trees contract and circuit acts as an ZK-efficient register of
|
||||
deposit and withdrawal transactions that the Anonymity Mining functions can
|
||||
use to validate claims made by users about their
|
||||
---
|
||||
|
||||
The anonymity mining protocol underpins the [Anonymity Mining Program](../anonymity-mining.md), which rewards users according to the block duration that they wait before withdrawing their deposits.
|
||||
# Tornado Trees
|
||||
|
||||
## Tornado Trees
|
||||
|
||||
Before we get into how rewards are calculated and claimed for anonymity mining, we first need to understand how some important state information is recorded regarding deposits and withdrawal events.
|
||||
|
||||
### Tornado Proxy
|
||||
## Tornado Proxy
|
||||
|
||||
When accessing the Tornado.cash deposit contracts using the official UI, all transactions execute through a proxy contract called the [Tornado Proxy](https://github.com/tornadocash/tornado-trees/blob/master/contracts/TornadoTrees.sol). Since the deposit contracts themselves are immutable, and many features of Tornado.cash were added well after the original deposit contracts were deployed, the Tornado Proxy provides a way to inject additional functionality without replacing the battle-tested deposit contract instances.
|
||||
|
||||
|
|
@ -22,7 +23,7 @@ Registering a withdrawal is the essentially the same as registering a deposit, e
|
|||
|
||||
The `registerDeposit` and `registerWithdrawal` contract methods of the Tornado Trees contract each emit a corresponding event, `DepositData` and `WithdrawalData` containing the same values as were included in the computed hash, plus an additional event field indication the order in which they entered into the queue.
|
||||
|
||||
### Chunked Merkle Tree Update
|
||||
## Chunked Merkle Tree Update
|
||||
|
||||
Standard Merkle Trees are fairly expensive to store and update, especially if you want to commit to a large number of leaves. Depositing a note into the Tornado.cash deposit contracts can cost upwards of 1.2M gas, which can be hundreds of dollars worth of ETH if depositing on Ethereum mainnet. Most of this gas cost results from simply inserting a commitment into the deposit contract Merkle Tree.
|
||||
|
||||
|
|
@ -30,7 +31,7 @@ What if, instead of spending all of that gas, we could instead simply propose a
|
|||
|
||||
However, verifying Zero Knowledge proofs is itself quite expensive. So, instead of updating the Merkle Tree for every change, we can batch insertions together into aggregate commitments which can be verified as a whole.
|
||||
|
||||
#### Chunked Tree Structure
|
||||
### Chunked Tree Structure
|
||||
|
||||
The deposit and withdrawal trees are both fixed-size Merkle Trees 20 levels deep, but with a notable feature. The "chunk size" of the tree determines a level at which updates are computed in aggregate, instead of as individual insertions.
|
||||
|
||||
|
|
@ -38,13 +39,13 @@ In the case of Tornado Trees, the chunk size is 256 (2^8), so each chunk is 8 le
|
|||
|
||||
The hash function used to produce node labels is [Poseidon](https://www.poseidon-hash.info), which is similar to the [Pedersen](https://iden3-docs.readthedocs.io/en/latest/iden3\_repos/research/publications/zkproof-standards-workshop-2/pedersen-hash/pedersen.html) hash function used in the core deposit contract, in that it's an elliptic curve hashing algorithm. The major difference between the two is that Poseidon operates over the BN128 elliptic curve instead of Baby Jubjub, and where Pedersen uses 1.7 constraints per bit in a ZK proof, Poseidon only uses between 0.2 and 0.45 constraints per bit.
|
||||
|
||||
#### Collecting the Events
|
||||
### Collecting the Events
|
||||
|
||||
In order to compute an update to the tree, it's necessary to know the existing structure of the tree. To obtain this, you query from the contract logs the `DepositData` or `WithdrawalData` events emitted earlier, depending on which tree you're updating.
|
||||
|
||||
Using the index indicated by `lastProcessedDepositLeaf` or `lastProcessedWithdrawalLeaf`, you can then split the events into two sets of leaves - "committed" and "pending". As the names would imply, the former set of leaves are the ones that are already committed within the Merkle Tree, and the latter are all of the leaves which still need to be inserted.
|
||||
|
||||
#### Computing a Tree Update
|
||||
### Computing a Tree Update
|
||||
|
||||
Using the committed events, we're able to reconstruct the current state of Merkle Tree by first computing the Poseidon hash for each of the existing leaves, using the Tornado instance address, commitment/nullifier hash, and block number as the inputs to the hashing algorithm.
|
||||
|
||||
|
|
@ -56,7 +57,7 @@ Now that we have the "old root", we can proceed to take a chunk of pending event
|
|||
|
||||
Next, we need to collect a list of path elements starting from the subtree leaf, as well as an array of `0/1` bits indicating whether each path element is to the left or right of its parent node.
|
||||
|
||||
#### Computing the Args Hash
|
||||
### Computing the Args Hash
|
||||
|
||||
The last thing that we need before we can compute a proof is a hashed list of arguments that we'll be passing into our proving circuit, with a very particular structure.
|
||||
|
||||
|
|
@ -72,9 +73,9 @@ Construct a message that is the concatenation of these fields:
|
|||
|
||||
Compute the SHA-256 hash of this message, and then modulus the hash against the BN128 group modulus found in the `SNARK_FIELD` constant of the Tornado Trees contract.
|
||||
|
||||
### Generating a Merkle Tree Update Witness
|
||||
## Generating a Merkle Tree Update Witness
|
||||
|
||||
#### Inputs to a Tree Update Witness
|
||||
### Inputs to a Tree Update Witness
|
||||
|
||||
The [Batch Tree Update](https://github.com/tornadocash/tornado-trees/blob/master/circuits/BatchTreeUpdate.circom) circuit takes a single public input, which is the resulting SHA-256 args hash in the BN128 field.
|
||||
|
||||
|
|
@ -89,25 +90,25 @@ The additional private inputs for a Tree Update witness are:
|
|||
2. An array of Tornado instance addresses
|
||||
3. An array of block numbers
|
||||
|
||||
#### Proven Claim
|
||||
### Proven Claim
|
||||
|
||||
To prove that we have updated the tree correctly, we don't have to provide a proof that spans the entire tree. Instead, we can prove just that a subtree of the 8-level chunk size, with a list of specified leaves, was added in place of the left-most zero leaf of a 12-level tree.
|
||||
|
||||
#### Proving the Args Hash
|
||||
### Proving the Args Hash
|
||||
|
||||
Instead of specifying all of the inputs publicly, we can take the Args Hash that we computed earlier and compare it to the result of computing the same hash within the ZK circuit, using the private inputs. This makes for a much more efficient proof verification execution.
|
||||
|
||||
#### Build the Subtree
|
||||
### Build the Subtree
|
||||
|
||||
Taking the three fields of each pending event in the order (instance, commitment/nullifier, block number), we compute the Poseidon hash of each leaf. We then construct the Merkle Tree just for the subtree that we're updating. Since the subtree is full, we don't need to worry about any zero leaves.
|
||||
|
||||
#### Verify the Subtree Insertion
|
||||
### Verify the Subtree Insertion
|
||||
|
||||
Lastly, we verify that inserting the subtree root at the proposed position results in the old root transforming to the new root. This works essentially the same way as for the [Merkle Tree Check](core-deposit-circuit.md#computing-the-witness) in the core deposit circuit, except using Poseidon instead of MiMC.
|
||||
Lastly, we verify that inserting the subtree root at the proposed position results in the old root transforming to the new root. This works essentially the same way as for the [Merkle Tree Check](../core-deposit-circuit.md#computing-the-witness) in the core deposit circuit, except using Poseidon instead of MiMC.
|
||||
|
||||
The [Merkle Tree Updater](https://github.com/tornadocash/tornado-trees/blob/master/circuits/MerkleTreeUpdater.circom) first verifies that the specified path contains a zero leaf by computing what the root would be given the path elements, path indices, and a zero leaf. It compares this against the specified old root, and then repeats that process again with the proposed subtree leaf, comparing the resulting root to the new root.
|
||||
|
||||
### Completing the Tree Update
|
||||
## Completing the Tree Update
|
||||
|
||||
With the witness generated, and the proof generated from it, we can now call the corresponding `updateDepositTree` or `updateWithdrawalTree` method on the Tornado Trees contract.
|
||||
|
||||
|
|
@ -1,18 +1,18 @@
|
|||
# Community Involvement
|
||||
|
||||
**\[Work In Progress\]**
|
||||
**\[Work In Progress]**
|
||||
|
||||
In a Decentralized Autonomous Organization \(DAO\), significant elements such as protocol parameters & token distribution are controlled by the community through governance. This governance allows the community to shape & continuously improve the protocol.
|
||||
In a Decentralized Autonomous Organization (DAO), significant elements such as protocol parameters & token distribution are controlled by the community through governance. This governance allows the community to shape & continuously improve the protocol.
|
||||
|
||||
However, the role of a community does not stop to suggesting proposals & expressing its opinion through votes. The community can also actively contribute to the success and prosperity of their protocol through constructive debates, mutual help and specific actions.
|
||||
|
||||
You can meet Tornado.Cash community on its very own forum & on social medias. Here are useful links to join Tornado.Cash community
|
||||
|
||||
* \*\*\*\*[**Tornado.Cash community forum**](https://torn.community/)\*\*\*\*
|
||||
* \*\*\*\*[**Tornado.Cash community forum**](https://torn.community)\*\*\*\*
|
||||
* \*\*\*\*[**Tornado.Cash Discord Server**](https://discord.com/invite/TFDrM8K42j)\*\*\*\*
|
||||
* \*\*\*\*[**Tornado.Cash Telegram Discussions**](https://t.me/TornadoCashOfficial)\*\*\*\*
|
||||
|
||||
_If you are interested, more information is available about_ [_Tornado.Cash governance rules & functioning._ ](governance.md)\_\_
|
||||
_If you are interested, more information is available about_ [_Tornado.Cash governance rules & functioning._ ](governance.md)\__
|
||||
|
||||
## How to Get Involved?
|
||||
|
||||
|
|
@ -22,37 +22,37 @@ Tornado.Cash community is looking for:
|
|||
|
||||
* developers that can help continue building the protocol & its tools;
|
||||
* auditors who can review code to find bugs and vulnerabilities;
|
||||
* content creators in order to make educational or promotional content to attract new users to the protocol \(videos, blogs, memes, etc.\)
|
||||
* content creators in order to make educational or promotional content to attract new users to the protocol (videos, blogs, memes, etc.)
|
||||
* designers that can refine protocol architecture & design;
|
||||
* potential hires for the DAO;
|
||||
* ...
|
||||
|
||||
## Tornado.Cash Community Fund
|
||||
|
||||
On June 2021, Tornado.Cash community has voted the implementation of a community fund to award its key contributors \([proposal \#7](https://app.tornado.cash/governance/7)\). The management of this fund lies between the hand of the community. Tornado.Cash users are the one who decide whose contribution is eligible for a compensation.
|
||||
On June 2021, Tornado.Cash community has voted the implementation of a community fund to award its key contributors ([proposal #7](https://app.tornado.cash/governance/7)). The management of this fund lies between the hand of the community. Tornado.Cash users are the one who decide whose contribution is eligible for a compensation.
|
||||
|
||||
###
|
||||
###
|
||||
|
||||
### Fund Details
|
||||
|
||||
Tornado.Cash Community Fund has been allocated 5% of total available TORN of the governance treasury, broken down as follows:
|
||||
|
||||
* 5% of the already vested 485.3k TORN at that time, resulting on an **initial transfer of 22.9k TORN** _->_ [_Transaction Details_](https://etherscan.io/tx/0xbe95f4268df2023d9ef234c1eedbb597b99e4c6e7d396d8f521ee482a1d93d47) __
|
||||
* 5% of the monthly 91.6k that will be vested in the next 12 month, which result on **a monthly transfer of approx. 4.6k TORN** \(a total of approx. 55k TORN over a year\)
|
||||
* 5% of the already vested 485.3k TORN at that time, resulting on an **initial transfer of 22.9k TORN** _->_ [_Transaction Details_](https://etherscan.io/tx/0xbe95f4268df2023d9ef234c1eedbb597b99e4c6e7d396d8f521ee482a1d93d47) \__
|
||||
* 5% of the monthly 91.6k that will be vested in the next 12 month, which result on **a monthly transfer of approx. 4.6k TORN** (a total of approx. 55k TORN over a year)
|
||||
|
||||
The monthly allocation of the Fund was programmed through [Sablier](https://sablier.finance/), a protocol built on Ethereum that allows a live stream of remaining TORNs \(second by second\) over 12 months.
|
||||
The monthly allocation of the Fund was programmed through [Sablier](https://sablier.finance), a protocol built on Ethereum that allows a live stream of remaining TORNs (second by second) over 12 months.
|
||||
|
||||
In total, an amount of approximatively **78k TORN** was allocated to this Community Fund. As of the end of August 2021, the balance of the Community Fund is about ~12.6k TORN vested in Sablier & 15.5k TORN in the Gnosis safe.
|
||||
In total, an amount of approximatively **78k TORN** was allocated to this Community Fund. As of the end of August 2021, the balance of the Community Fund is about \~12.6k TORN vested in Sablier & 15.5k TORN in the Gnosis safe.
|
||||
|
||||
Tornado.Cash Community Contract is: [0xb04E030140b30C27bcdfaafFFA98C57d80eDa7B4](https://gnosis-safe.io/app/#/safes/0xb04E030140b30C27bcdfaafFFA98C57d80eDa7B4/balances).
|
||||
Tornado.Cash Community Contract is: [0xb04E030140b30C27bcdfaafFFA98C57d80eDa7B4](https://gnosis-safe.io/app/#/safes/0xb04E030140b30C27bcdfaafFFA98C57d80eDa7B4/balances).
|
||||
|
||||
Funds are handled through a Multi-signature Wallet on Gnosis Safe. Keys to manage this wallet were put between the hand of 5 peer-elected community members. To validate a transaction, a consensus of 4-of-5 signatures is needed.
|
||||
|
||||
Those multi-signatures key holders were chosen for their contribution & commitment to Tornado.Cash and its Community. They pledged to sign off transaction following the community instructions. Those guidelines are expressed through forum discussion and corroborated by a Snapshot vote.
|
||||
Those multi-signatures key holders were chosen for their contribution & commitment to Tornado.Cash and its Community. They pledged to sign off transaction following the community instructions. Those guidelines are expressed through forum discussion and corroborated by a Snapshot vote.
|
||||
|
||||
All signers also pledged to resign if they no longer fulfill their allegiance to Tornado’s prosperity. They can also be dismissed from their role under the decision of the the community. To reward their commitment as signers & key contributors for Tornado.Cash community, 100 TORN per month have been deployed through Sablier
|
||||
|
||||
The current 5 multi-signatures key holders are:
|
||||
The current 5 multi-signatures key holders are:
|
||||
|
||||
* [0xd26BaA5F41CC7839CEdb020b6d98E1C6e1642D75](https://etherscan.io/address/0xd26BaA5F41CC7839CEdb020b6d98E1C6e1642D75)
|
||||
* [0x0D5bbdBa8Fd6523102A0bb5a0E68b30441a3765F](https://etherscan.io/address/0x0D5bbdBa8Fd6523102A0bb5a0E68b30441a3765F)
|
||||
|
|
@ -60,27 +60,25 @@ The current 5 multi-signatures key holders are:
|
|||
* [0x647e9e26DA82C29AAFbbFB1C3f45d916AA9b300d](https://etherscan.io/address/0x647e9e26DA82C29AAFbbFB1C3f45d916AA9b300d)
|
||||
* [0xEA27752f7D6687CB3Be2F180B997713b784c9911](https://etherscan.io/address/0xEA27752f7D6687CB3Be2F180B997713b784c9911)
|
||||
|
||||
###
|
||||
###
|
||||
|
||||
### How to Claim a Reward?
|
||||
|
||||
Each member has the ability to ask the community for a compensation from this fund to reward his/her contribution to Tornado.Cash. Each member also has the ability to request a compensation on behalf of another member to reward him/her for his/her work.
|
||||
|
||||
To this extent, a new category titled **« Funding »** has been created on Tornado.Cash discussion forum. By creating a new post in the category, all members can open a funding request to use the Community Fund. Discussions regarding terms & conditions of such a request are discussed on this post.
|
||||
To this extent, a new category titled **« Funding »** has been created on Tornado.Cash discussion forum. By creating a new post in the category, all members can open a funding request to use the Community Fund. Discussions regarding terms & conditions of such a request are discussed on this post.
|
||||
|
||||
Once those terms & conditions are fixed, a vote is conducted on Snapshot to validate \(or not\) such a funding request.
|
||||
Once those terms & conditions are fixed, a vote is conducted on Snapshot to validate (or not) such a funding request.
|
||||
|
||||
Here is Tornado.Cash Snapshot space:[ https://snapshot.org/\#/torn-community.eth](%20https://snapshot.org/#/torn-community.eth).
|
||||
Here is Tornado.Cash Snapshot space:[ https://snapshot.org/#/torn-community.eth](https://github.com/snapshot.org#/torn-community.eth).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### How to Vote on Snapshot?
|
||||
|
||||
Each specific funding request is accompanied by a Snapshot vote, where TORN holders can explicitly express their position. The result of this Snapshot vote provides the final instruction to multi-signature key holders on wether to transfer the decided reward amount to the concerned member.
|
||||
|
||||
Each snapshot vote has a `window of 3 days` to accumulate TORN holders votes. When the end date is reached, the Snapshot status goes from`Active` to `Closed`. Community members can no longer vote.
|
||||
Each snapshot vote has a `window of 3 days` to accumulate TORN holders votes. When the end date is reached, the Snapshot status goes from`Active` to `Closed`. Community members can no longer vote.
|
||||
|
||||
|
||||
|
||||
|
|
@ -105,7 +103,4 @@ Steps to vote on Snapshot are quite intuitive. The community member needs to:
|
|||
|
||||
|
||||
|
||||
|
||||
|
||||
_Written by_ [_@ayefda_](https://torn.community/u/ayefda)\_\_
|
||||
|
||||
_Written by_ [_@ayefda_](https://torn.community/u/ayefda)\__
|
||||
|
|
|
|||
Loading…
Reference in New Issue