NNS Governance Canister

The NNS Governance canister is the core governance system of the Internet Computer Protocol. It manages neurons, proposals, and voting to enable decentralized control of the network.

Overview

The Governance canister provides:

Neuron Management: Create, configure, and manage ICP neurons with staking and voting power
Proposal System: Submit and vote on proposals that govern the Internet Computer
Voting Rewards: Distribute voting rewards to participating neurons
Network Economics: Manage network-wide economic parameters
SNS Creation: Launch Service Nervous Systems (SNS) for decentralized applications

Core Concepts

Neurons

Neurons are the fundamental unit of governance. They represent staked ICP tokens and provide voting power based on:

Stake amount: The amount of ICP locked in the neuron
Dissolve delay: The time until the neuron can be dissolved (up to 8 years)
Age: How long the neuron has been non-dissolving

Voting Power

Neurons have two types of voting power:

Potential Voting Power: Maximum voting power based on stake, age, and dissolve delay
Deciding Voting Power: Actual voting power used in proposals, which decreases if the neuron doesn’t refresh regularly

Neurons must refresh their voting power by:

Voting directly (not via following)
Setting followees
Calling refresh_voting_power

Proposals

Proposals are suggestions for changes to the Internet Computer. They can:

Upgrade canisters
Modify network economics
Manage subnet infrastructure
Create new SNS instances
Execute arbitrary NNS functions

Key Methods

Neuron Management

manage_neuron

Manage a neuron by executing various commands.

neuron_id_or_subaccount

NeuronIdOrSubaccount

required

Identifies the neuron to manage, either by neuron ID or subaccount

command

ManageNeuronCommandRequest

The operation to perform on the neuron:

Spawn: Create a new neuron from maturity
Split: Split neuron into two neurons
Follow: Set neuron to follow others on a topic
SetFollowing: Set multiple followees across topics
Configure: Change neuron configuration
Disburse: Withdraw ICP from neuron
DisburseMaturity: Convert maturity to ICP
StakeMaturity: Convert maturity to stake
MergeMaturity: Merge maturity into stake
Merge: Merge two neurons
MakeProposal: Submit a proposal
RegisterVote: Vote on a proposal
RefreshVotingPower: Refresh the neuron’s deciding voting power

command

Command_1

Result of the command execution, which varies based on the command type

create_neuron

Create a new neuron using ICRC-2 transfer_from (requires prior approval).

amount_e8s

nat64

required

The amount of ICP to stake in e8s (1 ICP = 100,000,000 e8s)

source_subaccount

blob

The subaccount to transfer ICP from (defaults to default subaccount)

controller

principal

The controller of the new neuron (defaults to caller)

followees

SetFollowing

The followees to set for the new neuron (defaults to network defaults)

dissolve_delay_seconds

nat64

The dissolve delay in seconds (defaults to 7 days, max 8 years)

dissolving

bool

Whether the neuron should start dissolving immediately (defaults to false)

auto_stake_maturity

bool

Whether to automatically stake maturity (defaults to false)

result

CreateNeuronResponse

Returns the newly created neuron ID on success

claim_or_refresh_neuron_from_account

Claim or refresh a neuron from a ledger account.

controller

principal

The principal that controls the neuron

memo

nat64

required

The memo used when transferring ICP to create the neuron

result

Result_1

Returns the neuron ID if successful, or an error

Neuron Operations

Configure Operations

When using the Configure command in manage_neuron, you can perform these operations: IncreaseDissolveDelay

additional_dissolve_delay_seconds

nat32

Number of seconds to add to the dissolve delay (max 8 years total)

StartDissolving Begin the countdown to unlock staked ICP. StopDissolving Pause the dissolve countdown and start aging again. SetDissolveTimestamp

dissolve_timestamp_seconds

nat64

Set an absolute timestamp when the neuron will be dissolved

AddHotKey

new_hot_key

principal

Add a principal that can vote and submit proposals (but not disburse)

RemoveHotKey

hot_key_to_remove

principal

Remove a previously added hot key

ChangeAutoStakeMaturity

requested_setting_for_auto_stake_maturity

bool

Enable or disable automatic staking of maturity

SetVisibility

visibility

int32

Set neuron visibility (0 = private, 1 = public)

