@dfinity/sns
Advanced tools
Readme
A library for interfacing with a Service Nervous System (SNS) project.
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
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.
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);
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);
sns-js implements following features:
Lookup for the canister ids of a Sns and initialize the wrapper to access its features.
| Function | Type |
|---|---|
initSnsWrapper | InitSnsWrapper |
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.List the neurons of the Sns
| Method | Type |
|---|---|
listNeurons | (params: SnsListNeuronsParams) => Promise<Neuron[]> |
List the proposals of the Sns
| Method | Type |
|---|---|
listProposals | (params: SnsListProposalsParams) => Promise<ListProposalsResponse> |
Get the proposal of the Sns
| Method | Type |
|---|---|
getProposal | (params: SnsGetProposalParams) => Promise<ProposalData> |
List Nervous System Functions Neurons can follow other neurons in specific Nervous System Functions.
| Method | Type |
|---|---|
listNervousSystemFunctions | (params: QueryParams) => Promise<ListNervousSystemFunctionsResponse> |
Get the Sns metadata (title, description, etc.)
| Method | Type |
|---|---|
metadata | (params: QueryParams) => Promise<GetMetadataResponse> |
Get the Sns nervous system parameters (default followees, max dissolve delay, max number of neurons, etc.)
| Method | Type |
|---|---|
nervousSystemParameters | (params: QueryParams) => Promise<NervousSystemParameters> |
Get the neuron of the Sns
| Method | Type |
|---|---|
getNeuron | (params: SnsGetNeuronParams) => Promise<Neuron> |
Same as getNeuron but returns undefined instead of raising error when not found.
| Method | Type |
|---|---|
queryNeuron | (params: SnsGetNeuronParams) => Promise<Neuron or undefined> |
Manage neuron. For advanced users.
| Method | Type |
|---|---|
manageNeuron | (request: ManageNeuron) => Promise<ManageNeuronResponse> |
Add permissions to a neuron for a specific principal
| Method | Type |
|---|---|
addNeuronPermissions | (params: SnsNeuronPermissionsParams) => Promise<void> |
Remove permissions to a neuron for a specific principal
| Method | Type |
|---|---|
removeNeuronPermissions | (params: SnsNeuronPermissionsParams) => Promise<void> |
Split neuron
| Method | Type |
|---|---|
splitNeuron | (params: SnsSplitNeuronParams) => Promise<NeuronId or undefined> |
Disburse neuron on Account
| Method | Type |
|---|---|
disburse | (params: SnsDisburseNeuronParams) => Promise<void> |
Start dissolving process of a neuron
| Method | Type |
|---|---|
startDissolving | (neuronId: NeuronId) => Promise<void> |
Stop dissolving process of a neuron
| Method | Type |
|---|---|
stopDissolving | (neuronId: NeuronId) => Promise<void> |
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 maturitypercentageToStake: Optional. Percentage of the current maturity to stake. If not provided, all of the neuron's current maturity will be staked.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 maturitypercentageToDisburse: What percentage of the available maturity to disburse.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 featureautoStake: true to enable the auto-stake maturity for this neuron, false to turn it offIncrease dissolve delay of a neuron
| Method | Type |
|---|---|
setDissolveTimestamp | (params: SnsSetDissolveTimestampParams) => Promise<void> |
Increase dissolve delay of a neuron
| Method | Type |
|---|---|
increaseDissolveDelay | (params: SnsIncreaseDissolveDelayParams) => Promise<void> |
Sets followees of a neuron for a specific Nervous System Function (topic)
| Method | Type |
|---|---|
setTopicFollowees | (params: SnsSetTopicFollowees) => Promise<void> |
Registers vote for a proposal from the neuron passed.
| Method | Type |
|---|---|
registerVote | (params: SnsRegisterVoteParams) => Promise<void> |
Refresh neuron
| Method | Type |
|---|---|
refreshNeuron | (neuronId: NeuronId) => Promise<void> |
Claim neuron
| Method | Type |
|---|---|
claimNeuron | ({ memo, controller, subaccount, }: SnsClaimNeuronParams) => Promise<NeuronId> |
| Method | Type |
|---|---|
create | (options: SnsCanisterOptions<_SERVICE>) => SnsRootCanister |
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| Method | Type |
|---|---|
create | (options: SnsCanisterOptions<_SERVICE>) => SnsSwapCanister |
Get the state of the swap
| Method | Type |
|---|---|
state | (params: QueryParams) => Promise<GetStateResponse> |
Notify of the payment failure to remove the ticket
| Method | Type |
|---|---|
notifyPaymentFailure | () => Promise<Ticket or undefined> |
Notify of the user participating in the swap
| Method | Type |
|---|---|
notifyParticipation | (params: RefreshBuyerTokensRequest) => Promise<RefreshBuyerTokensResponse> |
Get user commitment
| Method | Type |
|---|---|
getUserCommitment | (params: GetBuyerStateRequest and QueryParams) => Promise<BuyerState or undefined> |
Get sale buyers state
| Method | Type |
|---|---|
getDerivedState | ({ certified, }: QueryParams) => Promise<GetDerivedStateResponse> |
Get sale parameters
| Method | Type |
|---|---|
getSaleParameters | ({ certified, }: QueryParams) => Promise<GetSaleParametersResponse> |
Return a sale ticket if created and not yet removed (payment flow)
| Method | Type |
|---|---|
getOpenTicket | (params: QueryParams) => Promise<Ticket or undefined> |
Create a sale ticket (payment flow)
| Method | Type |
|---|---|
newSaleTicket | (params: NewSaleTicketParams) => Promise<Ticket> |
Get sale lifecycle state
| Method | Type |
|---|---|
getLifecycle | (params: QueryParams) => Promise<GetLifecycleResponse> |
Get sale lifecycle state
| Method | Type |
|---|---|
getFinalizationStatus | (params: QueryParams) => Promise<GetAutoFinalizationStatusResponse> |
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.
public: Constructor to instantiate a Sns
Parameters:
__0| Method | Type |
|---|---|
listNeurons | (params: Omit<SnsListNeuronsParams, "certified">) => Promise<Neuron[]> |
| Method | Type |
|---|---|
listProposals | (params: Omit<SnsListProposalsParams, "certified">) => Promise<ListProposalsResponse> |
| Method | Type |
|---|---|
getProposal | (params: Omit<SnsGetProposalParams, "certified">) => Promise<ProposalData> |
| Method | Type |
|---|---|
listNervousSystemFunctions | (params: Omit<QueryParams, "certified">) => Promise<ListNervousSystemFunctionsResponse> |
| Method | Type |
|---|---|
metadata | (params: Omit<QueryParams, "certified">) => Promise<[GetMetadataResponse, IcrcTokenMetadataResponse]> |
| Method | Type |
|---|---|
nervousSystemParameters | (params: Omit<QueryParams, "certified">) => Promise<NervousSystemParameters> |
| Method | Type |
|---|---|
ledgerMetadata | (params: Omit<QueryParams, "certified">) => Promise<IcrcTokenMetadataResponse> |
| Method | Type |
|---|---|
transactionFee | (params: Omit<QueryParams, "certified">) => Promise<bigint> |
| Method | Type |
|---|---|
totalTokensSupply | (params: Omit<QueryParams, "certified">) => Promise<bigint> |
| Method | Type |
|---|---|
balance | (params: Omit<BalanceParams, "certified">) => Promise<bigint> |
| Method | Type |
|---|---|
transfer | (params: TransferParams) => Promise<bigint> |
| Method | Type |
|---|---|
getNeuron | (params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron> |
| Method | Type |
|---|---|
queryNeuron | (params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron or undefined> |
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; }> |
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> |
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> |
| Method | Type |
|---|---|
getNeuronBalance | (neuronId: NeuronId) => Promise<bigint> |
| Method | Type |
|---|---|
addNeuronPermissions | (params: SnsNeuronPermissionsParams) => Promise<void> |
| Method | Type |
|---|---|
refreshNeuron | (neuronId: NeuronId) => Promise<void> |
| Method | Type |
|---|---|
claimNeuron | (params: SnsClaimNeuronParams) => Promise<NeuronId> |
| Method | Type |
|---|---|
removeNeuronPermissions | (params: SnsNeuronPermissionsParams) => Promise<void> |
| Method | Type |
|---|---|
splitNeuron | (params: SnsSplitNeuronParams) => Promise<NeuronId or undefined> |
| Method | Type |
|---|---|
disburse | (params: SnsDisburseNeuronParams) => Promise<void> |
| Method | Type |
|---|---|
startDissolving | (neuronId: NeuronId) => Promise<void> |
| Method | Type |
|---|---|
stopDissolving | (neuronId: NeuronId) => Promise<void> |
| Method | Type |
|---|---|
setDissolveTimestamp | (params: SnsSetDissolveTimestampParams) => Promise<void> |
| Method | Type |
|---|---|
increaseDissolveDelay | (params: SnsIncreaseDissolveDelayParams) => Promise<void> |
| Method | Type |
|---|---|
setTopicFollowees | (params: SnsSetTopicFollowees) => Promise<void> |
| Method | Type |
|---|---|
registerVote | (params: SnsRegisterVoteParams) => Promise<void> |
| Method | Type |
|---|---|
swapState | (params: Omit<QueryParams, "certified">) => Promise<GetStateResponse> |
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> |
| Method | Type |
|---|---|
notifyParticipation | (params: RefreshBuyerTokensRequest) => Promise<RefreshBuyerTokensResponse> |
| Method | Type |
|---|---|
getUserCommitment | (params: GetBuyerStateRequest) => Promise<BuyerState or undefined> |
| Method | Type |
|---|---|
getOpenTicket | (params: Omit<QueryParams, "certified">) => Promise<Ticket or undefined> |
| Method | Type |
|---|---|
newSaleTicket | (params: NewSaleTicketParams) => Promise<Ticket> |
| Method | Type |
|---|---|
getLifecycle | (params: Omit<QueryParams, "certified">) => Promise<GetLifecycleResponse or undefined> |
| Method | Type |
|---|---|
getFinalizationStatus | (params: Omit<QueryParams, "certified">) => Promise<GetAutoFinalizationStatusResponse or undefined> |
| Method | Type |
|---|---|
getSaleParameters | (params: Omit<QueryParams, "certified">) => Promise<GetSaleParametersResponse or undefined> |
| Method | Type |
|---|---|
getDerivedState | (params: Omit<QueryParams, "certified">) => Promise<GetDerivedStateResponse or undefined> |
| Method | Type |
|---|---|
getTransactions | (params: GetAccountTransactionsParams) => Promise<GetTransactions> |
| Method | Type |
|---|---|
stakeMaturity | (params: SnsNeuronStakeMaturityParams) => Promise<void> |
| Method | Type |
|---|---|
disburseMaturity | (params: SnsNeuronDisburseMaturityParams) => Promise<void> |
| Method | Type |
|---|---|
autoStakeMaturity | (params: SnsNeuronAutoStakeMaturityParams) => Promise<void> |
FAQs
A library for interfacing with a Service Nervous System (SNS) project.
The npm package @dfinity/sns receives a total of 2,099 weekly downloads. As such, @dfinity/sns popularity was classified as popular.
We found that @dfinity/sns demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 10 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.