Skip to content

Latest commit

 

History

History
178 lines (118 loc) · 5.85 KB

OPERATOR_GUIDE.md

File metadata and controls

178 lines (118 loc) · 5.85 KB
Raw

IoTeX W3bstream (Node Operator Guide)

W3bstream is a permissionless, decentralized protocol within the IoTeX Network, where node operators contribute computing power to support verifiable computations for blockchain applications. These applications rely on insights from real-world data to trigger their token economies. Anyone can become a W3bstream Node Operator in the IoTeX Network, choosing which dApps to support in processing data and generating ZK (Zero Knowledge) Proofs. This guide covers how to operate a W3bstream node, register it in the IoTeX Network, join specific projects, and claim rewards.

Run a W3bstream Node

The recommended method to run a W3bstream node is using official Docker images from IoTeX.

Prerequisites

  • Docker Engine (version 18.02 or higher):

    Check your Docker version:

      docker version

    Installation instructions → https://docs.docker.com/engine/install/

  • Docker Compose Plugin

    Verify Docker Compose installation:

      docker compose version
  # Install with → sudo apt install docker-compose-plugin

  • Blockchain Wallet: A funded wallet on the target blockchain is required for your W3bstream node to dispatch proofs to blockchain contracts. For IoTeX Testnet, see create a wallet, and claim test IOTX

  • Bonsai API Key: If you are joining a project requiring RISC0 snark proofs, as the W3bstream protocol currently utilizes the Bonsai API, obtain an API key here.

Download Docker Images

Fetch the latest stable docker-compose.yaml:

curl https://raw.githubusercontent.com/machinefi/sprout/release/docker-compose.yaml > docker-compose.yaml

Pull the required images:

docker compose pull

Configure your blockchain account

To enable your node to send proofs to the destination blockchain, set up a funded account on the target chain:

export PRIVATE_KEY=${your private key}

Optional: Provide your BONSAI API Key

For projects using RISC0 Provers, supply your Bonsai API Key:

export BONSAI_KEY=${your bonsai key}

Refer to the W3bstream project documentation for the dApp you are joining to determine if Risc Zero proofs are required.

Set the projects folder

The default path for the Docker volume, where dApp Projects are downloaded, is ./test/project. Modify the PROJECT_FILE_DIRECTORY in docker-compose.yaml to change this path.

When you change this value (or any other value inside `docker-compose.yaml) make sure you restart your node.

Join a W3bstream Project

W3bstream-based dApps are registered in a "W3bstream Project Management Contract" on the IoTeX Blockchain with a unique project ID. Configure this project ID in your node [WIP]. The respective W3bstream Project file will automatically download to the node's Projects Folder if missing or outdated [WIP].

For testing, download project files from GitHub to the default project folder (./test/project).

Manage the node

To start W3bstream, run the following command in the directory containing docker-compose.yaml:

docker compose up -d

Monitor the W3bstream instance status:

docker-compose logs -f enode znode

To shut down the W3bstream instance:

docker-compose down

Interacting with the node

Install ioctl: The command-line interface for interacting with the IoTeX blockchain.

brew tap iotexproject/ioctl-unstable
brew install iotexproject/ioctl-unstable/ioctl-unstable
alias ioctl=`which ioctl-unstable`

set the ioctl's wsEndpoint configuration option to your node endpoint:

ioctl config set wsEndpoint localhost:9000

More on the IoTeX ioctl client →

Test W3bstream projects are located in the default Projects Folder (test/project by default). Each file's name is its unique project ID: 10000, 10001 and 10002, containing a JSON object with the prover's binary code, VM type, and parameters. All three of them compute a range proof using the Risc0, Halo2, and ZkWASM frameworks respectively.

Sending messages to the node

Send a message to a RISC0-based test project (ID 10000):

ioctl ws message send --project-id 10000 --project-version "0.1" --data "{\"private_input\":\"14\", \"public_input\":\"3,34\", \"receipt_type\":\"Snark\"}"

Send a message to the Halo2-based test project (ID 10001):

ioctl ws message send --project-id 10001 --project-version "0.1" --data "{\"private_a\": 3, \"private_b\": 4}"

Send a message to a zkWasm-based test project (ID 10002):

ioctl ws message send --project-id 10002 --project-version "0.1" --data "{\"private_input\": [1, 1] , \"public_input\": [] }"

Query the status of a proof request

After sending a message, you'll receive a message ID as a response from the node, e.g.,

{
 "messageID": "4abbc43a-798f-49e8-bc05-b6baeafec630"
}

you can quesry the history of the proof request with:

ioctl ws message query --message-id "4abbc43a-798f-49e8-bc05-b6baeafec630"

example result:

{
 "messageID": "4abbc43a-798f-49e8-bc05-b6baeafec630",
 "states": [{
   "state": "received",
   "time": "2023-12-06T16:11:03.498785+08:00",
   "comment": ""
  },
  {
   "state": "fetched",
   "time": "2023-12-06T16:11:04.663608+08:00",
   "comment": ""
  },
  {
   "state": "proving",
   "time": "2023-12-06T16:11:04.664008+08:00",
   "comment": ""
  }
 ]
}

When the request is in "proved" state, you can check out the node logs to find out the hash of the blockchain transaction that wrote the proof to the destination chain.