feat(explorer): add balance breakdown to address page

.changeset/old-geckos-travel.md

@@ -0,0 +1,5 @@
+---
+'@iota/apps-ui-kit': patch
+---
+
+Fix tooltip being cut by other boxes

apps/core/src/hooks/stake/useTotalDelegatedStake.ts

@@ -3,10 +3,13 @@
 
 import { useMemo } from 'react';
 import { type ExtendedDelegatedStake } from '../../utils/stake';
+import { ExtendedDelegatedTimelockedStake } from '../../interfaces';
 
-export function useTotalDelegatedStake(delegatedStake: ExtendedDelegatedStake[]) {
+export function useTotalDelegatedStake(
+    delegatedStakes: ExtendedDelegatedStake[] | ExtendedDelegatedTimelockedStake[],
+) {
     return useMemo(() => {
-        if (!delegatedStake) return 0n;
-        return delegatedStake.reduce((acc, curr) => acc + BigInt(curr.principal), 0n);
-    }, [delegatedStake]);
+        if (!delegatedStakes) return 0n;
+        return delegatedStakes.reduce((acc, curr) => acc + BigInt(curr.principal), 0n);
+    }, [delegatedStakes]);
 }

apps/core/src/interfaces/index.ts

@@ -4,3 +4,4 @@
 export * from './balanceChange.interfaces';
 export * from './transactions.interfaces';
 export * from './stakeEvent.interfaces';
+export * from './timelock.interfaces';

apps/wallet-dashboard/lib/interfaces/timelock.interfaces.ts → apps/core/src/interfaces/timelock.interfaces.ts

@@ -1,6 +1,8 @@
 // Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+import { TimelockedStake } from '@iota/iota-sdk/client';
+
 export interface UID {
     id: string;
 }
@@ -22,3 +24,8 @@ export interface TimelockedIotaResponse {
     expiration_timestamp_ms: string;
     label?: string;
 }
+
+export type ExtendedDelegatedTimelockedStake = TimelockedStake & {
+    validatorAddress: string;
+    stakingPool: string;
+};

apps/core/src/utils/formatDelegatedTimelockedStake.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { DelegatedTimelockedStakeSchema } from './stake/types';
+import type { DelegatedTimelockedStake } from '@iota/iota-sdk/client';
+import type { ExtendedDelegatedTimelockedStake } from '../interfaces';
+
+export function formatDelegatedTimelockedStake(
+    delegatedTimelockedStakeData: DelegatedTimelockedStake[],
+): ExtendedDelegatedTimelockedStake[] {
+    return delegatedTimelockedStakeData.flatMap((delegatedTimelockedStake) => {
+        const validatedDelegatedTimelockedStake =
+            DelegatedTimelockedStakeSchema.parse(delegatedTimelockedStake);
+
+        return validatedDelegatedTimelockedStake.stakes.map((stake) => {
+            return {
+                validatorAddress: delegatedTimelockedStake.validatorAddress,
+                stakingPool: delegatedTimelockedStake.stakingPool,
+                estimatedReward: stake.status === 'Active' ? stake.estimatedReward : '',
+                stakeActiveEpoch: stake.stakeActiveEpoch,
+                stakeRequestEpoch: stake.stakeRequestEpoch,
+                status: stake.status,
+                timelockedStakedIotaId: stake.timelockedStakedIotaId,
+                principal: stake.principal,
+                expirationTimestampMs: stake.expirationTimestampMs,
+                label: stake.label,
+            };
+        });
+    });
+}

apps/core/src/utils/index.ts

@@ -27,6 +27,8 @@ export * from './toTitleCase';
 export * from './formatBalanceToUSD';
 export * from './getGasBudgetErrorMessage';
 export * from './sumCoinBalances';
+export * from './mapTimelockObjects';
+export * from './formatDelegatedTimelockedStake';
 
 export * from './stake';
 export * from './transaction';

apps/core/src/utils/mapTimelockObjects.ts

@@ -0,0 +1,33 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { IotaObjectData } from '@iota/iota-sdk/client';
+import { TimelockedIotaObjectSchema, TimelockedObjectFieldsSchema } from './stake/types';
+import { TimelockedIotaResponse, TimelockedObject } from '../interfaces/timelock.interfaces';
+
+export function mapTimelockObjects(iotaObjects: IotaObjectData[]): TimelockedObject[] {
+    return iotaObjects.map((iotaObject) => {
+        const validIotaObject = TimelockedIotaObjectSchema.parse(iotaObject);
+
+        if (
+            !validIotaObject?.content?.dataType ||
+            validIotaObject.content.dataType !== 'moveObject'
+        ) {
+            return {
+                id: { id: '' },
+                locked: { value: 0n },
+                expirationTimestampMs: 0,
+            };
+        }
+        const fields = validIotaObject.content.fields as unknown as TimelockedIotaResponse;
+
+        const validFields = TimelockedObjectFieldsSchema.parse(fields);
+
+        return {
+            id: validFields.id,
+            locked: { value: BigInt(validFields?.locked || '0') },
+            expirationTimestampMs: Number(validFields.expiration_timestamp_ms),
+            label: validFields.label,
+        };
+    });
+}

