Worker Node is an lightweight offchain processing unit with an ability to execute business logic in a form of NodeRed flow file.
Worker Node executing logic can actively contribute in meaningful way to range of use cases. Examples can be found here: Worker Node Usage Use Cases.
Worker Nodes functionalities and EWX blockchain connection enables transparency and verification capabilities for your system. Additionaly, thanks to its lightweight architecture, worker nodes are perfectly suitable and a good fit for applications that require decetralized execution components.
Worker Node, apart from its initial set-up, is entirely controlled by Blockchain based actions. That means once your initial Worker set-up is completed no more changes would need to be applied afterwards.
Blockchain based action controlling Worker Node behaviour could be applied via Marketplace App -> which is EW built Blockchain Operator UI or directly interacting with blockchain.
For full documentation please visit Worker Node Server Official Documnetation.
Below you can find a High Level Architecture to understand how worker node fit into larger EWX ecosystem. 
If you would like to run Worker Node in fully managed (SaaS) or in Bring your own cloud (BYOC) mode, please refer to our Launchpad Worker Node offering. Worker Node Managed Offering Documentation can be found here: Worker Node Managed Offer
If you would like to proceed with self-deployment option, use instructions described below.
As blockchain-based operations and setting up Worker Node server are independent you can eaither proceed with blockchain-based preparation now, or after you are finished with Worker Node set-up.
If you would like to proceed with Blockchain-setup now go to Blockchain Account Set Up Documentation and follow the insturctions.
Worker Node gets solutions Worklogic NodeRed flow files from IPFS (Inter Planetary File System). Hence, if solutions you intend to run are stored in IPFS, you need to configure proper credentials.
By default it's configured to ipfs.io so there is no configuration required but if you experience any issues with that you can switch to different IPFS Gateway.
In order to make it work you need to modify IPFS_URL environment variable with one of the gateways.
It's possible to use it with Infura IPFS, in order to do that provide IPFS_API_KEY and IPFS_SECRET_KEY. Change IPFS_URL to https://ipfs.infura.io:5001 and set IPFS_CONTEXT_PATH to /api/v0/cat?arg=.
If you intend to ONLY run Solutions that have their WorkLogic stored locally, you can configure any dummy values for IPFS.
The Docker image is available at the following link: ewx-worker-node-server.
Run the following command to pull the image:
docker pull ghcr.io/energywebfoundation/ewx-worker-node-server/ewx-worker-node-server:latestYou can read more about the environment variables here.
-
Run the following command to copy the default environment file:
cp .env.default .env
-
Replace
<SEED>under theVOTING_WORKER_SEEDkey with your Worker Account Seed. Keep in mind that your Worker Account have to be different thatn Operator Account. If you havent done it already, to generate Worker Node account you can use any of the wallets mentioned in official Polkadot Docs -
Replace
<infura_ipfs_APIKEY>&<infura_ipfs_APISECRET>with your infura API key and secret -
Optionally, you can change
PRETTY_PRINTtotrueorfalsedepending on your use case.
You can run the worker node with Kubernetes, Docker Compose, or natively.
docker run --env-file .env --rm ghcr.io/energywebfoundation/ewx-worker-node-server/ewx-worker-node-server:latestdocker compose up> Make sure SEED, ipfs_APIKEY & ipfs_APISECRET are also replaced in ./helm-chart/values.yaml
helm install ewx-workers-node-service -f helm-chart/values.yaml oci://ghcr.io/energywebfoundation/generic-microservice-helm -n ewxCall GET http://localhost:3002/status
| Status | Description |
|---|---|
| STARTED | The application has started bootstrapping. |
| EXPOSED_HTTP | The HTTP server has been exposed. |
| INITIALIZED_WORKER_ACCOUNT | The worker account has been initialized. |
| PERFORMED_CHECKS | Required checks have been performed. |
| STARTED_RED_SERVER | The NodeRed server has started. |
| READY | The application is fully ready. |
Your Worker Set-up is Completed! From that moment most of the following, neccesary operations will need to be conducted with usage of your Operator Account against EWX. If you havent went through Blockchain set-up earlier (as a part of step 0), you can proceed to prepare Blockchain-based set-up now in order for your Worker to start running desired logic.
Please proceed to Operator Account Set Up Documentation and go through set-up instructions.
- When you subscribe to any Solution Group using your Operator Account linked to Worker Account configured for your Worker, there is a max-24-hours period before any votes from your Worker will be accepted by EWX.
- After that time, your worker will start executing Solutions WorkLogic from Solutions that are in Active state in non-expired Solution Groups that your Operator Account is subscribed to.
- You should be able to view votes being submitted from your Worker
- In Worker Node logs
- In Marketplace App UI after checking details of Solution Groups you subscribed to
- By querring EWX chainstate as shown in Picture (Use Operator Address here)
- By Querring EWX indexer as shown in Screenshot (Use Worker Address here)
Keep in mind, that depending on solution WorkLogic that yor Worker is running - frequency, quantity of votes and way of interaction with EWX might significantly vary.
The best way to check whether your Worker is failing, is to monitor logs for errors & Worker Node status
To build the Docker image locally, run the following command:
docker build --tag ewx-worker-node-server:latest .-
Run the following command to build the project:
npm run build
-
Run the project using Node.js:
node dist/main.js
-
While nothing prevents assignment of public endpoint to the Worker Node, recommended and advised use always assumes that it is securely placed in private network and use NodeRed flows with either scheduled or pull based triggers.
-
Each worker node should have an unique Worker Account seed and always run in single replica mode. Multiple replica set-up could cause problems if used with certain applications. To ensure reliability by scallability, always configure unique Worker Account seeds for each Worker Node instance.
-
Always treat worker seed as a secret value.
A: Yes, follow these steps to manually create an operator account:
- Visit PolkadotJS.
- Select MAINNET EWX, depending on your use case.
- Go to PolkadotJS Extrinsics.
- As the operator, call the extrinsic
workerNodePallet.signupWorkerNodeOperator. - As the operator, call the extrinsic
workerNodePallet.registerWorker, passing the address of your worker. - Finally, as the operator, call the extrinsic
workerNodePallet.subscribeOperatorToSolutionGroup. To obtain the group, go toDeveloper->Chain state->workerNodePallet->solutionsGroups.
A: For now, single Operator to Worker account assignment is supported. You can always disconnect previourly connected Worker Account and replace it with different one.
A: Yes, you can switch and move to new Worker any moment. If you dont want to tamper with blockchain-setup you just need to use the same Worker Account Seed in your new Worker. Keep in mind that old Worker Node instance should be stopped right after new one is set up.
For Full version of FAQ, please check our Official Docs
- 01.12.2023 Audit Report - cure53 (Not Available Yet)
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this project better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Here’s how you can contribute:
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: Add some AmazingFeature') following Conventional Commits - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for details.
Project Link: ewx-worker-node-server