@dfinity/sns

sns-js

A library for interfacing with a Service Nervous System (SNS) project.

Table of contents

• Installation
• Usage
• Features

Installation

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

npm i @dfinity/sns

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 @dfinity/ledger

Usage

sns-js can be utilized with two distinct approaches. The first approach is explorative, where you only need to provide the SNS root canister ID of your project to initialize a wrapper that handles routing the calls to the appropriate canister. This means having a single entry point for all functions. The second approach, which is more common, involves instantiating the specific canisters you require.

Explorative way

The explorative approach has the advantage to simplify the code but, implies more costs as it queries the root canister for the list of canister IDs of the Sns project upon initialization.

import { createAgent } from "@dfinity/utils";
import { initSnsWrapper } from "@dfinity/sns";

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

const snsWrapper = await initSnsWrapper({
  rootOptions: {
    canisterId: rootCanisterId,
  },
  agent,
  certified,
});

const { metadata, swapState } = wrapper;
const [data, token] = await metadata({});

console.log("Sns:", data, token, swapState);

Descriptive way

The descriptive approach limits the scope of the features but, is more verbose.

import { createAgent } from "@dfinity/utils";
import { SnsGovernanceCanister } from "@dfinity/sns";

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

const { metadata } = SnsGovernanceCanister.create({
  agent,
  canisterId: rootCanisterId,
});

const data = await metadata({ certified: true });

console.log("Summary data:", data);

Features

sns-js implements following features:

🧰 Functions

• initSnsWrapper

⚙️ initSnsWrapper

Lookup for the canister ids of a Sns and initialize the wrapper to access its features.

Function	Type
initSnsWrapper	InitSnsWrapper

🔗 Source

🏭 SnsGovernanceCanister

🔗 Source

Methods

• create
• listNeurons
• listProposals
• getProposal
• listNervousSystemFunctions
• metadata
• nervousSystemParameters
• getNeuron
• queryNeuron
• manageNeuron
• addNeuronPermissions
• removeNeuronPermissions
• splitNeuron
• disburse
• startDissolving
• stopDissolving
• stakeMaturity
• disburseMaturity
• autoStakeMaturity
• setDissolveTimestamp
• increaseDissolveDelay
• setTopicFollowees
• registerVote
• refreshNeuron
• claimNeuron

⚙️ create

Instantiate a canister to interact with the governance of a Sns project.

Method	Type
create	(options: SnsCanisterOptions<_SERVICE>) => SnsGovernanceCanister

Parameters:

• options: Miscellaneous options to initialize the canister. Its ID being the only mandatory parammeter.

🔗 Source

⚙️ listNeurons

List the neurons of the Sns

Method	Type
listNeurons	(params: SnsListNeuronsParams) => Promise<Neuron[]>

🔗 Source

⚙️ listProposals

List the proposals of the Sns

Method	Type
listProposals	(params: SnsListProposalsParams) => Promise<ListProposalsResponse>

🔗 Source

⚙️ getProposal

Get the proposal of the Sns

Method	Type
getProposal	(params: SnsGetProposalParams) => Promise<ProposalData>

🔗 Source

⚙️ listNervousSystemFunctions

List Nervous System Functions Neurons can follow other neurons in specific Nervous System Functions.

Method	Type
listNervousSystemFunctions	(params: QueryParams) => Promise<ListNervousSystemFunctionsResponse>

🔗 Source

⚙️ metadata

Get the Sns metadata (title, description, etc.)

Method	Type
metadata	(params: QueryParams) => Promise<GetMetadataResponse>

🔗 Source

⚙️ nervousSystemParameters

Get the Sns nervous system parameters (default followees, max dissolve delay, max number of neurons, etc.)

Method	Type
nervousSystemParameters	(params: QueryParams) => Promise<NervousSystemParameters>

🔗 Source

⚙️ getNeuron

Get the neuron of the Sns

Method	Type
getNeuron	(params: SnsGetNeuronParams) => Promise<Neuron>

🔗 Source

⚙️ queryNeuron

Same as getNeuron but returns undefined instead of raising error when not found.

Method	Type
queryNeuron	(params: SnsGetNeuronParams) => Promise<Neuron or undefined>

🔗 Source

⚙️ manageNeuron

Manage neuron. For advanced users.

Method	Type
manageNeuron	(request: ManageNeuron) => Promise<ManageNeuronResponse>

🔗 Source

⚙️ addNeuronPermissions

Add permissions to a neuron for a specific principal

Method	Type
addNeuronPermissions	(params: SnsNeuronPermissionsParams) => Promise<void>

🔗 Source

⚙️ removeNeuronPermissions

Remove permissions to a neuron for a specific principal

Method	Type
removeNeuronPermissions	(params: SnsNeuronPermissionsParams) => Promise<void>

🔗 Source

⚙️ splitNeuron

