@dfinity/nns
Version:
A library for interfacing with the Internet Computer's Network Nervous System.
359 lines (358 loc) • 13.3 kB
TypeScript
import { type AccountIdentifierHex, type LedgerCanister } from "@dfinity/ledger-icp";
import type { Principal } from "@dfinity/principal";
import type { NeuronSubaccount, RewardEvent } from "../candid/governance";
import type { NeuronVisibility, Vote } from "./enums/governance.enums";
import type { E8s, NeuronId } from "./types/common";
import type { GovernanceCanisterOptions } from "./types/governance.options";
import type { ClaimOrRefreshNeuronRequest, FollowRequest, FolloweesForTopic, GovernanceCachedMetrics, KnownNeuron, ListProposalsRequest, ListProposalsResponse, MakeProposalRequest, NetworkEconomics, NeuronInfo, ProposalId, ProposalInfo } from "./types/governance_converters";
export declare class GovernanceCanister {
private readonly canisterId;
private readonly service;
private readonly certifiedService;
private readonly oldListNeuronsCertifiedService;
private readonly agent;
private constructor();
static create(options?: GovernanceCanisterOptions): GovernanceCanister;
/**
* 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.
*
* The backend treats `includeEmptyNeurons` as false if absent.
*
* The response from the canister might be paginated. In this case, all pages will be fetched in parallel and
* combined into a single return value.
*/
listNeurons: ({ certified, neuronIds, includeEmptyNeurons, includePublicNeurons, neuronSubaccounts, }: {
certified: boolean;
neuronIds?: NeuronId[];
includeEmptyNeurons?: boolean;
includePublicNeurons?: boolean;
neuronSubaccounts?: NeuronSubaccount[];
}) => Promise<NeuronInfo[]>;
private fetchNeuronsWithOldMethodAndNoPagination;
private fetchNeuronsPage;
/**
* 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.
*/
listKnownNeurons: (certified?: boolean) => Promise<KnownNeuron[]>;
/**
* Returns the latest reward event.
*
* If `certified` is true, the request is fetched as an update call, otherwise
* it's fetched using a query call.
*
*/
getLatestRewardEvent: (certified?: boolean) => Promise<RewardEvent>;
/**
* 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.
*
* @param request the options to list the proposals (limit number of results, topics to search for, etc.)
* @param certified query or update calls
*/
listProposals: ({ request, certified, }: {
request: ListProposalsRequest;
certified?: boolean;
}) => Promise<ListProposalsResponse>;
/**
* @throws {@link InsufficientAmountError}
* @throws {@link StakeNeuronTransferError}
* @throws {@link CouldNotClaimNeuronError}
* @throws {@link TransferError}
*/
stakeNeuron: ({ stake, principal, fromSubAccount, ledgerCanister, createdAt, fee, }: {
stake: bigint;
principal: Principal;
fromSubAccount?: number[];
ledgerCanister: LedgerCanister;
createdAt?: bigint;
fee?: E8s;
}) => Promise<NeuronId>;
/**
* Increases dissolve delay of a neuron
*
* @throws {@link GovernanceError}
*/
increaseDissolveDelay: ({ neuronId, additionalDissolveDelaySeconds, }: {
neuronId: NeuronId;
additionalDissolveDelaySeconds: number;
}) => Promise<void>;
/**
* Sets dissolve delay of a neuron.
* The new date is now + dissolveDelaySeconds.
*
* @param {NeuronId} neuronId
* @param {number} dissolveDelaySeconds
* @throws {@link GovernanceError}
*/
setDissolveDelay: ({ neuronId, dissolveDelaySeconds, }: {
neuronId: NeuronId;
dissolveDelaySeconds: number;
}) => Promise<void>;
/**
* Start dissolving process of a neuron
*
* @throws {@link GovernanceError}
*/
startDissolving: (neuronId: NeuronId) => Promise<void>;
/**
* Stop dissolving process of a neuron
*
* @throws {@link GovernanceError}
*/
stopDissolving: (neuronId: NeuronId) => Promise<void>;
/**
* Neuron joins the community fund
*
* @throws {@link GovernanceError}
*/
joinCommunityFund: (neuronId: NeuronId) => Promise<void>;
/**
* 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.
*
* @param {neuronId: NeuronId; autoStake: boolean;} params
* @param {NeuronId} neuronId The id of the neuron for which to request a change of the auto stake feature
* @param {number} autoStake `true` to enable the auto-stake maturity for this neuron, `false` to turn it off
*
* @throws {@link GovernanceError}
*/
autoStakeMaturity: (params: {
neuronId: NeuronId;
autoStake: boolean;
}) => Promise<void>;
/**
* Neuron leaves the community fund
*
* @throws {@link GovernanceError}
*/
leaveCommunityFund: (neuronId: NeuronId) => Promise<void>;
/**
* Set visibility of a neuron
*
* @throws {@link GovernanceError}
*/
setVisibility: (neuronId: NeuronId, visibility: NeuronVisibility) => Promise<void>;
/**
* Sets node provider reward account.
* Where the reward is paid to.
*
* @param {string} accountIdentifier
* @throws {@link GovernanceError}
* @throws {@link InvalidAccountIDError}
*/
setNodeProviderAccount: (accountIdentifier: string) => Promise<void>;
/**
* Merge two neurons
*
* @throws {@link GovernanceError}
*/
mergeNeurons: (request: {
sourceNeuronId: NeuronId;
targetNeuronId: NeuronId;
}) => Promise<void>;
/**
* Simulate merging two neurons
*
* @throws {@link GovernanceError}
*/
simulateMergeNeurons: (request: {
sourceNeuronId: NeuronId;
targetNeuronId: NeuronId;
}) => Promise<NeuronInfo>;
/**
* Splits a neuron creating a new one
*
* @returns newNeuronId
* @throws {@link GovernanceError}
*/
splitNeuron: ({ neuronId, amount, }: {
neuronId: NeuronId;
amount: bigint;
}) => Promise<NeuronId>;
/**
* 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.
*/
getProposal: ({ proposalId, certified, }: {
proposalId: bigint;
certified?: boolean;
}) => Promise<ProposalInfo | undefined>;
/**
* Create new proposal
*
* @returns The newly created proposal ID or undefined if the success response returned by the Governance canister does not provide such information.
* @throws {@link GovernanceError}
*/
makeProposal: (request: MakeProposalRequest) => Promise<NeuronId | undefined>;
/**
*
* Registers vote for a proposal from the neuron passed.
*
* @throws {@link GovernanceError}
*/
registerVote: ({ neuronId, vote, proposalId, }: {
neuronId: NeuronId;
vote: Vote;
proposalId: ProposalId;
}) => Promise<void>;
/**
* Edit neuron followees per topic
*
* @throws {@link GovernanceError}
*/
setFollowees: (followRequest: FollowRequest) => Promise<void>;
/**
* Disburse neuron on Account
*
* @throws {@link GovernanceError}
* @throws {@link InvalidAccountIDError}
*/
disburse: ({ neuronId, toAccountId, amount, }: {
neuronId: NeuronId;
toAccountId?: string;
amount?: E8s;
}) => Promise<void>;
/**
* Refreshes voting power of a neuron
* (Resets the `votingPowerRefreshedTimestampSeconds`
* parameter of the neuron to the current time).
*
* @throws {@link GovernanceError}
*/
refreshVotingPower: ({ neuronId, }: {
neuronId: NeuronId;
}) => Promise<void>;
/**
* Merge Maturity of a neuron
*
* @throws {@link GovernanceError}
* @throws {@link InvalidPercentageError}
*
*/
mergeMaturity: ({ neuronId, percentageToMerge, }: {
neuronId: NeuronId;
percentageToMerge: number;
}) => Promise<void>;
/**
* Stake the maturity of a neuron.
*
* @param {neuronId: NeuronId; percentageToStake: number;} params
* @param {NeuronId} neuronId The id of the neuron for which to stake the maturity
* @param {number} percentageToStake Optional. Percentage of the current maturity to stake. If not provided, all of the neuron's current maturity will be staked.
*
* @throws {@link GovernanceError}
* @throws {@link InvalidPercentageError}
*
*/
stakeMaturity: ({ neuronId, percentageToStake, }: {
neuronId: NeuronId;
percentageToStake?: number;
}) => Promise<void>;
/**
* Merge Maturity of a neuron
*
* @throws {@link GovernanceError}
* @throws {@link InvalidPercentageError}
*
*/
spawnNeuron: ({ neuronId, percentageToSpawn, newController, nonce, }: {
neuronId: NeuronId;
percentageToSpawn?: number;
newController?: Principal;
nonce?: bigint;
}) => Promise<bigint>;
/**
* Add hotkey to neuron
*
* @throws {@link GovernanceError}
*/
addHotkey: ({ neuronId, principal, }: {
neuronId: NeuronId;
principal: Principal;
}) => Promise<void>;
/**
* Remove hotkey to neuron
*
* @throws {@link GovernanceError}
*/
removeHotkey: ({ neuronId, principal, }: {
neuronId: NeuronId;
principal: Principal;
}) => Promise<void>;
/**
* Gets the NeuronID of a newly created neuron.
*/
claimOrRefreshNeuronFromAccount: ({ memo, controller, }: {
memo: bigint;
controller?: Principal;
}) => Promise<NeuronId | undefined>;
/**
* Refreshes neuron and returns neuronId when successful
* Uses query call only.
*
* @throws {@link UnrecognizedTypeError}
*/
claimOrRefreshNeuron: (request: ClaimOrRefreshNeuronRequest) => Promise<NeuronId | undefined>;
private getGovernanceService;
/**
* Return the data of the neuron provided as id.
*/
getNeuron: ({ certified, neuronId, }: {
certified: boolean;
neuronId: NeuronId;
}) => Promise<NeuronInfo | undefined>;
/**
* Return the [Network Economics](https://github.com/dfinity/ic/blob/d90e934eb440c730d44d9d9b1ece2cc3f9505d05/rs/nns/governance/proto/ic_nns_governance/pb/v1/governance.proto#L1847).
*/
getNetworkEconomicsParameters: ({ certified, }: {
certified: boolean;
}) => Promise<NetworkEconomics>;
/**
* Disburses a neuron's maturity (always certified).
* Reference: https://github.com/dfinity/ic/blob/ca2be53acf413bb92478ee7694ac0fb92af07030/rs/sns/governance/src/governance.rs#L1614
*
* @preconditions
* - The neuron exists
* - The caller is authorized to perform this neuron operation (NeuronPermissionType::DisburseMaturity)
* - The given percentage_to_merge is between 1 and 100 (inclusive)
* - The neuron's id is not yet in the list of neurons with ongoing operations
* - The e8s equivalent of the amount of maturity to disburse is more than the transaction fee.
*
* @param {Object} params
* @param {NeuronId} params.neuronId The id of the neuron for which to disburse maturity
* @param {number} params.percentageToDisburse The percentage of the neuron's maturity to disburse, between 1 and 100 (inclusive).
* @param {AccountIdentifierHex} [params.accountIdentifier] Optional. The account identifier to which the maturity will be disbursed. If not provided, the maturity will be disbursed to the caller's Main account.
*/
disburseMaturity: ({ neuronId, percentageToDisburse, toAccountIdentifier, }: {
neuronId: NeuronId;
percentageToDisburse: number;
toAccountIdentifier?: AccountIdentifierHex;
}) => Promise<void>;
/**
* Set the following topics for a neuron.
*
* @param {Object} params
* @param {NeuronId} params.neuronId The id of the neuron for which to set the following topics
* @param {Array<FolloweesForTopic>} params.topicFollowing The topics and the followees for each topic that the neuron should follow.
*/
setFollowing: ({ neuronId, topicFollowing, }: {
neuronId: NeuronId;
topicFollowing: Array<FolloweesForTopic>;
}) => Promise<void>;
getMetrics: ({ certified, }: {
certified: boolean;
}) => Promise<GovernanceCachedMetrics>;
}