NNS1-3139: Utils to get maturity from nns/sns neurons (#5235)

# Motivation

Make getting available/staked maturity from nns/sns neurons consistent
and straightforward.
I plan to use these for the projects table as well as the neurons table.

# Changes

1. Add utility functions get available and staked maturity from NNS and
SNS neurons.
2. Use them in `neurons-table.utils.ts` instead of getting the maturity
directly.

# Tests

1. Unit tests added for the new functions.
2. Existing `frontend/src/lib/utils/neurons-table.utils.ts` tests pass.

# Todos

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

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

@@ -472,6 +472,12 @@ export const neuronStake = (neuron: NeuronInfo): bigint =>
     ? neuron.fullNeuron?.cachedNeuronStake - neuron.fullNeuron?.neuronFees
     : 0n;
 
+export const neuronAvailableMaturity = (neuron: NeuronInfo): bigint =>
+  neuron.fullNeuron?.maturityE8sEquivalent ?? 0n;
+
+export const neuronStakedMaturity = (neuron: NeuronInfo): bigint =>
+  neuron.fullNeuron?.stakedMaturityE8sEquivalent ?? 0n;
+
 export interface FolloweesNeuron {
   neuronId: NeuronId;
   topics: [Topic, ...Topic[]];

frontend/src/lib/utils/neurons-table.utils.ts

@@ -6,7 +6,9 @@ import { buildNeuronUrl } from "$lib/utils/navigation.utils";
 import {
   getNeuronTags,
   isSpawning,
+  neuronAvailableMaturity,
   neuronStake,
+  neuronStakedMaturity,
 } from "$lib/utils/neuron.utils";
 import {
   createAscendingComparator,
@@ -15,21 +17,18 @@ import {
 } from "$lib/utils/responsive-table.utils";
 import {
   getSnsDissolveDelaySeconds,
+  getSnsNeuronAvailableMaturity,
   getSnsNeuronIdAsHexString,
   getSnsNeuronStake,
+  getSnsNeuronStakedMaturity,
   getSnsNeuronState,
   getSnsNeuronTags,
 } from "$lib/utils/sns-neuron.utils";
 import type { Identity } from "@dfinity/agent";
 import type { NeuronInfo } from "@dfinity/nns";
 import { NeuronState } from "@dfinity/nns";
 import type { SnsNeuron } from "@dfinity/sns";
-import {
-  ICPToken,
-  TokenAmountV2,
-  fromNullable,
-  type Token,
-} from "@dfinity/utils";
+import { ICPToken, TokenAmountV2, type Token } from "@dfinity/utils";
 
 export const tableNeuronsFromNeuronInfos = ({
   neuronInfos,
@@ -60,8 +59,8 @@ export const tableNeuronsFromNeuronInfos = ({
         amount: neuronStake(neuronInfo),
         token: ICPToken,
       }),
-      availableMaturity: neuronInfo.fullNeuron?.maturityE8sEquivalent ?? 0n,
-      stakedMaturity: neuronInfo.fullNeuron?.stakedMaturityE8sEquivalent ?? 0n,
+      availableMaturity: neuronAvailableMaturity(neuronInfo),
+      stakedMaturity: neuronStakedMaturity(neuronInfo),
       dissolveDelaySeconds,
       state: neuronInfo.state,
       tags: getNeuronTags({
@@ -102,9 +101,8 @@ export const tableNeuronsFromSnsNeurons = ({
         amount: getSnsNeuronStake(snsNeuron),
         token,
       }),
-      availableMaturity: snsNeuron.maturity_e8s_equivalent ?? 0n,
-      stakedMaturity:
-        fromNullable(snsNeuron.staked_maturity_e8s_equivalent) ?? 0n,
+      availableMaturity: getSnsNeuronAvailableMaturity(snsNeuron),
+      stakedMaturity: getSnsNeuronStakedMaturity(snsNeuron),
       dissolveDelaySeconds,
       state: getSnsNeuronState(snsNeuron),
       tags: getSnsNeuronTags({

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

@@ -121,6 +121,12 @@ export const getSnsNeuronStake = ({
   neuron_fees_e8s,
 }: SnsNeuron): bigint => cached_neuron_stake_e8s - neuron_fees_e8s;
 
+export const getSnsNeuronAvailableMaturity = (neuron: SnsNeuron): bigint =>
+  neuron.maturity_e8s_equivalent;
+
+export const getSnsNeuronStakedMaturity = (neuron: SnsNeuron): bigint =>
+  fromNullable(neuron.staked_maturity_e8s_equivalent) ?? 0n;
+
 export const getSnsNeuronByHexId = ({
   neuronIdHex,
   neurons,

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

@@ -56,8 +56,10 @@ import {
   maturityLastDistribution,
   minNeuronSplittable,
   neuronAge,
+  neuronAvailableMaturity,
   neuronCanBeSplit,
   neuronStake,
+  neuronStakedMaturity,
   neuronVotingPower,
   neuronsVotingPower,
   sortNeuronsByStake,
@@ -989,6 +991,50 @@ describe("neuron-utils", () => {
     });
   });
 
+  describe("neuronAvailableMaturity", () => {
+    it("should calculate available maturity", () => {
+      const maturity = 100234n;
+      const neuron = {
+        ...mockNeuron,
+        fullNeuron: {
+          ...mockFullNeuron,
+          maturityE8sEquivalent: maturity,
+        },
+      };
+      expect(neuronAvailableMaturity(neuron)).toBe(maturity);
+    });
+
+    it("should return 0n when maturity is not available", () => {
+      const neuron = {
+        ...mockNeuron,
+        fullNeuron: undefined,
+      };
+      expect(neuronAvailableMaturity(neuron)).toBe(0n);
+    });
+  });
+
+  describe("neuronStakedMaturity", () => {
+    it("should calculate staked maturity", () => {
+      const maturity = 100235n;
+      const neuron = {
+        ...mockNeuron,
+        fullNeuron: {
+          ...mockFullNeuron,
+          stakedMaturityE8sEquivalent: maturity,
+        },
+      };
+      expect(neuronStakedMaturity(neuron)).toBe(maturity);
+    });
+
+    it("should return 0n when maturity is not available", () => {
+      const neuron = {
+        ...mockNeuron,
+        fullNeuron: undefined,
+      };
+      expect(neuronStakedMaturity(neuron)).toBe(0n);
+    });
+  });
+
   describe("ballotsWithDefinedProposal", () => {
     const ballot: BallotInfo = {
       vote: Vote.Yes,

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

@@ -22,10 +22,12 @@ import {
   getSnsDissolvingTimeInSeconds,
   getSnsDissolvingTimestampSeconds,
   getSnsLockedTimeInSeconds,
+  getSnsNeuronAvailableMaturity,
   getSnsNeuronByHexId,
   getSnsNeuronHotkeys,
   getSnsNeuronIdAsHexString,
   getSnsNeuronStake,
+  getSnsNeuronStakedMaturity,
   getSnsNeuronState,
   getSnsNeuronTags,
   getSnsNeuronVote,
@@ -352,6 +354,36 @@ describe("sns-neuron utils", () => {
     });
   });
 
+  describe("getSnsNeuronAvailableMaturity", () => {
+    it("returns available maturity", () => {
+      const maturity = 1234n;
+      const neuron: SnsNeuron = {
+        ...mockSnsNeuron,
+        maturity_e8s_equivalent: maturity,
+      };
+      expect(getSnsNeuronAvailableMaturity(neuron)).toBe(maturity);
+    });
+  });
+
+  describe("getSnsNeuronStakedMaturity", () => {
+    it("returns staked maturity", () => {
+      const maturity = 5432n;
+      const neuron: SnsNeuron = {
+        ...mockSnsNeuron,
+        staked_maturity_e8s_equivalent: [maturity],
+      };
+      expect(getSnsNeuronStakedMaturity(neuron)).toBe(maturity);
+    });
+
+    it("returns 0 when absent", () => {
+      const neuron: SnsNeuron = {
+        ...mockSnsNeuron,
+        staked_maturity_e8s_equivalent: [],
+      };
+      expect(getSnsNeuronStakedMaturity(neuron)).toBe(0n);
+    });
+  });
+
   describe("getSnsNeuronIdAsHexString", () => {
     it("returns id numbers concatenated", () => {
       const id = [