JSPM

@dfinity/nns

8.3.1-next-2025-03-03
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 17594
  • Score
    100M100P100Q153649F
  • License Apache-2.0

A library for interfacing with the Internet Computer's Network Nervous System.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@dfinity/nns) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    nns-js

    A library for interfacing with the Internet Computer's Network Nervous System.

    npm version GitHub license

    Table of contents

    Installation

    You can use nns-js by installing it in your project.

    npm i @dfinity/nns

    The bundle needs peer dependencies, be sure that following resources are available in your project as well.

    npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils

    Usage

    Most features are provided through the use of classes. For example, querying the list of neurons controlled by the caller with the governance canister:

    import { GovernanceCanister } from "@dfinity/nns";
import { createAgent } from "@dfinity/utils";

const agent = await createAgent({
  identity,
  host: HOST,
});

const { listNeurons } = GovernanceCanister.create({
  agent,
  canisterId: MY_GOVERNANCE_CANISTER_ID,
});

const myNeurons = await listNeurons({ certified: false });

    To execute this on a local environment, you will need to fetch the root key when initializing the agent. Additionally, you might need to adapt the port. The following snippet also demonstrates how you can inline a canister ID as well.

    import { GovernanceCanister } from "@dfinity/nns";
import { Principal } from "@dfinity/principal";
import { createAgent } from "@dfinity/utils";

const agent = await createAgent({
  identity,
  host: "http://localhost:8000",
  fetchRootKey: true,
});

const { listNeurons } = GovernanceCanister.create({
  agent,
  canisterId: Principal.fromText("rrkah-fqaaa-aaaaa-aaaaq-cai"),
});