apps/explorer/src/pages/address-result/AddressBalanceBreakdown.tsx

@@ -0,0 +1,222 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    Collapsible,
+    formatDelegatedStake,
+    formatDelegatedTimelockedStake,
+    mapTimelockObjects,
+    TIMELOCK_IOTA_TYPE,
+    useBalance,
+    useFormatCoin,
+    useGetAllOwnedObjects,
+    useGetDelegatedStake,
+    useGetTimelockedStakedObjects,
+    useTotalDelegatedStake,
+} from '@iota/core';
+import { Divider, KeyValueInfo, Panel, Skeleton, Title, TitleSize } from '@iota/apps-ui-kit';
+import { useState } from 'react';
+
+const TOOLTIP_TEXT = 'This balance breakdown does not include unmigrated stardust funds.';
+interface BalanceBreakdownElement {
+    keyText: string;
+    value: string;
+    supportingLabel: string;
+    isLoading?: boolean;
+    isError?: boolean;
+    tooltipText?: string;
+}
+
+export function AddressBalanceBreakdown({ address }: { address: string }): React.JSX.Element {
+    const [open, setOpen] = useState(true);
+    const {
+        data: balance,
+        isLoading: isLoadingBalance,
+        isError: isBalanceErrored,
+    } = useBalance(address);
+
+    const [totalAvailableBalance, symbol] = useFormatCoin({
+        balance: balance?.totalBalance,
+    });
+
+    const {
+        data: delegatedStake,
+        isLoading: isLoadingDelegatedStakes,
+        isError: isDelegatedStakeErrored,
+    } = useGetDelegatedStake({
+        address,
+    });
+    const delegatedStakes = delegatedStake ? formatDelegatedStake(delegatedStake) : [];
+    const totalDelegatedStake = useTotalDelegatedStake(delegatedStakes);
+    const [formattedDelegatedStake] = useFormatCoin({
+        balance: totalDelegatedStake,
+    });
+
+    const {
+        data: timelockedStakedObjects,
+        isLoading: isLoadingTimelockedStakeObjects,
+        isError: isTimelockedStakedObjectsErrored,
+    } = useGetTimelockedStakedObjects(address);
+
+    const extendedDelegatedTimelockedStakes = formatDelegatedTimelockedStake(
+        timelockedStakedObjects || [],
+    );
+
+    const totalTimelockedStaked = useTotalDelegatedStake(extendedDelegatedTimelockedStakes);
+    const [formattedTimelockedStake] = useFormatCoin({
+        balance: totalTimelockedStaked,
+    });
+
+    const {
+        data: timelockedObjects,
+        isLoading: isTimelockedObjectsLoading,
+        isError: isTimelockedObjectsError,
+    } = useGetAllOwnedObjects(address, {
+        StructType: TIMELOCK_IOTA_TYPE,
+    });
+
+    const mappedTimelockedObjects = mapTimelockObjects(timelockedObjects || []);
+
+    const totalTimelockedTokens = mappedTimelockedObjects.reduce(
+        (acc, obj) => acc + BigInt(obj.locked.value),
+        BigInt(0),
+    );
+
+    const [formattedTimelockedTokens] = useFormatCoin({
+        balance: totalTimelockedTokens,
+    });
+
+    const totalBalanceBreakdown =
+        BigInt(balance?.totalBalance || 0) +
+        BigInt(totalDelegatedStake || 0) +
+        BigInt(totalTimelockedStaked || 0) +
+        BigInt(totalTimelockedTokens || 0);
+
+    const [formattedTotalBalance] = useFormatCoin({
+        balance: totalBalanceBreakdown,
+    });
+
+    const isLoadingTotalBalance =
+        isLoadingBalance ||
+        isLoadingDelegatedStakes ||
+        isLoadingTimelockedStakeObjects ||
+        isTimelockedObjectsLoading;
+
+    const isTotalBalanceErrored =
+        isBalanceErrored ||
+        isDelegatedStakeErrored ||
+        isTimelockedStakedObjectsErrored ||
+        isTimelockedObjectsError;
+
+    const BALANCE_BREAKDOWN: BalanceBreakdownElement[] = [
+        {
+            keyText: 'Available',
+            value: totalAvailableBalance,
+            supportingLabel: symbol,
+            isLoading: isLoadingBalance,
+            isError: isBalanceErrored,
+            tooltipText: 'IOTA that can be used or transferred immediately.',
+        },
+        {
+            keyText: 'Staked',
+            value: formattedDelegatedStake,
+            supportingLabel: symbol,
+            isLoading: isLoadingDelegatedStakes,
+            isError: isDelegatedStakeErrored,
+            tooltipText: 'IOTA currently locked in staking. Cannot be used until unstaked.',
+        },
+        {
+            keyText: 'Timelocked Staked',
+            value: formattedTimelockedStake,
+            supportingLabel: symbol,
+            isLoading: isLoadingTimelockedStakeObjects,
+            isError: isTimelockedStakedObjectsErrored,
+            tooltipText:
+                'IOTA both timelocked and staked. To access these funds, they must first be unstaked, and then handled according to their timelock conditions.',
+        },
+        {
+            keyText: 'Timelocked',
+            value: formattedTimelockedTokens,
+            supportingLabel: symbol,
+            isLoading: isTimelockedObjectsLoading,
+            isError: isTimelockedObjectsError,
+            tooltipText:
+                "IOTA locked until a specific time. Depending on the lock's expiration, these funds can either be used for staking or collected when the timelock allows it.",
+        },
+    ];
+    return (
+        <Panel>
+            <div className="relative overflow-visible">
+                <Collapsible
+                    hideBorder
+                    isOpen={open}
+                    onOpenChange={(isOpen) => setOpen(isOpen)}
+                    render={() => (
+                        <div className="flex w-full flex-row items-center justify-between">
+                            <Title
+                                size={TitleSize.Small}
+                                title="Balance Breakdown"
+                                tooltipText={TOOLTIP_TEXT}
+                            />
+                        </div>
+                    )}
+                >
+                    <div className="flex flex-col gap-y-sm p-md--rs">
+                        {BALANCE_BREAKDOWN.map((item) => (
+                            <KeyValueInfo
+                                key={item.keyText}
+                                keyText={item.keyText}
+                                tooltipText={item.tooltipText}
+                                fullwidth
+                                value={
+                                    <RenderBalanceValue
+                                        value={item.value}
+                                        isLoading={item.isLoading}
+                                        isError={item.isError}
+                                    />
+                                }
+                                supportingLabel={item.supportingLabel}
+                            />
+                        ))}
+                    </div>
+                </Collapsible>
+                <div className="flex flex-col gap-y-sm px-md pb-md">
+                    <Divider />
+                    <KeyValueInfo
+                        keyText="Total"
+                        value={
+                            <RenderBalanceValue
+                                value={formattedTotalBalance}
+                                isLoading={isLoadingTotalBalance}
+                                isError={isTotalBalanceErrored}
+                            />
+                        }
+                        fullwidth
+                        supportingLabel={symbol}
+                    />
+                </div>
+            </div>
+        </Panel>
+    );
+}
+
+interface RenderBalanceValueProps {
+    value: string;
+    isLoading?: boolean;
+    isError?: boolean;
+}
+
+function RenderBalanceValue({
+    value,
+    isLoading,
+    isError,
+}: RenderBalanceValueProps): React.JSX.Element | string {
+    if (isLoading) {
+        return <Skeleton widthClass="w-20" heightClass="h-4" />;
+    }
+    if (isError) {
+        return '--';
+    }
+
+    return value;
+}

