GovernanceTypes - OpenChat Bot SDK

The GovernanceTypes module contains all type definitions used for interacting with Internet Computer governance canisters, including the NNS governance canister. These types are generated Motoko bindings that correspond to the Candid interface of governance canisters.

Overview

This module provides comprehensive type definitions for:

Proposals and proposal filtering
Neurons and neuron management
Voting and ballot information
Governance canister metadata
Nervous system functions
Network economics parameters

Core Types

ProposalInfo

Contains detailed information about a governance proposal.

public type ProposalInfo = {
    id : ?NeuronId;
    status : Int32;
    topic : Int32;
    failure_reason : ?GovernanceError;
    ballots : [(Nat64, Ballot)];
    proposal_timestamp_seconds : Nat64;
    reward_event_round : Nat64;
    deadline_timestamp_seconds : ?Nat64;
    failed_timestamp_seconds : Nat64;
    reject_cost_e8s : Nat64;
    derived_proposal_information : ?DerivedProposalInformation;
    latest_tally : ?Tally;
    reward_status : Int32;
    decided_timestamp_seconds : Nat64;
    proposal : ?Proposal;
    proposer : ?NeuronId;
    executed_timestamp_seconds : Nat64;
};

?NeuronId

The unique identifier for this proposal.

status

Int32

The current status of the proposal:

1: Open (accepting votes)
2: Rejected
3: Accepted
4: Executed
5: Failed

topic

Int32

The proposal topic/category (e.g., Governance, NetworkEconomics, NodeAdmin).

ballots

[(Nat64, Ballot)]

Map of neuron IDs to their votes on this proposal.

proposal_timestamp_seconds

Nat64

Unix timestamp when the proposal was created.

latest_tally

?Tally

The current vote tally for this proposal.

proposal

?Proposal

The actual proposal content including title, summary, and action.

proposer

?NeuronId

The neuron ID that submitted this proposal.

Proposal

The actual content and action of a governance proposal.

public type Proposal = {
    url : Text;
    title : ?Text;
    action : ?Action;
    summary : Text;
};

url

Text

URL with additional information about the proposal.

title

?Text

The proposal title.

action

?Action

The action to be executed if the proposal passes. See Action type.

summary

Text

A markdown-formatted summary of the proposal.

Action

The action to be executed when a proposal is adopted.

public type Action = {
    #RegisterKnownNeuron : KnownNeuron;
    #ManageNeuron : ManageNeuron;
    #CreateServiceNervousSystem : CreateServiceNervousSystem;
    #ExecuteNnsFunction : ExecuteNnsFunction;
    #RewardNodeProvider : RewardNodeProvider;
    #OpenSnsTokenSwap : OpenSnsTokenSwap;
    #SetSnsTokenSwapOpenTimeWindow : SetSnsTokenSwapOpenTimeWindow;
    #SetDefaultFollowees : SetDefaultFollowees;
    #RewardNodeProviders : RewardNodeProviders;
    #ManageNetworkEconomics : NetworkEconomics;
    #ApproveGenesisKyc : ApproveGenesisKyc;
    #AddOrRemoveNodeProvider : AddOrRemoveNodeProvider;
    #Motion : Motion;
};

A variant type representing different governance actions. Common actions include:

Motion: A motion proposal (non-executable, advisory)
ManageNeuron: Manage a specific neuron
ExecuteNnsFunction: Execute an NNS function
ManageNetworkEconomics: Update network economics parameters

Tally

Vote tallying information for a proposal.

public type Tally = {
    no : Nat64;
    yes : Nat64;
    total : Nat64;
    timestamp_seconds : Nat64;
};

Nat64

Total voting power that voted against the proposal.

yes

Nat64

Total voting power that voted in favor of the proposal.

total

Nat64

Total voting power eligible to vote on this proposal.

timestamp_seconds

Nat64

Unix timestamp when this tally was calculated.

ListProposalInfo

Filter criteria for listing proposals.

public type ListProposalInfo = {
    include_reward_status : [Int32];
    omit_large_fields : ?Bool;
    before_proposal : ?NeuronId;
    limit : Nat32;
    exclude_topic : [Int32];
    include_all_manage_neuron_proposals : ?Bool;
    include_status : [Int32];
};

limit

Nat32

Maximum number of proposals to return.

before_proposal

?NeuronId

Return proposals created before this proposal ID (for pagination).

include_status

[Int32]

Array of proposal status codes to include. Empty array means include all statuses.

include_reward_status

[Int32]

Array of reward status codes to include. Empty array means include all reward statuses.

exclude_topic

[Int32]

Array of topic IDs to exclude from results.

omit_large_fields

?Bool

If true, omits large fields from the response for better performance.

include_all_manage_neuron_proposals

?Bool

If true, includes all ManageNeuron proposals (which are normally filtered).

ListProposalInfoResponse

Response containing a list of proposals.

public type ListProposalInfoResponse = { 
    proposal_info : [ProposalInfo] 
};

proposal_info

[ProposalInfo]

Array of ProposalInfo objects matching the filter criteria.

