diff --git a/package.json b/package.json index 8eb5cdad..68f3a912 100644 --- a/package.json +++ b/package.json @@ -114,7 +114,7 @@ { "name": "@dfinity/sns", "path": "./packages/sns/dist/index.js", - "limit": "14 kB", + "limit": "16 kB", "ignore": [ "@dfinity/agent", "@dfinity/candid", diff --git a/packages/sns/README.md b/packages/sns/README.md index fa49db3a..faa78ae6 100644 --- a/packages/sns/README.md +++ b/packages/sns/README.md @@ -83,7 +83,7 @@ Lookup for the canister ids of a Sns and initialize the wrapper to access its fe ### :factory: SnsGovernanceCanister -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L60) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L62) #### Methods @@ -104,6 +104,7 @@ Lookup for the canister ids of a Sns and initialize the wrapper to access its fe - [startDissolving](#gear-startdissolving) - [stopDissolving](#gear-stopdissolving) - [stakeMaturity](#gear-stakematurity) +- [disburseMaturity](#gear-disbursematurity) - [autoStakeMaturity](#gear-autostakematurity) - [setDissolveTimestamp](#gear-setdissolvetimestamp) - [increaseDissolveDelay](#gear-increasedissolvedelay) @@ -124,7 +125,7 @@ Parameters: - `options`: Miscellaneous options to initialize the canister. Its ID being the only mandatory parammeter. -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L66) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L68) ##### :gear: listNeurons @@ -134,7 +135,7 @@ List the neurons of the Sns | ------------- | ----------------------------------------------------- | | `listNeurons` | `(params: SnsListNeuronsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L80) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L82) ##### :gear: listProposals @@ -144,7 +145,7 @@ List the proposals of the Sns | --------------- | ------------------------------------------------------------- | | `listProposals` | `(params: SnsListProposalsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L94) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L96) ##### :gear: getProposal @@ -154,7 +155,7 @@ Get the proposal of the Sns | ------------- | --------------------------------------------------------- | | `getProposal` | `(params: SnsGetProposalParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L108) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L110) ##### :gear: listNervousSystemFunctions @@ -165,7 +166,7 @@ Neurons can follow other neurons in specific Nervous System Functions. | ---------------------------- | ---------------------------------------------------------------------- | | `listNervousSystemFunctions` | `(params: QueryParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L127) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L129) ##### :gear: metadata @@ -175,7 +176,7 @@ Get the Sns metadata (title, description, etc.) | ---------- | ------------------------------------------------------- | | `metadata` | `(params: QueryParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L135) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L137) ##### :gear: nervousSystemParameters @@ -185,7 +186,7 @@ Get the Sns nervous system parameters (default followees, max dissolve delay, ma | ------------------------- | ----------------------------------------------------------- | | `nervousSystemParameters` | `(params: QueryParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L141) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L143) ##### :gear: getNeuron @@ -195,7 +196,7 @@ Get the neuron of the Sns | ----------- | ------------------------------------------------- | | `getNeuron` | `(params: SnsGetNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L149) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L151) ##### :gear: queryNeuron @@ -205,7 +206,7 @@ Same as `getNeuron` but returns undefined instead of raising error when not foun | ------------- | ------------------------------------------------- | | `queryNeuron` | `(params: SnsGetNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L167) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L169) ##### :gear: manageNeuron @@ -215,7 +216,7 @@ Manage neuron. For advanced users. | -------------- | ---------------------------------------------------------- | | `manageNeuron` | `(request: ManageNeuron) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L187) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L189) ##### :gear: addNeuronPermissions @@ -225,7 +226,7 @@ Add permissions to a neuron for a specific principal | ---------------------- | ------------------------------------------------------- | | `addNeuronPermissions` | `(params: SnsNeuronPermissionsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L200) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L202) ##### :gear: removeNeuronPermissions @@ -235,7 +236,7 @@ Remove permissions to a neuron for a specific principal | ------------------------- | ------------------------------------------------------- | | `removeNeuronPermissions` | `(params: SnsNeuronPermissionsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L210) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L212) ##### :gear: splitNeuron @@ -245,7 +246,7 @@ Split neuron | ------------- | ----------------------------------------------------- | | `splitNeuron` | `(params: SnsSplitNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L220) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L222) ##### :gear: disburse @@ -255,7 +256,7 @@ Disburse neuron on Account | ---------- | ---------------------------------------------------- | | `disburse` | `(params: SnsDisburseNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L251) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L253) ##### :gear: startDissolving @@ -265,7 +266,7 @@ Start dissolving process of a neuron | ----------------- | --------------------------------------- | | `startDissolving` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L259) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L261) ##### :gear: stopDissolving @@ -275,7 +276,7 @@ Stop dissolving process of a neuron | ---------------- | --------------------------------------- | | `stopDissolving` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L267) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L269) ##### :gear: stakeMaturity @@ -290,7 +291,23 @@ 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. -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L279) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L281) + +##### :gear: disburseMaturity + +Disburse the maturity of a neuron. + +| Method | Type | +| ------------------ | ------------------------------------------------------------ | +| `disburseMaturity` | `(params: SnsNeuronDisburseMaturityParams) => Promise` | + +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. + +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L302) ##### :gear: autoStakeMaturity @@ -305,7 +322,7 @@ 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 -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L299) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L318) ##### :gear: setDissolveTimestamp @@ -315,7 +332,7 @@ Increase dissolve delay of a neuron | ---------------------- | ---------------------------------------------------------- | | `setDissolveTimestamp` | `(params: SnsSetDissolveTimestampParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L309) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L328) ##### :gear: increaseDissolveDelay @@ -325,7 +342,7 @@ Increase dissolve delay of a neuron | ----------------------- | ----------------------------------------------------------- | | `increaseDissolveDelay` | `(params: SnsIncreaseDissolveDelayParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L319) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L338) ##### :gear: setTopicFollowees @@ -335,7 +352,7 @@ Sets followees of a neuron for a specific Nervous System Function (topic) | ------------------- | ------------------------------------------------- | | `setTopicFollowees` | `(params: SnsSetTopicFollowees) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L329) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L348) ##### :gear: registerVote @@ -345,7 +362,7 @@ Registers vote for a proposal from the neuron passed. | -------------- | -------------------------------------------------- | | `registerVote` | `(params: SnsRegisterVoteParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L337) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L356) ##### :gear: refreshNeuron @@ -355,7 +372,7 @@ Refresh neuron | --------------- | --------------------------------------- | | `refreshNeuron` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L345) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L364) ##### :gear: claimNeuron @@ -365,7 +382,7 @@ Claim neuron | ------------- | -------------------------------------------------------------------------------- | | `claimNeuron` | `({ memo, controller, subaccount, }: SnsClaimNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L355) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/governance.canister.ts#L374) ### :factory: SnsRootCanister @@ -517,7 +534,7 @@ 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. -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L82) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L83) #### Constructors @@ -569,6 +586,7 @@ Parameters: - [getDerivedState](#gear-getderivedstate) - [getTransactions](#gear-gettransactions) - [stakeMaturity](#gear-stakematurity) +- [disburseMaturity](#gear-disbursematurity) - [autoStakeMaturity](#gear-autostakematurity) ##### :gear: listNeurons @@ -577,7 +595,7 @@ Parameters: | ------------- | ------------------------------------------------------------------------ | | `listNeurons` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L128) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L129) ##### :gear: listProposals @@ -585,7 +603,7 @@ Parameters: | --------------- | -------------------------------------------------------------------------------- | | `listProposals` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L132) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L133) ##### :gear: getProposal @@ -593,7 +611,7 @@ Parameters: | ------------- | ---------------------------------------------------------------------------- | | `getProposal` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L137) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L138) ##### :gear: listNervousSystemFunctions @@ -601,7 +619,7 @@ Parameters: | ---------------------------- | ----------------------------------------------------------------------------------------- | | `listNervousSystemFunctions` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L142) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L143) ##### :gear: metadata @@ -609,7 +627,7 @@ Parameters: | ---------- | ------------------------------------------------------------------------------------------------------- | | `metadata` | `(params: Omit) => Promise<[GetMetadataResponse, IcrcTokenMetadataResponse]>` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L147) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L148) ##### :gear: nervousSystemParameters @@ -617,7 +635,7 @@ Parameters: | ------------------------- | ------------------------------------------------------------------------------ | | `nervousSystemParameters` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L155) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L156) ##### :gear: ledgerMetadata @@ -625,7 +643,7 @@ Parameters: | ---------------- | -------------------------------------------------------------------------------- | | `ledgerMetadata` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L160) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L161) ##### :gear: transactionFee @@ -633,7 +651,7 @@ Parameters: | ---------------- | ------------------------------------------------------------- | | `transactionFee` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L165) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L166) ##### :gear: totalTokensSupply @@ -641,7 +659,7 @@ Parameters: | ------------------- | ------------------------------------------------------------- | | `totalTokensSupply` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L170) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L171) ##### :gear: balance @@ -649,7 +667,7 @@ Parameters: | --------- | --------------------------------------------------------------- | | `balance` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L175) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L176) ##### :gear: transfer @@ -657,7 +675,7 @@ Parameters: | ---------- | --------------------------------------------- | | `transfer` | `(params: TransferParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L179) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L180) ##### :gear: getNeuron @@ -665,7 +683,7 @@ Parameters: | ----------- | -------------------------------------------------------------------- | | `getNeuron` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L182) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L183) ##### :gear: queryNeuron @@ -673,7 +691,7 @@ Parameters: | ------------- | -------------------------------------------------------------------- | | `queryNeuron` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L186) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L187) ##### :gear: nextNeuronAccount @@ -693,7 +711,7 @@ This is how the backend can identify which neuron is being claimed. | ------------------- | ------------------------------------------------------------------------------ | | `nextNeuronAccount` | `(controller: Principal) => Promise<{ account: IcrcAccount; index: bigint; }>` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L207) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L208) ##### :gear: stakeNeuron @@ -707,7 +725,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------- | ------------------------------------------------------------------------------------------------ | | `stakeNeuron` | `({ stakeE8s, source, controller, createdAt, fee, }: SnsStakeNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L254) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L255) ##### :gear: increaseStakeNeuron @@ -721,7 +739,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | --------------------- | ---------------------------------------------------------------------------------- | | `increaseStakeNeuron` | `({ stakeE8s, source, neuronId, }: SnsIncreaseStakeNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L302) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L303) ##### :gear: getNeuronBalance @@ -729,7 +747,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------------ | ----------------------------------------- | | `getNeuronBalance` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L321) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L322) ##### :gear: addNeuronPermissions @@ -737,7 +755,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ---------------------- | ------------------------------------------------------- | | `addNeuronPermissions` | `(params: SnsNeuronPermissionsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L330) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L331) ##### :gear: refreshNeuron @@ -745,7 +763,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | --------------- | --------------------------------------- | | `refreshNeuron` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L334) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L335) ##### :gear: claimNeuron @@ -753,7 +771,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------- | ----------------------------------------------------- | | `claimNeuron` | `(params: SnsClaimNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L338) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L339) ##### :gear: removeNeuronPermissions @@ -761,7 +779,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------------------- | ------------------------------------------------------- | | `removeNeuronPermissions` | `(params: SnsNeuronPermissionsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L342) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L343) ##### :gear: splitNeuron @@ -769,7 +787,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------- | ----------------------------------------------------- | | `splitNeuron` | `(params: SnsSplitNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L347) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L348) ##### :gear: disburse @@ -777,7 +795,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ---------- | ---------------------------------------------------- | | `disburse` | `(params: SnsDisburseNeuronParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L351) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L352) ##### :gear: startDissolving @@ -785,7 +803,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ----------------- | --------------------------------------- | | `startDissolving` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L355) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L356) ##### :gear: stopDissolving @@ -793,7 +811,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ---------------- | --------------------------------------- | | `stopDissolving` | `(neuronId: NeuronId) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L359) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L360) ##### :gear: setDissolveTimestamp @@ -801,7 +819,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ---------------------- | ---------------------------------------------------------- | | `setDissolveTimestamp` | `(params: SnsSetDissolveTimestampParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L363) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L364) ##### :gear: increaseDissolveDelay @@ -809,7 +827,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ----------------------- | ----------------------------------------------------------- | | `increaseDissolveDelay` | `(params: SnsIncreaseDissolveDelayParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L368) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L369) ##### :gear: setTopicFollowees @@ -817,7 +835,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ------------------- | ------------------------------------------------- | | `setTopicFollowees` | `(params: SnsSetTopicFollowees) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L373) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L374) ##### :gear: registerVote @@ -825,7 +843,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | -------------- | -------------------------------------------------- | | `registerVote` | `(params: SnsRegisterVoteParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L377) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L378) ##### :gear: swapState @@ -833,7 +851,7 @@ This is a convenient method that transfers the stake to the neuron subaccount an | ----------- | ----------------------------------------------------------------------- | | `swapState` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L380) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L381) ##### :gear: notifyPaymentFailure @@ -847,7 +865,7 @@ Always certified | ---------------------- | ----------------------- | | `notifyPaymentFailure` | `() => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L393) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L394) ##### :gear: notifyParticipation @@ -855,7 +873,7 @@ Always certified | --------------------- | ---------------------------------------------------------------------------- | | `notifyParticipation` | `(params: RefreshBuyerTokensRequest) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L397) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L398) ##### :gear: getUserCommitment @@ -863,7 +881,7 @@ Always certified | ------------------- | ------------------------------------------------------- | | `getUserCommitment` | `(params: GetBuyerStateRequest) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L402) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L403) ##### :gear: getOpenTicket @@ -871,7 +889,7 @@ Always certified | --------------- | ------------------------------------------------------------- | | `getOpenTicket` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L407) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L408) ##### :gear: newSaleTicket @@ -879,7 +897,7 @@ Always certified | --------------- | -------------------------------------------------- | | `newSaleTicket` | `(params: NewSaleTicketParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L413) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L414) ##### :gear: getLifecycle @@ -887,7 +905,7 @@ Always certified | -------------- | --------------------------------------------------------------------------- | | `getLifecycle` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L416) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L417) ##### :gear: getSaleParameters @@ -895,7 +913,7 @@ Always certified | ------------------- | -------------------------------------------------------------------------------- | | `getSaleParameters` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L421) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L422) ##### :gear: getDerivedState @@ -903,7 +921,7 @@ Always certified | ----------------- | ------------------------------------------------------------------------------ | | `getDerivedState` | `(params: Omit) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L426) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L427) ##### :gear: getTransactions @@ -911,7 +929,7 @@ Always certified | ----------------- | -------------------------------------------------------------------- | | `getTransactions` | `(params: GetAccountTransactionsParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L432) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L433) ##### :gear: stakeMaturity @@ -919,7 +937,15 @@ Always certified | --------------- | --------------------------------------------------------- | | `stakeMaturity` | `(params: SnsNeuronStakeMaturityParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L437) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L438) + +##### :gear: disburseMaturity + +| Method | Type | +| ------------------ | ------------------------------------------------------------ | +| `disburseMaturity` | `(params: SnsNeuronDisburseMaturityParams) => Promise` | + +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L442) ##### :gear: autoStakeMaturity @@ -927,6 +953,6 @@ Always certified | ------------------- | ------------------------------------------------------------- | | `autoStakeMaturity` | `(params: SnsNeuronAutoStakeMaturityParams) => Promise` | -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L441) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/sns/src/sns.wrapper.ts#L446) diff --git a/packages/sns/src/converters/governance.converters.ts b/packages/sns/src/converters/governance.converters.ts index 5d50bc2a..c2e26cba 100644 --- a/packages/sns/src/converters/governance.converters.ts +++ b/packages/sns/src/converters/governance.converters.ts @@ -35,6 +35,7 @@ import type { SnsIncreaseDissolveDelayParams, SnsListProposalsParams, SnsNeuronAutoStakeMaturityParams, + SnsNeuronDisburseMaturityParams, SnsNeuronPermissionsParams, SnsNeuronStakeMaturityParams, SnsRegisterVoteParams, @@ -178,6 +179,23 @@ export const toStakeMaturityRequest = ({ }, }); +export const toDisburseMaturityRequest = ({ + neuronId, + percentageToDisburse, + toAccount, +}: SnsNeuronDisburseMaturityParams): ManageNeuron => + toManageNeuronCommand({ + neuronId, + command: { + DisburseMaturity: { + // currently there is a main account only support + to_account: + toAccount === undefined ? [] : toNullable(toCandidAccount(toAccount)), + percentage_to_disburse: percentageToDisburse, + }, + }, + }); + export const toAutoStakeMaturityNeuronRequest = ({ neuronId, autoStake: requested_setting_for_auto_stake_maturity, diff --git a/packages/sns/src/governance.canister.spec.ts b/packages/sns/src/governance.canister.spec.ts index e82b3de0..b885e142 100644 --- a/packages/sns/src/governance.canister.spec.ts +++ b/packages/sns/src/governance.canister.spec.ts @@ -39,6 +39,7 @@ import { import { rootCanisterIdMock } from "./mocks/sns.mock"; import { SnsDisburseNeuronParams, + SnsNeuronDisburseMaturityParams, SnsRegisterVoteParams, SnsSplitNeuronParams, } from "./types/governance.params"; @@ -1136,6 +1137,81 @@ describe("Governance canister", () => { }); }); + describe("disburseMaturity", () => { + const toAccount = { + owner: Principal.fromText("aaaaa-aa"), + subaccount: arrayOfNumberToUint8Array([0, 0, 1]), + }; + const params: SnsNeuronDisburseMaturityParams = { + neuronId: { + id: arrayOfNumberToUint8Array([1, 2, 3]), + }, + percentageToDisburse: 50, + toAccount, + }; + + it("should disburse maturity of the neuron", async () => { + const request: ManageNeuron = { + subaccount: params.neuronId.id, + command: [ + { + DisburseMaturity: { + to_account: [toCandidAccount(toAccount)], + percentage_to_disburse: params.percentageToDisburse, + }, + }, + ], + }; + + const service = mock>(); + service.manage_neuron.mockResolvedValue({ + command: [{ DisburseMaturity: { amount_disbursed_e8s: BigInt(0) } }], + }); + + const canister = SnsGovernanceCanister.create({ + canisterId: rootCanisterIdMock, + certifiedServiceOverride: service, + }); + + await canister.disburseMaturity(params); + + expect(service.manage_neuron).toBeCalled(); + expect(service.manage_neuron).toBeCalledWith(request); + }); + + it("throws error if percentage not valid", () => { + const service = mock>(); + + const canister = SnsGovernanceCanister.create({ + canisterId: rootCanisterIdMock, + certifiedServiceOverride: service, + }); + + const call = () => + canister.disburseMaturity({ + ...params, + percentageToDisburse: 500, + }); + + expect(call).rejects.toThrow(InvalidPercentageError); + expect(service.manage_neuron).not.toBeCalled(); + }); + + it("should raise an error", async () => { + const service = mock>(); + service.manage_neuron.mockResolvedValue(mockErrorCommand); + + const canister = SnsGovernanceCanister.create({ + canisterId: rootCanisterIdMock, + certifiedServiceOverride: service, + }); + const call = () => canister.disburseMaturity(params); + + expect(call).rejects.toThrowError(SnsGovernanceError); + expect(service.manage_neuron).toBeCalled(); + }); + }); + describe("autoStakeMaturity", () => { const testAutoStakeMaturitySuccess = async ( requested_setting_for_auto_stake_maturity: boolean, diff --git a/packages/sns/src/governance.canister.ts b/packages/sns/src/governance.canister.ts index 547e148c..8d473cb4 100644 --- a/packages/sns/src/governance.canister.ts +++ b/packages/sns/src/governance.canister.ts @@ -26,6 +26,7 @@ import { toAddPermissionsRequest, toAutoStakeMaturityNeuronRequest, toClaimOrRefreshRequest, + toDisburseMaturityRequest, toDisburseNeuronRequest, toFollowRequest, toIncreaseDissolveDelayRequest, @@ -49,6 +50,7 @@ import type { SnsListNeuronsParams, SnsListProposalsParams, SnsNeuronAutoStakeMaturityParams, + SnsNeuronDisburseMaturityParams, SnsNeuronPermissionsParams, SnsNeuronStakeMaturityParams, SnsRegisterVoteParams, @@ -289,6 +291,23 @@ export class SnsGovernanceCanister extends Canister { await this.manageNeuron(request); }; + /** + * Disburse the maturity of a neuron. + * + * @param {neuronId: NeuronId; toAccount?: IcrcAccount; percentageToDisburse: number; } params + * @param {IcrcAccount} toAccount. Account to disburse maturity. + * @param {NeuronId} neuronId The id of the neuron for which to disburse the maturity + * @param {number} percentageToDisburse What percentage of the available maturity to disburse. + */ + disburseMaturity = async ( + params: SnsNeuronDisburseMaturityParams, + ): Promise => { + assertPercentageNumber(params.percentageToDisburse); + + const request: ManageNeuron = toDisburseMaturityRequest(params); + await this.manageNeuron(request); + }; + /** * Changes auto-stake maturity for a Neuron. * diff --git a/packages/sns/src/sns.wrapper.spec.ts b/packages/sns/src/sns.wrapper.spec.ts index 22d9b5ce..eff8fdb3 100644 --- a/packages/sns/src/sns.wrapper.spec.ts +++ b/packages/sns/src/sns.wrapper.spec.ts @@ -609,6 +609,27 @@ describe("SnsWrapper", () => { }); }); + it("should call disburseMaturity", async () => { + const neuronId = { + id: arrayOfNumberToUint8Array([1, 2, 3]), + }; + const toAccount = { + owner: Principal.fromText("aaaaa-aa"), + subaccount: arrayOfNumberToUint8Array([0, 0, 1]), + }; + const percentageToDisburse = 50; + await snsWrapper.disburseMaturity({ + neuronId, + percentageToDisburse, + toAccount, + }); + expect(mockGovernanceCanister.disburseMaturity).toHaveBeenCalledWith({ + neuronId, + percentageToDisburse, + toAccount, + }); + }); + it("should call autoStakeMaturity", async () => { const neuronId = { id: arrayOfNumberToUint8Array([1, 2, 3]), diff --git a/packages/sns/src/sns.wrapper.ts b/packages/sns/src/sns.wrapper.ts index d8dfa1a7..03640b48 100644 --- a/packages/sns/src/sns.wrapper.ts +++ b/packages/sns/src/sns.wrapper.ts @@ -47,6 +47,7 @@ import type { SnsListNeuronsParams, SnsListProposalsParams, SnsNeuronAutoStakeMaturityParams, + SnsNeuronDisburseMaturityParams, SnsNeuronPermissionsParams, SnsNeuronStakeMaturityParams, SnsRegisterVoteParams, @@ -437,6 +438,10 @@ export class SnsWrapper { stakeMaturity = (params: SnsNeuronStakeMaturityParams): Promise => this.governance.stakeMaturity(params); + // Always certified + disburseMaturity = (params: SnsNeuronDisburseMaturityParams): Promise => + this.governance.disburseMaturity(params); + // Always certified autoStakeMaturity = ( params: SnsNeuronAutoStakeMaturityParams, diff --git a/packages/sns/src/types/governance.params.ts b/packages/sns/src/types/governance.params.ts index 5b8cfa12..7fa94166 100644 --- a/packages/sns/src/types/governance.params.ts +++ b/packages/sns/src/types/governance.params.ts @@ -165,6 +165,15 @@ export interface SnsNeuronStakeMaturityParams percentageToStake?: number; } +/** + * The parameters to disburse maturity of a neuron + */ +export interface SnsNeuronDisburseMaturityParams + extends SnsNeuronManagementParams { + toAccount?: IcrcAccount; + percentageToDisburse: number; +} + /** * The parameters to toggle auto stake maturity of a neuron */