Split neuron

Method	Type
splitNeuron	(params: SnsSplitNeuronParams) => Promise<NeuronId or undefined>

🔗 Source

⚙️ disburse

Disburse neuron on Account

Method	Type
disburse	(params: SnsDisburseNeuronParams) => Promise<void>

🔗 Source

⚙️ startDissolving

Start dissolving process of a neuron

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

🔗 Source

⚙️ stopDissolving

Stop dissolving process of a neuron

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

🔗 Source

⚙️ stakeMaturity

Stake the maturity of a neuron.

Method	Type
stakeMaturity	({ neuronId, percentageToStake, }: SnsNeuronStakeMaturityParams) => 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

⚙️ disburseMaturity

Disburse the maturity of a neuron.

Method	Type
disburseMaturity	(params: SnsNeuronDisburseMaturityParams) => Promise<void>

Parameters:

• toAccount. Account: to disburse maturity.
• neuronId: The id of the neuron for which to disburse the maturity
• percentageToDisburse: What percentage of the available maturity to disburse.

🔗 Source

⚙️ autoStakeMaturity

Changes auto-stake maturity for a Neuron.

Method	Type
autoStakeMaturity	(params: SnsNeuronAutoStakeMaturityParams) => 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

⚙️ setDissolveTimestamp

Increase dissolve delay of a neuron

Method	Type
setDissolveTimestamp	(params: SnsSetDissolveTimestampParams) => Promise<void>

🔗 Source

⚙️ increaseDissolveDelay

Increase dissolve delay of a neuron

Method	Type
increaseDissolveDelay	(params: SnsIncreaseDissolveDelayParams) => Promise<void>

🔗 Source

⚙️ setTopicFollowees

Sets followees of a neuron for a specific Nervous System Function (topic)

Method	Type
setTopicFollowees	(params: SnsSetTopicFollowees) => Promise<void>

🔗 Source

⚙️ registerVote

Registers vote for a proposal from the neuron passed.

Method	Type
registerVote	(params: SnsRegisterVoteParams) => Promise<void>

🔗 Source

⚙️ refreshNeuron

Refresh neuron

Method	Type
refreshNeuron	(neuronId: NeuronId) => Promise<void>

🔗 Source

⚙️ claimNeuron

Claim neuron

Method	Type
claimNeuron	({ memo, controller, subaccount, }: SnsClaimNeuronParams) => Promise<NeuronId>

🔗 Source

🏭 SnsRootCanister

🔗 Source

Methods

• create
• listSnsCanisters

⚙️ create

Method	Type
create	(options: SnsCanisterOptions<_SERVICE>) => SnsRootCanister

🔗 Source

⚙️ listSnsCanisters

List the canisters that are part of the Sns.

Source code: https://github.com/dfinity/ic/blob/master/rs/sns/root/src/lib.rs

Method	Type
listSnsCanisters	({ certified, }: { certified?: boolean or undefined; }) => Promise<ListSnsCanistersResponse>

Parameters:

• params.certified: - Query or update calls

🔗 Source

🏭 SnsSwapCanister

🔗 Source

Methods

• create
• state
• notifyPaymentFailure
• notifyParticipation
• getUserCommitment
• getDerivedState
• getSaleParameters
• getOpenTicket
• newSaleTicket
• getLifecycle
• getFinalizationStatus

⚙️ create

Method	Type
create	(options: SnsCanisterOptions<_SERVICE>) => SnsSwapCanister

🔗 Source

⚙️ state

Get the state of the swap

Method	Type
state	(params: QueryParams) => Promise<GetStateResponse>

🔗 Source

⚙️ notifyPaymentFailure

Notify of the payment failure to remove the ticket

Method	Type
notifyPaymentFailure	() => Promise<Ticket or undefined>

🔗 Source

⚙️ notifyParticipation

Notify of the user participating in the swap

Method	Type
notifyParticipation	(params: RefreshBuyerTokensRequest) => Promise<RefreshBuyerTokensResponse>

🔗 Source

⚙️ getUserCommitment

Get user commitment

Method	Type
getUserCommitment	(params: GetBuyerStateRequest and QueryParams) => Promise<BuyerState or undefined>

🔗 Source

⚙️ getDerivedState

Get sale buyers state

Method	Type
getDerivedState	({ certified, }: QueryParams) => Promise<GetDerivedStateResponse>

🔗 Source

⚙️ getSaleParameters

Get sale parameters

Method	Type
getSaleParameters	({ certified, }: QueryParams) => Promise<GetSaleParametersResponse>

🔗 Source

⚙️ getOpenTicket

Return a sale ticket if created and not yet removed (payment flow)

Method	Type
getOpenTicket	(params: QueryParams) => Promise<Ticket or undefined>

🔗 Source

⚙️ newSaleTicket

Create a sale ticket (payment flow)

