Internet Computer Governance

How to submit proposals to the Network Nervous System

Welcome to the Internet Computer community! You’re joining a large and expanding group of software developers, researchers, token holders, node operators, data centers, and others that are shaping the forward direction of the Internet Computer.

Anyone can join the community that oversees the governance of the Internet Computer. Before we talk about how to do that, let’s first cover some background on how governance works.

Background: How Governance Works

The Internet Computer is the world’s first blockchain with web speed and internet scale. As a blockchain, the Internet Computer is not owned or operated by any one group. All Internet Computer blockchain updates and operations are managed through an open, decentralized governance system called the Network Nervous System (NNS).

The NNS oversees everything from network operations to the token economics that make it possible to build DeFi and other dapps on the Internet Computer. Anyone can submit a proposal to the NNS, and if it is adopted by the Internet Computer community, it is immediately executed.

To submit a proposal to the NNS, you need to first set up, or ‘stake’, a neuron. A neuron is where you lock up a balance of Internet Computer utility tokens (ICP tokens) for a period of time. This enables you to submit and vote on proposals that govern the Internet Computer. By voting on proposals, you can earn rewards in the form of additional ICP tokens.

We describe below how you can submit two types of governance proposals to the NNS --

  • “Authorize-to-subnet” enables you, as a developer, to propose your app to be included in a verified subnet. The capacity of the Internet Computer is limited in the early days, while the network is being built out. During this period, there will be two types of subnets on which apps can run: verified subnets are for apps that have been reviewed and approved by the Internet Computer community through an NNS proposal; and public subnets are for all other apps. Compute and storage costs are lower in verified subnets during the Internet Computer beta period.

  • “Motion” enables you to propose your thoughts for the future strategy of the Internet Computer. This can be about anything you think is important for the community to consider. If the community adopts the motion, it will guide the future direction of the Internet Computer.

Please note: The Internet Computer is still in beta, and guidance on the process for proposal submissions is subject to change. We’ll include any updates to the proposal submission process, along with guidance on how to submit other types of proposals, in future articles.

With that as background, let’s get you started on submitting proposals.

