Merge pull request iden3#92 from victorcrrd/plonk-custom-gates-doc

Added some documentation regarding custom templates

Author: miguelis

mkdocs/docs/circom-language/custom-templates-snarkjs.md

@@ -0,0 +1,6 @@
+# Custom templates in [snarkjs](../index.md#snarkjs)
+
+[snarkjs](https://github.com/iden3/snarkjs) provides an implementation of the PLONK's zkSNARK. An extension of the scheme, [turbo-PLONK](https://docs.zkproof.org/pages/standards/accepted-workshop3/proposal-turbo_plonk.pdf), allows the definition of the so called custom gates: more general transition gates than the ones defined by default for the regular PLONK zkSNARK, that allows the circuit's designer to, maybe, reduce the number of used gates, probably resulting in shorter proofs size or verification times. This document will contain a list of the custom gates implemented in snarkjs that can me used in the circom language. Note that the list may grow over time with the new implementations from the iden3 collaborators or thanks to contributions from the community.
+
+## List of custom gates implemented in snarkjs
+At the moment there are no custom gates implemented in snarkjs yet.

mkdocs/docs/circom-language/pragma.md

@@ -1,12 +1,23 @@
 # Pragma
 
-All files with .circom extension should start with a first `pragma`instruction specifying the compiler version, like this: 
+## Version pragma
+
+All files with .circom extension should start with a first `pragma` instruction specifying the compiler version, like this: 
 
 ```text
 pragma circom xx.yy.zz;
 ```
 
-This is to ensure that the circuit is compatible with the compiler version indicated after the `pragma` instruction. Otherwise, the compiler throws a warning. 
+This is to ensure that the circuit is compatible with the compiler version indicated after the `pragma` instruction. Otherwise, the compiler throws a warning.
 
 If a file does not contain this instruction, it is assumed that the code is compatible with the latest compiler's version and a warning is thrown.
 
+## Custom templates pragma
+
+Since circom 2.0.6, the language allows the definition of custom templates (see [this](../circom-language/templates-and-components.md#custom-templates) for more information). This `pragma` allows the circom programmer to easily tell if it's using custom templates: if any file declaring a custom template or including a file declaring any custom template doesn't use this `pragma`, the compiler will produce an error. Moreover, it will inform the programmer about which files should include this pragma.
+
+To use it simply add the following instruction at the beginning (and after the version `pragma`) of the .circom files that needs it:
+
+```text
+pragma custom_templates;
+```

mkdocs/docs/circom-language/reserved-keywords.md

@@ -20,6 +20,6 @@ The list of reserved keywords is the following:
 * **assert:** Check the condition at construction time.
 * **include:** Include code of the indicated file.
 * **pragma circom**: Instruction to check the compiler version.
-
+* **pragma custom_templates**: Instruction to indicate the usage of custom templates.
 
 

mkdocs/docs/circom-language/templates-and-components.md

@@ -213,3 +213,21 @@ template parallel NameTemplate(...){...}
 
 If this tag is used, the resulting C++ file will contain the parallelized code to compute the witness. Parallelization becomes particularly relevant when dealing with large circuits.
 
+## Custom templates
+
+Since version 2.0.6, the language allows the definition of a new type of templates, custom templates. This new construction works similarly to standard templates: they are declared analogously, just adding the keyword `custom` in its declaration after `template`; and are instantiated in the exact same way. That is, a custom template `Example` is defined and then instantiated as follows:
+
+```text
+pragma circom 2.0.6; // note that custom templates are only allowed since version 2.0.6
+pragma custom_templates;
+
+template custom Example() {
+   // custom template's code
+}
+
+template UsingExample() {
+   component example = Example(); // instantiation of the custom template
+}
+```
+
+However, the way in which their computation is encoded is different from the one for standard templates. Instead of producing r1cs constraints, the usage of each defined custom template will be treated in a later stage by [snarkjs](../index.md#snarkjs) to generate and validate the zk proof, in this case using the PLONK scheme (and using the custom template's definitions as PLONK's custom gates, see [here](../circom-language/custom-templates-snarkjs.md) how). Information about the definition and usages of custom templates will be exported in the `.r1cs` file (see [here](https://github.com/iden3/r1csfile/blob/master/doc/r1cs_bin_format.md) sections 4 and 5). This means that custom templates cannot introduce any constraint inside their body, nor declare any subcomponent.