zkjson 0.6.1 → 1.0.2

package/docs/zkdb-rollup.md

@@ -0,0 +1,218 @@
+## zkDB Rollup Tutorial
+
+*zkJSON is still under active development, and neither the circuits nor the contracts have been audited. Please use it for only experimental purposes.*
+
+### Install `zkjson` Package
+
+Make sure you have [Circom](https://docs.circom.io/getting-started/installation/) and [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started#installation) installed globally.
+
+```bash
+git clone https://github.com/weavedb/zkjson.git
+cd zkjson
+yarn
+```
+
+### Generate Powers of Tau
+
+For the `db` circuit,
+
+```bash
+yarn ceremony --power 16
+```
+
+For the `rollup` circuit,
+
+```bash
+yarn ceremony --power 20
+```
+
+*Beware that power 20 takes hours.*
+
+### Compile Circuits
+
+We need to compile 2 circuits.
+
+```bash
+yarn compile --power 16 --circuit db
+yarn compile --power 20 --circuit rollup
+```
+
+### Create Solidity Project with Hardhat
+
+```bash
+cd ..
+mkdir myrollup
+cd myrollup
+npx hardhat init
+yarn add zkjson
+```
+
+### Copy Verifier Contracts
+
+```bash
+cp ../zkjson/circom/build/circuit/db/verifier.sol contracts/verifier_db.sol
+cp ../zkjson/circom/build/circuit/rollup/verifier.sol contracts/verifier_rollup.sol
+```
+
+Rename the contract name to `Groth16VerifierJSON` as we will have multiple verifiers with the same name.
+
+Open `myrollup/contracts/verifier_db.sol` and rename
+
+```solidity
+contract Groth16Verifier {
+```
+
+to
+
+```solidity
+contract Groth16VerifierDB {
+```
+
+Then open `myrollup/contracts/verifier_rollup.sol` and rename
+
+```solidity
+contract Groth16Verifier {
+```
+
+to
+
+```solidity
+contract Groth16VerifierRU {
+```
+
+### Write Solidity Contract
+
+`myrollup/contracts/MyRollup.sol`
+
+```solidity
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity >=0.7.0 <0.9.0;
+import "../node_modules/zkrjson/contracts/ZKRollup.sol";
+
+interface VerifierDB {
+  function verifyProof(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[14] calldata _pubSignals) view external returns (bool);
+}
+
+contract MyRollup is ZKRollup {
+  uint constant SIZE_PATH = 5;
+  uint constant SIZE_VAL = 5;
+  address public verifierDB;
+
+  constructor (address _verifierRU, address _verifierDB, address _committer){
+    verifierRU = _verifierRU;
+    verifierDB = _verifierDB;
+    committer = _committer;
+  }
+  
+  function validateQuery(uint[] memory path, uint[] memory zkp) private view returns(uint[] memory){
+    verify(zkp, VerifierDB.verifyProof.selector, verifierDB);
+    return _validateQueryRU(path, zkp, SIZE_PATH, SIZE_VAL);    
+  }
+
+  function qInt (uint[] memory path, uint[] memory zkp) public view returns (int) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qInt(value);
+  }
+
+  function qFloat (uint[] memory path, uint[] memory zkp) public view returns (uint[3] memory) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qFloat(value);
+  }
+
+  function qRaw (uint[] memory path, uint[] memory zkp) public view returns (uint[] memory) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qRaw(value);
+  }
+  
+  function qString (uint[] memory path, uint[] memory zkp) public view returns (string memory) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qString(value);
+  }
+
+  function qBool (uint[] memory path, uint[] memory zkp) public view returns (bool) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qBool(value);
+  }
+  
+  function qNull (uint[] memory path, uint[] memory zkp) public view returns (bool) {
+    uint[] memory value = validateQuery(path, zkp);
+    return _qNull(value);
+  }
+}
+```
+
+### Write Tests
+
+`myrollup/test/MyRollup.js`
+
+```javascript
+const { loadFixture } = require("@nomicfoundation/hardhat-network-helpers")
+const { toIndex, path, DB } = require("zkjson")
+const { resolve } = require("path")
+const { expect } = require("chai")
+
+async function deploy() {
+  const [committer] = await ethers.getSigners()
+  const VerifierRU = await ethers.getContractFactory("Groth16VerifierRU")
+  const verifierRU = await VerifierRU.deploy()
+  const VerifierDB = await ethers.getContractFactory("Groth16VerifierDB")
+  const verifierDB = await VerifierDB.deploy()
+
+  const MyRU = await ethers.getContractFactory("MyRollup")
+  const myru = await MyRU.deploy( verifierRU.address, verifierDB.address, committer.address )
+  return { myru, committer }
+}
+
+describe("MyRollup", function () {
+  let myru, committer, db, col_id, ru
+  this.timeout(0)
+
+  beforeEach(async () => {
+    const dep = await loadFixture(deploy)
+    myru = dep.myru
+    committer = dep.committer
+  })
+
+  it("should verify rollup transactions", async function () {
+    db = new DB({
+      level: 100,
+      size_path: 5,
+      size_val: 5,
+      size_json: 256,
+      size_txs: 10,
+      level_col: 8,
+      wasmRU: resolve(  __dirname, "../../zkjson/circom/build/circuits/rollup/index_js/index.wasm" ),
+      zkeyRU: resolve(  __dirname, "../../zkjson/circom/build/circuits/rollup/index_0001.zkey" ),
+      wasm: resolve(  __dirname, "../../zkjson/circom/build/circuits/db/index_js/index.wasm" ),
+      zkey: resolve( __dirname, "../../zkjson/circom/build/circuits/db/index_0001.zkey" ),
+    })
+    await db.init()
+    col_id = await db.addCollection()
+    const people = [
+      { name: "Bob", age: 10 },
+      { name: "Alice", age: 20 },
+      { name: "Mike", age: 30 },
+      { name: "Beth", age: 40 },
+    ]
+    let txs = people.map(v => { return [col_id, v.name, v] })
+	
+    // batch commit write queries
+    const zkp = await db.genRollupProof(txs)
+    await myru.commit(zkp)
+
+    // query Bob's age
+    const zkp2 = await db.genProof({ json: people[0], col_id, path: "age", id: "Bob" })
+    expect((await myru.qInt([col_id, toIndex("Bob"), ...path("age")], zkp2)).toNumber()).to.eql(10)
+	
+    // query Beth's name
+    const zkp3 = await db.genProof({ json: people[3], col_id, path: "name", id: "Beth" })
+    expect(await myru.qString([col_id, toIndex("Beth"), ...path("name")], zkp3)).to.eql("Beth")
+  })
+})
+```
+
+Then run the tests.
+
+```bash
+yarn hardhat test test/MyRollup.js
+```

package/docs/zkjson-sdk.md

@@ -0,0 +1,254 @@
+## zkJSON SDK
+
+### Install
+
+```bash
+yarn add zkjson
+```
+
+### Encoder / Decoder
+
+Encode / Decode JSON
+
+```javascript
+const { encode, decode, toSignal, fromSignal } = require("zkjson")
+
+const json = { a : 1 }
+const encoded = encode(json) // [ 1, 1, 97, 2, 1, 0,  1 ]
+const signal = toSignal(encoded) // [ '111129712111011' ]
+const encoded2 = fromSignal(signal) // [ 1, 1, 97, 2, 1, 0, 1 ]
+const decoded = decode(encoded2) // { a : 1 }
+```
+
+Encode / Decode paths
+
+```javascript
+const { toSignal, fromSignal, encodePath, decodePath, path } = require("zkjson")
+
+const _path = "a"
+const encodedPath = encodePath(_path) // [ 1, 1, 97 ]
+const signalPath = toSignal(encodedPath) // [ "1111297" ]
+const encodedPath2 = fromSignal(signalPath) // [ 1, 1, 97 ]
+const decodedPath = decodePath(encodedPath) // "a"
+
+const signalPath2 = path(_path) // [ "1111297" ]
+```
+
+Encode / Decode values
+
+```javascript
+const { toSignal, fromSignal, encodeVal, decodeVal, val } = require("zkjson")
+
+const _val = 1
+const encodedVal = encodeVal(_val) // [ 2, 1, 0, 1 ]
+const signalVal = toSignal(encodedVal) // [ "12111011" ]
+const encodedVal2 = fromSignal(signalVal) // [ 2, 1, 0, 1 ]
+const decodedVal = decodeVal(encodedVal) // 1
+
+const signalVal2 = val(_val) // [ "12111011" ]
+```
+
+Encode / Decode conditional queries
+
+```javascript
+const { toSignal, fromSignal, encodeQuery, decodeQuery, query } = require("zkjson")
+
+const _query = [ "$gt", 1 ]
+const encodedQuery = encodeQuery(_query) // [ 12, 2, 1, 0, 1 ]
+const signalQuery = toSignal(encodedQuery) // [ "21212111011" ]
+const encodedQuery2 = fromSignal(signalQuery) // [ 12, 2, 1, 0, 1 ]
+const decodedQuery = decodeQuery(encodedQuery) // [ "$gt", 1 ]
+
+const signalQuery2 = query(_query) // [ "21212111011" ]
+```
+
+### Document ID <> Index Conversion
+
+```javascript
+ const { toIndex, fromIndexs } = require("zkjson")
+ 
+ const index = toIndex("zkJSON") // 1513609181413
+ const str = fromIndex(index) // "zkJSON"
+```
+
+### Doc
+
+```javascript
+const { loadFixture } = require("@nomicfoundation/hardhat-network-helpers")
+const { path, Doc } = require("../../sdk")
+const { resolve } = require("path")
+const { expect } = require("chai")
+
+async function deploy() {
+  const Verifier = await ethers.getContractFactory("Groth16VerifierJSON")
+  const verifier = await Verifier.deploy()
+  const MyApp = await ethers.getContractFactory("SimpleJSON")
+  const myapp = await MyApp.deploy(verifier.address)
+  return { myapp }
+}
+
+describe("MyApp", function () {
+  let myapp
+  this.timeout(0)
+
+  beforeEach(async () => {
+    const dep = await loadFixture(deploy)
+    myapp = dep.myapp
+  })
+
+  it("should verify JSON", async function () {
+    const doc = new Doc({
+      wasm: resolve(
+        __dirname,
+        "../../circom/build/circuits/json/index_js/index.wasm"
+      ),
+      zkey: resolve(
+        __dirname,
+        "../../circom/build/circuits/json/index_0001.zkey"
+      ),
+    })
+    const json = {
+      num: 1,
+      float: 1.23,
+      str: "string",
+      bool: true,
+      null: null,
+      array: [1, 2, 3],
+    }
+
+    // query number
+    const zkp = await doc.genProof({ json, path: "num" })
+    expect((await myapp.qInt(path("num"), zkp)).toNumber()).to.eql(1)
+
+    // query string
+    const zkp2 = await doc.genProof({ json, path: "str" })
+    expect(await myapp.qString(path("str"), zkp2)).to.eql("string")
+
+    // query bool
+    const zkp3 = await doc.genProof({ json, path: "bool" })
+    expect(await myapp.qBool(path("bool"), zkp3)).to.eql(true)
+
+    // query null
+    const zkp4 = await doc.genProof({ json, path: "null" })
+    expect(await myapp.qNull(path("null"), zkp4)).to.eql(true)
+
+    // query float
+    const zkp5 = await doc.genProof({ json, path: "float" })
+    expect(
+      (await myapp.qFloat(path("float"), zkp5)).map(f => f.toNumber())
+    ).to.eql([1, 2, 123])
+
+    // query array and get number
+    const zkp6 = await doc.genProof({ json, path: "array" })
+    expect(
+      (await myapp.qCustom(path("array"), path("[1]"), zkp6)).toNumber()
+    ).to.eql(2)
+	
+    // conditional operator
+    const zkp7 = await doc.genProof({ json, path: "num", query: ["$gt", 0] })
+    expect(await myapp.qCond(path("num"), zkp7.slice(15, 21), zkp7)).to.eql(
+      true
+    )
+
+  })
+})
+```
+
+### DB
+
+```javascript
+const { loadFixture } = require("@nomicfoundation/hardhat-network-helpers")
+const { toIndex, path, DB } = require("../../sdk")
+const { resolve } = require("path")
+const { expect } = require("chai")
+
+async function deploy() {
+  const [committer] = await ethers.getSigners()
+  const VerifierRU = await ethers.getContractFactory("Groth16VerifierRU")
+  const verifierRU = await VerifierRU.deploy()
+  const VerifierDB = await ethers.getContractFactory("Groth16VerifierDB")
+  const verifierDB = await VerifierDB.deploy()
+
+  const MyRU = await ethers.getContractFactory("SimpleRU")
+  const myru = await MyRU.deploy(
+    verifierRU.address,
+    verifierDB.address,
+    committer.address
+  )
+  return { myru, committer }
+}
+
+describe("MyRollup", function () {
+  let myru, committer, db, col_id, ru
+  this.timeout(0)
+
+  beforeEach(async () => {
+    const dep = await loadFixture(deploy)
+    myru = dep.myru
+    committer = dep.committer
+  })
+
+  it("should verify rollup transactions", async function () {
+    db = new DB({
+      level: 100,
+      size_path: 5,
+      size_val: 5,
+      size_json: 256,
+      size_txs: 10,
+      level_col: 8,
+      wasmRU: resolve(
+        __dirname,
+        "../../circom/build/circuits/rollup/index_js/index.wasm"
+      ),
+      zkeyRU: resolve(
+        __dirname,
+        "../../circom/build/circuits/rollup/index_0001.zkey"
+      ),
+      wasm: resolve(
+        __dirname,
+        "../../circom/build/circuits/db/index_js/index.wasm"
+      ),
+      zkey: resolve(
+        __dirname,
+        "../../circom/build/circuits/db/index_0001.zkey"
+      ), 
+    })
+    await db.init()
+    col_id = await db.addCollection()
+    const people = [
+      { name: "Bob", age: 10 },
+      { name: "Alice", age: 20 },
+      { name: "Mike", age: 30 },
+      { name: "Beth", age: 40 },
+    ]
+    let txs = people.map(v => {
+      return [col_id, v.name, v]
+    })
+    const zkp = await db.genRollupProof(txs)
+    await myru.commit(zkp)
+
+    const zkp2 = await db.genProof({
+      json: people[0],
+      col_id,
+      path: "age",
+      id: "Bob",
+    })
+
+    expect(
+      (
+        await myru.qInt([col_id, toIndex("Bob"), ...path("age")], zkp2)
+      ).toNumber()
+    ).to.eql(10)
+
+    const zkp3 = await db.genProof({
+      json: people[3],
+      col_id,
+      path: "name",
+      id: "Beth",
+    })
+    expect(
+      await myru.qString([col_id, toIndex("Beth"), ...path("name")], zkp3)
+    ).to.eql("Beth")
+  })
+})
+```