Skip to main content

Proposal format

Intermediate
Governance
Concept

Overview​

Each proposal submitted to the NNS has the following fields:

  • Summary: Text providing a short description of the proposal using a maximum of 280 bytes.

  • URL: The web address of additional content required to evaluate the proposal, specified using HTTPS. For example, the URL's content might describe supporting the assignment of a DCID (data center ID) to a new data center.

  • Proposer: The ID of the neuron that submitted the proposal. When a proposal is submitted, a “charge” is placed on its balance in case it is rejected. The balance needs to be enough to pay the charge on all rejection(s). The NNS requires a neuron to have a dissolve delay of ≥ 6 months to vote, which also applies to submitting proposals.

  • Proposal type: The type of the proposal determines the function that will process the proposal if it is adopted, and the type and structure of the parameters that will be passed to that function. The type also infers what topic a proposal belongs to, which is used for following.

  • Parameters: The parameters that will be passed to the system function and invoked if the proposal is adopted, as determined by its type. When a proposal is submitted, the NNS checks these parameters.

The NNS assigns a unique identity to each proposal that it receives.

Proposal topics and types​

Each proposal has a proposal type, which determines what happens if the proposal is adopted or rejected. This defines which canister method is invoked with which arguments. Each type of proposal belongs to a specific proposal topic. Topics are used for following and also determine some other details about how the proposal is processed. For example, the voting period and the voting reward weight are defined per topic.

We present the proposals grouped by their topics, with the corresponding proposal types that they contain.

Topic: NetworkCanisterManagement​

Installing and upgrading system canisters that belong to the network. This includes the NNS DAO canisters, the ICP ledger canister, and other canisters on the system subnets such as Internet Identity (II), ckBTC, ckETH, ckERC20, and the Wasm version of the SNS canisters (governance, root, ledger, swap).

  • NnsCanisterUpgrade: A proposal to upgrade an existing system canister. This proposal type is executed by the root canister. Beyond upgrading the Wasm module of the target canister, the proposal can also set the authorization information and the allocations.
  • NnsCanisterInstall: A proposal to add a new canister to be installed and executed on the NNS subnet. The root canister, which controls all canisters on the NNS except for itself, handles this proposal type. The call also expects the Wasm module that shall be installed.
  • NnsRootUpgrade: A proposal to upgrade the root canister on the NNS subnet. The proposal is processed by the Lifeline canister, which controls the root canister. The proposal updates the Wasm module.
  • HardResetNnsRootToVersion: Uninstall and install root with the Wasm provided in the function. If InitArgs are provided, they will be passed to the canister_init function of the Wasm provided. This function is meant as a 'break glass' mechanism for when an open call context in the root canister is preventing root or another canisters from upgrading.
  • StopOrStartNnsCanister: Stop or start an NNS canister. Usually this is done as part of a canister upgrade, but this proposal offers the flexibility to just start or stop a canister if needed.

The following proposal types are specific for SNS canisters:

  • AddSnsWasm: Add a new SNS canister Wasm to SNS-W. All SNS DAOs can then upgrade to new versions along the upgrade path defined in SNS-W.
  • InsertSnsWasmUpgradePathEntries: Insert custom upgrade path entries into SNS-W for all SNSes, or for an SNS specified by its governance canister ID.

The following proposal type is specific for the Bitcoin canister:

  • BitcoinSetConfig: A proposal to set the configuration of the underlying Bitcoin Canister that powers the Bitcoin API. The configuration includes whether or not the Bitcoin Canister should sync new blocks from the network, whether the API is enabled, the fees to charge, etc.

How to verify NNS core canister upgrades​

If you are looking to verify NNS core canister upgrades apart from regularly checking open proposals, you might want to consider the following information for proposals submitted by the DFINITY foundation:

  • For updates to the NNS canisters, you can follow this repository. More specifically, the following sub-directories are relevant:
  • rs/rosetta-api/icp_ledger/src
  • rs/rosetta-api/ledger_core
  • rs/rosetta-api/ledger_canister_core
  • rs/packages/icrc-ledger_types
  • rs/registry/canister
  • rs/nns/governance
  • rs/rosetta-api/ledger_canister/ledger,
  • rs/rosetta-api/icp_ledger/archive
  • rs/nns/handlers/root/impl
  • rs/nns/cmc
  • rs/nns/handlers/lifeline,
  • rs/nns/gtc
  • rs/nns/identity
  • rs/nns/nns-ui
  • rs/nns/sns-wasm
  • NNS core canister 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).

