nns-js
A library for interfacing with the Internet Computer's Network Nervous System.
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
⚙️ 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.
⚙️ 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.
⚙️ votedNeurons
Filter the neurons that have voted for a proposal.
Function | Type |
---|---|
votedNeurons |
({ neurons, proposal: { id: proposalId }, }: { neurons: NeuronInfo[]; proposal: ProposalInfo; }) => NeuronInfo[] |
Parameters:
-
params.neurons
: The neurons to filter. -
params.proposal
: The proposal for which some neurons might have already voted.
🔧 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
- listNeurons
- listKnownNeurons
- listProposals
- stakeNeuron
- increaseDissolveDelay
- setDissolveDelay
- startDissolving
- stopDissolving
- joinCommunityFund
- autoStakeMaturity
- leaveCommunityFund
- setNodeProviderAccount
- mergeNeurons
- splitNeuron
- getProposal
- makeProposal
- registerVote
- setFollowees
- disburse
- mergeMaturity
- stakeMaturity
- spawnNeuron
- addHotkey
- removeHotkey
- claimOrRefreshNeuronFromAccount
- claimOrRefreshNeuron
- getNeuron
⚙️ 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, createdAt, }: { stake: bigint; principal: Principal; fromSubAccount?: number[]; ledgerCanister: LedgerCanister; createdAt?: bigint; }) => 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> |
⚙️ 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
⚙️ 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> |
⚙️ stakeMaturity
Stake the maturity of a neuron.
Method | Type |
---|---|
stakeMaturity |
({ neuronId, percentageToStake, }: { neuronId: bigint; percentageToStake?: number; }) => 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.
⚙️ 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[]> |