From 6dd9e86df0b1ec6a91d96bf319debb95b294c196 Mon Sep 17 00:00:00 2001 From: Erhan Tezcan Date: Sat, 8 Apr 2023 00:20:05 +0300 Subject: [PATCH] readmes --- README.md | 56 ++++++++++++++++++++++++-------- circuits/fibonacci.circom | 4 +-- package.json | 3 +- scripts/cli.sh | 6 ++-- scripts/functions/instantiate.sh | 1 - scripts/functions/type.sh | 16 ++++++--- utils/instantiate.ts | 2 +- 7 files changed, 62 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e8fb732..056b01c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,12 @@

+- [x] **Generic Circuit Creation**: Using circuit configs, you can programmatically create the `main` component for a circuit. +- [x] **Template Testing**: You can test every template in a circuit, with minimal code-repetition. +- [x] **Simple CLI**: A very easy to use CLI is provided as a wrapper around SnarkJS commands, and they are all provided as `package.json` scripts! +- [ ] **Multiple Proof-Systems**: Soon, only Groth16 for now! +- [ ] **Type Generation**: Generate input & output types for a given circuit, perhaps in future. + ## Usage Clone the repository or create a new one with this as the template! You need [Circom](https://docs.circom.io/getting-started/installation/) to compile circuits. Other than that, just `yarn` or `npm install` to get started. It will also install [Circomlib](https://github.com/iden3/circomlib/tree/master/circuits) which has many utility circuits. @@ -34,10 +40,10 @@ Write your circuits under the `circuits` folder; the circuit code itself should ```js // circuit name is the key multiplier_3: { - // template to instantiate the main component - template: 'Multiplier', // file to include for the template file: 'multiplier', + // template to instantiate the main component + template: 'Multiplier', // array of public inputs publicInputs: [], // template parameters, order is important @@ -45,10 +51,10 @@ multiplier_3: { } ``` -Use the [CLI](./scripts/cli.sh), or its wrapper scripts in [package.json](./package.json) to do stuff with your circuits. +Use the [CLI](./scripts/cli.sh), or its wrapper scripts in [package.json](./package.json) to do stuff with your circuits. There are also some environment variables that the CLI can make use of, they are written under [.cli.env](./.cli.env) file. ```bash -# Compile the circuit +# Compile the circuit (generates the main component too) yarn compile circuit-name [-d directory-name (default: main)] # Phase-2 Circuit-specific setup @@ -57,12 +63,6 @@ yarn ptau circuit-name -p phase1-ptau-path [-n num-contribs (default: 1)] # Shorthand for `compile` and then `ptau` yarn keygen circuit-name -p phase1-ptau-path [-n num-contribs (default: 1)] -# Generate a proof for a JSON input -yarn prove circuit-name -i input-name - -# Verify a proof for some JSON input -yarn verify circuit-name -i input-name - # Clean circuit artifacts yarn clean circuit-name @@ -73,16 +73,35 @@ yarn test circuit-name yarn test:all ``` -There are some environment variables that the CLI can make use of, they are written under [.cli.env](./.cli.env) file. +If you just want to generate the `main` component but not compile it, you can also call: -### Examples +```bash +yarn instantiate circuit-name [-d directory-name (default: main)] +``` + +### Working with Input Signals + +Some actions such as generating a witness, generating a proof and verifying a proof require JSON inputs to provide the signal values. For that, we specifically create our input files under the `inputs` folder, and under the target circuit name there. For example, an input named `foobar` for some circuit named `circ` would be at `inputs/circ/foobar.json`. + +```bash +# Generate a witness for some input +yarn witness circuit-name -i input-name + +# Generate a proof for some input +yarn prove circuit-name -i input-name + +# Verify a proof for some input (public signals only) +yarn verify circuit-name -i input-name +``` + +### Example Circuits We have several example circuits to help guide you: - **Multiplier**: A circuit to prove that you know the factors of a number. -- **Floating Point Addition**: A circuit to compute the sum of two floating-point numbers, adapted from [Berkeley ZKP MOOC 2023 - Lab 1](https://github.com/rdi-berkeley/zkp-mooc-lab). - **Fibonacci**: A circuit to compute Fibonacci numbers. - **Sudoku**: A circuit to prove that you know the solution to a Sudoku puzzle. +- **Floating-Point Addition**: A circuit to compute the sum of two floating-point numbers, adapted from [Berkeley ZKP MOOC 2023 - Lab 1](https://github.com/rdi-berkeley/zkp-mooc-lab). ## Testing @@ -264,3 +283,14 @@ circomkit │ └── verification_key.json └── ... ``` + +## Styling + +We use [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html) for the TypeScript codes. + +```bash +# check the formatting +yarn format +# lint everything +yarn lint +``` diff --git a/circuits/fibonacci.circom b/circuits/fibonacci.circom index 19adc10..5995e9c 100644 --- a/circuits/fibonacci.circom +++ b/circuits/fibonacci.circom @@ -4,7 +4,7 @@ pragma circom 2.0.0; template Fibonacci(n) { assert(n >= 2); signal input in[2]; - signal output out; + signal output out[3]; signal fib[n+1]; fib[0] <== in[0]; @@ -13,7 +13,7 @@ template Fibonacci(n) { fib[i] <== fib[i-2] + fib[i-1]; } - out <== fib[n]; + out <== [fib[n], fib[n], fib[n]]; } // Fibonacci with custom starting numbers, recursive & inefficient diff --git a/package.json b/package.json index 0225129..843fdcc 100644 --- a/package.json +++ b/package.json @@ -15,9 +15,10 @@ "clean": "./scripts/cli.sh -f clean -c", "ptau": "./scripts/cli.sh -f ptau -c", "keygen": "./scripts/cli.sh -f keygen -c", + "witness": "./scripts/cli.sh -f witness -c", "prove": "./scripts/cli.sh -f prove -c", "verify": "./scripts/cli.sh -f verify -c", - "_help": "./scripts/cli.sh -f help", + "usage": "./scripts/cli.sh -f help", "format": "npx prettier --check ./**/*.ts", "lint": "npx gts lint" }, diff --git a/scripts/cli.sh b/scripts/cli.sh index e475af3..8febd8f 100755 --- a/scripts/cli.sh +++ b/scripts/cli.sh @@ -67,7 +67,7 @@ case $FUNC in clean $CIRCUIT ;; compile) - compile $CIRCUIT $COMPILE_DIR + instantiate $CIRCUIT $COMPILE_DIR && compile $CIRCUIT $COMPILE_DIR ;; instantiate) instantiate $CIRCUIT $COMPILE_DIR @@ -103,8 +103,8 @@ case $FUNC in echo " verify Verify a proof & public signals" echo " keygen Shorthand for compile & ptau" echo " -c " - echo " -d " - echo " -n (default: 1)" + echo " -d (default: $COMPILE_DIR)" + echo " -n (default: $NUM_CONTRIBS)" echo " -i " echo " -p " ;; diff --git a/scripts/functions/instantiate.sh b/scripts/functions/instantiate.sh index f7adf53..53e42c3 100755 --- a/scripts/functions/instantiate.sh +++ b/scripts/functions/instantiate.sh @@ -5,7 +5,6 @@ instantiate() { local DIR=$2 # generate the circuit main component - mkdir -p ./circuits/$DIR npx ts-node ./utils/instantiate.ts $CIRCUIT $DIR echo -e "${CIRCOMKIT_COLOR_LOG}Done!${CIRCOMKIT_COLOR_RESET}" diff --git a/scripts/functions/type.sh b/scripts/functions/type.sh index 01c8b9a..c1d6af1 100755 --- a/scripts/functions/type.sh +++ b/scripts/functions/type.sh @@ -1,18 +1,24 @@ ## Parse the template circuit that you are using for your main component ## and generate TypeScript interfaces for it -## TODO: not sure i need this yet type() { set -e echo -e "\n${CIRCOMKIT_COLOR_TITLE}=== Generating types ===${CIRCOMKIT_COLOR_RESET}" local CIRCUIT=$1 local SYM=./build/$CIRCUIT/$CIRCUIT.sym - local TMP=./scripts/utils.tmp.txt # choose lines with 1 dot only (these are the signals of the main component), extract their names - cat $SYM | awk -F '.' 'NF==2{print $2}' + local MAIN_SIGNALS=$(cat $SYM | awk -F '.' 'NF==2 {print $2}') + + # get the unique signal names + local MAIN_SIGNAL_NAMES=$(echo "$MAIN_SIGNALS" | awk -F '[' '{print $1}' | uniq) + + # get the last signal for each signal name + local SIGNALS="" + for SIGNAL in $MAIN_SIGNAL_NAMES; do + SIGNALS+="$(echo "$MAIN_SIGNALS" | grep $SIGNAL | tail -n 1) " + done + echo "$SIGNALS" echo -e "\n${CIRCOMKIT_COLOR_LOG}Types generated!${CIRCOMKIT_COLOR_RESET}" } - - # cat ./build/multiplier3/multiplier3.sym | awk -F '.' 'NF==2{print $2}' diff --git a/utils/instantiate.ts b/utils/instantiate.ts index 29bbdf5..44387ec 100644 --- a/utils/instantiate.ts +++ b/utils/instantiate.ts @@ -18,7 +18,7 @@ export function instantiate(name: string, directory: string, circuitConfig?: Cir circuitConfig = config[name]; } - // generate the main component code using the tempalte + // generate the main component code using the template const ejsPath = './circuits/ejs/template.circom'; // add "../" to the filename in include, one for each "/" in directory name