full proof workflow description and scripts

.gitignore

@@ -1,4 +1,5 @@
 .DS_store
 *.o
 *.hi
-build
+build
+ceremony/

README.md

@@ -11,8 +11,10 @@ Repo organization
 - `README.md` - this document
 - `circuit/` - the proof circuit (`circom` code)
 - `reference/haskell/` - Haskell reference implementation of the proof input generation
-- `reference/nim/` - Nim reference implementation of the proof input generation
+- `reference/nim/proof_input/` - Nim reference implementation of the proof input generation
+- `reference/nim/testvectors/` - Nim script to generate test vectors for Poseidon2 sponge hash
 - `test/` - tests for (some parts of the) circuit (using the `r1cs-solver` tool)
+- `workflow/` - description and script for the full proof workflow
 
 
 Setup

workflow/.gitignore

@@ -0,0 +1 @@
+build/

workflow/README.md

@@ -0,0 +1,115 @@
+
+Guide though the whole proof workflow
+-------------------------------------
+
+The workflow described below is implemented with shell scripts in this directory.
+So the below is more like an explanation.
+
+The run the full workflow:
+
+- set the parameters by editing `params.sh`
+- run `setup.sh` to do the circuit-specific setup
+- run `prove.sh` to generate input, compute witness and create (and verify) the proof
+
+NOTE: the examples below assume `bash`. In particular, it won't work with `zsh` 
+(which is the dafault on newer macOS)! Because, you know, reasons...
+
+### Preliminaries
+
+- install `circom`, `snarkjs`, `rapidsnark`: <https://docs.circom.io/getting-started/installation>
+- install Nim: <https://nim-lang.org/>
+
+Build the Nim cli proof input generator:
+
+    $ cd ../reference/nim/proof_input/
+    $ nimble build -d:release cli
+    $ cd ../../../workflow
+
+### Powers of tau setup
+
+Either download a ready-to-use "powers of tau" setup file (section 7), or generate one
+youself using `snarkjs` (sections 1..7), see the README here: <https://github.com/iden3/snarkjs>
+
+Size `2^21` (file size about 2GB) should be big enough:
+
+    $ cd ..
+    $ mkdir -p ceremony
+    $ cd ceremony
+    $ wget https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_21.ptau
+    $ cd ../workflow
+
+Note: generating this yourself will probably take quite a long time.
+
+### Set the parameters
+
+There are quite a few parameters (run `cli --help` too see them), it's probably
+best to collect them into a parameter file. Check out `params.sh` and `cli_args.sh` 
+to see one way to do that.
+
+You can edit `params.sh` to your taste before running the workflow scripts.
+
+### Compile the circuit
+
+First create the main component:
+
+    $ mkdir -p build
+    $ cd build
+    $ source ./cli_args.sh && ../../reference/nim/proof_input/cli $CLI_ARGS -v --circom="proof_main.circom"
+
+Then compile the circuit:
+
+    $ circom --r1cs --O2 -l../../circuit proof_main.circom
+
+### Do the circuit-specific setup
+
+See the [`snarkjs` README](https://github.com/iden3/snarkjs) for an overview of
+the whole process.
+
+    $ snarkjs groth16 setup proof_main.r1cs ../../ceremony/powersOfTau28_hez_final_21.ptau proof_main_0000.zkey
+    $ snarkjs zkey contribute proof_main_0000.zkey proof_main_0001.zkey --name="1st Contributor Name"
+
+You can add more contributors here if you want.
+
+Finally rename the last contributions result and export the verification key:
+
+    $ rm proof_main_0000.zkey
+    $ mv proof_main_0001.zkey proof_main.zkey
+    
+    $ snarkjs zkey export verificationkey proof_main.zkey proof_main_verification_key.json
+
+NOTE: You have redo all the above if you change any of the five parameters the circuit 
+depends on (these are: maxdepth, maxslots, cellsize, blocksize, nsamples).
+
+### Generate an input to the circuit
+
+    $ source ../cli_args.sh && ../../reference/nim/proof_input/cli $CLI_ARGS -v --output=input.json
+
+### Generate the witness
+
+    $ cd proof_main_js
+    $ time node generate_witness.js proof_main.wasm ../input.json ../witness.wtns
+    $ cd ..
+
+### Create the proof
+
+Using `snarkjs` (very slow, but more portable):
+
+    $ snarkjs groth16 prove proof_main.zkey witness.wtns proof.json public.json
+
+Or using `rapidsnark` (fast, but not very portable):
+
+    $ rapidsnark proof_main.zkey witness.wtns proof.json public.json
+
+The output of this step will consist of:
+
+- `proof.json` containing the proof itself
+- `public.json` containing the public inputs
+
+### Verify the proof (on CPU)
+
+    $ snarkjs groth16 verify proof_main_verification_key.json public.json proof.json
+
+### Generate solidity verifier contract
+
+    $ snarkjs zkey export solidityverifier proof_main.zkey verifier.sol
+

workflow/cli_args.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+MY_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+source ${MY_DIR}/params.sh
+
+CLI_ARGS="--depth=$MAXDEPTH \
+ --maxslots=$MAXSLOTS \
+ --cellsize=$CELLSIZE \
+ --blocksize=$BLOCKSIZE \
+ --nsamples=$NSAMPLES \
+ --entropy=$ENTROPY \
+ --seed=$SEED \
+ --nslots=$NSLOTS \
+ --ncells=$NCELLS \
+ --index=$SLOTINDEX"
+
+if [[ "$1" =~ "--export" ]]
+then
+  echo "exporting CLI_ARGS"
+  export CLI_ARGS
+fi

workflow/params.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+MAXDEPTH=16        # maximum depth of the slot tree 
+MAXSLOTS=256       # maximum number of slots  
+CELLSIZE=2048      # cell size in bytes 
+BLOCKSIZE=65536    # block size in bytes 
+NSAMPLES=5         # number of samples to prove
+
+ENTROPY=1234567    # external randomness
+SEED=12345         # seed for creating fake data
+
+NSLOTS=11          # number of slots in the dataset
+SLOTINDEX=3        # which slot we prove (0..NSLOTS-1)
+NCELLS=512         # number of cells in a slot
+

workflow/paths.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+ORIG=`pwd`
+
+NIMCLI_DIR="${ORIG}/../reference/nim/proof_input/"
+CIRCUIT_DIR="${ORIG}/../circuit/"
+PTAU_DIR="${ORIG}/../ceremony"
+
+PTAU_FILE="powersOfTau28_hez_final_21.ptau"
+PTAU_PATH="${PTAU_DIR}/${PTAU_FILE}"
+
+CIRCUIT_MAIN="proof_main"

workflow/prove.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+source ./paths.sh
+source ./cli_args.sh
+
+# --- setup build directory ---
+
+mkdir -p build 
+cd build
+
+# --- generate input for the circuit ---
+
+echo ""
+echo "generating the input for the proof circuit..."
+${NIMCLI_DIR}/cli $CLI_ARGS -v --output=input.json
+
+# --- generate the witness ---
+
+echo ""
+echo "generating the witness..."
+cd ${CIRCUIT_MAIN}_js
+time node generate_witness.js ${CIRCUIT_MAIN}.wasm ../input.json ../witness.wtns
+cd ${ORIG}/build
+
+# --- create the proof ---
+
+PROVER="snarkjs"
+
+RS=`which rapidsnark`
+if [[ ! -z "$RS" ]]
+then
+  PROVER="rapidsnark"
+fi
+
+echo ""
+echo "creating the proof... using prover: \`$PROVER\`"
+
+case $PROVER in
+  snarkjs)
+    time snarkjs groth16 prove ${CIRCUIT_MAIN}.zkey witness.wtns proof.json public.json
+    ;;
+  rapidsnark)
+    time rapidsnark ${CIRCUIT_MAIN}.zkey witness.wtns proof.json public.json
+    ;;
+  *)
+    echo "unknown prover \`$PROVER\`"
+    exit 99
+    ;;
+esac
+
+# --- verify the proof ---
+
+echo ""
+echo "verifying the proof:"
+snarkjs groth16 verify ${CIRCUIT_MAIN}_verification_key.json public.json proof.json
+
+# --- create solidity verifier contract ---
+
+echo ""
+echo "creating solidity verifier contract:"
+snarkjs zkey export solidityverifier ${CIRCUIT_MAIN}.zkey verifier.sol
+
+# --- finish  ---
+
+cd $ORIG