Neuron Types

NeuronId

Unique identifier for a neuron.

public type NeuronId = { id : Nat64 };

Nat64

The numeric identifier for the neuron.

Neuron

Complete neuron information.

public type Neuron = {
    id : ?NeuronId;
    staked_maturity_e8s_equivalent : ?Nat64;
    controller : ?Principal;
    recent_ballots : [BallotInfo];
    kyc_verified : Bool;
    neuron_type : ?Int32;
    not_for_profit : Bool;
    maturity_e8s_equivalent : Nat64;
    cached_neuron_stake_e8s : Nat64;
    created_timestamp_seconds : Nat64;
    auto_stake_maturity : ?Bool;
    aging_since_timestamp_seconds : Nat64;
    hot_keys : [Principal];
    account : Blob;
    joined_community_fund_timestamp_seconds : ?Nat64;
    dissolve_state : ?DissolveState;
    followees : [(Int32, Followees)];
    neuron_fees_e8s : Nat64;
    transfer : ?NeuronStakeTransfer;
    known_neuron_data : ?KnownNeuronData;
    spawn_at_timestamp_seconds : ?Nat64;
};

?NeuronId

The unique identifier for this neuron.

controller

?Principal

The principal that controls this neuron.

cached_neuron_stake_e8s

Nat64

The amount of ICP staked in this neuron (in e8s, where 1 ICP = 100,000,000 e8s).

maturity_e8s_equivalent

Nat64

The maturity of this neuron in e8s equivalent.

dissolve_state

?DissolveState

The dissolve state of the neuron (dissolving or locked with a delay).

followees

[(Int32, Followees)]

Map of topics to the neurons this neuron follows for automatic voting.

NeuronInfo

Summary information about a neuron (lighter weight than full Neuron type).

public type NeuronInfo = {
    dissolve_delay_seconds : Nat64;
    recent_ballots : [BallotInfo];
    neuron_type : ?Int32;
    created_timestamp_seconds : Nat64;
    state : Int32;
    stake_e8s : Nat64;
    joined_community_fund_timestamp_seconds : ?Nat64;
    retrieved_at_timestamp_seconds : Nat64;
    known_neuron_data : ?KnownNeuronData;
    voting_power : Nat64;
    age_seconds : Nat64;
};

stake_e8s

Nat64

The amount of ICP staked in this neuron (in e8s).

voting_power

Nat64

The voting power of this neuron, including bonuses.

state

Int32

The state of the neuron:

1: Not dissolving (locked)
2: Dissolving
3: Dissolved

dissolve_delay_seconds

Nat64

The dissolve delay in seconds.

age_seconds

Nat64

The age of the neuron in seconds.

Voting Types

Ballot

A vote cast by a neuron on a proposal.

public type Ballot = { 
    vote : Int32; 
    voting_power : Nat64 
};

vote

Int32

The vote value:

0: Unspecified (not voted)
1: Yes
2: No

voting_power

Nat64

The voting power used for this vote.

BallotInfo

Information about a neuron’s vote on a specific proposal.

public type BallotInfo = { 
    vote : Int32; 
    proposal_id : ?NeuronId 
};

vote

Int32

The vote cast (0 = unspecified, 1 = yes, 2 = no).

proposal_id

?NeuronId

The ID of the proposal this ballot is for.

Nervous System Functions

NervousSystemFunction

Defines a callable function in a governance canister.

public type NervousSystemFunction = {
    id : Nat64;
    name : Text;
    description : ?Text;
};

Nat64

The unique identifier for this function.

name

Text

The name of the function (e.g., “CreateSubnet”, “AddNodeToSubnet”).

description

?Text

Optional description of what this function does.

ListNervousSystemFunctionsResponse

Response containing the list of available nervous system functions.

public type ListNervousSystemFunctionsResponse = {
    reserved_ids : [Nat64];
    functions : [NervousSystemFunction];
};

functions

[NervousSystemFunction]

Array of available nervous system functions.

reserved_ids

[Nat64]

Array of function IDs that are reserved and cannot be used for custom functions.

Error Types

GovernanceError

Error information returned by governance operations.

public type GovernanceError = { 
    error_message : Text; 
    error_type : Int32 
};

error_message

Text

Human-readable error message.

error_type

Int32

Error type code indicating the category of error.

Governance Canister Interface

GovernanceCanister

The actor interface for interacting with governance canisters.

public type GovernanceCanister = actor {
    // Query Methods
    get_pending_proposals : shared query () -> async [ProposalInfo];
    get_proposal_info : shared query Nat64 -> async ?ProposalInfo;
    list_proposals : shared query ListProposalInfo -> async ListProposalInfoResponse;
    get_metadata : shared query () -> async ({
        url: ?Text; 
        logo: ?Text; 
        name: ?Text; 
        description: ?Text
    });
    list_nervous_system_functions : shared query () -> async ListNervousSystemFunctionsResponse;
    
    // ... (additional methods)
};

This type defines the interface for making calls to governance canisters. The GovernanceService uses this interface internally.

Network Economics Types

NetworkEconomics

