§ Wiki · Wiki entry

Validation of Candidate Node Machines

How prospective node operators check whether their planned machines actually improve network decentralization, using the community optimization model and the IC target topology.

·May 4, 2026·4 min read

Before a node-operator proposal goes to the NNS, the candidate machines need to be checked against the network's decentralization targets. This entry explains the optimization model, what it produces, and how to use it to size and locate a deployment.

Background

The community adopted an optimization model that balances node rewards against decentralization — calculating the minimum number of additional node machines required to reach the target topology. The target topology covers a 6–12 month horizon and sets goals for Gen-1 and Gen-2 distribution across subnets.

The community-approved target topology lives in proposal 125549, adopted on 12 November 2023. Earlier groundwork sits in proposal 125367.

The tool produces an ObjectiveValue: the number of additional node machines required to reach the decentralization targets. When the ObjectiveValue is zero, no further onboarding is warranted.

Starting points to internalise

  • The IC target topology is community-voted and not permanent. It is updated as growth expectations change.
  • The target topology exists to assess whether adding nodes helps and to identify nodes that are not relevant from a decentralization standpoint.
  • The model does not set node rewards. Rewards are decided separately by NNS proposal.

Step 1 — Install the optimization tool

The tool is open source at github.com/dfinity/decentralization.

Two ways to run it:

  • Command line. Clone the repository, install Python Poetry, and follow the README.
  • Jupyter notebook. Copy the relevant code into notebook cells, omitting the import lines and the main() block.

Read the node-diversification forum posts before running the model so the inputs and outputs are interpretable:

Step 2 — Determine the candidate configuration

Collect:

  • Node provider name.
  • Data center name.
  • Data center provider name.
  • Country (ISO code).
  • Number of intended nodes.

Reference reading:

Step 3 — Run the model

Locate the df_candidate_nodes definition in main.py and update its parameters:

df_candidate_nodes = create_candidate_node_dataframe(
  node_provider='[Name]',
  data_center='[Center]',
  data_center_provider='[Provider]',
  country='[Code]',
  is_sev=True,
  no_nodes=[Number]
)

The evaluation principle is 1:1 reduction: every candidate node machine should reduce the ObjectiveValue by one. If the baseline is 68 and you add six nodes, the new ObjectiveValue should be 62. Lower reductions mean diminishing decentralization benefit, and the proposal is unlikely to be accepted.

Step 4 — Submit the node-operator proposal

If the model confirms a 1:1 (or close to 1:1) improvement, follow the standard onboarding flow described in Node Provider Onboarding:

  1. Node-provider proposal — only if not already accepted.
  2. Data-center proposal — only if the location is new.
  3. Node-operator proposal, with the summary including:
    • the planned node count,
    • provider and data-center details,
    • reproducible evidence from the optimization model,
    • a PDF of the analysis uploaded to the wiki,
    • the document hash,
    • the exact configuration that was run,
    • the ObjectiveValue before and after the candidate nodes are added.

Worked example

A fictional operator "Lionel Messi" plans to add nodes in Buenos Aires through Perron Corporation (country code AR).

Candidate nodesObjectiveValue
068
167
464
662
860
960

Up to eight nodes the reduction is 1:1. The ninth produces no further improvement: subnet constraints have already been satisfied for that country. Eight is the optimal deployment size in this scenario; proposing nine would not be accepted.

FAQ

What's the maximum number of nodes per country?

The approved target topology (proposal 125549) sets per-subnet country limits of 2–3. Across roughly 40 subnets, that implies a theoretical ceiling of 80–120 nodes per country, before diminishing returns set in.

Related