Skip to main content

Verifying proposals

Advanced
Governance
Tutorial

The decentralized nature of the NNS is one of the key factors of the Internet Computer's security - it ensures that there is no single point of failure. Therefore, it is important that proposals are verified by as many governance participants as possible. Each neuron verifying a proposal can define their own criteria for when a proposal should be adopted or rejected. This provides inputs that can be considered in this process.

The community is encouraged to discuss proposals and their verification on the developer forum, using the category Governance with sub-category NNS proposal discussion and using the proposal’s topic as a tag.

Verify protocol canister management proposals​

If you are looking to verify protocol canister management proposals, you can refer to this video that explains the process on the example of an NNS governance canister upgrade:

Apart from regularly checking open proposals, the following sections list some relevant information for proposals submitted by the DFINITY foundation.

NNS canister upgrades​

  • For updates to the NNS canisters, you can follow the IC repository. More specifically, the following sub-directories are relevant:

    • rs/ledger_suite/common/ledger_canister_core
    • rs/ledger_suite/common/ledger_core
    • rs/ledger_suite/icp/archive
    • rs/ledger_suite/icp/index,
    • rs/ledger_suite/icp/ledger/src
    • rs/nns/cmc
    • rs/nns/governance
    • rs/nns/gtc
    • rs/nns/handlers/lifeline,
    • rs/nns/handlers/root/impl
    • rs/nns/identity
    • rs/nns/nns-ui
    • rs/packages/icrc-ledger_types
    • rs/registry/canister

  • NNS core canister upgrade proposals are announced on the developer forum.

  • You can find the instructions on how to verify that the Wasm in the proposal was indeed build from the provided git commit in the proposal's section "Wasm Verification" (see this example proposal).

ICP ledger suite upgrades​

  • For updates on the ICP ledger suite, you can follow the IC repository. More specifically, the following sub-directories are relevant:
    • rs/ledger_suite/icp/ledger is the directory for the ICP ledger

Verify IC OS version election proposals​

If you are looking to verify IC OS version election proposals, you can refer to this video:

You can also consider the following information for proposals submitted by the DFINITY foundation:

  • Each proposal submitted by the DFINITY foundation has a corresponding post on the forum (see example). Relevant posts can be found under the Governance category with the tags replica and release.
  • The relevant code is available in the IC repository.
  • To verify that the code in the proposal is built from the specified git commit, follow the instructions in the README file of the IC repository.
  • Each proposal summary includes instructions for verifying the proposal payload. See this example. These steps are tested on Ubuntu 22.04, which is the recommended operating system for the verification process.
# From https://github.com/dfinity/ic#verifying-releases
sudo apt-get install -y curl && curl --proto '=https' --tlsv1.2 -sSLO https://raw.githubusercontent.com/dfinity/ic/ec35ebd252d4ffb151d2cfceba3a86c4fb87c6d6/gitlab-ci/tools/repro-check.sh && chmod +x repro-check.sh && ./repro-check.sh -c ec35ebd252d4ffb151d2cfceba3a86c4fb87c6d6
  • The reproducibility check script is versioned, cryptographically checksummed, and open-sourced, ensuring it cannot change post-submission. The proposal summary is immutable after submission. The upgrade image contents are cryptographically checksummed, and the checksum is included in the proposal payload and verified during the upgrade process.
  • For GuestOS, DFINITY aims for a weekly release cycle, resulting in approximately one proposal per week plus additional feature builds.
  • For HostOS, there is no fixed release cycle, but an upgrade is typically proposed every 3-6 months.

Verify participant management proposals​

If you are looking to verify participant management proposals, these are some steps you can consider for verification.

Add or remove node providers​

For proposals that add or remove node providers, you can check that:

  • There is a proper forum introduction by the new node provider.
  • Self-declaration and identity documents have been uploaded on the wiki.
  • Hashes of the self-declaration and identity document match the hashes in the proposal.
  • If this is a new region or community, there is an entry in the public Chamber of Commerce register (if Chamber of Commerce number is provided).

Add or remove data centers​

For proposals that add or remove data centers, you can:

  • Check who submitted the proposal. This is typically only a new node provider.
  • Perform an Internet search to verify whether this is a legitimate data center.

Verify node admin proposals​

If you are looking to verify node admin proposals, these are some steps you can consider for verification.

Update node configuration​

