Rename neuronVotingPower (#6288)

# Motivation

To better reflect its purpose, the neuronVotingPower function has been
renamed to neuronPotentialVotingPower. This change was made because,
with the introduction of periodic confirmation, an NNS neuron can have
both potential and deciding voting power, which are not the same.

# Changes

- Renamed the function for clarity.
- Updated comments for better documentation.

# Tests

- Pass.

# Todos

- [ ] Add entry to changelog (if necessary).
Not necessary.

frontend/src/lib/components/neurons/ConfirmDissolveDelay.svelte

@@ -7,7 +7,7 @@
   import {
     formatVotingPower,
     neuronStake,
-    neuronVotingPower,
+    neuronPotentialVotingPower,
   } from "$lib/utils/neuron.utils";
   import { formatTokenE8s } from "$lib/utils/token.utils";
   import { valueSpan } from "$lib/utils/utils";
@@ -66,7 +66,7 @@
     <p class="label">{$i18n.neurons.voting_power}</p>
     <p class="value">
       {formatVotingPower(
-        neuronVotingPower({
+        neuronPotentialVotingPower({
           neuron,
           newDissolveDelayInSeconds: delayInSeconds,
         })

frontend/src/lib/components/neurons/SetNnsDissolveDelay.svelte

@@ -6,7 +6,7 @@
   import { i18n } from "$lib/stores/i18n";
   import {
     neuronStake as getNeuronStake,
-    neuronVotingPower,
+    neuronPotentialVotingPower,
   } from "$lib/utils/neuron.utils";
   import type { NeuronInfo } from "@dfinity/nns";
 
@@ -23,7 +23,7 @@
   });
   const calculateVotingPower = (delayInSeconds: number) =>
     Number(
-      neuronVotingPower({
+      neuronPotentialVotingPower({
         neuron,
         newDissolveDelayInSeconds: BigInt(Math.round(delayInSeconds)),
       })

frontend/src/lib/utils/neuron.utils.ts

@@ -113,11 +113,12 @@ const stateInfoMapper: StateMapper = {
 export const getStateInfo = (neuronState: NeuronState): StateInfo =>
   stateInfoMapper[neuronState];
 
-// TODO(mstr): Rename to neuronPotentialVotingPower
 /**
- * Calculation of the voting power of a neuron.
+ * Calculation of the potential voting power of a neuron.
  *
- * Note: This calculation ignores the case where the neuron starts missing voting rewards due to user inactivity (related to votingPowerRefreshedTimestampSeconds).
+ * Note: The result is equal to the neuron’s potentialVotingPower field value.
+ * The actual voting power of the neuron can be found in the decidingVotingPower field,
+ * as it accounts for missing voting rewards due to user inactivity (votingPowerRefreshedTimestampSeconds).
  *
  * If neuron's dissolve delay is less than 6 months, the voting power is 0.
  *
@@ -139,7 +140,7 @@ export const getStateInfo = (neuronState: NeuronState): StateInfo =>
  * @param {number} params.newDissolveDelayInSeconds It will calculate the voting power with the new dissolve delay if provided
  * @returns {bigint}
  */
-export const neuronVotingPower = ({
+export const neuronPotentialVotingPower = ({
   neuron,
   newDissolveDelayInSeconds,
 }: {
@@ -171,12 +172,12 @@ interface VotingPowerParams {
   minDissolveDelaySeconds?: number;
 }
 
-// TODO(mstr): Rename to calculatePotentialNeuronVotingPower
-// Because it doesn't take into account the NNS neuron's activity state.
 /**
- * For now used only internally in this file.
+ * Calculate the voting power of a neuron.
  *
- * It might be useful to use it for SNS neurons.
+ * Note: For the NNS neurons it calculates potential voting power (similar to neuron.potentialVotingPower).
+ * The actual voting power of the NNS neuron can be found in the decidingVotingPower field,
+ * as it accounts for missing voting rewards due to user inactivity (votingPowerRefreshedTimestampSeconds).
  *
  * @param {VotingPowerParams}
  * @returns {bigint}

frontend/src/tests/lib/utils/neuron.utils.spec.ts

@@ -65,9 +65,9 @@ import {
   neuronAge,
   neuronAvailableMaturity,
   neuronCanBeSplit,
+  neuronPotentialVotingPower,
   neuronStake,
   neuronStakedMaturity,
-  neuronVotingPower,
   neuronsVotingPower,
   secondsUntilMissingReward,
   shouldDisplayMissingRewardNotification,
@@ -118,7 +118,7 @@ describe("neuron-utils", () => {
     neuronsStore.setNeurons({ neurons: [], certified: true });
   });
 
-  describe("votingPower", () => {
+  describe("neuronPotentialVotingPower", () => {
     const tokenStake = TokenAmount.fromString({
       amount: "2.2",
       token: ICPToken,
@@ -134,7 +134,7 @@ describe("neuron-utils", () => {
     };
     it("should return zero for delays less than six months", () => {
       expect(
-        neuronVotingPower({
+        neuronPotentialVotingPower({
           neuron: mockNeuron,
           newDissolveDelayInSeconds: 100n,
         })
@@ -143,7 +143,7 @@ describe("neuron-utils", () => {
 
     it("should return more than stake when delay more than six months", () => {
       expect(
-        neuronVotingPower({
+        neuronPotentialVotingPower({
           neuron,
           newDissolveDelayInSeconds: BigInt(
             SECONDS_IN_HALF_YEAR + SECONDS_IN_HOUR
@@ -158,7 +158,7 @@ describe("neuron-utils", () => {
         dissolveDelaySeconds: BigInt(SECONDS_IN_EIGHT_YEARS),
       };
       expect(
-        neuronVotingPower({
+        neuronPotentialVotingPower({
           neuron: agedNeuron,
         })
       ).toBe(tokenStake.toE8s() * 2n);
@@ -176,10 +176,10 @@ describe("neuron-utils", () => {
         ageSeconds: 2n,
         dissolveDelaySeconds: BigInt(SECONDS_IN_YEAR),
       };
-      const powerWithAge = neuronVotingPower({
+      const powerWithAge = neuronPotentialVotingPower({
         neuron: agedNeuron,
       });
-      const powerWithoutAge = neuronVotingPower({
+      const powerWithoutAge = neuronPotentialVotingPower({
         neuron: notSoAgedNeuron,
       });
       expect(powerWithAge).toBeGreaterThan(powerWithoutAge);
@@ -191,11 +191,11 @@ describe("neuron-utils", () => {
         ageSeconds: BigInt(SECONDS_IN_YEAR),
         dissolveDelaySeconds: BigInt(SECONDS_IN_YEAR),
       };
-      const powerWithNewDissolve = neuronVotingPower({
+      const powerWithNewDissolve = neuronPotentialVotingPower({
         neuron: agedNeuron,
         newDissolveDelayInSeconds: BigInt(SECONDS_IN_EIGHT_YEARS),
       });
-      const powerWithoutAge = neuronVotingPower({
+      const powerWithoutAge = neuronPotentialVotingPower({
         neuron: agedNeuron,
       });
       expect(powerWithNewDissolve).toBeGreaterThan(powerWithoutAge);
@@ -211,7 +211,7 @@ describe("neuron-utils", () => {
           cachedNeuronStake: 200_000_000n,
         },
       };
-      const power = neuronVotingPower({
+      const power = neuronPotentialVotingPower({
         neuron,
       });
       expect(power).toEqual(252_343_750n);