@dfinity/sns
Version:
A library for interfacing with a Service Nervous System (SNS) project.
161 lines (160 loc) • 9.51 kB
TypeScript
import type { BalanceParams, GetAccountTransactionsParams, IcrcAccount, IcrcBlockIndex, IcrcGetTransactions, IcrcIndexCanister, IcrcLedgerCanister, IcrcTokenMetadataResponse, IcrcTokens, TransferParams } from "@dfinity/ledger-icrc";
import type { Principal } from "@dfinity/principal";
import type { QueryParams } from "@dfinity/utils";
import type { GetMetadataResponse, ListNervousSystemFunctionsResponse, ListProposalsResponse, NervousSystemParameters, Neuron, NeuronId, ProposalData } from "../candid/sns_governance";
import type { BuyerState, GetAutoFinalizationStatusResponse, GetBuyerStateRequest, GetDerivedStateResponse, GetLifecycleResponse, GetSaleParametersResponse, GetStateResponse, RefreshBuyerTokensRequest, RefreshBuyerTokensResponse, Ticket } from "../candid/sns_swap";
import type { SnsGovernanceCanister } from "./governance.canister";
import type { SnsRootCanister } from "./root.canister";
import type { SnsSwapCanister } from "./swap.canister";
import type { SnsClaimNeuronParams, SnsDisburseNeuronParams, SnsGetNeuronParams, SnsGetProposalParams, SnsIncreaseDissolveDelayParams, SnsIncreaseStakeNeuronParams, SnsListNeuronsParams, SnsListProposalsParams, SnsNeuronAutoStakeMaturityParams, SnsNeuronDisburseMaturityParams, SnsNeuronPermissionsParams, SnsNeuronStakeMaturityParams, SnsRegisterVoteParams, SnsSetDissolveTimestampParams, SnsSetFollowingParams, SnsSetTopicFollowees, SnsSplitNeuronParams, SnsStakeNeuronParams } from "./types/governance.params";
import type { NewSaleTicketParams } from "./types/swap.params";
interface SnsWrapperOptions {
/** The wrapper for the "root" canister of the particular Sns */
root: SnsRootCanister;
/** The wrapper for the "governance" canister of the particular Sns */
governance: SnsGovernanceCanister;
/** The wrapper for the "ledger" canister of the particular Sns */
ledger: IcrcLedgerCanister;
/** The wrapper for the "swap" canister of the particular Sns */
swap: SnsSwapCanister;
/** The wrapper for the "index" canister of the particular Sns */
index: IcrcIndexCanister;
/** The wrapper has been instantiated and should perform query or update calls */
certified: boolean;
}
/**
* 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.
*/
export declare class SnsWrapper {
private readonly root;
private readonly governance;
private readonly ledger;
private readonly swap;
private readonly index;
private readonly certified;
/**
* Constructor to instantiate a Sns
*/
constructor({ root, governance, ledger, swap, index: index, certified, }: SnsWrapperOptions);
/**
* Binds the list of canister ids of the Sns.
*/
get canisterIds(): {
rootCanisterId: Principal;
ledgerCanisterId: Principal;
governanceCanisterId: Principal;
swapCanisterId: Principal;
indexCanisterId: Principal;
};
listNeurons: (params: Omit<SnsListNeuronsParams, "certified">) => Promise<Neuron[]>;
listProposals: (params: Omit<SnsListProposalsParams, "certified">) => Promise<ListProposalsResponse>;
getProposal: (params: Omit<SnsGetProposalParams, "certified">) => Promise<ProposalData>;
listNervousSystemFunctions: (params: Omit<QueryParams, "certified">) => Promise<ListNervousSystemFunctionsResponse>;
metadata: (params: Omit<QueryParams, "certified">) => Promise<[GetMetadataResponse, IcrcTokenMetadataResponse]>;
nervousSystemParameters: (params: Omit<QueryParams, "certified">) => Promise<NervousSystemParameters>;
ledgerMetadata: (params: Omit<QueryParams, "certified">) => Promise<IcrcTokenMetadataResponse>;
transactionFee: (params: Omit<QueryParams, "certified">) => Promise<IcrcTokens>;
totalTokensSupply: (params: Omit<QueryParams, "certified">) => Promise<IcrcTokens>;
balance: (params: Omit<BalanceParams, "certified">) => Promise<IcrcTokens>;
transfer: (params: TransferParams) => Promise<IcrcBlockIndex>;
getNeuron: (params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron>;
queryNeuron: (params: Omit<SnsGetNeuronParams, "certified">) => Promise<Neuron | 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.
*
* @param controller
* @returns
*/
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.
*
* @param {SnsStakeNeuronParams} params
* @param {Principal} params.controller
* @param {bigint} params.stakeE8s
* @param {source} params.source
* @returns {NeuronId}
*/
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.
*
* @param {SnsStakeNeuronParams} params
* @param {Principal} params.controller
* @param {bigint} params.stakeE8s
* @param {source} params.source
* @returns {NeuronId}
*/
increaseStakeNeuron: ({ stakeE8s, source, neuronId, }: SnsIncreaseStakeNeuronParams) => Promise<void>;
getNeuronBalance: (neuronId: NeuronId) => Promise<IcrcTokens>;
addNeuronPermissions: (params: SnsNeuronPermissionsParams) => Promise<void>;
refreshNeuron: (neuronId: NeuronId) => Promise<void>;
claimNeuron: (params: SnsClaimNeuronParams) => Promise<NeuronId>;
removeNeuronPermissions: (params: SnsNeuronPermissionsParams) => Promise<void>;
splitNeuron: (params: SnsSplitNeuronParams) => Promise<NeuronId | undefined>;
disburse: (params: SnsDisburseNeuronParams) => Promise<void>;
startDissolving: (neuronId: NeuronId) => Promise<void>;
stopDissolving: (neuronId: NeuronId) => Promise<void>;
setDissolveTimestamp: (params: SnsSetDissolveTimestampParams) => Promise<void>;
increaseDissolveDelay: (params: SnsIncreaseDissolveDelayParams) => Promise<void>;
setTopicFollowees: (params: SnsSetTopicFollowees) => Promise<void>;
setFollowing: (params: SnsSetFollowingParams) => Promise<void>;
registerVote: (params: SnsRegisterVoteParams) => Promise<void>;
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
*
* @param params
*/
notifyPaymentFailure: () => Promise<Ticket | undefined>;
notifyParticipation: (params: RefreshBuyerTokensRequest) => Promise<RefreshBuyerTokensResponse>;
getUserCommitment: (params: GetBuyerStateRequest) => Promise<BuyerState | undefined>;
getOpenTicket: (params: Omit<QueryParams, "certified">) => Promise<Ticket | undefined>;
newSaleTicket: (params: NewSaleTicketParams) => Promise<Ticket>;
getLifecycle: (params: Omit<QueryParams, "certified">) => Promise<GetLifecycleResponse | undefined>;
getFinalizationStatus: (params: Omit<QueryParams, "certified">) => Promise<GetAutoFinalizationStatusResponse | undefined>;
getSaleParameters: (params: Omit<QueryParams, "certified">) => Promise<GetSaleParametersResponse | undefined>;
getDerivedState: (params: Omit<QueryParams, "certified">) => Promise<GetDerivedStateResponse | undefined>;
getTransactions: (params: GetAccountTransactionsParams) => Promise<IcrcGetTransactions>;
stakeMaturity: (params: SnsNeuronStakeMaturityParams) => Promise<void>;
disburseMaturity: (params: SnsNeuronDisburseMaturityParams) => Promise<void>;
autoStakeMaturity: (params: SnsNeuronAutoStakeMaturityParams) => Promise<void>;
private mergeParams;
private assertCertified;
/**
* Each Sns neuron id is a subaccount of the related Sns ledger account of the Sns governance canister.
*
* In other words, the Sns governance canister is the owner. It has an account in the related Sns ledger and each neuron is both a child of the Sns governance canister and a subaccount in the Sns ledger.
*
* @private
*/
private get owner();
}
export {};