How to verify ledger canister upgrades​

If you are looking to verify the ledger suite, which includes the ICP ledger and all ICRC ledgers (used for ckBTC, ckETC, ckERC20) apart from regularly checking open proposals, you might want to consider the following information for proposals submitted by the DFINITY foundation:

More specifically, the following sub-directories are relevant:

  • rs/rosetta-api/icp_ledger is the directory for the ICP ledger
  • rs/rosetta-api/icrc1/ledger for the ckBTC, ckETH, and ckERC20 ledgers, where rs/rosetta-api/icrc1/ledger:ledger_canister is the Wasm relevant for the ckBTC ledger and rs/rosetta-api/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.

How to verify Internet Identity upgrades​

If you are looking to verify Internet Identity (II) canister upgrades apart from regularly checking open proposals, you might want to consider the following information for proposals submitted by the DFINITY foundation:

  • For updates to the 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.

How to verify SNS canister Wasm upgrades​

If you are looking to verify SNS canister Wasm upgrades apart from regularly checking open proposals, you might want to consider the following 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 Rosetta 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).

How to verify Bitcoin canister upgrades

If you are looking to verify Bitcoin canister upgrades apart from regularly checking open proposals, you might want to consider the following information:

  • 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).

For more information about the Bitcoin canister, you can read the Bitcoin canister documentation.

Topic: IcOsVersionElection​

To upgrade the ICP protocol, the NNS DAO first elects new IC OS versions (the software that is run by ICP nodes), then in a second step, selected nodes can be upgraded to the previously elected IC OS versions. This proposal type is for the first part, i.e., to elect new versions.

This topic contains the following proposal types:

  • ReviseElectedGuestosVersions: A proposal to change the set of elected GuestOS versions. The version to elect (identified by the hash of the installation image) is added to the registry. Besides creating a record for that version, the proposal also appends that version to the list of elected versions that can be installed on nodes of a subnet. Only elected GuestOS versions can be deployed.
  • ReviseElectedHostosVersions: A proposal to change the set of currently elected HostOS versions by electing a new version, and/or un-electing some priorly elected versions. HostOS versions are identified by the hash of the installation image. The version to elect is added to the registry, and the versions to un-elect are removed from the registry, ensuring that HostOS cannot upgrade to these versions anymore.

How to verify Ic OS Version Election proposals​

To upgrade the ICP protocol, the NNS DAO first elects new IC OS versions (the software run by ICP nodes), pre-approves the deployment of the new IC-OS versions, and then upgrades selected parts of the IC to these versions. The IcOsVersionElection proposal topic addresses the first part: electing new IC-OS versions.

The topic includes the following proposal types:

  • ReviseElectedGuestosVersions: Proposes changes to the list of elected GuestOS versions. The proposal adds the version to the registry, identified by the Git revision of the installation image, along with the URLs of the upgrade image and the SHA-256 checksum of the image. Only elected GuestOS versions can be deployed.
  • ReviseElectedHostosVersions: Similar to the GuestOS version proposal, this proposes changes to the list of elected HostOS versions.

HostOS is the hypervisor OS running on the IC node machine. Its main responsibilities include initializing and configuring the node machine hardware and passing it through to the GuestOS. The GuestOS, a VM running on the HostOS, contains the critical parts of the IC Protocol code, including the IC Replica, which runs the IC Canisters smart contracts.

How to verify IC operating system version election proposals

To verify IC OS version election proposals, besides regularly checking open proposals, 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 this 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.

Topic: IcOsVersionDeployment​

This proposal is used to upgrade selected nodes to IC OS versions that have previously been approved ("elected") by the NNS DAO under the IcOsVersionElection topic.

This topic includes the following proposal types:

  • DeployHostosToSomeNodes: Deploy a HostOS version to a specified set of nodes, changing the HostOS version used on those nodes.
  • DeployGuestosToAllSubnetNodes: Deploy a GuestOS version to a specified subnet, changing the GuestOS version used on that subnet. The version must be in the list of elected GuestOS versions. The upgrade is complete when the subnet nodes create the next regular CUP, and then all subnet nodes restart and load the CUP with the new code.
  • DeployGuestosToSomeApiBoundaryNodes: Update the GuestOS version on a set of API Boundary Nodes.
  • DeployGuestosToAllUnassignedNodes: Update the GuestOS version on all unassigned nodes.

Topic: Governance​

The are less technical proposals that administer governance. In contrast to other topics, this topic has reward weight 20. This means that participation in this topic is rewarded more.