In such a proposal, a node provider sets the number of nodes and the node_type (Gen1, Gen2). You can:

  • Check these against the originally approved node allowance (whether that allowance was approved, and whether it matches the IC target topology using the GitHub tooling

Add node operator​

This proposal sets the allowance for a particular node provider in a specific data center. You can perform the following checks:

  • If it matches the IC target topology using the GitHub tooling. For example, such proposals should be rejected if the target topology has been reached.
  • Whether the node provider-id and data center-id match with the previously submitted add node provider and add data center proposals.

Remove nodes from the network​

This is a proposal to remove (unhealthy) nodes from the network. You can:

  • Check whether the nodes are indeed unassigned and not in a particular subnet.

Verify subnet management proposals​

If you are looking to verify subnet management proposals, these are some steps you can consider for verification.

Node replacement proposals​

You can:

  • Check whether the nodes are replaced because they are dead/unhealthy, or replaced for other good reasons.

Other proposals of this topic​

You can:

  • Check whether the reasoning in the proposal makes sense with regard to which proposals need to be adopted in which order.

Verify service nervous system management proposals​

If you are looking to verify service nervous system management proposals, you can refer to this video that explains the process using an example of an NNS proposal that elects a new SNS governance Wasm:

Apart from regularly checking open proposals, here some relevant information for proposals submitted by the DFINITY foundation.

  • You can find the code for the SNS governance, SNS root, and SNS swap in the SNS repository. The SNS also uses the ICRC ledger suite, which you can find in the ledger suite repository.
  • SNS upgrade proposals are announced in this forum thread.
  • You can find the instructions on how to verify that the Wasm in the proposal was indeed build from the provided git commit in the proposal's section "Wasm Verification" (see this example proposal).

Verify application canister management proposals​

If you are looking to verify application canister management proposals, you can refer to this video that explains the process on the example of an NNS frontend dapp upgrade proposal:

Apart from regularly checking open proposals, the following sections list some relevant information for proposals submitted by the DFINITY foundation.

NNS frontend dapp upgrades​

Ledger upgrades for ckBTC, ckETH, and ckERC20​

  • For updates to the NNS canisters, you can follow the IC repository. More specifically, the following sub-directories are relevant:

    • rs/ledger_suite/icrc1/ledger for the ckBTC, ckETH, and ckERC20 ledgers, where rs/ledger_suite/icrc1/ledger:ledger_canister is the Wasm relevant for the ckBTC ledger and rs/ledger_suite/icrc1/ledger:ledger_canister_u256.wasm the Wasm for the ckETH and ckERC20 ledgers.

  • You can find the instructions on how to verify that the Wasm in the proposal was indeed build from the provided git commit in the proposal.

Ledger suite orchestrator canister upgrades​

The ledger suite orchestrator manages all ledger suites of all ckERC20 tokens. The orchestrator can upgrade managed canisters or add new ckERC20 tokens. See the README for more details.

  • The following sub-directories in the IC repository are relevant:

    • rs/ethereum/ledger-suite-orchestrator

  • You can find the instructions on how to verify that the Wasm in the proposal was indeed built from the provided git commit in the proposal.

Internet Identity upgrades​

  • For updates to the Internet Identity (II) canister, you can find the code in the II repository.
  • Each proposal points to the relevant commit that was used.
  • You can find the instructions on how to verify that the Wasm in the proposal was indeed build from the provided git commit in the proposal itself (see for example the section "Wasm Verification" in this example proposal) and in the GitHub release pages.

Bitcoin canister upgrades​

Please refer to the Bitcoin canister documentation for more information about the Bitcoin canister.

  • You can find the code for the Bitcoin canister in the bitcoin-canister repository.
  • These proposals are not expected to happen frequently, but rather when there are important updates to be applied to the Bitcoin canister. You can expect that a new release will be cut in preparation of an upgrade in the above repository. See this example release.
  • There are 2 Bitcoin canisters, one following the Bitcoin testnet and one following the Bitcoin mainnet network. The proposals will be specific to one of these canisters. Typically, you can expect that the proposal to upgrade the Bitcoin testnet canister happens 1 week before the one to upgrade the Bitcoin mainnet canister.
  • You can find the instructions on how to verify that the Wasm in the proposal was indeed built from the provided git commit in the proposal's section "How can I verify the Wasm hash of this canister?" (see this example proposal).