How-To: Create an NNS motion proposal

This article explains one way to submit NNS motion proposals by using a few command line tools and a self-custody neuron.

1 Background

To properly follow what is going on, there are a few high-level points worth highlighting:

1.1 Only Neurons can submit NNS proposals

Neurons with at least 10 ICP and 6 months of dissolve delay can submit NNS proposals. So the first step is to create such a neuron.

1.2 The NNS Governance Canister accepts motion proposals

The Governance Canister is just a canister like any other, so it has a Candid file, it accepts messages, etc... This article describes a way where you can have your local computer send a message to the governance canister (signed on behalf of a neuron) that contains a motion proposal.

2 One-time setup

2.1 Install Tools

2.1.1 Install dfx

• dfx is the canister SDK and it will be used to send messages from your machine to NNS
• smartcontracts.org

$ dfx [OPTIONS] <SUBCOMMAND>

2.1.2 Install quill

• quill is a minimalist "governance toolkit". It is wrapper for crafting & sending messages to the NNS and manage one's neuron.
• https://github.com/dfinity/quill
• this article will assume that you execute quill on your local machine by running

$ quill [OPTIONS] <SUBCOMMAND>

2.2 Create a neuron via command-line tools

2.2.1 Create a private.pem (private/public keypair) and Ledger account id

Before one starts, they need a private/public keypair.

$ quill generate --seed-file seed.txt --pem-file identity.pem

When done, your account id should look something like this: 612ec300g9ec990da900d6ec45919e7d5dbb9fa0dd8e69c54d374df93aa28d57.

2.2.2 Link this private/public keypair to dfx so you can use it as an "Identity"

In this case, the new identity is called "proposals"

$ dfx identity import proposals private.pem

• If you see “creating identity: proposals” in the terminal, this means it worked
• further reading on dfx identities: dfx identity

2.2.3 Send ICP to the account id generated in step 2.2.1

You should send at least 10.001 in order to have enough ICP to create a neuron and pay for the Ledger transaction fees.

To send ICP to the account, all you need is to input the account id in your wallet of choice.

2.2.4 Now that the account has the required ICP, spawn a neuron

Note: This section assumes you have quill installed properly.

// Craft a message to "stake a the neuron by choosing a 8-character $NAME and an $AMOUNT to stake"
// Note: you need to stake at LEAST 10 ICP to send proposals as $AMOUNT
$ quill --pem-file private.pem neuron-stake --name $NAME --amount $AMOUNT > message.json

//Send the message crafted above.
$ quill send message.json

• You should see a message with a neuron ID spawned
• If successful, response will return neuron ID: 9_218_890_096_040_352_708. This means the neuron ID is 9218890096040352708.

2.2.5 Increase neuron dissolve to at least 6 months

• Time is measured in seconds in the NNS
• One year in seconds: 31557600 seconds

// Craft message to increase dissolve delay of neuron to 1 year
$ quill --pem-file private.pem neuron-manage 9218890096040352708 --additional-dissolve-delay-seconds 31557600 > message.json

//send message created above to the NNS
$ quill send message.json

3 How to send a proposal

This sections shows how to create a motion proposal similar to this one: https://dashboard.internetcomputer.org/proposal/42626

3.1 Craft a proposal in markdown

The IC Dashboard and the NNS frontend dapp both render markdown of the summary field. It is recommended to use standard markdown for your motion proposal.

Example markdown for a NNS motion proposal:

## Objective

Service nervous systems (SNSs) are algorithmic DAOs that allow developers to create decentralized, token-based governance systems for their dapps. The proposed governance canister design is similar to the  governance canister of the Network Nervous System (NNS) but simpler and more flexible, allowing each SNS community to choose the configurations according to their needs. This design is also presented and discussed in this forum: https://forum.dfinity.org/t/open-governance-canister-for-sns-design-proposal/10224 .

## Background

