From 97b870b725e89ab62c63c8de60b9ac3b7e4dbc59 Mon Sep 17 00:00:00 2001 From: Marta Belles Date: Fri, 6 Sep 2019 17:14:45 +0200 Subject: [PATCH] Updated README files --- README.md | 17 +- circuits/README.md | 818 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 832 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2eb00da..9dfb020 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,17 @@ -# cirpedersen +# CircomLib -Pedersen Hash and Exponentiation circuits using Baby Jub Curve in circom language +## Description +- This repository contains a library of circuit templates. +- All files are copyrighted under 2018 0KIMS association and part of the free software [circom](https://github.com/iden3/circom) (Zero Knowledge Circuit Compiler). + +## Organisation + +This respository contains 5 folders: +- `circuits`: it contains the implementation of different cryptographic primitives in circom language. +- `calcpedersenbases`: set of functions in JavaScript used to find a set of points in [Baby Jubjub](https://github.com/barryWhiteHat/baby_jubjub) elliptic curve that serve as basis for the [Pedersen Hash](https://github.com/zcash/zcash/issues/2234). +- `doc`: it contains some circuit schemes in ASCII (must be opened with Monodraw, an ASCII art editor for Mac). +- `src`: it contains similar implementation of circuits in JavaScript. +- `test`: tests. + +A description of the specific circuit templates for the `circuit` folder will be soon updated. \ No newline at end of file diff --git a/circuits/README.md b/circuits/README.md index 6c9e76a..30b1cd2 100644 --- a/circuits/README.md +++ b/circuits/README.md @@ -1,3 +1,19 @@ +# CircomLib/Circuits + +## Description + +- This folder contains circuit templates for standard operations and many cryptographic primitives. +- Below you can find specifications of each function. In the representation of elements, there are three tyes: + - Binary + - String + - Field element (the field is specified in each case. We consider 2 possible fields: Fp and Fr, where p... and r... .) + +## Table of Contents + +[TOC] + +## Jordi + * compconstant - Returns 1 if `in` (expanded to binary array) > `ct` * aliascheck - check if `in` (expanded to binary array) oveflowed its 254 bits (<= -1) * babyjub - twisted Edwards curve 168700.x^2 + y^2 = 1 + 168696.x^2.y^2 @@ -11,4 +27,804 @@ * zcash/zcash#2233 * smt - Sparse Merkle Tree * https://ethresear.ch/t/optimizing-sparse-merkle-trees/3751 -* montgomery https://en.wikipedia.org/wiki/Montgomery_curve \ No newline at end of file +* montgomery https://en.wikipedia.org/wiki/Montgomery_curve + +## Circuits + +### sha256 + +Folder containing the implementation of sha256 hash circuit. + +### smt + +Folder containing the circuit implementation of Sparse Merkle Trees. + +### aliascheck + +- `AliasCheck()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### babyjub + +Arithmetic on [Baby Jubjub elliptic curve](https://github.com/barryWhiteHat/baby_jubjub) in twisted Edwards form. (TODO: Expose here the characteristics of the curve?) + + +- `BabyAdd()` + + - DESCRIPTION + + It adds two points on the Baby Jubjub curve. More specifically, given two points P1 = (`x1`, `y1`) and P2 = (`x2`, `y2`) it returns a point P3 = (`xout`, `yout`) such that + + (`xout`, `yout`) = (`x1`,`y1`) + (`x2`,`y2`) + = ((`x1y2`+`y1x2`)/(1+`dx1x2y1y2`)),(`y1y2`-`ax1x2`)/(1-`dx1x2y1y2`)) + + - SCHEMA + ``` + var a var d + | | + | | + ______v_________v_______ + input x1 ----> | | + input y1 ----> | BabyAdd() | ----> output xout + input x2 ----> | | ----> output yout + input y2 ----> |________________________| + ``` + + - INPUTS + + | Input | Representation | Description | | + | ------------- | ------------- | ------------- | ------------- | + | `x1` | Bigint | Field element of Fp | First coordinate of a point (x1, y1) on E. | + | `y1` | Bigint | Field element of Fp | Second coordinate of a point (x1, y1) on E. | + | `x2` | Bigint | Field element of Fp | First coordinate of a point (x2, y2) on E. | + | `y2` | Bigint | Field element of Fp | Second coordinate of a point (x2, y2) on E. | + + Requirement: at least `x1`!=`x2` or `y1`!=`y2`. + + - OUTPUT + + | Input | Representation | Description | | + | ------------- | ------------- | ------------- | ------------- | + | `xout` | Bigint | Field element of Fp | First coordinate of the addition point (xout, yout) = (x1, y1) + (x2, y2). | + | `yout` | Bigint | Field element of Fp | Second coordinate of the addition point (xout, yout) = (x1, y1) + (x2, y2). | + + - BENCHMARKS (constraints) + + - EXAMPLE + +- `BabyDbl()` + - DESCRIPTION : doubles a point (`xout`,`yout`) = 2*(`x`,`y`). + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `BabyCheck()` + + - DESCRIPTION : checks if a given point is in the curve. + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `BabyPbk()` + + - DESCRIPTION: : given a private key, it returns the associated public key. + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + + +### binsub + +- `BinSub(n)` + + - DESCRIPTION: binary substraction. + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### binsum + +- `nbits(a)` + + - DESCRIPTION : binary sum. + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `BinSum(n, ops)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### bitify + +- `Num2Bits()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Num2Bits_strict()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Bits2Num()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Bits2Num_strict()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Num2BitsNeg()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### comparators + +- `IsZero() ` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `IsEqual()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `ForceEqualIfEnabled()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `LessThan()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `GreaterThan()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `GreaterEqThan()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### compconstant + +- `CompConstant(ct)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### eddsa + +Edwards Digital Signature Algorithm in Baby Jubjbub (link a eddsa) + +- `EdDSAVerifier(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### eddsamimc + +- `EdDSAMiMCVerifier()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### eddsamimcsponge + +- `EdDSAMiMCSpongeVerifier()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### eddsaposeidon + +- `EdDSAPoseidonVerifier()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### escalarmul + +- `EscalarMulWindow(base, k)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `EscalarMul(n, base)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### escalarmulany + +- `Multiplexor2()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `BitElementMulAny()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `SegmentMulAny(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `EscalarMulAny(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### escalarmulfix + +- `WindowMulFix()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `SegmentMulFix(nWindows)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `EscalarMulFix(n, BASE)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### escalarmulw4table + +- `pointAdd` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `EscalarMulW4Table` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### gates + +- `XOR` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `AND` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `OR` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `NOT` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `NAND` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `NOR` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `MultiAND` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mimc + +Implementation of MiMC-7 hash in Fp being... (link to description of the hash) + +- `MiMC7(nrounds)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `MultiMiMC7(nInputs, nRounds)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mimcsponge + +- `MiMCSponge(nInputs, nRounds, nOutputs)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `MiMCFeistel(nrounds)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### montgomery + +- `Edwards2Montgomery()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Montgomery2Edwards()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `MontgomeryAdd()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `MontgomeryDouble()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### multiplexer + +- `log2(a)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `EscalarProduct(w)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Decoder(w)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Multiplexer(wIn, nIn)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mux1 + +- `MultiMux1(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Mux1()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mux2 + +- `MultiMux2(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Mux2()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mux3 + +- `MultiMux3(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Mux3()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### mux4 + +- `MultiMux4(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Mux4()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### pedersen_old + +Old version of the Pedersen hash (do not use any +more?). + +### pedersen + +- `Window4()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Segment(nWindows)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Pedersen(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### pointbits + +- `sqrt(n)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Bits2Point()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Bits2Point_Strict()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Point2Bits` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Point2Bits_Strict` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### poseidon + +Implementation of Poseidon hash function (LINK) + +- `Sigma()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Ark(t, C)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Mix(t, M)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +- `Poseidon(nInputs, t, nRoundsF, nRoundsP)` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### sign + +- `Sign()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE + +### switcher + +- `Switcher()` + + - DESCRIPTION + - SCHEMA + - INPUT + - OUTPUT + - BENCHMARKS + - EXAMPLE