JSPM

@dfinity/nns

0.9.0-next-2022-09-28
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 15756
  • Score
    100M100P100Q143214F
  • License Apache-2.0

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

Package Exports

  • @dfinity/nns
  • @dfinity/nns/dist/cjs/index.cjs.js
  • @dfinity/nns/dist/esm/index.js

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. e.g. querying the ledger for an account balance in a NodeJS context can be developed as following:

import { AccountIdentifier, LedgerCanister } from "@dfinity/nns";

// If not running in browser, add polyfill of `window.fetch` for agent-js to work.
import fetch from "cross-fetch";
global.fetch = fetch;

const main = async () => {
  const ledger = LedgerCanister.create();

  const accountIdentifier = AccountIdentifier.fromHex(
    "efa01544f509c56dd85449edf2381244a48fad1ede5183836229c00ab00d52df"
  );

  const balance = await ledger.accountBalance({ accountIdentifier });

  console.log(`Balance: ${balance.toE8s()}`);
};

await main();

Features

nns-js implements following features:

🧰 Functions

⚙️ convertStringToE8s

Receives a string representing a number and returns the big int or error.

Function Type
convertStringToE8s (amount: string) => bigint or FromStringToTokenError

Parameters:

  • amount: - in string format

🔧 Constants

⚙️ ICPToken

Constant Type
ICPToken Token

🏭 AccountIdentifier

Methods

⚙️ fromHex
Method Type
fromHex (hex: string) => AccountIdentifier
⚙️ fromPrincipal
Method Type
fromPrincipal ({ principal, subAccount, }: { principal: Principal; subAccount?: SubAccount; }) => AccountIdentifier
⚙️ toProto
Method Type
toProto () => AccountIdentifier
⚙️ toHex
Method Type
toHex () => string
⚙️ toUint8Array
Method Type
toUint8Array () => Uint8Array
⚙️ toNumbers
Method Type
toNumbers () => number[]
⚙️ toAccountIdentifierHash
Method Type
toAccountIdentifierHash () => AccountIdentifier

🏭 SubAccount

Methods

⚙️ fromBytes
Method Type
fromBytes (bytes: Uint8Array) => SubAccount or Error
⚙️ fromPrincipal
Method Type
fromPrincipal (principal: Principal) => SubAccount
⚙️ fromID
Method Type
fromID (id: number) => SubAccount
⚙️ toUint8Array
Method Type
toUint8Array () => Uint8Array

🏭 GenesisTokenCanister

Methods

⚙️ create
Method Type
create (options?: CanisterOptions<_SERVICE>) => GenesisTokenCanister
⚙️ claimNeurons
Method Type
claimNeurons ({ hexPubKey, }: { hexPubKey: string; }) => Promise<bigint[]>

🏭 TokenAmount

Represents an amount of tokens.

Methods

⚙️ fromE8s

Initialize from a bigint. Bigint are considered e8s.

Method Type
fromE8s ({ amount, token, }: { amount: bigint; token: Token; }) => TokenAmount

Parameters:

  • params.amount: The amount in bigint format.
  • params.token: The token type.
⚙️ fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Method Type
fromString ({ amount, token, }: { amount: string; token: Token; }) => FromStringToTokenError or TokenAmount

Parameters:

  • params.amount: The amount in string format.
  • params.token: The token type.
⚙️ fromNumber

Initialize from a number.

1 integer is considered E8S_PER_TOKEN

Method Type
fromNumber ({ amount, token, }: { amount: number; token: Token; }) => TokenAmount

Parameters:

  • params.amount: The amount in number format.
  • params.token: The token type.
⚙️ toE8s
Method Type
toE8s () => bigint
⚙️ toProto

TODO: Remove this method when ICP class is not used anymore

Method Type
toProto () => ICPTs

🏭 LedgerCanister

Methods

⚙️ create
Method Type
create (options?: LedgerCanisterOptions) => LedgerCanister
⚙️ accountBalance

Returns the balance of the specified account identifier.

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

Method Type
accountBalance ({ accountIdentifier, certified, }: { accountIdentifier: AccountIdentifier; certified?: boolean; }) => Promise<bigint>
⚙️ transactionFee

Returns the transaction fee of the ledger canister

Method Type
transactionFee () => Promise<bigint>
⚙️ transfer

Transfer ICP from the caller to the destination accountIdentifier. Returns the index of the block containing the tx if it was successful.

Method Type
transfer (request: TransferRequest) => Promise<bigint>

🏭 GovernanceCanister

Methods

⚙️ create
Method Type
create (options?: GovernanceCanisterOptions) => GovernanceCanister
⚙️ 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.

Method Type
listNeurons ({ certified, neuronIds, }: { certified: boolean; neuronIds?: bigint[]; }) => Promise<NeuronInfo[]>
⚙️ 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[]>
⚙️ 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; }) => Promise<ListProposalsResponse>

Parameters:

  • request: the options to list the proposals (limit number of results, topics to search for, etc.)
  • certified: query or update calls
⚙️ stakeNeuron
Method Type
stakeNeuron ({ stake, principal, fromSubAccount, ledgerCanister, }: { stake: bigint; principal: Principal; fromSubAccount?: number[]; ledgerCanister: LedgerCanister; }) => Promise<bigint>
⚙️ increaseDissolveDelay

Increases dissolve delay of a neuron

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

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

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

Start dissolving process of a neuron

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

Stop dissolving process of a neuron

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

Neuron joins the community fund

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

Neuron leaves the community fund

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

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

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

Merge two neurons

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

Splits a neuron creating a new one

Method Type
splitNeuron ({ neuronId, amount, }: { neuronId: bigint; amount: bigint; }) => Promise<bigint>
⚙️ 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; }) => Promise<ProposalInfo>
⚙️ makeProposal

Create new proposal

Method Type
makeProposal (request: MakeProposalRequest) => Promise<void>
⚙️ registerVote

Registers vote for a proposal from the neuron passed.

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

Edit neuron followees per topic

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

Disburse neuron on Account

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

Merge Maturity of a neuron

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

Merge Maturity of a neuron

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

Add hotkey to neuron

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

Remove hotkey to neuron

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

Gets the NeuronID of a newly created neuron.

Method Type
claimOrRefreshNeuronFromAccount ({ memo, controller, }: { memo: bigint; controller?: Principal; }) => Promise<bigint>
⚙️ claimOrRefreshNeuron

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

Method Type
claimOrRefreshNeuron (request: ClaimOrRefreshNeuronRequest) => Promise<bigint>
⚙️ getNeuron

Return the data of the neuron provided as id.

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

🏭 ICP

We don't extend to keep fromE8s and fromString as backwards compatible.

Methods

⚙️ fromE8s
Method Type
fromE8s (amount: bigint) => ICP
⚙️ fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Method Type
fromString (amount: string) => FromStringToTokenError or ICP
⚙️ toE8s
Method Type
toE8s () => bigint
⚙️ toProto
Method Type
toProto () => ICPTs

🏭 SnsWasmCanister

Methods

⚙️ create
Method Type
create (options?: CanisterOptions<_SERVICE>) => SnsWasmCanister
⚙️ listSnses
Method Type
listSnses ({ certified, }: { certified?: boolean; }) => Promise<DeployedSns[]>