This topic includes the following proposal types:

  • Motion: Motion proposals are the only proposals that don't have a direct on-chain effect. Rather they can be used as polls that should guide the future strategy of the ICP ecosystem.
  • UninstallCode: Uninstall code of a canister.
  • SetDefaultFollowees: Sets default following. Each newly created NNS neurons will be created with this default choice of followers for the topics.
  • RegisterKnownNeuron: This proposal registers a known neuron, also called 'Named neurons'. This gives a given neuron a name and a short description and ensure that the neuron will be shown on the NNS dapp when people select who to follow for voting decisions.

Topic: SnsAndCommunityFund​

This topic includes proposals that concern SNS DAO launches and the Neurons' Fund (formerly called Community Fund).

In contrast to other topics, this topic has reward weight 20. This means that participation in this topic is rewarded more.

This topic currently only includes one proposal type that is still in use:

  • CreateServiceNervousSystem: This proposal launches a new SNS DAO and specifies all settings, including the initial token distribution, the conditions for the initial decentralization swap, the initial SNS DAO parameters, as well as the Neurons' Fund contribution.

Topic: NetworkEconomics​

This topic includes proposals that administer network economics. This topic contains the following proposal types:

  • ClearProvisionalWhitelist: Clears the provisional whitelist, which allows the listed principals to create canisters with cycles. The mechanism is only needed for bootstrap and testing and must be deactivated afterward.
  • UpdateNodeRewardsTable: Update the node rewards table. This table is the basis for distributing rewards to node providers according to some rules, depending on where they are. You can find more information and the current reward table on this Wiki page.
  • NetworkEconomics: Network economics contains the parameters for several operations related to the economy of the network and settings of the NNS DAO that can be changed by a proposal of this type. A single proposal can update one or several economic parameters. The default values (0) are considered unchanged. Thus, a valid proposal only needs to set the parameters that it wishes to change. Note that this also means that it is not possible to set any of the values to 0. The following parameters can be changed:
  • Reject cost: The amount of ICP the proposer of a rejected proposal will be charged to prevent the spamming of frivolous proposals.
  • Minimum neuron stake: Set the minimum number of ICP required for the creation of a neuron. The same limit must also be respected when increasing the dissolve delay or changing the neuron state from dissolving to aging.
  • Neuron management fee: The cost in ICP per neuron management proposal. Here the NNS is doing work on behalf of a specific neuron, and a small fee will be applied to prevent overuse of this feature (i.e., spam).
  • Minimum ICP/SDR rate: To prevent mistakes, there is a lower bound for the ICP/SDR rate, managed by network economic proposals.
  • Dissolve delay of spawned neurons: The dissolve delay of a neuron spawned from the maturity of an existing neuron.
  • Maximum node provider rewards: The maximum rewards to be distributed to node providers in a single distribution event (proposal).
  • Transaction fee: The transaction fee that must be paid for each ledger transaction.
  • Maximum number of proposals to keep per topic: The maximum number of proposals to keep, per topic. When the total number of proposals for a given topic is greater than this number, the oldest proposals that have reached a “final” state may be deleted to save space.
  • Neurons' Fund economics: This includes all parameters related to the Neurons' Fund:
    • max_theoretical_neurons_fund_participation_amount_xdr: A theoretical limit which should be smaller than any realistic amount of maturity that practically needs to be reserved from the Neurons' Fund for a given SNS swap.
    • neurons_fund_matched_funding_curve_coefficients: Defines a threshold specifying the shape of the matching function used by the Neurons' Fund to determine how much to contribute for a given direct participation amount.
    • minimum_icp_xdr_rate and maximum_icp_xdr_rate are respectively the minimum and maximum value of the ICP/XDR conversion rate used by the Neurons' Fund for converting XDR values into ICP.

Topic: SubnetManagement​

All proposals that administer network subnets.

