Skip to content

DEVELOPER_GUIDE.md

Latest commit

 

History

History
215 lines (139 loc) · 5.94 KB

DEVELOPER_GUIDE.md

File metadata and controls

215 lines (139 loc) · 5.94 KB
Raw

IoTeX W3bstream Project Developer Guide

W3bstream significantly enhances scalability and trust for dApps where the token economy depends on verifiable processing of real-world data. By providing a decentralized infrastructure to process raw data and generate custom Zero-Knowledge (ZK) Proofs, W3bstream ensures data authenticity and reliability in dApps' token economies.

Integrate W3bstream in your dApp

Dapps looking to utilize W3bstream capabilities should:

  1. Create a W3bstream project
  2. Test the project
  3. Register it on the IoTeX blockchain

Prerequisites

  • ioctl: The command-line interface for interacting with the IoTeX blockchain.
git clone https://github.com/iotexproject/iotex-core.git
cd iotex-core
make ioctl && mv bin/ioctl __YOUR_SYSTEM_PATH__

More on the IoTeX ioctl client →

Create a W3bstream Project

A W3bstream project primarily includes the binary code of the a ZK Prover and the destination contract for dispatching proofs. The steps involve first compiling a zk circuit into a prover using one of the supported ZK frameworks, and then generating a W3bstream project file using ioctl command line client.

Start by cloning the W3bstream repository:

git clone https://github.com/iotexproject/w3bstream.git
cd sprout

Create a W3bstream Project Using Halo2

For more details on creating Halo2 circuits see the Halo2 README.

NOTE: If you want to develop your circuit, please refer halo2 development documentation

Install wasm-pack

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

build the wasm prover with:

cd examples/halo2-circuit/
wasm-pack build --target nodejs --out-dir pkg

The halo2_simple_bg.wasm will be located under the pkg folder.

Generate the W3bstream project file:

# Customize the output project file name "$ID" with a unique number
ioctl ws project config -t "halo2" -i "halo2_wasm_bg.wasm" -c "path/$ID"

Create the blockchain verifier (Solidity)

target/release/halo2-simple-circuit solidity -f path/filename.sol

Create a W3bstream Project Using zkWASM

For more details on zkWASM circuits see the zkWASM README.

NOTE: If you want to develop your circuit, please refer zkwasm project bootstrap

Ensure you have AssemblyScript installed:

npm install -g assemblyscript

Build the circuit:

cd examples/zkwasm-circuit/
asc src/add.ts -O --noAssert -o zkwasm_demo.wasm

Create the verifier

# Work in progress

Generate the W3bstream project:

# Customize the output project file name "$ID" with a unique number
ioctl ws project config -t "zkwasm" -i "zkwasm_demo.wasm" -o "path/ID"

Create a W3bstream Project Using RISC0

More details and options for Risc0 circuit are given in its README.

NOTE: If you want to develop your circuit, please refer more risc0 guest examples

Make sure you have cargo 1.72.0 or higher

cargo version
# Update with: rustup update

Install the rustzero toolchain

cargo install cargo-risczero
cargo risczero install

Build the circuit

cd examples/risc0-circuit/
cargo build --release

The path of methods.rs will be printed to the console, like in the output example below:

warning: methods_path is: "sprout/examples/risc0-circuits/target/release/build/risc0-circuits-5efc4ff59af940ab/out/methods.rs"

Generate the W3bstream Project

ioctl ws project config -t "risc0" -i "methods.rs" -o "path/filename.json" -e "{\"image_id\":\"RANGE_ID\", \"elf\":\"RANGE_ELF\"}"

The values of image_id and elf are variable names, and will be found in the methods.rs file.

Test Your W3bstream Project

Once you have generated a W3bstream project file that includes a custom prover for your dApp, you might want to test it.

Please refer to the OPERATOR GUIDE for instructions on how to:

  1. Run a W3bstream node locally.
  2. Copy the W3bstream project file into the node's project directory (default location is ./test/project).
  3. Run the node and send your test messages.

Registering Your Project

To allow W3bstream node operators to download your project and compute ZK proofs for your dApp, you must register your W3bstream project on the IoTeX blockchain:

Acquire a Project ID

ioctl ioid register "your project name"

Register Project

ioctl ws project register --id "your project id"

Use the Project File Generated above and Update Project Config

ioctl ws project update --id "your project id" --path "path/to/project_file"

Start the Project

ioctl ws project resume --id "your project id"

Retrieve Project Info

ioctl ws project query --id "your project id"

Set Required Prover Amount of the Project

The default prover amount will process the project's tasks is one. And we can customize it by

ioctl ws project attributes set --id "your project id" --key "RequiredProverAmount" --val "your expected amount"

Stop the Project

If you want to stop the project's task process, can use this cmd

ioctl ws project pause --id "your project id"

Bind Your Dapp Contract

If you want to verify zk proof in your Dapp contract, you need to bind the project with the Dapp.

ioctl ws router bind --project-id "your project id" --dapp "your dapp contract address"

If you want to unbind the project with the Dapp.

ioctl ws router unbind --project-id "your project id"