forked from wl-buildingtools/nightfall
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' of https://github.com/EYBlockchain/nightfall in…
…to xcert # Conflicts: # README.md
- Loading branch information
Showing
95 changed files
with
8,026 additions
and
6,014 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| language: node_js | ||
| node_js: | ||
| - 11 | ||
| script: | ||
| - npm lint |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,5 @@ | ||
| See [./nightfall-v1.pdf](./nightfall-v1.pdf) for the whitepaper. | ||
| # Whitepaper | ||
|
|
||
| We recommend downloading the PDF, because Github's viewer doesn't support the internal hyperlinks of PDF's. | ||
|
|
||
| - See [./nightfall-v1.pdf](./nightfall-v1.pdf) for the Whitepaper. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| \relax | ||
| \providecommand\hyper@newdestlabel[2]{} | ||
| \providecommand\zref@newlabel[2]{} | ||
| \@writefile{lof}{\contentsline {xsect}{Finite Fields and Bit Lengths}{19}{figure.caption.17}\protected@file@percent } | ||
| \@writefile{lot}{\contentsline {xsect}{Finite Fields and Bit Lengths}{19}{figure.caption.17}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {section}{\numberline {6}Finite Fields and Bit Lengths}{19}{section.6}\protected@file@percent } | ||
| \newlabel{sec:finiteFieldsAndBitLengths}{{6}{19}{Finite Fields and Bit Lengths}{section.6}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {14}{\ignorespaces $y^2 = x^3 + 3$ over the real numbers.\relax }}{19}{figure.caption.18}\protected@file@percent } | ||
| \newlabel{pic:ftShield}{{14}{19}{$y^2 = x^3 + 3$ over the real numbers.\relax }{figure.caption.18}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {15}{\ignorespaces $y^2 = x^3 + 3$ over $\mathbb {F}_7$ shown as green dots.\relax }}{20}{figure.caption.19}\protected@file@percent } | ||
| \newlabel{pic:ftShield}{{15}{20}{$y^2 = x^3 + 3$ over $\mathbb {F}_7$ shown as green dots.\relax }{figure.caption.19}{}} | ||
| \@setckpt{application/finiteFieldsAndBitLengths}{ | ||
| \setcounter{page}{22} | ||
| \setcounter{equation}{0} | ||
| \setcounter{enumi}{15} | ||
| \setcounter{enumii}{0} | ||
| \setcounter{enumiii}{0} | ||
| \setcounter{enumiv}{0} | ||
| \setcounter{footnote}{0} | ||
| \setcounter{mpfootnote}{0} | ||
| \setcounter{part}{2} | ||
| \setcounter{section}{6} | ||
| \setcounter{subsection}{0} | ||
| \setcounter{subsubsection}{0} | ||
| \setcounter{paragraph}{0} | ||
| \setcounter{subparagraph}{0} | ||
| \setcounter{figure}{15} | ||
| \setcounter{table}{2} | ||
| \setcounter{ptc}{2} | ||
| \setcounter{parttocdepth}{2} | ||
| \setcounter{stc}{6} | ||
| \setcounter{secttocdepth}{3} | ||
| \setcounter{parentequation}{0} | ||
| \setcounter{Item}{18} | ||
| \setcounter{Hfootnote}{0} | ||
| \setcounter{bookmark@seq@number}{8} | ||
| \setcounter{nlinenum}{0} | ||
| \setcounter{ongoingEnumCounter}{0} | ||
| \setcounter{mdf@globalstyle@cnt}{0} | ||
| \setcounter{mdfcountframes}{0} | ||
| \setcounter{mdf@env@i}{0} | ||
| \setcounter{mdf@env@ii}{0} | ||
| \setcounter{mdf@zref@counter}{0} | ||
| \setcounter{caption@flags}{0} | ||
| \setcounter{ContinuedFloat}{0} | ||
| \setcounter{float@type}{8} | ||
| \setcounter{lstnumber}{17} | ||
| \setcounter{definition}{0} | ||
| \setcounter{theorem}{0} | ||
| \setcounter{section@level}{1} | ||
| \setcounter{lstlisting}{0} | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| \section{Finite Fields and Bit Lengths} | ||
| \label{sec:finiteFieldsAndBitLengths} | ||
|
|
||
| \noindent | ||
| For those who go through the Nightfall code, you mght realise there are many number conversions being made in the zkp microservice. In particular, there are frequently conversions and restrictions to $216$-bit ($27$-byte) values in much of today's Nightfall code. These conversions are a consequence of working with zk-SNARKs.\\ | ||
| \\ | ||
| Like many cryptographic protocols, zk-SNARKs make use of representing numbers as points on an elliptic curve. In doing so, the results of our computations become quite difficult to `unravel' -- that is, given an output, it becomes computationally infeasible for someone to determine the inputs. However, it also restricts the mathematics we can do. This is a gross oversimplification of why elliptic curves are used, but let's talk about them.\\ | ||
| \\ | ||
| Currently on Ethereum, there is only one elliptic curve for which it is `cheap' (in terms of gas costs) to perform calculations (due to there being precompile contracts supporting calculations on this curve): | ||
| \begin{align*} | ||
| E := y^2 = x^3 + 3 | ||
| \end{align*} | ||
|
|
||
| This curve looks like this: | ||
| \begin{figure}[H] | ||
| \begin{center} | ||
| \includegraphics[width=0.8\textwidth]{images/ellipticCurveReals.png} | ||
| \end{center} | ||
| \caption{$y^2 = x^3 + 3$ over the real numbers.} | ||
| \label{pic:ftShield} | ||
| \end{figure} | ||
|
|
||
| As an example, let's restrict the $x$ and $y$ coordinates to be the field of integers modulo $7$. I.e. we only allow the numbers $\mathbb{F}_7 = {0, 1, 2, 3, 4, 5, 6}$. In this world, $5 + 5 = 10 = 3\;(mod\;7)$.\\ | ||
| \\ | ||
| Let's consider the possible $y$-values of our elliptic curve $E$ when restricted to $\mathbb{F}_7$ (note: we write $E[\mathbb{F}_7]$ for 'the elliptic curve defined over the finite field $\mathbb{F}_7$). | ||
|
|
||
| \begin{tabular}{|c|c|c|c|c|c|c|c|} | ||
| \hline | ||
| $y$ & $0$ & $1$ & $2$ & $3$ & $4$ & $5$ & $6$ \\ | ||
| \hline | ||
| $y^2$ & $0$ & $1$ & $4$ & $9=2$ & $16=2$ & $25=4$ & $36=1$ \\ | ||
| \hline | ||
| \end{tabular} | ||
|
|
||
| Now let's consider the $x$-values of $E[\mathbb{F}_7]$: | ||
|
|
||
| \begin{tabular}{|c|c|c|c|c|c|c|c|} | ||
| \hline | ||
| $x$ & $0$ & $1$ & $2$ & $3$ & $4$ & $5$ & $6$ \\ | ||
| \hline | ||
| $x^3$ & $0$ & $1$ & $8=1$ & $27=6$ & $64=1$ & $125=6$ & $216=6$ \\ | ||
| \hline | ||
| $x^3+3$ & $3$ & $4$ & $4$ & $9=2$ & $4$ & $9=2$ & $9=2$ \\ | ||
| \hline | ||
| $= y^2$ & - & $4$ & $4$ & $2$ & $4$ & $2$ & $2$ \\ | ||
| \hline | ||
| Valid $y$-values & | ||
| -- & | ||
| \makecell{$2$\\$5$} & | ||
| \makecell{$2$\\$5$} & | ||
| \makecell{$3$\\$4$} & | ||
| \makecell{$2$\\$5$} & | ||
| \makecell{$3$\\$4$} & | ||
| \makecell{$3$\\$4$} \\ | ||
| \hline | ||
| \end{tabular} | ||
|
|
||
| So we have a set of valid points of $\infty, (1,2), (1,5), (2,2), (2,5), (3,3), (3,4), (4,2), (4,5), (5,3), (5,4), (6,3), (6,4)$.\\ | ||
| \\ | ||
| These $13$ points are the only points which exist on $E[\mathbb{F}_7]$. $E[\mathbb{F}_7]$ is a `group' of order $13$.\\ | ||
| In other words: the curve $E: y^2 = x^3 + 3$ --- when restricted to the $7$ values of $\mathbb{F}_7$ --- produces a group $E[\mathbb{F}_7]$ of order $13$.\\ | ||
| \\ | ||
| We superimpose the points of $E[\mathbb{F}_7]$ (in green) below: | ||
| \begin{figure}[H] | ||
| \begin{center} | ||
| \includegraphics[width=0.8\textwidth]{images/ellipticCurveF7.png} | ||
| \end{center} | ||
| \caption{$y^2 = x^3 + 3$ over $\mathbb{F}_7$ shown as green dots.} | ||
| \label{pic:ftShield} | ||
| \end{figure} | ||
|
|
||
| An important thing to take away from this example, is that there are 3 distinct things for us to be aware of: an elliptic curve equation $E$, a finite field $\mathbb{F}$, and the resulting group $G = E[\mathbb{F}]$. Sometimes the number of elements in the group $G$ is \textit{more than} the number of elements in the field $\mathbb{F}$ (as in the above example), and sometimes the number of elements in the group $G$ is \textit{less than} the number of elements in the field $\mathbb{F}$ (as we will see is the case with Ethereum).\\ | ||
| \\ | ||
| In practice, the finite field $\mathbb{F}_p$ used in Ethereum is of size | ||
| \begin{align*} | ||
| p = 21888242871839275222246405745257275088696311157297823662689037894645226208583 | ||
| \end{align*} | ||
|
|
||
| The elliptic curve $E: y^2 = x^3 + 3$, when restricted to the $p$ values of $\mathbb{F}_p$, produces a group $G_1 = E[\mathbb{F}_p]$ of prime order | ||
| \begin{align*} | ||
| q = 21888242871839275222246405745257275088548364400416034343698204186575808495617 | ||
| \end{align*} | ||
|
|
||
| I.e. $G_1 = E[\mathbb{F}_p]$ is a group with $q$ distinct points. Here, $q < p$; the size of the group $G_1$ is less than the size of the field $\mathbb{F_p}$.\\ | ||
| \\ | ||
| This has an important consequence when working within ZoKrates. To generate zk-SNARKs, ZoKrates will convert the numbers we pass as inputs to our off-chain calculation (as well as all intermediate numbers of the calculation) into elliptic curve points. To tie-in with Ethereum, ZoKrates converts all of the numbers used in its calculations into elements of the group $G_1$. Therefore, we need to make sure that \textbf{all} of the inputs we pass into ZoKrates are \textbf{less than} the size of the group $G_1$, $q = 21888242871839275222246405745257275088548364400416034343698204186575808495617$.\\ | ||
| \\ | ||
| This value of $q$ is slightly less than $254$-bits. I.e. $2^{253} < q < 2^{254}$.\\ | ||
| \\ | ||
| Hence, to be sure we don't `overflow' modulo-$q$, it's safest to only pass numbers to ZoKrates which are $\leq 253$-bits. When working with Ethereum, we often work with hex numbers (because Solidity `likes' hex numbers), which means it's often nice for the bit-length we work with to be divisible by $8$. Since $248$ is the largest number below $253$ which is divisible by $8$, this would have been a nice choice for all of the numbers Nightfall passes to ZoKrates.\\ | ||
| \\ | ||
| However, you might notice we instead restrict all our numbers to $216$-bits. The reason for this is the maximum size of a message in the NIST specification of the sha256 hashing algorithm. The largest message size for `one round' of sha256 hashing is $447$-bits. The version of ZoKrates used in Nightfall currently only supports `one round' of sha256 hashing. Hence our inputs to each hashing iteration must be $447$-bits or less.\\ | ||
| \\ | ||
| You'll see in the protocols below, that we frequently need to concatenate two values and then hash them. Hence we need each of the two values to be at most $223$-bits to fit inside `one round' of sha256 hashing. Given that we also prefer bit-lengths which are divisible by $8$, $216$-bits becomes the best choice for our purposes.\\ | ||
| \\ | ||
| \textbf{And that's why you'll see conversions and restrictions to 216-bit (27-byte) values in much of today's Nightfall code.}\\ | ||
| \\ | ||
| In cases where we need to use a number with a greater bit-length than $216$ (for security purposes), we deconstruct that number into an array of $216$-bit values. E.g. a $512$-bit number might be deconstructed into an array [$80$-bits, $216$-bits, $216$-bits]. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| \relax | ||
| \providecommand\hyper@newdestlabel[2]{} | ||
| \providecommand\zref@newlabel[2]{} | ||
| \@writefile{lof}{\contentsline {xsect}{Microservices}{15}{subsection.4.5}\protected@file@percent } | ||
| \@writefile{lot}{\contentsline {xsect}{Microservices}{15}{subsection.4.5}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {section}{\numberline {5}Microservices}{15}{section.5}\protected@file@percent } | ||
| \newlabel{sec:microservices}{{5}{15}{Microservices}{section.5}{}} | ||
| \@writefile{toc}{\contentsline {subsection}{\numberline {5.1}zkp}{15}{subsection.5.1}\protected@file@percent } | ||
| \newlabel{sec:zkp}{{5.1}{15}{zkp}{subsection.5.1}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.1}\texttt {f-token-controller.js}}{15}{subsubsection.5.1.1}\protected@file@percent } | ||
| \newlabel{sec:f-token-controller}{{5.1.1}{15}{\texttt {f-token-controller.js}}{subsubsection.5.1.1}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.2}\texttt {f-token-zkp.js}}{15}{subsubsection.5.1.2}\protected@file@percent } | ||
| \newlabel{sec:f-token-zkp}{{5.1.2}{15}{\texttt {f-token-zkp.js}}{subsubsection.5.1.2}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.3}\texttt {nf-token-controller.js}}{15}{subsubsection.5.1.3}\protected@file@percent } | ||
| \newlabel{sec:nf-token-controller}{{5.1.3}{15}{\texttt {nf-token-controller.js}}{subsubsection.5.1.3}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.4}\texttt {nf-token-zkp.js}}{15}{subsubsection.5.1.4}\protected@file@percent } | ||
| \newlabel{sec:nf-token-zkp}{{5.1.4}{15}{\texttt {nf-token-zkp.js}}{subsubsection.5.1.4}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.5}\texttt {zokrates.js}}{15}{subsubsection.5.1.5}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.6}\texttt {vk-controller.js}}{15}{subsubsection.5.1.6}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.7}\texttt {vkIds.json}}{16}{subsubsection.5.1.7}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.1.8}\texttt {stats.json}}{16}{subsubsection.5.1.8}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsection}{\numberline {5.2}offchain}{16}{subsection.5.2}\protected@file@percent } | ||
| \newlabel{sec:offchain}{{5.2}{16}{offchain}{subsection.5.2}{}} | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.2.1}whisper}{16}{subsubsection.5.2.1}\protected@file@percent } | ||
| \newlabel{sec:whisper}{{5.2.1}{16}{whisper}{subsubsection.5.2.1}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {10}{\ignorespaces Limitation: Nightfall does not currently receive Whisper messages if the User is not logged in.\relax }}{16}{figure.caption.14}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsubsection}{\numberline {5.2.2}pkd}{16}{subsubsection.5.2.2}\protected@file@percent } | ||
| \newlabel{sec:pkd}{{5.2.2}{16}{pkd}{subsubsection.5.2.2}{}} | ||
| \@writefile{toc}{\contentsline {subsection}{\numberline {5.3}accounts}{17}{subsection.5.3}\protected@file@percent } | ||
| \newlabel{sec:accounts}{{5.3}{17}{accounts}{subsection.5.3}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {11}{\ignorespaces Privacy warning: A future update is required to Nightfall to allow user's to reliably and consistently transact with the Shield contract anonymously.\relax }}{17}{figure.caption.15}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsection}{\numberline {5.4}database}{17}{subsection.5.4}\protected@file@percent } | ||
| \newlabel{sec:database}{{5.4}{17}{database}{subsection.5.4}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {12}{\ignorespaces Security warning: Secret keys are currently stored in the User's db.\relax }}{17}{figure.caption.16}\protected@file@percent } | ||
| \@writefile{toc}{\contentsline {subsection}{\numberline {5.5}ui}{17}{subsection.5.5}\protected@file@percent } | ||
| \newlabel{sec:ui}{{5.5}{17}{ui}{subsection.5.5}{}} | ||
| \@writefile{lof}{\contentsline {figure}{\numberline {13}{\ignorespaces Security warning: Ensure you're comfortable with any random number generation in the application\relax }}{18}{figure.caption.17}\protected@file@percent } | ||
| \@setckpt{application/microservices}{ | ||
| \setcounter{page}{19} | ||
| \setcounter{equation}{0} | ||
| \setcounter{enumi}{15} | ||
| \setcounter{enumii}{0} | ||
| \setcounter{enumiii}{0} | ||
| \setcounter{enumiv}{0} | ||
| \setcounter{footnote}{0} | ||
| \setcounter{mpfootnote}{0} | ||
| \setcounter{part}{2} | ||
| \setcounter{section}{5} | ||
| \setcounter{subsection}{5} | ||
| \setcounter{subsubsection}{0} | ||
| \setcounter{paragraph}{0} | ||
| \setcounter{subparagraph}{0} | ||
| \setcounter{figure}{13} | ||
| \setcounter{table}{2} | ||
| \setcounter{ptc}{2} | ||
| \setcounter{parttocdepth}{2} | ||
| \setcounter{stc}{5} | ||
| \setcounter{secttocdepth}{3} | ||
| \setcounter{parentequation}{0} | ||
| \setcounter{Item}{18} | ||
| \setcounter{Hfootnote}{0} | ||
| \setcounter{bookmark@seq@number}{7} | ||
| \setcounter{nlinenum}{0} | ||
| \setcounter{ongoingEnumCounter}{0} | ||
| \setcounter{mdf@globalstyle@cnt}{0} | ||
| \setcounter{mdfcountframes}{0} | ||
| \setcounter{mdf@env@i}{0} | ||
| \setcounter{mdf@env@ii}{0} | ||
| \setcounter{mdf@zref@counter}{0} | ||
| \setcounter{caption@flags}{0} | ||
| \setcounter{ContinuedFloat}{0} | ||
| \setcounter{float@type}{8} | ||
| \setcounter{lstnumber}{17} | ||
| \setcounter{definition}{0} | ||
| \setcounter{theorem}{0} | ||
| \setcounter{section@level}{2} | ||
| \setcounter{lstlisting}{0} | ||
| } |
Oops, something went wrong.