Difference between revisions of "How-To: Create an NNS motion proposal"

From Internet Computer Wiki
Jump to: navigation, search
(Changed the instructions for the terminal for "Create a private.pem (private/public keypair) and Ledger account id" because the instructions proposed to create a "identity.pem" and in the next step trying to import a "private.pem" to dfx)
 
(49 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
__NUMBEREDHEADINGS__
 
This article explains one way to submit NNS motion proposals by using a few command line tools and a self-custody neuron.
 
This article explains one way to submit NNS motion proposals by using a few command line tools and a self-custody neuron.
  
Line 7: Line 8:
 
===Only Neurons can submit NNS proposals===
 
===Only Neurons can submit NNS proposals===
  
−
Neurons with at least 1 ICP and 6 months of dissolve delay can submit NNS proposals. So the first step is to create such a neuron.
+
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.
  
 
===The NNS Governance Canister accepts motion proposals===
 
===The NNS Governance Canister accepts motion proposals===
Line 17: Line 18:
 
===Install Tools===
 
===Install Tools===
  
−
1. Install '''dfx'''
+
====Install '''dfx'''====
  
 
* '''dfx''' is the canister SDK and it will be used to send messages from your machine to NNS
 
* '''dfx''' is the canister SDK and it will be used to send messages from your machine to NNS
Line 25: Line 26:
 
</pre>
 
</pre>
  
−
2. Install '''keysmith'''
+
====Install '''quill'''====
  
−
* '''keysmith''' will be used to generate a privat/public key pair for the IC
+
* '''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/keysmith
+
* https://github.com/dfinity/quill
 
* this article will assume that you execute '''quill''' on your local machine by running  
 
* this article will assume that you execute '''quill''' on your local machine by running  
  
 
<pre>
 
<pre>
−
$ keysmith [OPTIONS] <SUBCOMMAND>
+
$ quill [OPTIONS] <SUBCOMMAND>
 
</pre>
 
</pre>
  
−
3. Install '''quill'''
+
===Create a neuron via command-line tools===
  
−
* '''quill''' is a minimalist "governance toolkit". It is wrapper for crafting & sending messages to the NNS and manage one's neuron.
+
====Create a <code>private.pem</code> (private/public keypair) and Ledger <code>account id</code>====
−
* https://github.com/dfinity/quill
+
 
−
* this article will assume that you execute '''quill''' on your local machine by running
+
Before one starts, they need a private/public keypair.
  
 
<pre>
 
<pre>
−
$ target/release/quill [OPTIONS] <SUBCOMMAND>
+
$ quill generate --seed-file seed.txt --pem-file private.pem
 
</pre>
 
</pre>
  
−
===Create a neuron===
+
When done, your <code>account id</code> should look something like this: <code>612ec300g9ec990da900d6ec45919e7d5dbb9fa0dd8e69c54d374df93aa28d57</code>.
  
−
====1. Create a <code>private.pem/code> (private/public keypair) and Ledger <code>account id</code>====  
+
====Link this private/public keypair to <code>dfx</code> so you can use it as an "Identity"====
  
−
Before one starts, they need a private/public keypair.
+
In this case, the new identity is called "proposals"
  
 
<pre>
 
<pre>
−
// Create seed phrase
+
$ dfx identity import proposals private.pem
−
$ keysmith generate -o seed.txt
+
</pre>
  
−
//Create private.pem
+
* If you see “creating identity: proposals” in the terminal, this means it worked
−
$ keysmith private-key -o private.pem
+
* further reading on dfx identities: [https://smartcontracts.org/docs/developers-guide/cli-reference/dfx-identity.html dfx identity]
  
−
//Derive Ledger account from private key
+
====Send ICP to the <code>account id</code> generated in step 2.2.1====
−
$ keysmith account -i 0
+
 
 +
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 <code>account id</code> in your wallet of choice.
 +
 
 +
====Now that the account has the required ICP, spawn a neuron====
 +
 
 +
Note: This section assumes you have '''quill''' installed properly.
 +
 
 +
<pre>
 +
// 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
 
</pre>
 
</pre>
  
−
====2. Link this private/public keypair to <code>dfx</code> so you can use it as an "Identity"====
+
* You should see a message with a neuron ID spawned
 +
* If successful, response will return <code>neuron ID: 9_218_890_096_040_352_708</code>. This means the neuron ID is <code>9218890096040352708</code>.
  
−
=====2.1 Install that key into dfx and create an identity=====
+
====Increase neuron dissolve to at least 6 months====
  
−
In this case, the new identity is called "proposals"
+
* Time is measured in seconds in the NNS
 +
* One year in seconds: 31557600 seconds
  
 
<pre>
 
<pre>
−
$ dfx identity import proposals private.pem
+
// 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
 
</pre>
 
</pre>
  
−
* If you see “creating identity: proposals” in the terminal, this means it worked*
+
==How to send a proposal==
−
* further reading on dfx identities: dfx identity :: Internet Computer 2
 
  
−
====3. Send 1.0001 ICP to the "account ID" represented by the public/private keypair (now called the "identity")====
+
This sections shows how to create a motion proposal similar to this one: https://dashboard.internetcomputer.org/proposal/42626
  
 +
===Craft a proposal in markdown===
 +
 +
The IC Dashboard and the NNS frontend dapp both render markdown of the <code>summary</code> field. It is recommended to use standard markdown for your motion proposal.
 +
 +
Example markdown for a NNS motion proposal:
  
−
=====3.1 Send 1.0001 ICP to the <code>account</code> from 1.4=====
+
<pre>
 +
## 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
 +
</pre>
  
−
====4. Now that the account has the required ICP, spawn a neuron====
+
===Send proposal via dfx===
  
−
Note: This section assumes you have Quill installed
+
Example structure of sending an NNS motion proposal with placeholders <code>$TITLE</code>, <code>$MOTION_TEXT</code>, <code>$SUMMARY</code>, and <code>$NEURON_ID</code> (these are not meant to be Unix variables and you need to fill them directly within the command):
  
−
=====4.1 Craft and send a message to spawn a neuron from the account=====
+
* 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.
  
 
<pre>
 
<pre>
−
$ target/release/quill --pem-file private.pem neuron-stake --name $NAME --amount $AMOUNT > message.json
+
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="
  
−
$ target/release/quill send message.json
+
$SUMMARY
 +
 
 +
"}}; neuron_id_or_subaccount=opt variant {NeuronId=record {id=$NEURON_ID:nat64}}})'
 
</pre>
 
</pre>
  
−
* You should see a message with a neuron ID spawned
+
Example NNS motion proposal with <code>$TITLE</code>, <code>$MOTION_TEXT</code>, <code>$SUMMARY</code>, and <code>$NEURON_ID</code> filled out:
 +
 
 +
<pre>
 +
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:
  
−
====5. Increase neuron dissolve to at least 6 months====
+
* 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
  
−
* Time is measured in milliseconds in the NNS
+
## What is asked of the community:
−
* One year: 31557600 milliseconds
 
  
−
=====5.1 Craft message to send the neuron=====
+
* 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}}})'
 +
</pre>
 +
 
 +
===Check dashboard to see proposal was successful===
 +
 
 +
If successful, dfx will return something like this:
  
 
<pre>
 
<pre>
−
$ target/release/quill --pem-file private.pem neuron-manage 148885932052941245 --additional-dissolve-delay-seconds 31557600 > message.json
+
(
 +
  record {
 +
    2_171_433_291 = opt variant {
 +
      3_217_030_240 = record {
 +
        2_744_746_248 = opt record { 23_515 = 42_626 : nat64 };
 +
      }
 +
    };
 +
  },
 +
)
 
</pre>
 
</pre>
  
−
=====5.2 Send just-created message to the Governance canister=====
+
where '''42_626'''  or rather <code>42626</code> 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
 +
 
 +
==Best practices for motion proposals==
 +
 
 +
===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:
  
 
<pre>
 
<pre>
−
$ target/release/quill send message.json
+
# 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
 
</pre>
 
</pre>
  
−
==How to send a proposal==
+
===Communicating the proposal===
  
−
===Craft a proposal in markdown===
+
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.
  
−
===Send proposal via dfx===
+
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.
  
−
===Check dashboard to see proposal was successful===
+
==See Also==
 +
* '''The Internet Computer project website (hosted on the IC): [https://internetcomputer.org/ internetcomputer.org]'''
 +
* [[Network Nervous System]]
 +
* [[Staking and Voting]]
 +
* [[Governance of the Internet Computer]]
 +
* [[ICP token]]

Latest revision as of 10:05, 25 April 2024

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 private.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

Retrieved from "https://wiki.internetcomputer.org/w/index.php?title=How-To:_Create_an_NNS_motion_proposal&oldid=7721"