diff --git a/README-archived.md b/README-archived.md new file mode 100644 index 0000000..fdf819b --- /dev/null +++ b/README-archived.md @@ -0,0 +1,248 @@ +# zkGraph Template + +> **_NOTE:_** THIS REPO HAS BEEN ARCHIEVED AND UPGRADED TO [ora-io/cle](https://github.com/ora-io/cle) . + +## Getting Started + +To create your zkGraph project based on this template: + +Option 1: + +Click `Use this template`, and `Creating a new repository`. + +Option 2: + +Use `gh` cli + +```bash +gh repo create zkgraph-new --public --template="https://github.com/hyperoracle/zkgraph.git" +``` + +### 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 = { + // Update your Etherum JSON RPC provider URL here. + // Recommended provider: ANKR. + JsonRpcProviderUrl: { + mainnet: "https://{URL}", + // ...or other networks. + }, + UserPrivateKey: "0x{PRIVATE_KEY}", + // ...and other configs. +}; +``` + +Then run: + +```bash +npm install +``` + +### Quick Start + +To test the whole flow of the library, run this after you have done the configuration: + +```bash +sh test.sh +``` + +## Commands + +> Note: Only `full` image will be processed by zkOracle node. `local` (generated by commands ending with `-local`) means the zkGraph is compiled locally and only contains partial computation (so that proving and executing will be faster). + +The workflow of local zkGraph development must follow: `Develop` (code in /src) -> `Compile` (get compiled wasm image) -> `Execute` (get expected output) -> `Prove` (generate input and pre-test for actual proving in zkOracle) -> `Deploy` (deploy verification contract) -> `Verify` (verify proof on-chain). + +To upload and publish your zkGraph, you should `Upload` (upload code to IPFS), and then `Publish` (register zkGraph on onchain zkGraph Registry). + +If you encounter any problem, please refer to the [test.sh](./test.sh) for the example usage of the commands. + +### Compile for Local Image + +```bash +npm run compile-local +``` + +### Execute Local Image + +```bash +npm run exec-local -- +``` + +Please save the `ZKGRAPH_STATE_OUTPUT` string for following prove steps. + +### Set Up Local Image + +```bash +npm run setup-local +``` + +- `circuit-size`: Specify the circuit size of image instead of the default recommended. eg. `npm run setup-local -- --circuit-size (eg. 22)`. + +### Prove Local Image (input generation / pre-test / prove) + +```bash +npm run prove-local -- --inputgen +npm run prove-local -- --test +npm run prove-local -- --prove +``` + +### Deploy Verification Contract for Local Image + +```bash +npm run deploy-local +``` + +Please save the `verifer_contract_address` from the output dialog for following publish steps. + +- `network_name`: Specify the network name of deployed verification smart contract, instead of loading `dataDestinations.network` from `zkgraph.yaml`. eg. `npm run deploy-local -- --network-name `. + +### Upload Local zkGraph (Code and Local Image) + +```bash +npm run upload-local +``` + +### Compile for Full Image(Link Compiled with Compiler Server) + +```bash +npm run compile +``` + +### Execute Full Image + +```bash +npm run exec -- +``` + +### Set Up Full Image + +```bash +npm run setup +``` + +- `circuit-size`: Specify the circuit size of image instead of the default recommended. eg. `npm run setup -- --circuit-size +npm run prove -- --pretest +npm run prove -- --prove +``` + +After the prove task is completed, please save the proof task id from the output dialog for following verify step. + +### Deploy Verification Contract for Full Image + +```bash +npm run deploy -- [network_name (sepolia / goerli)] +``` + +Please save the `verifer_contract_address` from the output dialog for following publish steps. + +- `network_name`: load `dataDestinations.network` from `zkgraph.yaml` if not passed from command. + +### Upload zkGraph (Code and Full Image) + +```bash +npm run upload +``` + +Please save the `ipfs_hash` from the output dialog for following publish steps. + +### Verify Proof Onchain + +```bash +npm run verify -- +``` + +### Publish and Register zkGraph Onchain + +```bash +npm run publish -- +``` + +See also: [Verifier Contract Interface](https://github.com/DelphinusLab/halo2aggregator-s/blob/main/sol/contracts/AggregatorVerifier.sol#L40). + +## 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); + 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 + +1. Provable program needs to be compilable and runnable in normal execution runtime first. +2. To running on zkwasm, do not use io syscalls like `console` etc. +3. You may need to use `BigEndian` version functions for Ethereum data structures. +4. For operators of `BigInt` (eg. `+`, `-`, `*`, `/`), use syntax like `a.plus(b)` instead of `a + b` (this still works, but triggers compiler warning). +5. `require` is a cool [Solidity-like](https://docs.soliditylang.org/en/v0.8.20/control-structures.html#error-handling-assert-require-revert-and-exceptions) language feature zkWasm provides, but will trigger warning when using in zkGraph's `mapping.ts`. To ignore the error: when importing, add `// @ts-ignore` after the import line; when using, write something like `require(true ? 1 : 0)` to convert the boolean to number for the ts compiler. + +### Optimization + +1. Look at (approximate) WASM cost for each operation! Complexer logic (eg. anything with lots of `if` or `string`) usally means more instructions, which means longer proof generation time. +2. Don't use template literals (`${}`), for example when throwing errors, because it will be compiled to too many WASM instructions (~1000 diff). +3. Try not to use keywords that may introduce extra global init code e.g. `new`, `static` etc. (`changetype` is fine). + +## Lib Dev Tips + +1. Don't use `I8.parseInt` because it will be compiled to `i32.extend8_s (aka. Unknown opcode 192 (0xC0) in WASM)`. +2. Try not to use template literals (`${}`), for example when throwing errors, because it will be compiled to too many WASM instructions (~1000 diff). +3. Try not to use `FC extensions` opcodes (`parseInt(...)`, `f64`, or `Math`), because it will be compiled to `Unknown opcode 252 (0xFC) in WASM`, and generates too many instructions. + +References: [WebAssembly Opcodes](https://pengowray.github.io/wasm-ops/). + +## Structure + +This repo has the following folders relevant to zkGraph development: + +- `api`: APIs (the scripts in `package.json`) for compile, execute, prove, and deploy zkGraph for testing locally, and fully with zkWASM node. +- `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) +- The Graph AssemblyScript API Specification: [graphprotocol/graph-tooling](https://github.com/graphprotocol/graph-tooling) +- Polywrap BigInt Implementation: [polywrap/as-bigint](https://github.com/polywrap/as-bigint) +- Near Base58 Implementation: [near/as-base58](https://github.com/near/as-base58)