Method	Type
newSaleTicket	(params: NewSaleTicketParams) => Promise<Ticket>

🔗 Source

⚙️ getLifecycle

Get sale lifecycle state

Method	Type
getLifecycle	(params: QueryParams) => Promise<GetLifecycleResponse>

🔗 Source

⚙️ getFinalizationStatus

Get sale lifecycle state

Method	Type
getFinalizationStatus	(params: QueryParams) => Promise<GetAutoFinalizationStatusResponse>

🔗 Source

🏭 SnsWrapper

Sns wrapper - notably used by NNS-dapp - ease the access to a particular Sns. It knows all the Sns' canisters, wrap and enhance their available features. A wrapper either performs query or update calls.

🔗 Source

Constructors

public: Constructor to instantiate a Sns

Parameters:

• __0

Methods

• listNeurons
• listProposals
• getProposal
• listNervousSystemFunctions
• metadata
• nervousSystemParameters
• ledgerMetadata
• transactionFee
• totalTokensSupply
• balance
• transfer
• getNeuron
• queryNeuron
• nextNeuronAccount
• stakeNeuron
• increaseStakeNeuron
• getNeuronBalance
• addNeuronPermissions
• refreshNeuron
• claimNeuron
• removeNeuronPermissions
• splitNeuron
• disburse
• startDissolving
• stopDissolving
• setDissolveTimestamp
• increaseDissolveDelay
• setTopicFollowees
• registerVote
• swapState
• notifyPaymentFailure
• notifyParticipation
• getUserCommitment
• getOpenTicket
• newSaleTicket
• getLifecycle
• getFinalizationStatus
• getSaleParameters
• getDerivedState
• getTransactions
• stakeMaturity
• disburseMaturity
• autoStakeMaturity

⚙️ listNeurons

Method	Type
listNeurons	(params: Omit<SnsListNeuronsParams, "certified">) => Promise<Neuron[]>

🔗 Source

⚙️ listProposals

Method	Type
listProposals	(params: Omit<SnsListProposalsParams, "certified">) => Promise<ListProposalsResponse>

🔗 Source

⚙️ getProposal

Method	Type
getProposal	(params: Omit<SnsGetProposalParams, "certified">) => Promise<ProposalData>

🔗 Source

⚙️ listNervousSystemFunctions

Method	Type
listNervousSystemFunctions	(params: Omit<QueryParams, "certified">) => Promise<ListNervousSystemFunctionsResponse>

🔗 Source

⚙️ metadata

Method	Type
metadata	(params: Omit<QueryParams, "certified">) => Promise<[GetMetadataResponse, IcrcTokenMetadataResponse]>

🔗 Source

⚙️ nervousSystemParameters

Method	Type
nervousSystemParameters	(params: Omit<QueryParams, "certified">) => Promise<NervousSystemParameters>

🔗 Source

⚙️ ledgerMetadata

Method	Type
ledgerMetadata	(params: Omit<QueryParams, "certified">) => Promise<IcrcTokenMetadataResponse>

🔗 Source

⚙️ transactionFee

Method	Type
transactionFee	(params: Omit<QueryParams, "certified">) => Promise<bigint>

🔗 Source

⚙️ totalTokensSupply

Method	Type
totalTokensSupply	(params: Omit<QueryParams, "certified">) => Promise<bigint>

🔗 Source

⚙️ balance

Method	Type
balance	(params: Omit<BalanceParams, "certified">) => Promise<bigint>

🔗 Source

⚙️ transfer

Method	Type
transfer	(params: TransferParams) => Promise<bigint>

🔗 Source

⚙️ getNeuron