JoinCommunityFund Make the neuron participate in the Neurons’ Fund for SNS launches. LeaveCommunityFund Remove the neuron from the Neurons’ Fund.

Proposal Management

MakeProposal

Submit a new proposal (via manage_neuron command).

url

text

required

URL with additional information about the proposal

title

text

Short title for the proposal

summary

text

required

Description of the proposal

action

ProposalActionRequest

required

The action to execute if the proposal is adopted:

Motion: Text motion with no execution
ManageNetworkEconomics: Update economic parameters
ManageNeuron: Perform neuron operation
InstallCode: Install/upgrade canister code
StopOrStartCanister: Stop or start a canister
CreateServiceNervousSystem: Launch an SNS
ExecuteNnsFunction: Execute arbitrary NNS function
AddOrRemoveNodeProvider: Manage node providers
RewardNodeProvider: Reward node providers
And many more…

proposal_id

ProposalId

The ID of the newly created proposal

message

text

Optional message with additional information

list_proposals

Query proposals with filtering options.

limit

nat32

required

Maximum number of proposals to return

before_proposal

ProposalId

Return proposals with IDs less than this (for pagination)

include_status

vec int32

Filter by proposal status (1=Open, 2=Rejected, 3=Adopted, 4=Executed, 5=Failed)

include_reward_status

vec int32

Filter by reward status

exclude_topic

vec int32

Exclude proposals on specific topics

include_all_manage_neuron_proposals

bool

Include all manage neuron proposals (otherwise only caller’s)

omit_large_fields

bool

Omit large fields like ballots to reduce response size

proposal_info

vec ProposalInfo

List of proposals matching the filters

get_proposal_info

Get detailed information about a specific proposal.

proposal_id

nat64

required

The ID of the proposal to query

proposal_info

ProposalInfo

Complete information about the proposal including:

Current status and voting deadline
Proposer neuron ID
Vote tallies
Ballots from all neurons
Execution timestamps
Failure reason (if failed)

get_pending_proposals

Get all proposals that are currently open for voting.

proposals

vec ProposalInfo

List of all open proposals

Voting

RegisterVote

Vote on a proposal (via manage_neuron command).

proposal

ProposalId

required

The proposal to vote on

vote

int32

required

The vote to cast:

1 = Yes
2 = No

Query Methods

list_neurons

List neurons with filtering and pagination.

neuron_ids

vec nat64

Specific neuron IDs to include

include_neurons_readable_by_caller

bool

Include neurons where caller is controller or hotkey

include_public_neurons_in_full_neurons

bool

Include full details for public neurons

page_number

nat64

Page number for pagination

page_size

nat64

Number of neurons per page

neuron_infos

vec NeuronInfo

Public information about neurons (redacted view)

full_neurons

vec Neuron

Complete neuron data (only for authorized neurons)

total_pages_available

nat64

Total number of pages available

get_full_neuron

Get complete information about a neuron by ID.

neuron_id

nat64

required

The ID of the neuron to query

neuron

Neuron

Complete neuron data if caller is authorized, including:

Stake and maturity
Dissolve state
Followees
Hot keys
Voting power (potential and deciding)
Recent ballots

get_neuron_info

Get public information about a neuron.

neuron_id

nat64

required

The ID of the neuron to query

neuron_info

NeuronInfo

Public neuron information including:

Dissolve delay and state
Stake amount
Age in seconds
Voting power
Created timestamp

list_known_neurons

List all publicly known neurons (neurons with public visibility).

known_neurons

vec KnownNeuron

List of known neurons with their metadata:

Neuron ID
Name and description
Links (social media, website, etc.)
Topics they’re committed to voting on

get_network_economics_parameters

Get current network economic parameters.

parameters

NetworkEconomics

Current economic parameters including:

Neuron minimum stake
Transaction fees
Reject cost for proposals
Maximum node provider rewards
Voting power economics (refresh thresholds)

get_metrics

Get cached governance metrics.

metrics

GovernanceCachedMetrics

Comprehensive governance statistics including:

Total staked ICP
Total supply
Neuron counts by state
Maturity totals
Voting power distributions
Community fund statistics
Subset metrics for different neuron categories

Advanced Features

list_neuron_votes

