Merge pull request #42 from hyperoracle/dev

Fix merging result of dev and suning

.github/workflows/main.yml

@@ -4,12 +4,20 @@ name: Prettier Action
 # https://github.com/marketplace/actions/prettier-action
 on:
   pull_request:
+    branches:
+      - master
+      - main
   push:
     branches:
       - master
+      - main
 
 jobs:
   prettier:
+    # https://github.com/ad-m/github-push-action/issues/96
+    # Allow write permission for github-actions
+    permissions:
+      contents: write
     runs-on: ubuntu-latest
 
     steps:
@@ -18,8 +26,19 @@ jobs:
         with:
           # Make sure the actual branch is checked out when running on pull requests
           ref: ${{ github.head_ref }}
+          # https://stackoverflow.com/questions/72375995/how-to-get-commit-count-of-the-repository-in-github-actions
+          # 0 indicates all history for all branches and tags.
+          fetch-depth: 0
+
+      - name: Get commit count
+        id: commit-count
+        run: |
+          echo "COMMIT_COUNT=$(git rev-list --count HEAD)" >> $GITHUB_ENV
+          echo "Commit count: ${{ env.COMMIT_COUNT }}"
 
       - name: Prettify code
+        # Step only run if the repo is not created by "using this template" (commit count is 1)
+        if: ${{ env.COMMIT_COUNT != '1' }}
         uses: creyD/prettier_action@v4.3
         with:
           # This part is also where you can pass other options, for example:

.gitignore

@@ -107,4 +107,6 @@ build
 *.wasm
 *.wat
 
-.DS_Store
+.DS_Store
+
+config.js

README.md

@@ -1,23 +1,41 @@
-# zkGraph SDK and Library
+# zkGraph Template
 
-## Develop zkGraph
+## Getting Started
 
-### Getting Started
+To create your zkGraph project based on this template, click `Use this template`, and `Creating a new repository`.
 
-First, fork this repo, and clone your forked repo. Then, run:
+### Configuration
+
+After clone your project, you need to create `config.js` file at root folder based on `config-example.js`
+
+```js
+// ./config.js
+export const config = {
+  // Etherum JSON RPC provider URL:
+  // (Please note the provider must support debug_getRawReceipts RPC method.)
+  JsonRpcProviderUrl: "https://{URL}",
+};
+```
+
+Then run:
 
 ```bash
-git update-index --skip-worktree constants.js
 npm install
 ```
 
-To test the whole flow of the library locally, update `constants.js` file with your data, then run:
+### Quick Start
+
+To test the whole flow of the library, run this after you have done the configuration:
 
 ```bash
 sh test.sh
 ```
 
-## Usage Example
+## Commands
+
+The workflow of local zkGraph development is: `Develop` (code in /src) -> `Compile` (to get compiled wasm image) -> `Execute` (to get expected output) -> `Prove` (to generate input and pre-test for actual proving) -> `Deploy`.
+
+If you encounter any problem, please refer to the [test.sh](./test.sh) for the example usage of the commands.
 
 ### Compile Locally
 
