docs: readme (#46)

* docs: readme

* wip: pairing check

* docs

* Update README.md

Co-authored-by: Colin Roberts <[email protected]>

* Update README.md

Co-authored-by: Colin Roberts <[email protected]>

---------

Co-authored-by: Colin Roberts <[email protected]>

README.md

@@ -15,10 +15,89 @@
   <!-- [![Documentation](https://docs.rs/ronkathon/badge.svg)](https://docs.rs/ronkathon) -->
   </div>
 
+## Overview
+Ronkathon is an implementation of plonkish KZG-based proofs. It is inspired by the common python plonkathon repository, and plonk-by-hand. We use the same curve and field as plonk-by-hand (not secure), and are working towards building everything from scratch to understand everything from first principles.
+
+## Resources
+
+We have found the following resources helpful in understanding the foundational mathematics behind this implementation. After going through these, you should be able to understand the codebase. In order it is recommended to understand:
+- Finite Fields
+- Extension Fields
+- Elliptic Curves over Fields and Extension Fields
+- Embedding degree
+- Polynomials
+- FFTs
+- Pairings
+
+### Some notes on the KZG proof construction:
+Lets start simple with a finite field and work up to creating two elliptic curve *groups* that have a pairing or bilinear map (more on that later). 
+First lets pick a finite field of prime order $p$, we pick $p=101$ since it is small and we are able to follow along plonk-by-hand.
+In general large primes are good but we will use a small one just for the sake of example.
+Next lets pick an elliptic curve $y^2=x^3+3$, there are some heuristics to curves that i encourage you to learn more about if you like but you can also black box and know that this is a good curve.
+So now we have two algebraic structures:
+- finite field $F_{101}$
+- curve $y^2=x^3+3$
+Initially this elliptic curve is just a continuous squiggle, which isn't the most useful. But we can make it discrete by constraining it's points to reside in the field. 
+Now it doesn't look like the squiggle we know and love but instead a lattice (you can see [here](https://andrea.corbellini.name/ecc/interactive/modk-add.html) by switching from real numbers to finite fields ).
+
+Now we have a set of discrete points on the curve over the finite field that form a *[group](https://en.wikipedia.org/wiki/Group_(mathematics))*, a group has a single operation called the group operation, it is perhaps more abstract than a field. 
+The group operation on this set of curve points is point addition which we all know and love with the squiggly lines, intersections and reflections. From this group operation we can create point doubling, and as a result, scalar multiplication (how many times do we double a point) as handy abstractions over the single group operation. 
+
+To review we have a curve group call it $E1$ and the base field $F_{101}$
+Elements in the curve group are points (pairs of integers) that lie in the field $F_{101}$.
+
+Now to create a pairing friendly curve we first must find the curve groups order. 
+The order is how many times do we double the generator to get the generator again, the reason we can do this is because our group is cyclic.
+Now if our base field $F_{101}$ is of prime order, then any point in the curve group is a generator.
+So in practice you can pick a point and double it untill you get back to itself (remember to check the inverse!).
+This defines the scalar field $F_r$ where $r$ is the order. 
+In our case this is $17$. 
+Once we have have this we can computer the embedding degree.
+The embedding degree is the smallest number $k$ such that $r | p^k - 1$ where $r$ is the order of the curve: $17$
+For us this is $2$, we can check that 17 divides $101^2 -1$ as $10200 / 17 = 600$ ✅. 
+So now we have an embedding degree of our curve. 
+
+The next step is to construct a field extension from the first field such that $f_{p^2}$ is a field extension of $f_p$, we extend with $x^2 + 2$ which is irreducible in $F_{101}$
+The elements of the extension field are two degree polynomials where the coefficients are in $F_{101}$
+Now we can construct pairing friendly curve over the field extension and get a generator point for the second curve: $g2 = (31, 36x)$
+Our second curve group now E2, is over the same curve but now over the field extension. 
+It's points are now represented by two degree polynomials (because our embedding degree is two), not integers.
+We now have two pairing friendly groups $E1$ and $E2$ and generators for both of them. 
+
+The next step is to construct the structured refrence string SRS with g1 and g2. The structured refrence string is generated by multiplying the generator points by some randomness $\{S^i\}$, the SRS needs to be a vector of length $t$ where $t$ is the number of constraints in the proof. 
+This is same as the degree of the polynomial which we would like to prove knowledge of. 
+KZG Proves an arbitrary polynomial. Plonk can be used to represent some computation as a polynomial. 
+
+TODO: Talk more about plonk.
+
+Commit to a polynomial using the g1_SRS: This is done by multiplying the polynomial coefficients by the g1_SRS points (scalar multiplication in the curve group) and adding the resulting points to each other to get a single point that represents the commitment call it `p_commit`.
+
+Opening involves choosing a point to evauluate the polynomial at and dividing the polynomial by .... (need the notes for this). the resulting polynomial is also combined with the g1_SRS to get a new commitment curve point call it `q_commit`.
+
+Then we do the pairing check. 
+
+$e(q_{commit}, g2srs[0] - g2* point) = e(p_{commit} - g1srs[0] * val, g2)$
+
+
+
+### Theoretic Resources
+- [A gentle introduction to Fast Fourier Transforms over Finite Fields](https://vitalik.eth.limo/general/2019/05/12/fft.html)
+- [Introduction to Pairings](https://vitalik.eth.limo/general/2017/01/14/exploring_ecp.html)
+- [KZG introduction by dankrad](https://dankradfeist.de/ethereum/2020/06/16/kate-polynomial-commitments.html)
+- [Pairings in depth](https://static1.squarespace.com/static/5fdbb09f31d71c1227082339/t/5ff394720493bd28278889c6/1609798774687/PairingsForBeginners.pdf)
+- [Plonk by Hand P1](https://research.metastate.dev/plonk-by-hand-part-1/)
+- [Plonk by Hand P2](https://research.metastate.dev/plonk-by-hand-part-2-the-proof/)
+### Code Refrences
+- [Plonkathon](https://github.com/0xPARC/plonkathon/blob/main/README.md)
+- [Plonky3](https://github.com/Plonky3/Plonky3)
+- [py_pairing](https://github.com/ethereum/py_pairing/tree/master)
+- [arkworks](https://github.com/arkworks-rs)
+
+
 ## Math
 To see computations used in the background, go to the `math/` directory.
 From there, you can run the `.sage` files in a SageMath environment.
-In particular, the `math/field.sage` computes roots of unity in the `PlutoField` which is of size 101.
+In particular, the `math/field.sage` computes roots of unity in the `PlutoField` which is of size 101. To install sage on your machine, follow the instructions [here](https://doc.sagemath.org/html/en/installation/index.html). If you are on a Mac, you can install it via homebrew with `brew install --cask sage`.
 
 ## License
 Licensed under your option of either: