Work Generation

Every block published to the network, whether a send, receive or representative change block, requires a small, valid Proof-of-Work to be completed above a minimum difficulty floor (threshold).

This work value is not used in consensus, but instead is one of the first pieces of data used to validate blocks on the network and is a key component of maintaining consistent quality of service on the network.

System considerations¶

The following configuration options should be taken into careful consideration when planning work generation resources for services integrating with CGA. These options should be combined to provide the best separation of resources between node participation on network vs. work generation needs.

Representatives should avoid heavy RPC use and work generation

Supporting the network by running a representative is recommended for many services, however it is not recommended that voting nodes are used for heavy RPC or work generation activities. Wherever possible, integrations should utilize separate machines for their integration nodes and consensus-producing, voting nodes.

CPU vs. GPU¶

As GPUs provide faster and more energy efficient work generation than CPUs, and reduce RPC delays during heavy usage periods, they are preferred for any setups able to utilize them. In cases where the node is running on the same machine where work generation is done, GPUs are highly recommended to avoid performance impacts to the node that relying CPU cores can cause.

Choosing a machine¶

Using a separate machine to manage work generation is recommended where possible. The machine running the node should have a minimum of dedicated resources to keep in sync with the network and any potential interruption due to work generation activities should be avoided. Note that this separation introduces latency, so efforts should be done to keep that to a minimum including running machines in the same region or cluster, avoiding routing work requests through external edge networks, etc.

Software for work generation¶

Although the node can be configured to generate work directly, there are plans to separate work generation from the node into its own application and process. To help prepare for this future architecturs the preferred setup today is to use the CGA Work Server for work generation.

Number of work peers¶

To provide a more robust and redundant work generation setup, multiple work peers can be used. Any node configured with multiple peers will make requests serially from the list of work peers until a successful response is received.

Disable local CPU work generation

Since using the same CPU resources the node relies on for work generation can cause performance issues, local CPU work generation should be turned off by setting node.work_threads = 0 when using work peers.

Recommended configurations¶

Below are common, recommended configurations for planning work generation needs. Based on the considerations outlined above, the following general rules apply when planning resources:

GPU-based work generation is recommended wherever reasonable
Running the CGA Work Server is preferred, regardless of machine or CPU/GPU decisions
CPU-based work generation on the same machine the node is running is not recommended

Heavy RPC, regular work generation¶

Services with heavy RPC calls and work generation can benefit from ensuring dedicated resources exist for each process separately. To maximize performance a separate machine running the CGA Work Server with a GPU attached is recommended:

Setup a machine separate from the node with GPU attached
Install the CGA Work Server
Setup a service to start and monitor the work server process using the GPU option --gpu <PLATFORM:DEVICE> and run cga-work-server --help for additional options and details
Configure the machine running the node to allow traffic over TCP from the work generation machine's IP address
Add the work machine IP address as a work peer in the node's config-node.toml file

CPU for lower generation levels

For services with heavier RPC usage but less work generation needs excluding the GPU in the above example and relying on the CPU resources of the separate machine is also an option. This can be done by setting node.work_threads to the appropriate thread count for your needs.

Make sure to benchmark the machine performance to plan for any potential spikes, as CPU generation is slower.

Light RPC, regular work generation¶

Services where RPC usage is lighter but regular work generation is needed could move work generation to the same machine if a GPU is used:

Install the CGA Work Server on the same machine as the node
Setup a service to start and monitor the work server process with options for using the GPU - --gpu <PLATFORM:DEVICE:THREADS> is required, run cga-work-server --help for additional options and details
Configure the node to prevent local CPU work generation by setting node.work_threads = 0

Node work generation option

A less preferred alternative to setting up, running and monitoring the CGA Work Server is to use the node itself to generate work. This should only be done with an attached GPU by setting up and enabling OpenCL with opencl.enable = true and adusting opencl.device and opencl.platform to match your setup.

Practical guides¶

Work generated using the node, incl. work peers¶

graph TD A{Block signing location?} A -->|in the node| B[<a href='/commands/rpc-protocol/#block_create'>RPC block_create</a> no &quotwork&quot] A -->|not in the node| C_1(Create and sign block) B -->block((block)) C_1 -->|block| C_2[<a href='/commands/rpc-protocol/#work_generate'>RPC work_generate</a> &quotblock&quot: block] C_2 -->|work| C_3(Use work in block) C_3 -->block block -->D[<a href='/commands/rpc-protocol/#process'>RPC process</a> &quotwatch_work&quot: &quottrue&quot]

Work generated without using the node¶

Lower thresholds for receive blocks

Receive blocks benefit from a lower work threshold. In the following guide, replace uses of network_minimum and network_current with network_receive_minimum and network_receive_current, respectively, to benefit from the lower threshold.

graph TD M{Access to a node?} -->|yes| N[active_difficulty <a href='/commands/rpc-protocol/#active_difficulty'>RPC</a> or <a href='/integration-guides/websockets/#active-difficulty'>WS</a>] M --> |no| O_1(<a href='/protocol-design/networking/#node-telemetry'>Telemetry</a>) N -->P_1(Generate work at network_minimum difficulty) O_1 -->O_2((active difficulty)) P_1 -->|work| P_2(Use work in block) P_2 -->P_3((block)) P_3 -->P_4[<a href='/commands/rpc-protocol/#process'>RPC process</a> &quotwatch_work&quot: &quotfalse&quot] P_4 -->P_5(<a href='/integration-guides/block-confirmation-tracking/'>Track block confirmation</a>) P_5 -->P_6{Block unconfirmed after 5 seconds?} P_6 -->P_7[active_difficulty <a href='/commands/rpc-protocol/#active_difficulty'>RPC</a> or <a href='/integration-guides/websockets/#active-difficulty'>WS</a>] P_7 -->P_8{Block difficulty less than network_current ?} P_8 -->|yes| P_9(Generate work at network_current difficulty) P_8 -->|no| P_6 P_9 -->|updated_work| P_10(Use updated_work in block) P_10 -->P_4

Node Configuration¶

The following configuration options can be changed in config.json. For more information on the location of this file, and general information on the configuration of the node, see the Configuration page.

opencl_enable¶

When GPU acceleration is enabled, the CPU is also used by default

Make sure to set node.work_threads to 0 when using the GPU

To enable GPU acceleration for work generation, set this option to true. Other fields may need to be changed if you have multiple OpenCL-enabled platforms and devices.

node.work_threads¶

Recommended value: node.work_threads = 0

Determines the number of local CPU threads to used for work generation. While enabled by default, it is recommended to turn off local CPU work generation.

Set to 0 to turn off local CPU work generation.

node.work_peers¶

Used when offloading work generation to another node or service. Format must be ipv6, preceded by ::ffff: if ipv4. Calls are made to the address:port designated using the standard RPC format work_generate. Example:

[node]
work_peers = [
    "::ffff:010.010.1.25:7000",
    "::ffff:192.168.1.25:7077"
]