@@ -38,6 +56,45 @@ npm run prove-local -- --inputgen {block_id} {expected_state}
 npm run prove-local -- --pretest {block_id} {expected_state}
 ```
 
+## Develop
+
+### `config.js`
+
+The configuration (such as blockchain json rpc provider url) for the local development API.
+
+### `src/zkgraph.yaml`
+
+The configuration for the zkGraph.
+
+It specifies information including:
+
+- data source
+- target blockchain network
+- target smart contract address
+- target event
+- event handler
+
+### `src/mapping.ts`
+
+The logic of the event handler in AssemblyScript.
+
+It specifies how to handle the event data and generate the output state.
+
+```typescript
+export function handleEvents(events: Event[]): Bytes {
+  let state = new Bytes(0);
+  if (events.length > 0) {
+    state = events[0].address;
+  }
+  require(state.length == 20 ? 1 : 0);
+  return state;
+}
+```
+
+## Resources
+
+More info and API reference can be found in [Hyper Oracle zkGraph docs](https://docs.hyperoracle.io/zkgraph-standards/zkgraph).
+
 ## zkGraph Dev Tips
 
 ### Development
@@ -62,6 +119,15 @@ npm run prove-local -- --pretest {block_id} {expected_state}
 
 References: [WebAssembly Opcodes](https://pengowray.github.io/wasm-ops/).
 
+## Structure
+
+This repo has the following folders relevant to zkGraph development:
+
+- `bundle-js`: APIs (the scripts in `package.json`) for compile, execute, prove, and deploy zkGraph for testing locally.
+- `example`: Example zkGraphs.
+- `lib`: AssemblyScript library for zkGraph development, with data structure such as Bytes, ByteArray and BigInt.
+- `src`: Where your actual zkGraph should be in. Contains `mapping.ts` and `zkgraph.yaml`.
+
 ## Thanks
 
 - zkWasm Project: [DelphinusLab/zkWasm](https://github.com/DelphinusLab/zkWasm)

bundle-js/api-local/compile.js

@@ -5,26 +5,46 @@ import { logDivider } from "../common/utils.js";
 // Log script name
 console.log(">> COMPILE", "\n");
 
+let isCompilationSuccess = true;
+
 const commands = [
   "npx asc lib/main_local.ts -t build/zkgraph_local.wat -O --noAssert -o build/zkgraph_local.wasm --disable bulk-memory --use abort=lib/common/type/abort --target release --bindings esm --runtime stub",
 ];
 
 const combinedCommand = commands.join(" && ");
-execSync(combinedCommand, { encoding: "utf-8" });
+try {
+  execSync(combinedCommand, { encoding: "utf-8" });
+} catch (error) {
+  // Handle or log the error here if required
+  isCompilationSuccess = false;
+}
+
+if (isCompilationSuccess) {
+  // Log compiled file size by line count
+  const compiledFileContent = readFileSync("build/zkgraph_local.wat", "utf-8");
+  const compiledFileLineCount = compiledFileContent.split("\n").length;
+  console.log(
+    "[*]",
+    compiledFileLineCount,
+    compiledFileLineCount > 1
+      ? "lines in build/zkgraph_local.wat"
+      : "line in build/zkgraph_local.wat",
+  );
+
+  // Log status
+  console.log("[+] COMPILATION SUCCESS!", "\n");
+
+  logDivider();
+
+  process.exit(0);
+} else {
+  // Extra new line for error
+  console.log();
+
+  // Log status
+  console.log("[-] ERROR WITH COMPILING.", "\n");
+
+  logDivider();
 
-function getLineCount(filePath) {
-  const content = readFileSync(filePath, "utf-8");
-  const lines = content.split("\n");
-  return lines.length;
+  process.exit(1);
 }
-const compiledFileLineCount = getLineCount("build/zkgraph_local.wat");
-console.log(
-  "[*]",
-  compiledFileLineCount,
-  compiledFileLineCount > 1
-    ? "lines in build/zkgraph_local.wat"
-    : "lines in build/zkgraph_local.wat",
-);
-console.log("[+] COMPILATION COMPLETE!", "\n");
-
-logDivider();

bundle-js/api-local/exec.js

@@ -8,7 +8,7 @@ import {
 } from "../common/api_helper.js";
 import { loadConfig } from "../common/config.js";
 import { program } from "commander";
-import { constants } from "../../constants.js";
+import { config } from "../../config.js";
 // usage: node exec.js -b <blocknum/blockhash>
 // TODO: update handler func name by yaml config
 
@@ -31,7 +31,7 @@ const [source_address, source_esigs] = loadConfig("src/zkgraph.yaml");
 console.log("[*] Source contract address:", source_address);
 console.log("[*] Source events signatures:", source_esigs, "\n");
 
-const provider = new providers.JsonRpcProvider(constants.JsonRpcProviderUrl);
+const provider = new providers.JsonRpcProvider(config.JsonRpcProviderUrl);
 
 // Fetch raw receipts
 const rawreceiptList = await getRawReceipts(provider, blockid);
@@ -79,3 +79,5 @@ const state = asmain(rawReceipts, matchedEventOffsets);
 console.log("[+] ZKGRAPH STATE OUTPUT:", toHexString(state), "\n");
 
 logDivider();
+
+process.exit(0);

bundle-js/api-local/prove.js

@@ -17,7 +17,7 @@ import {
 } from "../common/utils.js";
 import { zkmain, setupZKWasmMock } from "../common/bundle_local.js";
 import { ZKWASMMock } from "../common/zkwasm_mock.js";
-import { constants } from "../../constants.js";
+import { config } from "../../config.js";
 
 program.version("1.0.0");
 
@@ -32,6 +32,21 @@ program.parse(process.argv);
 const args = program.args;
 const options = program.opts();
 
+// Log mode name first
+switch (options.inputgen || options.pretest) {
+  // Input generation mode
+  case options.inputgen:
+    // Log script name
+    console.log(">> PROVE: INPUT GENERATION MODE", "\n");
+    break;
+
+  // Pretest mode
+  case options.pretest:
+    // Log script name
+    console.log(">> PROVE: PRETEST MODE", "\n");
+    break;
+}
+
 // Read block id
 const blockid = args[0].length >= 64 ? args[0] : parseInt(args[0]); //17633573
 let expectedStateStr = args[1];
@@ -40,7 +55,7 @@ expectedStateStr = trimPrefix(expectedStateStr, "0x");
 // Load config
 const [source_address, source_esigs] = loadConfig("src/zkgraph.yaml");
 
-const provider = new providers.JsonRpcProvider(constants.JsonRpcProviderUrl);
+const provider = new providers.JsonRpcProvider(config.JsonRpcProviderUrl);
 
 // Fetch raw receipts
 let rawreceiptList = await getRawReceipts(provider, blockid);
@@ -89,20 +104,17 @@ const privateInputStr = formatVarLenInput([
 
 const publicInputStr = formatVarLenInput([expectedStateStr]);
 
+// Log content based on mode
 switch (options.inputgen || options.pretest) {
   // Input generation mode
   case options.inputgen:
-    // Log script name
-    console.log(">> PROVE: INPUT GENERATION MODE", "\n");
     console.log("[+] ZKGRAPH STATE OUTPUT:", expectedStateStr, "\n");
     console.log("[+] PRIVATE INPUT FOR ZKWASM:", "\n" + privateInputStr, "\n");
     console.log("[+] PUBLIC INPUT FOR ZKWASM:", "\n" + publicInputStr, "\n");
     break;
 
   // Pretest mode
   case options.pretest:
-    // Log script name
-    console.log(">> PROVE: PRETEST MODE", "\n");
     const mock = new ZKWASMMock();
     mock.set_private_input(privateInputStr);
     mock.set_public_input(publicInputStr);

bundle-js/common/api_helper.js

@@ -40,8 +40,6 @@ export function rlpDecodeAndEventFilter(rawreceiptList, srcAddr, srcEsigs) {
 }
 
 export function genStreamAndMatchedEventOffsets(rawreceiptList, eventList) {
-  console.log("test ", rawreceiptList);
-  console.log("test ", eventList);
   let matched_offset_list = [];
   let accumulateReceiptLength = 0;
   let rawreceipts = "";

config-example.js

@@ -0,0 +1,5 @@
+export const config = {
+  // Update your Etherum JSON RPC provider URL here.
+  // Please note that the provider must support debug_getRawReceipts RPC method.
+  JsonRpcProviderUrl: "https://{URL}",
+};