Parameters that govern the economic model of the network.

public type NetworkEconomics = {
    neuron_minimum_stake_e8s : Nat64;
    max_proposals_to_keep_per_topic : Nat32;
    neuron_management_fee_per_proposal_e8s : Nat64;
    reject_cost_e8s : Nat64;
    transaction_fee_e8s : Nat64;
    neuron_spawn_dissolve_delay_seconds : Nat64;
    minimum_icp_xdr_rate : Nat64;
    maximum_node_provider_rewards_e8s : Nat64;
};

neuron_minimum_stake_e8s

Nat64

Minimum amount of ICP (in e8s) required to create a neuron.

reject_cost_e8s

Nat64

Cost (in e8s) for a rejected proposal.

transaction_fee_e8s

Nat64

Transaction fee for ledger operations (in e8s).

Additional Types

DissolveState

Represents the dissolve state of a neuron.

public type DissolveState = {
    #DissolveDelaySeconds : Nat64;
    #WhenDissolvedTimestampSeconds : Nat64;
};

DissolveDelaySeconds: Neuron is not dissolving, has this delay remaining
WhenDissolvedTimestampSeconds: Neuron is dissolving, will be dissolved at this timestamp

Followees

List of neurons that are followed for a specific topic.

public type Followees = { followees : [NeuronId] };

KnownNeuronData

Metadata for publicly known neurons.

public type KnownNeuronData = { 
    name : Text; 
    description : ?Text 
};

name

Text

The public name of the neuron.

description

?Text

Optional description of the neuron’s purpose or owner.

Working with E8s

Many values in the governance types use “e8s” (satoshis) as the unit:

1 ICP = 100,000,000 e8s
1 e8s = 0.00000001 ICP

This provides precision for fractional ICP amounts. When displaying values to users, convert from e8s to ICP:

let icpAmount = Float.fromInt(Int64.toInt(Int64.fromNat64(stake_e8s))) / 100_000_000.0;

NNS Function IDs

The GovernanceUtils module provides a list of NNS function IDs and their names. For example:

0: Unspecified
1: CreateSubnet
2: AddNodeToSubnet
3: NnsCanisterInstall
4: NnsCanisterUpgrade
And many more…

These IDs correspond to the various system functions that can be executed via NNS proposals.

GovernanceService - Methods for interacting with governance canisters
OpenChat Bot SDK Overview - Getting started with the SDK

Type Usage Examples

Filtering Proposals

import GT "./Governance/GovernanceTypes";

let filter : GT.ListProposalInfo = {
    limit = 50;
    before_proposal = null;
    include_status = [1]; // Only open proposals
    include_reward_status = [];
    exclude_topic = [8]; // Exclude topic 8
    omit_large_fields = ?true;
    include_all_manage_neuron_proposals = ?false;
};

Checking Vote Tallies

func isProposalPassing(proposal : GT.ProposalInfo) : Bool {
    switch (proposal.latest_tally) {
        case (?tally) {
            tally.yes > tally.no
        };
        case null false;
    };
};

Processing Proposal Actions

func getProposalType(proposal : GT.ProposalInfo) : Text {
    switch (proposal.proposal) {
        case (?prop) {
            switch (prop.action) {
                case (?#Motion(_)) "Motion";
                case (?#ManageNeuron(_)) "Manage Neuron";
                case (?#ExecuteNnsFunction(_)) "Execute NNS Function";
                case (?#ManageNetworkEconomics(_)) "Network Economics";
                case _ "Other";
            };
        };
        case null "Unknown";
    };
};

Bot Service

OpenChat API

Governance

Proposal Management

Utilities

​Overview

​Core Types

​ProposalInfo

​Proposal

​Action

​Tally

​ListProposalInfo

​ListProposalInfoResponse

​Neuron Types

​NeuronId

​Neuron

​NeuronInfo

​Voting Types

​Ballot

​BallotInfo

​Nervous System Functions

​NervousSystemFunction

​ListNervousSystemFunctionsResponse

​Error Types

​GovernanceError

​Governance Canister Interface

​GovernanceCanister

​Network Economics Types

​NetworkEconomics

​Additional Types

​DissolveState

​Followees

​KnownNeuronData

​Working with E8s

​NNS Function IDs

​Related Documentation

​Type Usage Examples

​Filtering Proposals

​Checking Vote Tallies

​Processing Proposal Actions

Build docs developers (and LLMs) love

Overview

Core Types

ProposalInfo

Proposal

Action

Tally

ListProposalInfo

ListProposalInfoResponse

Neuron Types

NeuronId

Neuron

NeuronInfo

Voting Types

Ballot

BallotInfo

Nervous System Functions

NervousSystemFunction

ListNervousSystemFunctionsResponse

Error Types

GovernanceError

Governance Canister Interface

GovernanceCanister

Network Economics Types

NetworkEconomics

Additional Types

DissolveState

Followees

KnownNeuronData

Working with E8s

NNS Function IDs

Related Documentation

Type Usage Examples

Filtering Proposals

Checking Vote Tallies

Processing Proposal Actions