Funded Bounty - Circuit Documentation

This task consists of expanding the current documentation to give a technical overview to Tornado’s zkSNARK proving scripts (known as circuits), which are written in iden3’s circom language. Providing an educational resource towards the core architecture of the protocol.

Description

Tornado’s circuits can be categorised into two separate components; one for inserting deposits and withdrawals to each equivalent Merkle tree in batches at specific depths, the latter to issue anonymity mining rewards for commitments pushed to the withdrawal tree. Each has a github repository and the circom files are located in the circuits/ directory.

While the previous iteration of the protocol’s circuits (v1) has minimal documentation available, it could complement the applicant’s understanding of the current implementation - you can find the repository here.

Scope

Tornado’s documentation is hosted using Gitbook, applicants must add a new section for circuits to the documentation through forking the repository here and use a pull-request to submit their work. There should be thorough explanations for:

  • The higher level concepts
  • Parameters, input signals and output signals
  • Circuit flow and constraints
  • Installation and testing

Budget

80 TORN will be allocated to the best submission of this task.

4 Likes

I think that I’ll take a stab at a submission. It would be helpful to have some guidance around how the submissions will be judged.

  1. Who should be considered the audience of the circuit documentation? Is it intended as a development resource, to be used as reference material, or is this documentation intended for end users, to help them understand what they’re using, and how problems with it can be resolved?
  2. Are there any stylistic constraints on TC’s documentation? Should submissions attempt to maintain the same tone and structure as other existing documentation, or is there a degree of creative license?
  3. Should the circuit documentation attempt to describe functionality that is implemented in the closed-source front-end? (e.g. Note Accounts, Relayer Selection)
  4. Should the documentation delve into how Circom / ZK circuits work, or should it assume a degree of familiarity on the part of the reader? I’ve been doing a lot of work with circom of late, and it’s not likely that most people will have any understanding of it.
  5. How much of a race is this? If I put in the work to produce something high-quality, which takes longer to produce, do I run the risk of someone else’s more minimal submission being accepted instead?
3 Likes
  1. Who should be considered the audience of the circuit documentation? Is it intended as a development resource, to be used as reference material, or is this documentation intended for end users, to help them understand what they’re using, and how problems with it can be resolved?

It is for end users (who are often non-tech) and for software developers, that is why we need something which is well explained, even if it is complicated stuff.

  1. Are there any stylistic constraints on TC’s documentation? Should submissions attempt to maintain the same tone and structure as other existing documentation, or is there a degree of creative license?

We need something creative of course, it does not have to follow any other documentation style in my opinion, but it have to be readable and understandable. Using graphics and images could be interesting too.

  1. Should the circuit documentation attempt to describe functionality that is implemented in the closed-source front-end? (e.g. Note Accounts, Relayer Selection)

I will let @xgozzy answers regarding this

  1. Should the documentation delve into how Circom / ZK circuits work, or should it assume a degree of familiarity on the part of the reader? I’ve been doing a lot of work with circom of late, and it’s not likely that most people will have any understanding of it.

That is why we need someone able to make docs understandable. It should dig deep into Tornado circuits.

  1. How much of a race is this? If I put in the work to produce something high-quality, which takes longer to produce, do I run the risk of someone else’s more minimal submission being accepted instead?

We can put a time limit and at the end of it, the contributions will all be analyzed, so its the same for everyone.
Don’t forget that you can split the work with another person.

2 Likes

I’ll be pushing my progress up to this branch, if anyone wants to follow along:

Critical feedback is very-much-so appreciated. I have a pretty good understanding of circom and cryptography in general, but may get some of the math wrong, and I’m approaching the explanation of the TC circuits from a “this is probably what happens based on the code” perspective.

1 Like

Great to have you showing interest in this FrozenFire.

The original intention was for the documentation to be technical, I do not think time should be spent on this specific task normalizing and simplifying the circuit’s logic as there is already a mass of work to be done from the technical standpoint. It is more intended as a developer resource. Interesting that you ask this though and makes me think…

that we should create a separate bounty to write a simplified primer on how tornado uses zero-knowledge to keep your deposits unique to the end-user. After all, tornado is one of the most adopted applications of zero-knowledge in production to date.

Well having a concise structure should be first in mind when writing the documentation, with a flow where the primitives are first defined and are referenced throughout where necessary. You are free to look to other documentation for influence and write some short explainers (eg. Bob and Alice), with all that in mind there is room for creativity for sure (diagrams could be a possibility).

It should briefly mention where suitable but since that aspect of the stack is closed source, it is not relative to this task.

Most definitely.

I will wait for all submissions to be finalised (within a reasonable timeframe) before making the decision on which is best.

Happy to help where needed and I’m sure some others in the community will be too.