Merge pull request #108 from zk-passport/dev

Better README.md
2026-04-27 03:01:15 -04:00 · 2024-05-23 14:14:42 +09:00
parent dd9ca6c0e3 d4b982d3e3
commit 22e5ecc242
8 changed files with 98 additions and 41 deletions
--- a/app/README.md
+++ b/app/README.md
@@ -2,21 +2,32 @@

 ## Requirements

-Install `nodejs v18`, [circom](https://docs.circom.io/) and [snarkjs](https://github.com/iden3/snarkjs)
+| Requirement | Version | Installation Guide |
+|-------------|---------|--------------------|
+| nodejs      | > v18     | [Install nodejs](https://nodejs.org/) |
+| circom      | Latest  | [Install circom](https://docs.circom.io/) |
+| snarkjs     | Latest  | [Install snarkjs](https://github.com/iden3/snarkjs) |

-For Android, install Java, Android Studio and the Android SDK

-For iOS, install Xcode and [cocoapods](https://cocoapods.org/)
+### Android
+| Requirement | Version | Installation Guide |
+|-------------|---------|--------------------|
+| Java        | 11      | [Install Java](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) or [GPT4 guide](https://chatgpt.com/share/26cd879b-26bb-4fd4-b59e-cfe002a06afe) |
+| Android Studio | Latest | [Install Android Studio](https://developer.android.com/studio) |
+| Android SDK | Latest  | [Install Android SDK](https://developer.android.com/studio#downloads) |
+| Android Ndk         | 23.1.7779620 | [Install NDK](https://developer.android.com/studio) or [GPT4 guide](https://chatgpt.com/share/a6e2544b-d32a-4554-a452-402511d03ffc) |
+
+### iOS
+| Requirement | Version | Installation Guide |
+|-------------|---------|--------------------|
+| Xcode       | Latest  | [Install Xcode](https://developer.apple.com/xcode/) |
+| cocoapods   | Latest  | [Install cocoapods](https://cocoapods.org/) |
+

 ## Installation

 ```bash
-yarn
-```
-
-In `/common`, also run:
-```bash
-yarn
+yarn install-app
 ```

 ## Run the app
@@ -25,6 +36,11 @@ First, connect your phone to your computer and allow access.

 ### Android

+Create the file `android/local.properties` with the following content:
+```
+sdk.dir=/Users/<your-user-name>/Library/Android/sdk
+```
+
 Launch the react-native server:
 ```
 yarn start
@@ -36,7 +52,7 @@ To see the Android logs you'll have to use the Android Studio Logcat.

 ### iOS

-To run the app on iOS, you will need an Apple Developer account. Free accounts can't run apps that use NFC reading.
+To run the app on iOS, you will need an `Apple Developer account`. Free accounts can't run apps that use NFC reading.

 Open the ios project on Xcode and add your provisionning profile in Targets > ProofOfPassport > Signing and Capabilities

--- a/app/package.json
+++ b/app/package.json
@@ -7,7 +7,8 @@
    "ios": "react-native run-ios",
    "lint": "eslint .",
    "start": "watchman watch-del-all && react-native start",
-    "test": "jest"
+    "test": "jest",
+    "install-app": "cd ../common && yarn && cd ../app && yarn"
  },
  "dependencies": {
    "@amplitude/analytics-react-native": "^1.4.7",
@@ -74,4 +75,4 @@
  "engines": {
    "node": ">=16"
  }
-}
+}
--- a/circuits/README.md
+++ b/circuits/README.md
@@ -1,31 +1,77 @@
-# Proof of Passport Circuits
+# Proof of Passport Circuits 

-Proof of Passport circuits verify signatures of passport-emitting authorities.
+## Requirements

-🚧 under heavy development 🚧
+| Requirement | Version | Installation Guide |
+|-------------|---------|--------------------|
+| nodejs      | > v18     | [Install nodejs](https://nodejs.org/) |
+| circom      | Latest  | [Install circom](https://docs.circom.io/) |
+| snarkjs     | Latest  | [Install snarkjs](https://github.com/iden3/snarkjs) |

-#### Requirements

-Install `circom` and `nodejs v18`
+## Overview of the circuits

-#### Installation
+Circom circuits are located in the `circuits/` folder.
+The circuits are split into two parts: `register` and `disclose`.
+This design is close to that of [semaphore](https://semaphore.pse.dev/).
+
+The `register` circuit is used for the following:
+1. Verify the signature of the passport
+2. Verify that the public key which signed the passport is part of the registry merkle tree (a check of the merkle roots will be performed on-chain)
+3. Generate commitment = H (secret + passportData + some other data)
+
+Once the proof is generated, the user can register on-chain and their commitment will be added to the Lean merkle tree.
+
+As the hash function and signature algorithm is different upon the issuer country, there will be different `register` circuits for each of those set-ups.
+The `register` will follow the `register_<hash>With<signature>.circom` naming convention.
+One verifier for each register circuit will be deployed on-chain, all of them committing to the same merkle tree.
+
+The `disclose` circuit is used for the following:
+1. Verify that a user knows a secret e.g., he is able to reconstruct one leaf of the merkle tree (a check of the merkle roots will be performed on-chain)
+2. Passport expiry is verified
+3. A range check is performed over the age of the user
+4. The output is multiplied by an input bitmap to allow the user to disclose only what they want to disclose.
+5. Final output is packed.
+
+Any application that wants to use Proof of Passport can actually build its own `disclose` circuit.
+
+### 🚧 Under development 🚧
+Proof of Passport currently supports the following sig/hash algorithms:
+
+
+- [x] sha256WithRSAEncryption
+- [ ] sha1WithRSAEncryption (under development)
+- [ ] rsassaPss
+- [ ] ecdsa-with-SHA384
+- [ ] ecdsa-with-SHA1
+- [ ] ecdsa-with-SHA256
+- [ ] ecdsa-with-SHA512
+- [ ] sha512WithRSAEncryption
+
+> 💡  We currently have a bounty program if you implement a sig/hash setup.
+
+
+## Installation

 ```bash
-yarn
+yarn install-circuits
 ```

-#### Build circuits (dev only, not secure)
+
+
+## Build circuits (dev only)

 ```bash
 ./scripts/build_circuit.sh
 ```

-#### Run tests
+## Run tests

 ```bash
 yarn test
 ```
-
 This will run tests with sample data generated on the fly.

+The 
+
 To run tests with your own passport data, extract your `passportData.json` using the app (available soon), place it in `inputs/`, then run `yarn test`
--- a/circuits/package.json
+++ b/circuits/package.json
@@ -4,7 +4,8 @@
  "author": "",
  "license": "MIT",
  "scripts": {
-    "test": "yarn ts-mocha test/**/*.test.ts --exit"
+    "test": "yarn ts-mocha test/**/*.test.ts --exit",
+    "install-circuits": "cd ../common && yarn && cd ../circuits && yarn"
  },
  "dependencies": {
    "@types/chai-as-promised": "^7.1.6",
@@ -36,4 +37,4 @@
    "ts-mocha": "^10.0.0",
    "ts-node": "^10.9.2"
  }
-}
+}
--- a/circuits/test/disclose.test.ts
+++ b/circuits/test/disclose.test.ts
@@ -31,8 +31,6 @@ describe("start testing disclose.circom", function () {
        );

        const secret = BigInt(Math.floor(Math.random() * Math.pow(2, 254))).toString();
-        console.log("secret", secret);
-
        const attestation_name = "E-PASSPORT";
        attestation_id = poseidon1([
            BigInt(Buffer.from(attestation_name).readUIntBE(0, 6))
@@ -60,11 +58,8 @@ describe("start testing disclose.circom", function () {
            mrz_bytes[1],
            mrz_bytes[2]
        ])
-        console.log("commitment", commitment);
-
        tree = new LeanIMT((a, b) => poseidon2([a, b]), []);
        tree.insert(BigInt(commitment));
-        console.log("tree_nodes", tree._nodes);

        inputs = generateCircuitInputsDisclose(
            secret,
@@ -76,8 +71,6 @@ describe("start testing disclose.circom", function () {
            scope,
            user_identifier
        );
-
-        console.log(JSON.stringify(inputs, null, 2));
    });

    it("should compile and load the circuit", async function () {
--- a/circuits/test/is_older_than.test.ts
+++ b/circuits/test/is_older_than.test.ts
@@ -19,7 +19,7 @@ describe('DateIsLessChecker Circuit Test', function () {
     * 
     */

-    const n = 100;
+    const n = 10;
    const majority = 18;

    const yearStart = 2023;
--- a/circuits/test/is_valid.test.ts
+++ b/circuits/test/is_valid.test.ts
@@ -19,7 +19,7 @@ describe('DateIsLessChecker Circuit Test', function () {
     * 
     */

-    const n = 100;
+    const n = 10;

    const yearStart = 2023;
    const yearEnd = 2049;
--- a/circuits/test/register.test.ts
+++ b/circuits/test/register.test.ts
@@ -18,11 +18,13 @@ describe("Proof of Passport - Circuits - Register flow", function () {
    before(async () => {
        circuit = await wasm_tester(
            path.join(__dirname, "../circuits/register_sha256WithRSAEncryption_65537.circom"),
-            { include: [
-                "node_modules",
-                "./node_modules/@zk-kit/binary-merkle-root.circom/src",
-                "./node_modules/circomlib/circuits"
-            ] },
+            {
+                include: [
+                    "node_modules",
+                    "./node_modules/@zk-kit/binary-merkle-root.circom/src",
+                    "./node_modules/circomlib/circuits"
+                ]
+            },
        );

        const secret = BigInt(Math.floor(Math.random() * Math.pow(2, 254))).toString();
@@ -39,8 +41,6 @@ describe("Proof of Passport - Circuits - Register flow", function () {
            passportData,
            { developmentMode: true }
        );
-
-        console.log(JSON.stringify(inputs, null, 2));
    });

    it("should compile and load the circuit", async function () {
@@ -52,7 +52,7 @@ describe("Proof of Passport - Circuits - Register flow", function () {
        await circuit.checkConstraints(w);

        console.log("nullifier", (await circuit.getOutput(w, ["nullifier"])).nullifier);
-        
+
        const commitment_circom = (await circuit.getOutput(w, ["commitment"])).commitment;

        const mrz_bytes = packBytes(inputs.mrz);