Get voting history for a known neuron.

neuron_id

NeuronId

required

The neuron ID (must be a known neuron)

before_proposal

ProposalId

Return votes for proposals before this ID (for pagination)

limit

nat64

Maximum votes to return (max 500)

votes

vec NeuronVote

List of votes cast by the neuron

all_finalized_before_proposal

ProposalId

Proposals before this ID are finalized in history

get_neurons_fund_audit_info

Get audit information for Neurons’ Fund participation in an SNS swap.

nns_proposal_id

ProposalId

required

The NNS proposal ID that created the SNS

result

NeuronsFundAuditInfo

Complete audit trail including:

Initial participation amounts
Final participation amounts
Refund information
Neuron portions allocated

simulate_manage_neuron

Simulate a neuron management operation without executing it.

neuron_id_or_subaccount

NeuronIdOrSubaccount

required

The neuron to simulate the operation on

command

ManageNeuronCommandRequest

required

The command to simulate

command

Command_1

Simulated result of the command

Data Types

Neuron

Represents a staked ICP neuron with governance rights.

NeuronId

Unique identifier for the neuron

controller

principal

Principal with full control over the neuron

hot_keys

vec principal

Principals that can vote and submit proposals

cached_neuron_stake_e8s

nat64

Staked ICP in e8s (1 ICP = 100,000,000 e8s)

maturity_e8s_equivalent

nat64

Accumulated voting rewards (maturity) in e8s equivalent

staked_maturity_e8s_equivalent

nat64

Maturity that has been staked to increase voting power

neuron_fees_e8s

nat64

Accumulated fees that will be deducted on disburse

dissolve_state

DissolveState

Current dissolve state:

DissolveDelaySeconds: Neuron is not dissolving (delay in seconds)
WhenDissolvedTimestampSeconds: Neuron is dissolving (timestamp when dissolved)

aging_since_timestamp_seconds

nat64

When the neuron started aging (reset when dissolving starts)

created_timestamp_seconds

nat64

When the neuron was created

followees

vec record { int32; Followees }

Map of topic to followees for automatic voting

deciding_voting_power

nat64

Current voting power used in proposals (affected by refresh timing)

potential_voting_power

nat64

Maximum voting power if regularly refreshed

voting_power_refreshed_timestamp_seconds

nat64

When voting power was last refreshed

visibility

int32

Visibility setting: 0 = Private, 1 = Public

known_neuron_data

KnownNeuronData

Public metadata if this is a known neuron

ProposalInfo

ProposalId

Unique proposal identifier

proposer

NeuronId

Neuron that submitted the proposal

proposal

Proposal

Proposal content including title, summary, URL, and action

status

int32

Current status: 1=Open, 2=Rejected, 3=Adopted, 4=Executed, 5=Failed

topic

int32

Proposal topic/category

ballots

vec record { nat64; Ballot }

Map of neuron ID to ballot (vote and voting power)

latest_tally

Tally

Current vote counts (yes, no, total)

proposal_timestamp_seconds

nat64

When the proposal was created

deadline_timestamp_seconds

nat64

Voting deadline (affected by wait-for-quiet)

decided_timestamp_seconds

nat64

When the proposal was decided (if decided)

executed_timestamp_seconds

nat64

When the proposal was executed (if executed)

failed_timestamp_seconds

nat64

When the proposal failed (if failed)

failure_reason

GovernanceError

Error details if execution failed

reward_status

int32

Whether the proposal is eligible for voting rewards

Proposal Topics

Proposals are categorized by topic, which affects voting parameters:

NeuronManagement (1): Neuron operations
ExchangeRate (2): ICP/XDR exchange rate updates
NetworkEconomics (3): Economic parameter changes
Governance (4): Governance system upgrades
NodeAdmin (5): Node management
ParticipantManagement (6): Participant operations
SubnetManagement (7): Subnet configuration
Kyc (9): KYC verification
NodeProviderRewards (10): Node provider compensation
IcOsVersionDeployment (13): IC OS version deployments
IcOsVersionElection (14): IC OS version elections
SnsAndCommunityFund (15): SNS and Neurons’ Fund
ApiBoundaryNodeManagement (16): API boundary nodes
SubnetRental (17): Subnet rental management
ApplicationCanisterManagement (18): Application canisters
ProtocolCanisterManagement (19): Protocol canisters
ServiceNervousSystemManagement (20): SNS management