apps/explorer/src/pages/address-result/AddressResult.tsx

@@ -14,7 +14,7 @@ import { PageHeader, SplitPanes } from '~/components/ui';
 import { useBreakpoint } from '~/hooks/useBreakpoint';
 import { LocalStorageSplitPaneKey } from '~/lib/enums';
 import { Panel, Title, Divider } from '@iota/apps-ui-kit';
-import { TotalStaked } from './TotalStaked';
+import { AddressBalanceBreakdown } from './AddressBalanceBreakdown';
 
 const LEFT_RIGHT_PANEL_MIN_SIZE = 30;
 
@@ -23,7 +23,7 @@ interface AddressResultPageHeaderProps {
 }
 
 function AddressResultPageHeader({ address }: AddressResultPageHeaderProps): JSX.Element {
-    return <PageHeader type="Address" title={address} after={<TotalStaked address={address} />} />;
+    return <PageHeader type="Address" title={address} />;
 }
 
 function AddressResult({ address }: { address: string }): JSX.Element {
@@ -55,6 +55,7 @@ export function AddressResultPage(): JSX.Element {
             content={
                 <div className="flex flex-col gap-2xl">
                     <AddressResultPageHeader address={id!} />
+                    <AddressBalanceBreakdown address={id!} />
                     <AddressResult address={id!} />
                 </div>
             }