workflow/setup.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+source ./paths.sh
+source ./cli_args.sh
+
+# --- setup build directory ---
+
+mkdir -p build
+cd build
+
+# --- generate the main component ---
+
+${NIMCLI_DIR}/cli $CLI_ARGS -v --circom=${CIRCUIT_MAIN}.circom
+
+# --- compile the circuit ---
+
+circom --r1cs --wasm --O2 -l${CIRCUIT_DIR} ${CIRCUIT_MAIN}.circom
+
+# --- circuit specific setup ---
+
+snarkjs groth16 setup ${CIRCUIT_MAIN}.r1cs $PTAU_PATH ${CIRCUIT_MAIN}_0000.zkey
+
+echo "some_entropy_75289v3b7rcawcsyiur" | \
+snarkjs zkey contribute ${CIRCUIT_MAIN}_0000.zkey ${CIRCUIT_MAIN}_0001.zkey --name="1st Contributor Name"
+
+rm ${CIRCUIT_MAIN}_0000.zkey
+mv ${CIRCUIT_MAIN}_0001.zkey ${CIRCUIT_MAIN}.zkey
+snarkjs zkey export verificationkey ${CIRCUIT_MAIN}.zkey ${CIRCUIT_MAIN}_verification_key.json
+
+# --- finish the setup ---
+
+cd $ORIG