Error Types

Common governance error types:

Unspecified (0): Unknown error
InsufficientFunds (1): Not enough ICP for operation
InvalidCommand (2): Invalid command parameters
NotAuthorized (3): Caller not authorized
PreconditionFailed (4): Operation precondition not met
NotFound (5): Resource not found
ResourceExhausted (6): Rate limit or capacity exceeded
InvalidProposal (7): Invalid proposal parameters
AlreadyExists (8): Resource already exists
External (9): External call failed
LedgerUpdateOngoing (10): Ledger operation in progress

Best Practices

For Neuron Holders

Maximize Voting Power: Increase dissolve delay to 8 years and let neurons age
Stay Active: Regularly refresh voting power (vote directly, update followees, or call refresh_voting_power)
Set Followees: Configure followees on topics you want to delegate
Use Hot Keys: Add hot keys for voting without exposing controller keys
Auto-Stake Maturity: Enable to compound rewards automatically

For Developers

Batch Operations: Use list_neurons pagination for large queries
Query Methods: Use query methods when possible for faster responses
Error Handling: Always check for errors and handle retry logic
Simulate First: Use simulate_manage_neuron for testing
Monitor Refresh: Track voting_power_refreshed_timestamp_seconds

Examples

Creating a Neuron

// First, approve the governance canister to spend ICP
await ledger.icrc2_approve({
  spender: { owner: governanceCanisterId, subaccount: [] },
  amount: 100_000_000n, // 1 ICP
  fee: 10_000n
});

// Then create the neuron
const result = await governance.create_neuron({
  amount_e8s: [100_000_000n],
  dissolve_delay_seconds: [31_536_000n], // 1 year
  auto_stake_maturity: [true]
});

Voting on a Proposal

const result = await governance.manage_neuron({
  neuron_id_or_subaccount: [
    { NeuronId: { id: neuronId } }
  ],
  command: [{
    RegisterVote: {
      proposal: [{ id: proposalId }],
      vote: 1 // Yes
    }
  }]
});

Refreshing Voting Power

const result = await governance.manage_neuron({
  neuron_id_or_subaccount: [
    { NeuronId: { id: neuronId } }
  ],
  command: [{
    RefreshVotingPower: {}
  }]
});

Core APIs

Canisters

Networking

​NNS Governance Canister

​Overview

​Core Concepts

​Neurons

​Voting Power

​Proposals

​Key Methods

​Neuron Management

​manage_neuron

​create_neuron

​claim_or_refresh_neuron_from_account

​Neuron Operations

​Configure Operations

​Proposal Management

​MakeProposal

​list_proposals

​get_proposal_info

​get_pending_proposals

​Voting

​RegisterVote

​Query Methods

​list_neurons

​get_full_neuron

​get_neuron_info

​list_known_neurons

​get_network_economics_parameters

​get_metrics

​Advanced Features

​list_neuron_votes

​get_neurons_fund_audit_info

​simulate_manage_neuron

​Data Types

​Neuron

​ProposalInfo

​Proposal Topics

​Error Types

​Best Practices

​For Neuron Holders

​For Developers

​Examples

​Creating a Neuron

​Voting on a Proposal

​Refreshing Voting Power

​See Also

Build docs developers (and LLMs) love

NNS Governance Canister

Overview

Core Concepts

Neurons

Voting Power

Proposals

Key Methods

Neuron Management

manage_neuron

create_neuron

claim_or_refresh_neuron_from_account

Neuron Operations

Configure Operations

Proposal Management

MakeProposal

list_proposals

get_proposal_info

get_pending_proposals

Voting

RegisterVote

Query Methods

list_neurons

get_full_neuron

get_neuron_info

list_known_neurons

get_network_economics_parameters

get_metrics

Advanced Features

list_neuron_votes

get_neurons_fund_audit_info

simulate_manage_neuron

Data Types

Neuron

ProposalInfo

Proposal Topics

Error Types

Best Practices

For Neuron Holders

For Developers

Examples

Creating a Neuron

Voting on a Proposal

Refreshing Voting Power

See Also