### Relation to the original SNS design & overall approach
DFINITY Foundation presented a first proposed [SNS design](https://www.youtube.com/watch?v=L4443aaAP5A) in October 2021. 

## Community conversation & Timeline
The NNS team is ready to work on this feature!
To get the design approved by the community, the following schedule was followed:

* Jan 11-18th: Design discussion on the forum thread
* Jan 18th: Community conversation about the topic
* Jan 20th: Developer discussion on Discord
* today: motion proposal submission proposing the above design

## What is being asked of:

* Vote accept or reject on NNS Motion
* Participate in technical discussions as the motion moves forward

3.2 Send proposal via dfx

Example structure of sending an NNS motion proposal with placeholders $TITLE, $MOTION_TEXT, $SUMMARY, and $NEURON_ID (these are not meant to be Unix variables and you need to fill them directly within the command):

• note that rrkah-fqaaa-aaaaa-aaaaq-cai is the ID of the Governance Canister on the NNS so this command is is sending a message to the manage_neuron method of the Governance Canister of the NNS.

dfx --identity proposals canister --network ic call rrkah-fqaaa-aaaaa-aaaaq-cai manage_neuron '(record {id = null; command=opt variant {MakeProposal=record {url=""; title="$TITLE";action=opt variant {Motion=record {motion_text="$MOTION_TEXT"}}; summary="

$SUMMARY

"}}; neuron_id_or_subaccount=opt variant {NeuronId=record {id=$NEURON_ID:nat64}}})'

Example NNS motion proposal with $TITLE, $MOTION_TEXT, $SUMMARY, and $NEURON_ID filled out:

dfx --identity proposals canister --network ic call rrkah-fqaaa-aaaaa-aaaaq-cai manage_neuron '(record {id = null; command=opt variant {MakeProposal=record {url=""; title="Open Governance canister for SNS | Design proposal";action=opt variant {Motion=record {motion_text="Present design proposal for Open Governance canister"}}; summary="

## Objective

Service nervous systems (SNSs) are algorithmic DAOs that allow developers to create decentralized, token-based governance systems for their dapps. The proposed governance canister design is similar to the  governance canister of the Network Nervous System (NNS) but simpler and more flexible, allowing each SNS community to choose the configurations according to their needs. This design is also presented and discussed in this forum: https://forum.dfinity.org/t/open-governance-canister-for-sns-design-proposal/10224 .

## Background

### Relation to the original SNS design & overall approach
DFINITY Foundation presented a first proposed [SNS design](https://www.youtube.com/watch?v=L4443aaAP5A) in October 2021. 

## Community conversation & Timeline
The NNS team is ready to work on this feature!
To get the design approved by the community, the following schedule was followed:

* Jan 11-18th: Design discussion on the forum thread
* Jan 18th: Community conversation about the topic
* Jan 20th: Developer discussion on Discord
* today: motion proposal submission proposing the above design

## What is asked of the community:

* Vote accept or reject on NNS Motion
* Participate in technical discussions as the motion moves forward

"}}; neuron_id_or_subaccount=opt variant {NeuronId=record {id=9218890096040352708:nat64}}})'

3.3 Check dashboard to see proposal was successful

If successful, dfx will return something like this:

(
  record {
    2_171_433_291 = opt variant {
      3_217_030_240 = record {
        2_744_746_248 = opt record { 23_515 = 42_626 : nat64 };
      }
    };
  },
)

where 42_626 or rather 42626 is the ID of the proposal. Your proposal will have a different ID.

You will be able to see the proposal here: https://dashboard.internetcomputer.org/proposal/42626

4 Best practices for motion proposals

4.1 Writing the Proposal

The proposal can accept any free-form text. Below is a recommended starting template for anyone starting to think about how to write one:

# Example Motion Project Proposal

## 1. Objective
Lorem Ipsum

## 2. Background
Lorem Ipsum

## 3. Why this is important
Lorem Ipsum

## 4. Pros
Lorem Ipsum

## 5. Cons
Lorem Ipsum

## 6. Key milestones (if any)
Lorem Ipsum

## 7. Discussion leads (if any)
Alice, Bob, etc...

## 8. Security concerns (if any)
Lorem Ipsum

## 11. What is asked of the community

* Review comments, ask questions, give feedback

* Vote accept or reject on NNS Motion

Developer forum: https://forum.dfinity.org/t/long-term-r-d-tokenomics-proposal/9392/3

4.2 Communicating the proposal

Once the proposal is live, it will be open to voting for 4 days, and if there is a lot of contesting of votes, that deadline will be automatically extended up to an additional 4 days.

Proposals typically require significant communication and promotion (like in any organization) to make sure enough people vote for it. It is very common for proposals to be promoted 'before' submission so its intended voters are aware of it.

5 See Also

• The Internet Computer project website (hosted on the IC): internetcomputer.org
• Network Nervous System
• Staking and Voting
• Governance of the Internet Computer
• ICP token