From 148f8cad6ecf2f8365aedc0ecc033026e3ac1416 Mon Sep 17 00:00:00 2001 From: Victor Carrillo Redondo Date: Mon, 1 Aug 2022 17:40:09 +0200 Subject: [PATCH 1/5] added some documentation regarding custom templates --- mkdocs/docs/circom-language/pragma.md | 15 +++++++++++++-- mkdocs/docs/circom-language/reserved-keywords.md | 2 +- .../circom-language/templates-and-components.md | 6 ++++++ 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/mkdocs/docs/circom-language/pragma.md b/mkdocs/docs/circom-language/pragma.md index 190ba2a..9d657ca 100644 --- a/mkdocs/docs/circom-language/pragma.md +++ b/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; +``` diff --git a/mkdocs/docs/circom-language/reserved-keywords.md b/mkdocs/docs/circom-language/reserved-keywords.md index 093226c..3b813db 100644 --- a/mkdocs/docs/circom-language/reserved-keywords.md +++ b/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. diff --git a/mkdocs/docs/circom-language/templates-and-components.md b/mkdocs/docs/circom-language/templates-and-components.md index c8db987..b12ac5d 100644 --- a/mkdocs/docs/circom-language/templates-and-components.md +++ b/mkdocs/docs/circom-language/templates-and-components.md @@ -110,6 +110,12 @@ component main {public [in]} = A(1); During the compilation of this code, we obtain the next warning message: _"There is no output signal."_. +## 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. + +However, the way in which their computation is encoded is treated differently from standard templates. Instead of producing r1cs constraints, the usage of each defined custom template will be trated in a later stage by [snarkjs](../index.md#snarkjs) to generate and validate the zk proof, in this case using the PLONK scheme. 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)). This means that custom templates cannot introduce any constraint inside they body, nor declare any subcomponent. + ## Components A component defines an arithmetic circuit and, as such, it receives N input signals and produces M output signals and K intermediate signals. Additionally, it can produce a set of constraints. From cf2c3a485d8c04ae1f2975bff040178bd16bfcc4 Mon Sep 17 00:00:00 2001 From: Victor Carrillo Redondo Date: Tue, 2 Aug 2022 11:19:38 +0200 Subject: [PATCH 2/5] improved doc --- .../circom-language/templates-and-components.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/mkdocs/docs/circom-language/templates-and-components.md b/mkdocs/docs/circom-language/templates-and-components.md index b12ac5d..bf278b0 100644 --- a/mkdocs/docs/circom-language/templates-and-components.md +++ b/mkdocs/docs/circom-language/templates-and-components.md @@ -112,9 +112,19 @@ During the compilation of this code, we obtain the next warning message: _"There ## 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. +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: -However, the way in which their computation is encoded is treated differently from standard templates. Instead of producing r1cs constraints, the usage of each defined custom template will be trated in a later stage by [snarkjs](../index.md#snarkjs) to generate and validate the zk proof, in this case using the PLONK scheme. 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)). This means that custom templates cannot introduce any constraint inside they body, nor declare any subcomponent. +```text +pragma custom_templates; + +template custom Example() {} + +template UsingExample() { + component example = Example(); +} +``` + +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](TBC) 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. ## Components From d8819e4920d252f950ef00a3c4536a905fa00599 Mon Sep 17 00:00:00 2001 From: Victor Carrillo Redondo Date: Tue, 2 Aug 2022 12:18:22 +0200 Subject: [PATCH 3/5] custom templates defined in snarkjs file --- mkdocs/docs/circom-language/custom-templates-snarkjs.md | 6 ++++++ mkdocs/docs/circom-language/templates-and-components.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 mkdocs/docs/circom-language/custom-templates-snarkjs.md diff --git a/mkdocs/docs/circom-language/custom-templates-snarkjs.md b/mkdocs/docs/circom-language/custom-templates-snarkjs.md new file mode 100644 index 0000000..0b5b8ae --- /dev/null +++ b/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. diff --git a/mkdocs/docs/circom-language/templates-and-components.md b/mkdocs/docs/circom-language/templates-and-components.md index bf278b0..c61ee43 100644 --- a/mkdocs/docs/circom-language/templates-and-components.md +++ b/mkdocs/docs/circom-language/templates-and-components.md @@ -124,7 +124,7 @@ template UsingExample() { } ``` -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](TBC) 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. +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.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. ## Components From 5d2d43aeca6d22d0c591d394ca5d1e63515d1ced Mon Sep 17 00:00:00 2001 From: Victor Carrillo Redondo Date: Thu, 4 Aug 2022 16:21:18 +0200 Subject: [PATCH 4/5] suggestions by Xavier --- .../templates-and-components.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/mkdocs/docs/circom-language/templates-and-components.md b/mkdocs/docs/circom-language/templates-and-components.md index c61ee43..0d41f45 100644 --- a/mkdocs/docs/circom-language/templates-and-components.md +++ b/mkdocs/docs/circom-language/templates-and-components.md @@ -110,22 +110,6 @@ component main {public [in]} = A(1); During the compilation of this code, we obtain the next warning message: _"There is no output signal."_. -## 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 custom_templates; - -template custom Example() {} - -template UsingExample() { - component example = Example(); -} -``` - -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.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. - ## Components A component defines an arithmetic circuit and, as such, it receives N input signals and produces M output signals and K intermediate signals. Additionally, it can produce a set of constraints. @@ -229,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.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. From 138209104316fa8f4ff0d63cddcf6f4b96c67df8 Mon Sep 17 00:00:00 2001 From: Victor Carrillo Redondo Date: Thu, 4 Aug 2022 16:27:55 +0200 Subject: [PATCH 5/5] failing reference fixed --- mkdocs/docs/circom-language/templates-and-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs/docs/circom-language/templates-and-components.md b/mkdocs/docs/circom-language/templates-and-components.md index 0d41f45..34c0edf 100644 --- a/mkdocs/docs/circom-language/templates-and-components.md +++ b/mkdocs/docs/circom-language/templates-and-components.md @@ -230,4 +230,4 @@ template UsingExample() { } ``` -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.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. +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.