The following proposal types relate to the creation and composition of subnets:

  • CreateSubnet: Combine a specified set of nodes, typically drawn from data centers and operators in such a way as to guarantee their independence, into a new decentralized subnet. The execution of this external update first initiates a new instance of the distributed key generation protocol. The transcript of that protocol is written to a new subnet record in the registry, together with initial configuration information for the subnet, from where the nodes comprising the subnet pick it up.
  • UpdateConfigOfSubnet: Update a subnet's configuration. This proposal updates the subnet record in the registry, with the changes being picked up by the nodes on the subnet when they reference the respective registry version. Subnet configuration comprises protocol parameters that must be consistent across the subnet (e.g. message sizes).
  • AddNodeToSubnet: Add a new node to a subnet. The node cannot be currently assigned to a subnet. The execution of this proposal changes an existing subnet record to add a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry.
  • RemoveNodesFromSubnet: Remove a node from a subnet. It then becomes available for reassignment. The execution of this proposal changes an existing subnet record to remove a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry.
  • ChangeSubnetMembership: Change the subnet node membership. In a way, this function combines the separate functions for adding and removing nodes from the subnet record, but adds the property of atomic node replacement (node swap) on top. The nodes that are being added to the subnet must be currently unassigned. The nodes that are being removed from the subnet must be currently assigned to the subnet.
  • RecoverSubnet: Update a subnet’s recovery CUP used to recover subnets that have stalled. Nodes that find a recovery CUP for their subnet will load that CUP from the registry and restart the replica from that CUP.

The following proposal types relate to firewall rules:

  • SetFirewallConfig: Change the firewall configuration in the registry and configures which boundary nodes the subnet blockchain replicas will communicate with.
  • AddFirewallRules: Add firewall rules in the registry.
  • RemoveFirewallRules: Remove firewall rules in the registry.
  • UpdateFirewallRules: Update firewall rules in the registry.

The following proposal types concern which principals can create canisters on which subnets which is defined in the cycles minting canister:

  • SetAuthorizedSubnetworks: Informs the cycles minting canister that a certain principal is authorized to use certain subnetworks (from a list). Can also be used to set the “default” list of subnetworks that principals without special authorization are allowed to use.
  • UpdateSubnetType: Updates the available subnet types in the cycles minting canister.
  • ChangeSubnetTypeAssignment: Changes the assignment of subnets to subnet types in the cycles minting canister.
  • UpdateSnsWasmSnsSubnetIds: Update the list of SNS subnet IDs that SNS Wasm will deploy SNS instances to.

The following proposal types are used for canister migration, e.g., if it is ever needed to split a subnet:

  • RerouteCanisterRanges: Update the routing table in the registry which defines the range of canister IDs that are on which subnet.
  • PrepareCanisterMigration: Insert or update canister_migrations entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split).
  • CompleteCanisterMigration: Remove canister_migrations entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split).

Topic: ParticipantManagement​

All proposals that administer network participants, notably data center and node provider identities. This topic contains the following proposal types:

  • AddOrRemoveDataCenters: Add or remove data center records in the registry.
  • AddOrRemoveNodeProvider: Assign or revoke an identity to a node provider and any associated key information regarding the legal person that should provide a way to uniquely identify it.

Topic: NodeAdmin​

Proposals that administer node machines. This topic contains the following proposal types:

  • AssignNoid: Assign an identity to a node operator, such as a funding partner, associating key information regarding its ownership, the jurisdiction in which it is located, and other information. The node operator is stored as a record in the registry. It contains the remaining node allowance for that node operator, that is the number of nodes the node operator can still add to the ICP. When an additional node is added by the node operator, the remaining allowance is decreased.
  • UpdateNodeOperatorConfig: Change a node operator’s allowance in the registry.
  • RemoveNodeOperators: Remove a Node Operator from the registry.
  • RemoveNodes: Remove unassigned nodes from the registry.
  • UpdateSshReadonlyAccessForAllUnassignedNodes: A proposal to update SSH readonly access for all unassigned nodes.

Topic: KYC​

This topic only includes the following type concerned with KYCing Genesis neurons:

  • ApproveGenesisKYC: When new neurons are created at Genesis, they have GenesisKYC=false. This restricts what actions they can perform. Specifically, they cannot spawn new neurons, and once their dissolve delays are zero, they cannot be disbursed and their balances unlocked to new accounts. This proposal sets GenesisKYC=true for batches of principals.

The Genesis event disburses all ICP in the form of neurons, whose principals must be KYCed. Consequently, all neurons created after Genesis have GenesisKYC=true set automatically since they must have been derived from balances that have already been KYCed.

Topic: NeuronManagement (restricted voting)​

A special topic that can be used for multiple users to collectively manage a neuron. Specifically, a neuron can be managed by the followees for this topic. For proposals on this topic, only the neuron’s followers on this topic are allowed to vote.

Because the set of eligible voters for proposals on this topic is restricted, proposals on this topic have a shorter than normal voting period. This topic only includes one proposal type:

  • ManageNeuron: The proposal calls a major function on a specified target neuron. Only the followers of the target neuron may vote on these proposals.