Merge pull request #237 from ConsenSys/develop

v0.8.0

CHANGELOG.md

@@ -1,35 +1,72 @@
 <a name="v0.8.0"></a>
 
-Note: this version will be partially audited (bn254 & bls12-381 packages).
+## [v0.8.0] - 2022-08-03
 
-## [v0.8.0] - 2022-05-31
+This version was partially audited by Kudelski Security for the Algorand Foundation. (TODO insert report link).
+The scope of the audit covered `bn254` and `bls12-381` packages (including field arithmetic).
 
 ### Feat
 
-- field/generator suppors 1-limb modulus ([#175](https://github.com/ConsenSys/gnark-crypto/issues/175))
 - field/goldilocks (more efficient 1-limb modulus arith) ([#177](https://github.com/ConsenSys/gnark-crypto/issues/177))
-- **fri:** FRI protocol support and improvments
-- field.SetRandom: use random uniform sampling instead of mod reduce (zero-allocs)
-- adds BLS24-317 curve optimized for KZG ([#179](https://github.com/ConsenSys/gnark-crypto/pull/179))
+- field/generator suppors 1-limb modulus ([#175](https://github.com/ConsenSys/gnark-crypto/issues/175))
+- field.SetRandom zero-alloc uniform sampling
+- **E6/E12/E24:** GT torus-based batch compression/decompression
+- **fri:** modified challenge generation so it fits in a snark variable
+- **fri:** added check of correctness between rounds
 
 ### Fix
 
+- Handle edge case in Karabina decompression ([#219](https://github.com/ConsenSys/gnark-crypto/issues/219))
+- check nbTasks config when running msm, test all possible c-bit windows in when testing.Short not set) ([#226](https://github.com/ConsenSys/gnark-crypto/issues/226))
+- element.SetString(_) returns error if invalid input instead of panic
+- expand_msg_xmd copy bug, a few tests ([#201](https://github.com/ConsenSys/gnark-crypto/issues/201))
 - closes [#199](https://github.com/ConsenSys/gnark-crypto/issues/199). Correct bound in eddsa key gen template
 
-### Refactor & Cosmetics
+### Perf
+
+- remove unecessary inverse in KZG-verify
+- faster GLV scalar decompostion
+
+### Refactor & Docs
 
+- moved consensys/goff into field/goff ([#204](https://github.com/ConsenSys/gnark-crypto/issues/204))
 - clean comments in curves ([#193](https://github.com/ConsenSys/gnark-crypto/issues/193))
-- replace modulus generated by constants ([#194](https://github.com/ConsenSys/gnark-crypto/issues/194))
+- remove dead code ([#230](https://github.com/ConsenSys/gnark-crypto/issues/230))
+- cosmetic changes ([#197](https://github.com/ConsenSys/gnark-crypto/issues/197))
+- replace modulus generated by constants, add zero-alloc SetRandom ([#194](https://github.com/ConsenSys/gnark-crypto/issues/194))
 - remove uneeded x86 asm and files ([#192](https://github.com/ConsenSys/gnark-crypto/issues/192))
-- code cleaning & cosmetic changes ([#197](https://github.com/ConsenSys/gnark-crypto/issues/197))
-- clean HashToCurve APIs ([#188](https://github.com/ConsenSys/gnark-crypto/pull/188))
+- polish readme.md with updated godoc subpackage links ([#235](https://github.com/ConsenSys/gnark-crypto/issues/235))
+- acknowledge that inv(0)==0 in comments as a convention ([#233](https://github.com/ConsenSys/gnark-crypto/issues/233))
+- added note in pairing godoc - doesn't check inputs are in correct subgroup ([#231](https://github.com/ConsenSys/gnark-crypto/issues/231))
+- add security estimates of implemented curves in comments
+
+### Test
+
+- fix [#205](https://github.com/ConsenSys/gnark-crypto/issues/205) - msm bench with different bases ([#206](https://github.com/ConsenSys/gnark-crypto/issues/206))
+- vectors generated using <https://github.com/armfazh/h2c-go-ref>
+- **all curves:** compress/decompress pairing result
 
 ### Pull Requests
 
+- Merge pull request [#232](https://github.com/ConsenSys/gnark-crypto/issues/232) from ConsenSys/docs/comments
+- Merge pull request [#229](https://github.com/ConsenSys/gnark-crypto/issues/229) from ConsenSys/update_deps
+- Merge pull request [#227](https://github.com/ConsenSys/gnark-crypto/issues/227) from ConsenSys/fix/element_setstring
+- Merge pull request [#228](https://github.com/ConsenSys/gnark-crypto/issues/228) from ConsenSys/fix/race/test
+- Merge pull request [#224](https://github.com/ConsenSys/gnark-crypto/issues/224) from ConsenSys/refactor/scalarmul
+- Merge pull request [#220](https://github.com/ConsenSys/gnark-crypto/issues/220) from ConsenSys/perf/kzg-verify
+- Merge pull request [#223](https://github.com/ConsenSys/gnark-crypto/issues/223) from ConsenSys/doc/security-estimates-curves
+- Merge pull request [#216](https://github.com/ConsenSys/gnark-crypto/issues/216) from ConsenSys/feat/poly
+- Merge pull request [#217](https://github.com/ConsenSys/gnark-crypto/issues/217) from ConsenSys/string-utils
+- Merge pull request [#213](https://github.com/ConsenSys/gnark-crypto/issues/213) from ConsenSys/perf/glv
+- Merge pull request [#129](https://github.com/ConsenSys/gnark-crypto/issues/129) from ConsenSys/feat/GT-compression
+- Merge pull request [#209](https://github.com/ConsenSys/gnark-crypto/issues/209) from ConsenSys/codegen/svdw-not-e4
+- Merge pull request [#203](https://github.com/ConsenSys/gnark-crypto/issues/203) from ConsenSys/tests/bn254-vectors
+- Merge pull request [#196](https://github.com/ConsenSys/gnark-crypto/issues/196) from ConsenSys/patch/hashToFpGeneric
 - Merge pull request [#202](https://github.com/ConsenSys/gnark-crypto/issues/202) from ConsenSys/gbotrel/issue199
 - Merge pull request [#200](https://github.com/ConsenSys/gnark-crypto/issues/200) from tyGavinZJU/develop
 - Merge pull request [#85](https://github.com/ConsenSys/gnark-crypto/issues/85) from ConsenSys/feat/fri
 
+
 <a name="v0.7.0"></a>
 ## [v0.7.0] - 2022-03-24
 

README.md

@@ -2,19 +2,33 @@
 
 [![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/gnark_team.svg?style=social&label=Follow%20%40gnark_team)](https://twitter.com/gnark_team) [![License](https://img.shields.io/badge/license-Apache%202-blue)](LICENSE)  [![Go Report Card](https://goreportcard.com/badge/github.com/ConsenSys/gnark-crypto)](https://goreportcard.com/badge/github.com/ConsenSys/gnark-crypto) [![PkgGoDev](https://pkg.go.dev/badge/mod/github.com/consensys/gnark-crypto)](https://pkg.go.dev/mod/github.com/consensys/gnark-crypto) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5815453.svg)](https://doi.org/10.5281/zenodo.5815453)
 
-`gnark-crypto` provides:
-* [Elliptic curve cryptography](ecc/ecc.md) (+pairing) on BN254, BLS12-381, BLS12-377, BW6-761, BLS24-315, BLS24-317, BW6-633, BLS12-378 and BW6-756
-* [Finite field arithmetic](field/field.md) (fast big.Int)
-* FFT
-* Polynomial commitment schemes
-* MiMC
-* EdDSA (on the "companion" twisted edwards curves)
+`gnark-crypto` provides efficient cryptographic primitives, in Go:
+
+* Elliptic curve cryptography & **Pairing** on:
+  * [`bn254`] ([audit report]())
+  * [`bls12-381`] ([audit report]())
+  * [`bls24-317`]
+  * [`bls12-377`] / [`bw6-761`]
+  * [`bls24-315`] / [`bw6-633`]
+  * [`bls12-378`] / [`bw6-756`]
+  * Each of these curve has a [`twistededwards`] sub-package with its companion curve which allow efficient elliptic curve cryptography inside zkSNARK circuits.
+* [`field/goff`] - Finite field arithmetic code generator (blazingly fast big.Int)
+* [`fft`] - Fast Fourier Transform
+* [`fri`] - FRI (multiplicative) commitment scheme
+* [`fiatshamir`] - Fiat-Shamir transcript builder
+* [`mimc`] - MiMC hash function using Miyaguchi-Preneel construction
+* [`kzg`] - KZG commitment scheme
+* [`permutation`] - Permutation proofs
+* [`plookup`] - Plookup proofs
+* [`eddsa`] - EdDSA signatures (on the companion [`twistededwards`] curves)
 
 `gnark-crypto` is actively developed and maintained by the team ([email protected] | [HackMD](https://hackmd.io/@gnark)) behind:
-* [`gnark`: a framework to execute (and verify) algorithms in zero-knowledge](https://github.com/consensys/gnark) 
+
+* [`gnark`: a framework to execute (and verify) algorithms in zero-knowledge](https://github.com/consensys/gnark)
 
 ## Warning
-**`gnark-crypto` has not been audited and is provided as-is, use at your own risk. In particular, `gnark-crypto` makes no security guarantees such as constant time implementation or side-channel attack resistance.**
+
+**`gnark-crypto` is not fully audited and is provided as-is, use at your own risk. In particular, `gnark-crypto` makes no security guarantees such as constant time implementation or side-channel attack resistance.**
 
 **To report a security bug, please refer to [`gnark` Security Policy](https://github.com/ConsenSys/gnark/blob/master/SECURITY.md).**
 
@@ -24,7 +38,7 @@
 
 ### Go version
 
-`gnark-crypto` is tested with the last 2 major releases of Go (1.16 and 1.17).
+`gnark-crypto` is tested with the last 2 major releases of Go (1.17 and 1.18).
 
 ### Install `gnark-crypto`
 
@@ -34,24 +48,19 @@ go get github.com/consensys/gnark-crypto
 
 Note if that if you use go modules, in `go.mod` the module path is case sensitive (use `consensys` and not `ConsenSys`).
 
-### Documentation
-
-[![PkgGoDev](https://pkg.go.dev/badge/mod/github.com/consensys/gnark-crypto)](https://pkg.go.dev/mod/github.com/consensys/gnark-crypto)
-
-The APIs are consistent accross the curves. For example, [here is `bn254` godoc](https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254#pkg-overview).
-
 ### Development
 
 Most (but not all) of the code is generated from the templates in `internal/generator`.
 
-The generated code contains little to no interfaces and is strongly typed with a base field (generated by the `gnark-crypto/field`). The two main factors driving this design choice are:
+The generated code contains little to no interfaces and is strongly typed with a field (generated by the `gnark-crypto/field` package). The two main factors driving this design choice are:
 
 1. Performance: `gnark-crypto` algorithms manipulates millions (if not billions) of field elements. Interface indirection at this level, plus garbage collection indexing takes a heavy toll on perf.
-2. No generics in Go: need to derive (mostly) identical code for various moduli and curves, with consistent APIs
+2. Need to derive (mostly) identical code for various moduli and curves, with consistent APIs. Generics introduce significant performance overhead and are not yet suited for high performance computing.
 
 To regenerate the files, see `internal/generator/main.go`. Run:
-```
-go generate ./internal/...
+
+```bash
+go generate ./...
 ```
 
 ## Benchmarks
@@ -86,7 +95,26 @@ Please use the following BibTeX to cite the most recent release.
 
 We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/consensys/gnark-crypto/tags).
 
-
 ## License
 
-This project is licensed under the Apache 2 License - see the [LICENSE](LICENSE) file for details
+This project is licensed under the Apache 2 License - see the [LICENSE](LICENSE) file for details.
+
+[`field/goff`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/field/goff
+[`bn254`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254
+[`bls12-381`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bls12-381
+[`bls24-317`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bls24-317
+[`bls12-377`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bls12-377
+[`bls24-315`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bls24-315
+[`bls12-378`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bls12-378
+[`bw6-761`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bw6-761
+[`bw6-633`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bw6-633
+[`bw6-756`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bw6-756
+[`twistededwards`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/twistededwards
+[`eddsa`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/twistededwards/eddsa
+[`fft`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/fft
+[`fri`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/fri
+[`mimc`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/mimc
+[`kzg`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/kzg
+[`plookup`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/plookup
+[`permutation`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/ecc/bn254/fr/permutation
+[`fiatshamir`]: https://pkg.go.dev/github.com/consensys/gnark-crypto/fiat-shamir

ecc/bls12-377/bls12-377.go

@@ -1,3 +1,25 @@
+// Package bls12377 efficient elliptic curve, pairing and hash to curve implementation for bls12-377.
+//
+// bls12-377: A Barreto--Lynn--Scott curve with
+//		embedding degree k=12
+//		seed x₀=9586122913090633729
+// 		𝔽r: r=8444461749428370424248824938781546531375899335154063827935233455917409239041 (x₀⁴-x₀²+1)
+// 		𝔽p: p=258664426012969094010652733694893533536393512754914660539884262666720468348340822774968888139573360124440321458177 ((x₀-1)² ⋅ r(x₀)/3+x₀)
+// 		(E/𝔽p): Y²=X³+1
+// 		(Eₜ/𝔽p²): Y² = X³+1/u (D-type twist)
+// 		r ∣ #E(Fp) and r ∣ #Eₜ(𝔽p²)
+// Extension fields tower:
+// 		𝔽p²[u] = 𝔽p/u²+5
+// 		𝔽p⁶[v] = 𝔽p²/v³-u
+// 		𝔽p¹²[w] = 𝔽p⁶/w²-v
+// optimal Ate loop size:
+//		x₀
+// Security: estimated 126-bit level following [https://eprint.iacr.org/2019/885.pdf]
+// (r is 253 bits and p¹² is 4521 bits)
+//
+// Warning
+//
+// This code has not been audited and is provided as-is. In particular, there is no security guarantees such as constant time implementation or side-channel attack resistance.
 package bls12377
 
 import (
@@ -9,18 +31,6 @@ import (
 	"github.com/consensys/gnark-crypto/ecc/bls12-377/internal/fptower"
 )
 
-// BLS12-377: A Barreto--Lynn--Scott curve of embedding degree k=12 with seed x₀=9586122913090633729
-// 𝔽r: r=8444461749428370424248824938781546531375899335154063827935233455917409239041 (x₀⁴-x₀²+1)
-// 𝔽p: p=258664426012969094010652733694893533536393512754914660539884262666720468348340822774968888139573360124440321458177 ((x₀-1)² ⋅ r(x₀)/3+x₀)
-// (E/𝔽p): Y²=X³+1
-// (Eₜ/𝔽p²): Y² = X³+1/u (D-type twist)
-// r ∣ #E(Fp) and r ∣ #Eₜ(𝔽p²)
-// Extension fields tower:
-//     𝔽p²[u] = 𝔽p/u²+5
-//     𝔽p⁶[v] = 𝔽p²/v³-u
-//     𝔽p¹²[w] = 𝔽p⁶/w²-v
-// optimal Ate loop size: x₀
-
 // ID bls377 ID
 const ID = ecc.BLS12_377
 
@@ -89,7 +99,7 @@ func init() {
 
 	g1Gen.X.SetString("81937999373150964239938255573465948239988671502647976594219695644855304257327692006745978603320413799295628339695")
 	g1Gen.Y.SetString("241266749859715473739788878240585681733927191168601896383759122102112907357779751001206799952863815012735208165030")
-	g1Gen.Z.SetString("1")
+	g1Gen.Z.SetOne()
 
 	g2Gen.X.SetString("233578398248691099356572568220835526895379068987715365179118596935057653620464273615301663571204657964920925606294",
 		"140913150380207355837477652521042157274541796891053068589147167627541651775299824604154852141315666357241556069118")