const myNeurons = await listNeurons({ certified: false });

    Features

    nns-js implements following features:

    🧰 Functions

    ⚙️ ineligibleNeurons

    Filter the neurons that are ineligible to vote to a proposal.

    This feature needs the ballots of the proposal to contains accurate data. If the proposal has settled, as the ballots of the proposal are emptied for archive purpose, the function might return a list of ineligible neurons that are actually neurons that have not voted but would have been eligible.

    Long story short, check the status of the proposal before using this function.

    Function Type
    ineligibleNeurons ({ neurons, proposal, }: { neurons: NeuronInfo[]; proposal: ProposalInfo; }) => NeuronInfo[]

    Parameters:

    • params.neurons: The neurons to filter.
    • params.proposal: The proposal to match against the selected neurons.

    🔗 Source

    ⚙️ votableNeurons

    Filter the neurons that can vote for a proposal - i.e. the neurons that have not voted yet and are eligible

    Function Type
    votableNeurons ({ neurons, proposal, }: { neurons: NeuronInfo[]; proposal: ProposalInfo; }) => NeuronInfo[]

    Parameters:

    • params.neurons: The neurons to filter.
    • params.proposal: The proposal to match against the selected neurons.

    🔗 Source

    ⚙️ votedNeurons

    Filter the neurons that have voted for a proposal.

    Function Type
    votedNeurons ({ neurons, proposal, }: { neurons: NeuronInfo[]; proposal: ProposalInfo; }) => NeuronInfo[]

    Parameters:

    • params.neurons: The neurons to filter.
    • params.proposal: The proposal for which some neurons might have already voted.

    🔗 Source

    ⚙️ memoToNeuronSubaccount

    Function Type
    memoToNeuronSubaccount ({ controller, memo, }: { controller: Principal; memo: bigint; }) => SubAccount

    🔗 Source

    ⚙️ memoToNeuronAccountIdentifier

    Function Type
    memoToNeuronAccountIdentifier ({ controller, memo, governanceCanisterId, }: { controller: Principal; memo: bigint; governanceCanisterId: Principal; }) => AccountIdentifier

    🔗 Source

    🏭 GenesisTokenCanister

    🔗 Source

    Methods

    ⚙️ create
    Method Type
    create (options?: CanisterOptions<_SERVICE>) => GenesisTokenCanister

    🔗 Source

    ⚙️ claimNeurons
    Method Type
    claimNeurons ({ hexPubKey, }: { hexPubKey: string; }) => Promise<bigint[]>

    🔗 Source

    🏭 GovernanceCanister

    🔗 Source

    Methods

    ⚙️ create
    Method Type
    create (options?: GovernanceCanisterOptions) => GovernanceCanister

    🔗 Source

    ⚙️ listNeurons

    Returns the list of neurons controlled by the caller.

    If an array of neuron IDs is provided, precisely those neurons will be fetched.

    If certified is true, the request is fetched as an update call, otherwise it is fetched using a query call.

    The backend treats includeEmptyNeurons as false if absent.

    The response from the canister might be paginated. In this case, all pages will be fetched in parallel and combined into a single return value.

    Method Type
    listNeurons ({ certified, neuronIds, includeEmptyNeurons, includePublicNeurons, neuronSubaccounts, }: { certified: boolean; neuronIds?: bigint[] or undefined; includeEmptyNeurons?: boolean or undefined; includePublicNeurons?: boolean or undefined; neuronSubaccounts?: NeuronSubaccount[] or undefined; }) => Promise<...>

    🔗 Source

    ⚙️ listKnownNeurons

    Returns the list of neurons who have been approved by the community to appear as the default followee options.

    If certified is true, the request is fetched as an update call, otherwise it is fetched using a query call.

    Method Type
    listKnownNeurons (certified?: boolean) => Promise<KnownNeuron[]>

    🔗 Source

    ⚙️ getLastestRewardEvent

    Returns the latest reward event.

    If certified is true, the request is fetched as an update call, otherwise it's fetched using a query call.

    Method Type
    getLastestRewardEvent (certified?: boolean) => Promise<RewardEvent>

    🔗 Source

    ⚙️ listProposals

    Returns the list of proposals made for the community to vote on, paginated and filtered by the request.

    If certified is true (default), the request is fetched as an update call, otherwise it is fetched using a query call.

    Method Type
    listProposals ({ request, certified, }: { request: ListProposalsRequest; certified?: boolean or undefined; }) => Promise<ListProposalsResponse>

    Parameters:

    • request: the options to list the proposals (limit number of results, topics to search for, etc.)
    • certified: query or update calls

    🔗 Source

    ⚙️ stakeNeuron
    Method Type
    stakeNeuron ({ stake, principal, fromSubAccount, ledgerCanister, createdAt, fee, }: { stake: bigint; principal: Principal; fromSubAccount?: number[] or undefined; ledgerCanister: LedgerCanister; createdAt?: bigint or undefined; fee?: bigint or undefined; }) => Promise<...>

    🔗 Source

    ⚙️ increaseDissolveDelay

    Increases dissolve delay of a neuron

    Method Type
    increaseDissolveDelay ({ neuronId, additionalDissolveDelaySeconds, }: { neuronId: bigint; additionalDissolveDelaySeconds: number; }) => Promise<void>

    🔗 Source

    ⚙️ setDissolveDelay

    Sets dissolve delay of a neuron. The new date is now + dissolveDelaySeconds.

    Method Type
    setDissolveDelay ({ neuronId, dissolveDelaySeconds, }: { neuronId: bigint; dissolveDelaySeconds: number; }) => Promise<void>

    🔗 Source

    ⚙️ startDissolving

    Start dissolving process of a neuron

    Method Type
    startDissolving (neuronId: bigint) => Promise<void>

    🔗 Source

    ⚙️ stopDissolving

    Stop dissolving process of a neuron

    Method Type
    stopDissolving (neuronId: bigint) => Promise<void>

    🔗 Source

    ⚙️ joinCommunityFund

    Neuron joins the community fund

    Method Type
    joinCommunityFund (neuronId: bigint) => Promise<void>

    🔗 Source

    ⚙️ autoStakeMaturity

    Changes auto-stake maturity for this Neuron. While on, auto-stake maturity will cause all the maturity generated by voting rewards to this neuron to be automatically staked and contribute to the voting power of the neuron.

    Method Type
    autoStakeMaturity (params: { neuronId: bigint; autoStake: boolean; }) => Promise<void>

    Parameters:

    • neuronId: The id of the neuron for which to request a change of the auto stake feature
    • autoStake: true to enable the auto-stake maturity for this neuron, false to turn it off

    🔗 Source

    ⚙️ leaveCommunityFund

    Neuron leaves the community fund

    Method Type
    leaveCommunityFund (neuronId: bigint) => Promise<void>

    🔗 Source

    ⚙️ setVisibility

    Set visibility of a neuron

    Method Type
    setVisibility (neuronId: bigint, visibility: NeuronVisibility) => Promise<void>

    🔗 Source

    ⚙️ setNodeProviderAccount

    Sets node provider reward account. Where the reward is paid to.

    Method Type
    setNodeProviderAccount (accountIdentifier: string) => Promise<void>

    🔗 Source

    ⚙️ mergeNeurons

    Merge two neurons

    Method Type
    mergeNeurons (request: { sourceNeuronId: bigint; targetNeuronId: bigint; }) => Promise<void>

    🔗 Source

    ⚙️ simulateMergeNeurons

    Simulate merging two neurons

    Method Type
    simulateMergeNeurons (request: { sourceNeuronId: bigint; targetNeuronId: bigint; }) => Promise<NeuronInfo>

    🔗 Source

    ⚙️ splitNeuron

    Splits a neuron creating a new one

    Method Type
    splitNeuron ({ neuronId, amount, }: { neuronId: bigint; amount: bigint; }) => Promise<bigint>

    🔗 Source

    ⚙️ getProposal

    Returns single proposal info

    If certified is true (default), the request is fetched as an update call, otherwise it is fetched using a query call.

    Method Type
    getProposal ({ proposalId, certified, }: { proposalId: bigint; certified?: boolean or undefined; }) => Promise<ProposalInfo or undefined>

    🔗 Source

    ⚙️ makeProposal

    Create new proposal

    Method Type
    makeProposal (request: MakeProposalRequest) => Promise<bigint or undefined>

    🔗 Source

    ⚙️ registerVote

    Registers vote for a proposal from the neuron passed.

    Method Type
    registerVote ({ neuronId, vote, proposalId, }: { neuronId: bigint; vote: Vote; proposalId: bigint; }) => Promise<void>

    🔗 Source

    ⚙️ setFollowees

    Edit neuron followees per topic

    Method Type
    setFollowees (followRequest: FollowRequest) => Promise<void>

    🔗 Source

    ⚙️ disburse

    Disburse neuron on Account

    Method Type
    disburse ({ neuronId, toAccountId, amount, }: { neuronId: bigint; toAccountId?: string or undefined; amount?: bigint or undefined; }) => Promise<void>

    🔗 Source

    ⚙️ refreshVotingPower

    Refreshes voting power of a neuron (Resets the votingPowerRefreshedTimestampSeconds parameter of the neuron to the current time).

    Method Type
    refreshVotingPower ({ neuronId, }: { neuronId: bigint; }) => Promise<void>

    🔗 Source

    ⚙️ mergeMaturity

    Merge Maturity of a neuron

    Method Type
    mergeMaturity ({ neuronId, percentageToMerge, }: { neuronId: bigint; percentageToMerge: number; }) => Promise<void>

    🔗 Source

    ⚙️ stakeMaturity

    Stake the maturity of a neuron.

    Method Type
    stakeMaturity ({ neuronId, percentageToStake, }: { neuronId: bigint; percentageToStake?: number or undefined; }) => Promise<void>

    Parameters:

    • neuronId: The id of the neuron for which to stake the maturity
    • percentageToStake: Optional. Percentage of the current maturity to stake. If not provided, all of the neuron's current maturity will be staked.

    🔗 Source

    ⚙️ spawnNeuron

    Merge Maturity of a neuron

    Method Type
    spawnNeuron ({ neuronId, percentageToSpawn, newController, nonce, }: { neuronId: bigint; percentageToSpawn?: number or undefined; newController?: Principal or undefined; nonce?: bigint or undefined; }) => Promise<bigint>

    🔗 Source

    ⚙️ addHotkey

    Add hotkey to neuron

    Method Type
    addHotkey ({ neuronId, principal, }: { neuronId: bigint; principal: Principal; }) => Promise<void>

    🔗 Source

    ⚙️ removeHotkey

    Remove hotkey to neuron

    Method Type
    removeHotkey ({ neuronId, principal, }: { neuronId: bigint; principal: Principal; }) => Promise<void>

    🔗 Source

    ⚙️ claimOrRefreshNeuronFromAccount

    Gets the NeuronID of a newly created neuron.

    Method Type
    claimOrRefreshNeuronFromAccount ({ memo, controller, }: { memo: bigint; controller?: Principal or undefined; }) => Promise<bigint or undefined>

    🔗 Source

    ⚙️ claimOrRefreshNeuron

    Refreshes neuron and returns neuronId when successful Uses query call only.

    Method Type
    claimOrRefreshNeuron (request: ClaimOrRefreshNeuronRequest) => Promise<bigint or undefined>

    🔗 Source

    ⚙️ getNeuron

    Return the data of the neuron provided as id.

    Method Type
    getNeuron ({ certified, neuronId, }: { certified: boolean; neuronId: bigint; }) => Promise<NeuronInfo or undefined>

    🔗 Source

    ⚙️ getNetworkEconomicsParameters

    Return the Network Economics.

    Method Type
    getNetworkEconomicsParameters ({ certified, }: { certified: boolean; }) => Promise<NetworkEconomics>

    🔗 Source

    🏭 SnsWasmCanister

    🔗 Source

    Methods

    ⚙️ create
    Method Type
    create (options?: CanisterOptions<_SERVICE>) => SnsWasmCanister

    🔗 Source

    ⚙️ listSnses
    Method Type
    listSnses ({ certified, }: { certified?: boolean or undefined; }) => Promise<DeployedSns[]>

    🔗 Source