Worker Node Pallet
The Worker Node Pallet provides the core logic for orchestrating a decentralized network of worker nodes, enabling the validation of off-chain computation through on-chain consensus. It manages the registration of solution groups and their associated solutions, coordinates result submissions, and enforces validator consensus and reward distribution on Energy Web X.
Core Functionalities
Worker Node Operator Management
Enables the registration and configuration of worker node operators and their worker nodes and organises them into solution groups.
Enforces the locking of funds required to become a node operator and operational constraints (i.e. an operator can only have one connected worker node at a time).
Solution & Solution Group Management
Enables registrars to create, register and deregister solution groups and their constituent solutions, locking funds in the process to be distributed as worker node rewards.
Allows registrars to configure operational parameters for each solution including consensus majority threshold (
vote_threshold_percent), quorum (quorum_percent), and operator contribution requirements.Voter eligibility determines which workers are eligible to vote on solution results within a solution group. To be eligible to vote a worker must be subscribed to the corresponding solution group. If the registrar enables nominations, the worker must also be nominated.
On-chain Voting & Consensus
The pallet enables the initiation of voting rounds (either via workers or registrars), the tracking, storage and collation of vote submissions (results from off-chain computation) from eligible workers, and voting round expiry.
EWX validators (collators) determine the final result of expired voting rounds through threshold-based consensus mechanism (e.g. >60% of eligible votes are identical), configured per solution.
Validators re-submit the final consensus result on-chain and settle the voting round.
Reward Calculation & Distribution
Voting rounds conclude and settle within discrete time intervals known as reward periods. At the end of each period, validators determine which worker nodes qualify for active rewards based on whether their performance exceeds the configured SLA (service level agreement) threshold (
sla_voting_threshold).Validators track each worker’s contributions (correct votes, total eligible voting rounds, and stake) in VoteMetadata. If a worker node surpasses the SLA threshold for correct vote. percentage during the reward period, validators calculate its reward share, weighted by stake and voting accuracy. In this way, rewards are distributed proportionally to the most accurate and economically committed participants.
Active rewards are distributed in addition to the base rewards allocated to all actively subscribed nodes.
Registering Solution Groups and Solutions
The worker node pallet enables the creation and management of Solutions which are mapped to solution groups. Solutions are business units which require the execution of discrete business logics or off-chain computational tasks. Each solution group acts as a collective for managing operator participation, reward distribution and operational parameters.
Registrars define key configurations for each group including:
Namespace and info
Subscription (base) rewards and SLA-based (active) rewards
Staking requirements for operators
Majority and quorum
Operational windows
Withdrawal delays and eligibility criteria (such as nominations)
Solution Group Registration and Deregistration Rules
The registration of a new solution group is governed by the following rules:
The caller must be a registered solution registrar.
The registrar must provide all required parameters and configurations.
The registrar must have sufficient balance to reserve the funds required from the solution group’s operation and reward budget.
Upon successful registration, the registrar becomes the owner of the solution group.
A Solution Group can be deregistered under the following conditions:
Only the registrar owning the group can initiate the deregistration.
The group must not have any active solutions associated with it.
If the group still has subscribers with unclaimed rewards, it enters a virtual removal state preventing any new operations while still allowing users to claim rewards.
Solution Group Whitelisting
Registrars can enable Solution Group Whitelisting to restrict participation in a group to a curated list of trusted worker node operators. This feature is particularly useful for governance-sensitive applications such as those run by regulated entities or consortiums (e.g. SAFC), where only pre-approved partners are eligible to perform the work.
When creating or updating a solution group, the registrar can enable the has_operator_allow_list flag within the group’s OperatorConfig and set to true. Setting to false allows any operator to subscribe and participate subject to other constraints such as group size, minimum stake or nomination criteria.
Nominations
Registrars can exert granular control over which worker nodes are eligible to participate in voting rounds for a particular solution.
Enabling Nominations: A registrar can enable nominations for a solution. When nominations are enabled, only explicitly nominated worker nodes are eligible to vote.
Nomination Criteria: Registrars may apply custom nomination criteria when selecting eligible workers. For example, they may nominate only nodes within specific geographic regions (e.g., geofencing), or favor nodes with lower environmental impact, leveraging CarbonAware Nominations.
Enforcement: When a voting round is initiated, a snapshot of the nominated worker list is taken. Only nodes within this list can submit valid votes. Any attempt by a non-nominated worker to vote in that round will be rejected by the runtime (unauthorized error).
Management: All nomination settings are managed via extrinsics and enforced through on-chain logic.
Worker Node (Operator) Lifecycle
Operators lock tokens, register worker nodes, subscribe to Solution Groups, perform work by executing off-chain solution logic and submit results (votes) on-chain.
Operators register by:
Locking the requisite tokens
Subscribing to one or more active Solution Groups
Connecting a worker node instance (one per operator account per group)
Participating in voting rounds for the group’s solutions
Operators receive rewards based on their voting accuracy, stake, and adherence to performance requirements set by the registrar. Operators may unsubscribe at any time, subject to the configured withdrawal delay.
Voting Logic
Voting round initiation:
Voting rounds are configured to be started by either worker nodes or registrars
A voting round can only be initiated if it will conclude (determined by its max_waiting_threshold) before the expiration of its encompassing reward period.
Voting eligibility:
To vote within an active voting round, a worker must be subscribed to the corresponding solution group.
If nominations are enabled by the registrar, then only workers within the nominated list are eligible to vote. Nomination means the operator’s account is included in the array of nominated workers at the start of each voting round.
Only one vote per worker per voting round is accepted.
Voting outcome:
A voting round can be in one of four states: Active, when the round is open and pending processing; OffChainVote, when validators are evaluating and agreeing on the result; Settled, when consensus has been reached; and Unresolved, when consensus could not be reached for various reasons.
Consensus Logic
The consensus logic is designed to incentivise high performing nodes, protect against malicious actors while optimising scalability and security. Consensus is only calculated on submitted votes for valid voting rounds, and voting rounds are only considered valid if the minimum vote contribution threshold (quorum) is reached.
Quorum: quorum_percent defines the threshold for the minimum percentage of the current Solution Group subscribers (or nominations) which must submit a vote within a given voting round, for the round to be valid and able to reach consensus.
Majority: vote_threshold_percent defines the minimum percentage of workers within the quorum which must agree on the result for consensus to be declared (i.e. the percentage of the votes submitted which are identical).
Consensus Calculation: Consensus is calculated in the reward period after a voting round has finished, and utilises a snapshot of the subscriber list taken at the start of the voting round. If nominations are enabled, the subscriber list is adjusted to include only nominated workers.
Worked Example:
A solution group has 1000 subscribed workers, of which 800 are nominated.
The quorum threshold is set to 50%, meaning a minimum of 400 workers must submit a vote within the voting round for it to be valid.
The consensus threshold is set to 60%, which means of the 400 votes, 240 must be identical submission for consensus to be declared and the result validated.
Reward System
The reward system is designed to only reward high-performing workers who submit consistent and accurate votes, as stipulated by the service level agreement (SLA).
The SLA threshold (
sla_voting_threshold) is set by the solution group registrar, and stipulates the minimum percentage of correct (consensus-aligned) votes out of the total number of votes a particular worker was eligible to submit during the reward period.Reward share is proportional to the volume of correct votes submitted by a worker during a reward period, and weighted by its stake.
worker_reward = (worker_correct_votes × user_stake) / total_weighted_correct_votes × voting_reward_per_block × active_blocks
Where:
worker_reward: the amount of EWT distributed to the worker node operator as their active reward for participation in eligible voting rounds within the concluded reward period.worker_correct_votes: The number of correct (consensus aligned) votes submitted by the worker node in the eligible voting rounds within the concluded reward period.user_stake: The amount of tokens locked by the operator upon registration.total_weighted_correct_votes: Sum of correct votes weighted by stake across all worker nodes ( Σ(correct_votes_i * stake_i) ).voting_rewards_per_block: Amount of tokens allocated to voting rewards per block (configured by the solution registrar).active_blocks: Number of blocks spanning the reward period.
Worked example:
A Solution Group contains 150 operators. At the end of a reward period, 100 operators submitted sufficient votes to exceed the SLA threshold and are eligible for rewards.
From the eligible 100 operators, the average correct votes during the reward period is 100 and the average user stake is 1000.
Therefore: total_weighted_correct_votes = 100 * 100 * 1000 = 10,000,000
Worker Node A had 110 correct votes with a stake of 1000. There are 7200 active blocks in a voting round, and the votings rewards per block are set to 1 token.
Therefore: worker_node_A_reward = (110 * 1000) / 10000000 * 1 * 7200 = 79 tokens
Withdrawal Delay
The withdrawal delay is the period a user must wait between submitting an unsubscription request and withdrawing their tokens. This mechanism ensures every action (vote) has a consequence, protecting against malicious actors who may otherwise submit false votes and then immediately withdraw their stake to evade penalties. withdrawal delays are measured in reward periods instead of blocks.
In practice, after an operator initializes a withdrawal, they must wait a defined (by the registrar) number of additional reward periods before withdrawing their collateral. During this delay period, the node can still participate in voting rounds and continue to earn rewards, except for the final reward period in which the stake is released and voting eligibility ends. This ensures all pending rounds are properly settled and any rewards or penalties processed before a node can exit the network.
Voting Round Lifecycle
Initiation: A voting round is initiated via extrinsic from registrar or a worker node vote submission
Voting: Eligible worker nodes submit votes (solution results) to the worker node pallet
Expiration: The voting round expires after the configured number of blocks
Consensus: The collators reach agreement on the consensus result and update vote metadata to track correct submission per worker
Reward distribution: At the end of the corresponding reward period, worker performance is benchmarked against the SLA threshold, and rewards are calculated and distributed to qualifying workers
Consensus related Configurable Parameters
Below is a list of configurations which are set by the solution registrar, including the upper and lower bounds.
Solution Group registration Parameters
Subscription_reward_per_block: Tokens per block distributed as rewards to eligible worker node operators
withdrawal_delay: Number of reward periods to wait after withdrawal action
sla_voting_threshold: SLA voting threshold as a percent
Lower bound: 0
Upper bound: 100
Solution Registration Parameters
expiration_block: Block number when the solution expires
max_waiting _threshold: sets the number of blocks in which a voting round can remain active and open to receive votes, before it expires and concludes
Lower bound: 0
Upper bound: <= reward period length
vote_threshold_percent: Threshold for majority consensus ruling [%]
Lower bound: 0
Upper bound: 100
quorum_percent: Threshold for the quorum [%]
Lower bound: 0
Upper bound: 100
voting_start_method: Who can start voting rounds
Bound: Enum (e.g., Registrar, Anyone, etc.)
Last updated