Step-by-Step: Submitting Proposals to the Network Nervous System (NNS)

  1. Install the Internet Computer SDK. If you have already installed the Software Development Kit (SDK), you can skip this step. If not, follow these steps:

    1. Open a terminal shell on your local computer.

      For example on a Mac, open Applications - Utilities, then double-click Terminal or press ⌘+spacebar to open Search, then type terminal.

    2. Go to https://dfinity.org/developers and copy the link to install the Internet Computer SDK.

    3. Paste the command into the Terminal Window and hit return. This command prompts you to read and accept the license agreement before installing the execution command-line interface (CLI) and its dependencies on your local computer.
    4. Type y and press Return to continue with the installation.
  2. Install Prerequisites for MacOS. If you are using a Linux OS, you can skip this step. The icx-nns tool, which we’ll download in the next step, requires OpenSSL to be installed on your MacOs in order to run. To install this dependency, you will need to use a MacOs package manager such as “brew” to install OpenSSL.

    • Go to https://brew.sh/ and run the install script
    • Copy the command that you see on the home page. It should look something like this:

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    • Paste it into a Terminal Window and hit return. Input the password that you use to log into your MacOS, and hit return.

    • Once brew has finished installing, type in the following command to install OpenSSL.

      brew install openssl
  3. Download the icx-nns tool. This is the command line tool that will allow you to submit proposals to the NNS. You can find it at https://github.com/dfinity/icx-nns/releases.

    In the “Releases” page, you will see a list of icx-nns versions. It’s recommended you select the latest available version (to ensure you have the most up-to-date software.) Once you select a version, you can choose to download the file for your operating system. Currently, we support Linux and MacOS. You can download the appropriate file and save the file to the Downloads folder on your computer.

    icx-nns release

    By default, icx-nns will connect to the Internet Computer.

    Note: On MacOS, you may notice that you are unable to run the icx-nns-macos tool and its commands, and that the Settings warns you of using an unverified application. This is expected, and you can open System Preferences > Security & Privacy to allow the app. Here is a How-To article from Apple which will walk you through the steps: https://support.apple.com/en-us/HT202491.

  4. Add the binary in the download to your local bin. Open a Terminal window on your computer. For example, open Applications -- Utilities, then double-click Terminal or press ⌘+spacebar to open Search, then type terminal.

    Note: The file will be named per your operating system. So if you use MacOS, the tool will be named “icx-nns-macos” and if you use Linux, it will be named “icx-nns-linux64”. For the rest of the tutorial, we assume you are using MacOS. If you are using Linux, please substitute the file name for the Linux operating system version.

    Type in the following command:

    cp /Users/[yourname]/Downloads/icx-nns-macos /usr/local/bin

    The cp command makes a copy of the file from the source in the Downloads folder to /usr/local/bin. That’s the location where user supplied binaries such as this one need to be installed on your computer.

    You can confirm that it has been installed in /usr/local/bin by using the command ls.

    ls /usr/local/bin/icx-nns-macos

    The above command will return the following to confirm the installation.

    /usr/local/bin/icx-nns-macos

    We also need to run the following command, as a one time setup, in order to invoke the command line tools functionality from your terminal. You will be prompted to enter your Mac/Linux login password in order to allow this command to succeed.

    sudo chmod +x /usr/local/bin/icx-nns-macos

    Now let’s have a look at the commands available to you in the icx-nns command line tool. Type the following:

    icx-nns-macos --help

    As you’ll see, governance is one of the main subcommands for icx-nns. It enables you to submit proposals to the governance canister in the NNS.

    icx-nns-help

  5. Get ICP tokens transferred to your account

    In order to submit a proposal to the NNS, you will first need to acquire and transfer ICP tokens to your Internet Computer ledger account, and then stake the ICP tokens in a neuron.

    Generally, Coinmarketcap.com is a public source of information about ICP tokens, including which exchanges may have ICP tokens available. You can also earn ICP tokens as rewards for participating in governance of the Internet Computer. In either case, here’s how you transfer ICP tokens to your ledger account:

    • Get your Principal Identifier (Principal ID) from DFX. The first time you use the Internet Computer SDK, the dfx command-line tool creates a default developer identity for you. This identity is represented by a principal data type and a textual representation of the principal, or principal identifier.

      To get your Principal ID, use this command:

      dfx identity get-principal

      The command will then return your Principal ID in a form like this:

      2x3kc-3n2jw-v3q5h-ngy4b-w2rsb-2ef5e-xxwan-qvhuq-lesp5-zmkjb-bae

      Confirm that this is your ‘default’ developer identity by inputting this command. If it returns something else, note the name. You’ll need this in the next step.

      dfx identity whoami
    • Allow the ICX-NNS tool to use your Principal ID.

      In creating and staking a neuron, icx-nns is going to use your Principal ID and its associated ‘private key’. The ‘private key’ is used to confirm to the NNS that you are who you say you are.

      Type in the following command:

      export PEM_PATH=/Users/[Yourname]/.config/dfx/identity/[whoami_response]/identity.pem

      Where:

      • [whoami_response] is the response that you got above your developer identity -- default or some other naming.

      To confirm that icx-nns is now able to use your Principal ID, type in the following:

      icx-nns-macos get-principal

      It should return the same Principal ID as what was returned to you through DFX.

    • Get your account ID from the ledger. The ledger on the Internet Computer is a smart contract that holds information about accounts and transactions. To get your account ID, type in this command:

      icx-nns-macos ledger account-id

      This command displays the ledger account identifier associated with your developer identity. For example, you should see output similar to the following:

      3fc01e379b31b2ff852eca75075977e39d0aa7abbf2c1bbea868ed8b4b6c79ff
    • Transfer ICP tokens to your Account ID. Follow the instructions on the exchange where you purchased the ICP tokens, or on an existing source of ICP tokens, to transfer them to your account ID.

    • icx-nns can help verify you’ve received the ICP tokens. The following command will print your current balance.

      icx-nns-macos ledger balance

    Once you have the ICP tokens in your account, you can stake them in a neuron so that you can submit proposals, vote on proposals, and earn additional ICP token rewards for voting.

  6. Create and stake a neuron using icx-nns. To stake a neuron, follow this command structure.

    icx-nns-macos neuron stake-or-refresh <controller> <memo> --amount <amount>

    Where:

    • <controller> is your Principal ID, which you got earlier by using the command: dfx identity get-principal.
    • <memo> is just any arbitrary number that you want to assign to this staking event. Think of it as a reference number for your neuron. (You can refresh, or add more ICP tokens, to an existing neuron by specifying the same memo number that you set when it was created. Therefore, for future neuron refreshes this memo should be kept handy. The memo number can be seen in the transaction record when you search for the transaction in the Internet Computer Network Explorer.)
    • <amount> is the number of tokens which you are staking as part of creating the neuron. The minimum number of ICP tokens to stake is 1 ICP token in order to submit a proposal.

    Here’s an example of this command, where an ICP token holder has decided to stake 5 ICP tokens in a neuron.

    icx-nns-macos stake-or-refresh 2x3kc-3n2jw-v3q5h-ngy4b-w2rsb-2ef5e-xxwan-qvhuq-lesp5-zmkjb-bae 1234 --amount 5

    You should see output similar to the following on your console:

    Transfer sent at BlockHeight: 7
    Neuron id: NeuronId { id: 1234567890123456789 }

    As an FYI -- if you want to get information about your neurons, you can use these commands:

    • icx-nns-macos neuron ids

      This will return a list of neuron IDs associated with your principal. Example of what’s returned:

      [1234567890123456789]
    • icx-nns-macos neuron <neuron id> info This will return information about your neuron. Example of what’s returned:

      NeuronInfo { retrieved_at_timestamp_seconds: 1622604166, state: Dissolved, age_seconds: 96, dissolve_delay_seconds: 0, recent_ballots: [], voting_power: 1000000190, created_timestamp_seconds: 1622604070 }
  7. Setting your neuron’s dissolve delay.

    Now that you have staked a neuron using ICP tokens, you will need to set a dissolve delay in order to submit proposals to the NNS. A newly created neuron’s dissolve delay is 0 by default.

    To increase the dissolve delay, execute the following command. Note: A neuron’s minimum dissolve delay needs to be 6 months -- 15780000 in seconds -- in order to be able to submit proposals.

    icx-nns-macos neuron <neuron id> dissolve increase-delay <dissolve delay in seconds>

    Here’s an example of what the above command would look like, where an ICP token holder is setting the dissolve delay to 6 months:

    icx-nns-macos neuron 1234567890123456789 dissolve increase-delay 15780000
  8. Understanding proposal structure. Let’s see some more information about how proposals are structured and sent from icx-nns.

    Type the following:

    icx-nns-macos governance submit-proposal --help

    You’ll see the details of commands that are available to you under governance.

    icx-nns-help-2

    Again, there are two types of proposals that you can submit:

    • authorize-to-subnet enables you, as a developer, to propose your app to be included in a verified subnet. The capacity of the Internet Computer is limited in the early days, while the network is being built out. During this period, there will be two types of subnets on which apps can run: verified subnets are for apps that have been reviewed and approved by the Internet Computer community through an NNS proposal; and public subnets are for all other apps.

    • motion enables you to propose your thoughts in text about ideas for the future strategy of the Internet Computer. If the Internet Computer community adopts the motion, it will guide the future direction of the Internet Computer.

    The format for submitting a proposal is the same for both types:

    icx-nns-macos governance submit-proposal <neuron-id> --summary <summary> --url <url> <SUBCOMMAND>

    Where:

    • <neuron-id> is the identity number of the neuron you created earlier through icx-nns. Again, you can get the identity number of the neuron staked through this command:
      icx-nns-macos neuron ids
    • <summary> is a text summary description of the proposal, between quotation marks
    • <URL> is a link to the longer description of your proposal -- particularly relevant for Motion proposals. This is also between quotation marks.
    • <SUBCOMMAND> indicates whether it is an authorize-to-subnet or a motion proposal. This is also where you’ll also include the additional parameters or information that’s needed for each type of proposal.

    Important note on submitting proposals: If your proposal is rejected by the Internet Computer community, you will need to pay a small fee (1 ICP), which will be automatically deducted. This fee is in place to avoid the NNS being inundated by frivolous proposals.

  9. Submitting the proposal. Let’s now look at how you can submit an authorize-to-subnet and a motion proposal in practice.

    Authorize to Subnet

    The command for proposing that an app should be included in a verified subnet follows this format:

    icx-nns-macos governance submit-proposal <neuron-id> --summary <summary> --url <url> authorize-to-subnet --who <Principal ID> --subnets <subnet ID>

    Where:

    • <neuron-id> is the identity number of your neuron
    • <summary> is a brief text summary description of the proposal, between quotation marks. Please put a clear description of your authorize-to-subnet proposal so that the Internet Computer community can readily understand your proposal, e.g. “Please add me as a developer for the verified subnet for application XYZ”.
    • <URL> is a link to the longer description of your proposal, between quotation marks. You can post a link to your written proposal on the Internet Computer Association github site https://github.com/ic-association/nns-proposals under the folder “proposals”. Alternatively, you can create a web page that describes your motion. Your URL should link to a more detailed description of your app that is currently on the public subnet.
    • <Principal ID> is your developer identity, which we got earlier using the DFX tool.
    • <subnet ID> is the name of the verified subnet to which you want approval to deploy your app. You can see a list of available verified subnets through a dashboard created by an Internet Computer community member: https://ic.rocks/network. Choose one of the verified subnets as the subnet ID in your proposal submission.

    Here’s an example of a developer who is proposing to the Internet Computer community that her app should be included in a verified subnet.

    icx-nns-macos governance submit-proposal 39 --summary "Please add me as a developer for the verified subnet for the app SparkOne" --url "https://github.com/ic-association/nns-proposals/blob/main/proposals/governance/202SparkOne.md" authorize-to-subnet --who hc6tm-yakdh-m365z-vdtty-yqdq2-4f34f-t4m3g-3yk3m-2sduu-4i6pc-iae --subnets eq6en-6jqla-fbu5s-daskr-h6hx2-376n5-iqabl-qgrng-gfqmv-n3yjr-mqe

    The proposal is confirmed as submitted with a response like this:

    Proposal id: ProposalId { id: 3278 }

    Motion

    The command for proposing a motion on the forward strategic direction of the Internet Computer follows this format:

    icx-nns-macos governance submit-proposal <neuron-id> --summary <summary> --url <url> motion <motion-text>

    Where:

    • <neuron-id> is the identity number of your neuron
    • <summary> is a brief title of your motion that describes it, between quotation marks.
    • <URL> is a link to the longer description of your proposal, between quotation marks. You can post a link to your written proposal on the Internet Computer Association github site https://github.com/ic-association/nns-proposals under the folder “proposals”. Alternatively, you can create a web page that describes your motion.

    • <motion text> is a summary description of your motion, between quotation marks. Your summary description should cover the following areas:

      • Background: What is the problem that you think should be addressed, or the opportunity to be pursued, for the Internet Computer?
      • Solution: Describe what the proposed solution is to the issue or opportunity that you’ve raised. This could be summary details of a proposed roadmap item for the community to execute, an adjustment to the current Internet Computer structure, or some other strategic initiative.
      • Community Support: Summarize the input that you’ve received from other community members for the motion.
      • Implementation: Summarize your thoughts on how the motion should be implemented, and in what timeframe.

    Before you submit a motion proposal, it’s recommended that you first start a discussion with the Internet Computer community to get their thoughts and feedback. To do that:

    • Go to the Internet Computer community forum at https://forum.dfinity.org/.
    • Under the category “Governance”, create a new chat thread
    • Write a summary description of your proposal -- background, solution, and implementation -- and include a URL link to the details
    • Invite community members to comment on your proposal

    That feedback will help you to refine your motion proposal and include a summary of the community’s support for it when you submit it to the NNS.

    Here’s an example of a neuron holder who is proposing a motion to the Internet Computer community.

    icx-nns-macos governance submit-proposal 39 --summary "Data Subnets" --url "https://github.com/ic-association/nns-proposals/blob/main/proposals/governance/202DataSubnets.md" motion -- "Background - The Internet Computer offers System and Fidiciary subnets. There would be a real benefit for the community to offering a Data subnet. This would enable data to be archived but still on-chain, saving resources. Solution - Creating data subnets that can be queried but not call other canisters. Community Support - See this discussion thread on the developer site - many developers are in support of this and want to participate. Implementation - See the details on how this could be done on the github site proposal."

    The proposal is confirmed as submitted with a response like this:

    Proposal id: ProposalId { id: 3101 }

    You can use the Proposal ID to check on the status of your proposal.

  10. Checking on the status of your proposal. You have a couple of options --

    • Use the icx-nns command line to see the latest information. Type the following:

      icx-nns-macos governance get-proposal-info <Proposal ID>

      Here’s an example of the command and the response from the NNS on the status of your proposal

      icx-nns-macos governance get-proposal-info 3278
      ProposalInfo { id: Some(ProposalId { id: 3278 }), proposer: Some(NeuronId { id: 39 }), reject_cost_e8s: 100000000, proposal: Some(Proposal { summary: "a dummy proposal to authorize which doesn\'t need to be voted on", url: "No url provided", action: Some(ExecuteNnsFunction(ExecuteNnsFunction { nns_function: SetAuthorizedSubnetworks, payload: [68, 73, 68, 76, 4, 108, 2, 190, 206, 234, 2, 1, 246, 213, 179, 225, 2, 2, 110, 104, 110, 3, 109, 104, 1, 0, 1, 1, 29, 10, 25, 217, 191, 119, 53, 28, 231, 140, 64, 112, 215, 11, 190, 22, 124, 102, 205, 188, 43, 108, 212, 135, 74, 113, 30, 120, 144, 2, 1, 1, 1, 29, 48, 88, 10, 26, 118, 67, 4, 149, 19, 248, 247, 214, 255, 230, 245, 16, 0, 87, 3, 69, 166, 49, 96, 202, 183, 120, 76, 89, 2] })) }), proposal_timestamp_seconds: 1622519912, ballots: {39: Ballot { vote: Yes, voting_power: 1806621862 }}, latest_tally: Some(Tally { timestamp_seconds: 1622519912, yes: 1806621862, no: 0, total: 32490076378271988 }), decided_timestamp_seconds: 0, executed_timestamp_seconds: 0, failed_timestamp_seconds: 0, reward_event_round: 0, topic: Governance, status: Open, reward_status: AcceptVotes }
    • Go to the NNS App and check on the status of your proposal. You can learn more about the NNS App in this recent Medium post - Getting Started on the Internet Computer’s Network Nervous System Application & Wallet.

You are now armed with knowledge for participating in the governance of the world’s first blockchain that runs at web speed and can scale without bound. Welcome again to the Internet Computer community.

Start Coding