Method	Type
getNeuron	(params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron>

🔗 Source

⚙️ queryNeuron

Method	Type
queryNeuron	(params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron or undefined>

🔗 Source

⚙️ nextNeuronAccount

Returns the subaccount of the next neuron to be created.

The neuron account is a subaccount of the governance canister. The subaccount is derived from the controller and an ascending index.

‼️ The id of the neuron is the subaccount (neuron ID = subaccount) ‼️.

If the neuron does not exist for that subaccount, then we use it for the next neuron.

The index is used in the memo of the transfer and when claiming the neuron. This is how the backend can identify which neuron is being claimed.

Method	Type
nextNeuronAccount	(controller: Principal) => Promise<{ account: IcrcAccount; index: bigint; }>

🔗 Source

⚙️ stakeNeuron

Stakes a neuron.

This is a convenient method that transfers the stake to the neuron subaccount and then claims the neuron.

⚠️ This feature is provided as it without warranty. It does not implement any additional checks of the validity of the payment flow - e.g. it does not handle refund nor retries claiming the neuron in case of errors.

Method	Type
stakeNeuron	({ stakeE8s, source, controller, createdAt, fee, }: SnsStakeNeuronParams) => Promise<NeuronId>

🔗 Source

⚙️ increaseStakeNeuron

Increase the stake of a neuron.

This is a convenient method that transfers the stake to the neuron subaccount and then refresh the neuron.

⚠️ This feature is provided as it without warranty. It does not implement any additional checks of the validity of the payment flow - e.g. it does not handle refund nor calls refresh again in case of errors.

Method	Type
increaseStakeNeuron	({ stakeE8s, source, neuronId, }: SnsIncreaseStakeNeuronParams) => Promise<void>

🔗 Source

⚙️ getNeuronBalance

Method	Type
getNeuronBalance	(neuronId: NeuronId) => Promise<bigint>

🔗 Source

⚙️ addNeuronPermissions

Method	Type
addNeuronPermissions	(params: SnsNeuronPermissionsParams) => Promise<void>

🔗 Source

⚙️ refreshNeuron

Method	Type
refreshNeuron	(neuronId: NeuronId) => Promise<void>

🔗 Source

⚙️ claimNeuron

Method	Type
claimNeuron	(params: SnsClaimNeuronParams) => Promise<NeuronId>

🔗 Source

⚙️ removeNeuronPermissions

Method	Type
removeNeuronPermissions	(params: SnsNeuronPermissionsParams) => Promise<void>

🔗 Source

⚙️ splitNeuron

Method	Type
splitNeuron	(params: SnsSplitNeuronParams) => Promise<NeuronId or undefined>

🔗 Source

⚙️ disburse

Method	Type
disburse	(params: SnsDisburseNeuronParams) => Promise<void>

🔗 Source

⚙️ startDissolving

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

🔗 Source

⚙️ stopDissolving

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

🔗 Source

⚙️ setDissolveTimestamp

Method	Type
setDissolveTimestamp	(params: SnsSetDissolveTimestampParams) => Promise<void>

🔗 Source

⚙️ increaseDissolveDelay

Method	Type
increaseDissolveDelay	(params: SnsIncreaseDissolveDelayParams) => Promise<void>

🔗 Source

⚙️ setTopicFollowees

Method	Type
setTopicFollowees	(params: SnsSetTopicFollowees) => Promise<void>

🔗 Source

⚙️ registerVote

Method	Type
registerVote	(params: SnsRegisterVoteParams) => Promise<void>

🔗 Source

⚙️ swapState

Method	Type
swapState	(params: Omit<QueryParams, "certified">) => Promise<GetStateResponse>

🔗 Source

⚙️ notifyPaymentFailure

Returns the ticket if a ticket was found for the caller and the ticket was removed successfully. Returns None if no ticket was found for the caller. Only the owner of a ticket can remove it.

Always certified

Method	Type
notifyPaymentFailure	() => Promise<Ticket or undefined>

🔗 Source

⚙️ notifyParticipation

Method	Type
notifyParticipation	(params: RefreshBuyerTokensRequest) => Promise<RefreshBuyerTokensResponse>

🔗 Source

⚙️ getUserCommitment

Method	Type
getUserCommitment	(params: GetBuyerStateRequest) => Promise<BuyerState or undefined>

🔗 Source

⚙️ getOpenTicket

Method	Type
getOpenTicket	(params: Omit<QueryParams, "certified">) => Promise<Ticket or undefined>

🔗 Source

⚙️ newSaleTicket

Method	Type
newSaleTicket	(params: NewSaleTicketParams) => Promise<Ticket>

🔗 Source

⚙️ getLifecycle

Method	Type
getLifecycle	(params: Omit<QueryParams, "certified">) => Promise<GetLifecycleResponse or undefined>

🔗 Source

⚙️ getFinalizationStatus

Method	Type
getFinalizationStatus	(params: Omit<QueryParams, "certified">) => Promise<GetAutoFinalizationStatusResponse or undefined>

🔗 Source

⚙️ getSaleParameters

Method	Type
getSaleParameters	(params: Omit<QueryParams, "certified">) => Promise<GetSaleParametersResponse or undefined>

🔗 Source

⚙️ getDerivedState

Method	Type
getDerivedState	(params: Omit<QueryParams, "certified">) => Promise<GetDerivedStateResponse or undefined>

🔗 Source

⚙️ getTransactions

Method	Type
getTransactions	(params: GetAccountTransactionsParams) => Promise<GetTransactions>

🔗 Source

⚙️ stakeMaturity

Method	Type
stakeMaturity	(params: SnsNeuronStakeMaturityParams) => Promise<void>

🔗 Source

⚙️ disburseMaturity

Method	Type
disburseMaturity	(params: SnsNeuronDisburseMaturityParams) => Promise<void>

🔗 Source

⚙️ autoStakeMaturity

Method	Type
autoStakeMaturity	(params: SnsNeuronAutoStakeMaturityParams) => Promise<void>

🔗 Source