@ledgerhq/coin-hedera 1.16.0-nightly.20251211024123 → 1.16.0-nightly.20251213023821

package/src/logic/getBlock.ts

@@ -4,10 +4,19 @@ import type {
   BlockOperation,
   BlockTransaction,
 } from "@ledgerhq/coin-framework/api/types";
+import { HEDERA_TRANSACTION_NAMES } from "../constants";
 import { getBlockInfo } from "./getBlockInfo";
 import { apiClient } from "../network/api";
-import type { HederaMirrorCoinTransfer, HederaMirrorTokenTransfer } from "../types";
-import { getMemoFromBase64, getTimestampRangeFromBlockHeight } from "./utils";
+import type {
+  HederaMirrorCoinTransfer,
+  HederaMirrorTokenTransfer,
+  HederaMirrorTransaction,
+} from "../types";
+import {
+  getMemoFromBase64,
+  analyzeStakingOperation,
+  getTimestampRangeFromBlockHeight,
+} from "./utils";
 
 function toHederaAsset(
   mirrorTransfer: HederaMirrorCoinTransfer | HederaMirrorTokenTransfer,
@@ -45,18 +54,60 @@ function toBlockOperation(
   };
 }
 
+function createStakingRewardOperations(tx: HederaMirrorTransaction): BlockOperation[] {
+  return tx.staking_reward_transfers.map(rewardTransfer => ({
+    type: "transfer",
+    address: rewardTransfer.account,
+    asset: { type: "native" },
+    amount: BigInt(rewardTransfer.amount),
+  }));
+}
+
 export async function getBlock(height: number): Promise<Block> {
   const { start, end } = getTimestampRangeFromBlockHeight(height);
   const blockInfo = await getBlockInfo(height);
   const transactions = await apiClient.getTransactionsByTimestampRange(start, end);
 
+  // analyze CRYPTOUPDATEACCOUNT transactions to distinguish staking operations from regular account updates.
+  // this creates a map of transaction_hash -> StakingAnalysis to avoid repeated lookups.
+  const stakingAnalyses = await Promise.all(
+    transactions
+      .filter(tx => tx.name === HEDERA_TRANSACTION_NAMES.UpdateAccount)
+      .map(async tx => {
+        const payerAccount = tx.transaction_id.split("-")[0];
+        const analysis = await analyzeStakingOperation(payerAccount, tx);
+
+        return [tx.transaction_hash, analysis] as const;
+      }),
+  );
+  const stakingAnalysisMap = new Map(stakingAnalyses);
+
   const blockTransactions: BlockTransaction[] = transactions.map(tx => {
     const payerAccount = tx.transaction_id.split("-")[0];
-    const allTransfers = [...tx.transfers, ...tx.token_transfers];
+    const stakingAnalysis = stakingAnalysisMap.get(tx.transaction_hash);
+
+    let operations: BlockOperation[];
+
+    if (stakingAnalysis) {
+      operations = [
+        {
+          type: "other",
+          operationType: stakingAnalysis.operationType,
+          stakedNodeId: stakingAnalysis.targetStakingNodeId,
+          previousStakedNodeId: stakingAnalysis.previousStakingNodeId,
+          stakedAmount: stakingAnalysis.stakedAmount,
+        },
+      ];
+    } else {
+      const allTransfers = [...tx.transfers, ...tx.token_transfers];
+      operations = allTransfers.map(transfer =>
+        toBlockOperation(payerAccount, tx.charged_tx_fee, transfer),
+      );
+    }
 
-    const operations = allTransfers.map(transfer =>
-      toBlockOperation(payerAccount, tx.charged_tx_fee, transfer),
-    );
+    // add staking reward operations if present (can occur on any transaction type)
+    const rewardOperations = createStakingRewardOperations(tx);
+    operations.push(...rewardOperations);
 
     return {
       hash: tx.transaction_hash,

package/src/logic/getValidators.test.ts

@@ -0,0 +1,50 @@
+import { getValidators } from "./getValidators";
+import { apiClient } from "../network/api";
+
+jest.mock("../network/api");
+
+describe("getValidators", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should return formatted validators with APY", async () => {
+    (apiClient.getNodes as jest.Mock).mockResolvedValue({
+      nodes: [
+        {
+          node_id: 1,
+          node_account_id: "0.0.3",
+          description: "Hosted by Ledger | Paris, France",
+          stake: 1000000,
+          reward_rate_start: 3538,
+        },
+      ],
+      nextCursor: null,
+    });
+
+    const result = await getValidators();
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]).toMatchObject({
+      address: "0.0.3",
+      nodeId: "1",
+      name: "Ledger",
+      description: "Hosted by Ledger | Paris, France",
+      balance: BigInt(1000000),
+      apy: expect.any(Number),
+    });
+    expect(result.items[0].apy).toBeCloseTo(0.01291, 5);
+  });
+
+  it("should handle pagination cursor", async () => {
+    (apiClient.getNodes as jest.Mock).mockResolvedValue({
+      nodes: [],
+      nextCursor: "123",
+    });
+
+    const result = await getValidators("100");
+
+    expect(apiClient.getNodes).toHaveBeenCalledWith({ cursor: "100", fetchAllPages: false });
+    expect(result.next).toBe("123");
+  });
+});

package/src/logic/getValidators.ts

@@ -0,0 +1,22 @@
+import type { Cursor, Page, Validator } from "@ledgerhq/coin-framework/api/types";
+import { apiClient } from "../network/api";
+import { calculateAPY, extractCompanyFromNodeDescription } from "./utils";
+
+export async function getValidators(cursor?: Cursor): Promise<Page<Validator>> {
+  const res = await apiClient.getNodes({
+    fetchAllPages: false,
+    ...(cursor && { cursor }),
+  });
+
+  return {
+    next: res.nextCursor ?? undefined,
+    items: res.nodes.map(node => ({
+      address: node.node_account_id,
+      nodeId: node.node_id.toString(),
+      name: extractCompanyFromNodeDescription(node.description),
+      description: node.description,
+      balance: BigInt(node.stake),
+      apy: calculateAPY(node.reward_rate_start),
+    })),
+  };
+}

package/src/logic/index.ts

@@ -9,3 +9,4 @@ export { lastBlock } from "./lastBlock";
 export { listOperations } from "./listOperations";
 export { getAssetFromToken } from "./getAssetFromToken";
 export { getTokenFromAsset } from "./getTokenFromAsset";
+export { getValidators } from "./getValidators";

package/src/logic/listOperations.ts

@@ -6,10 +6,21 @@ import type { Pagination } from "@ledgerhq/coin-framework/api/types";
 import { getCryptoAssetsStore } from "@ledgerhq/cryptoassets/state";
 import { encodeAccountId, encodeTokenAccountId } from "@ledgerhq/coin-framework/account/accountId";
 import { encodeOperationId } from "@ledgerhq/coin-framework/operation";
+import { HEDERA_TRANSACTION_NAMES } from "../constants";
 import { apiClient } from "../network/api";
 import { parseTransfers } from "../network/utils";
-import type { HederaMirrorToken, HederaMirrorTransaction, HederaOperationExtra } from "../types";
-import { base64ToUrlSafeBase64, getMemoFromBase64, getSyntheticBlock } from "./utils";
+import type {
+  HederaMirrorToken,
+  HederaMirrorTransaction,
+  HederaOperationExtra,
+  StakingAnalysis,
+} from "../types";
+import {
+  analyzeStakingOperation,
+  base64ToUrlSafeBase64,
+  getMemoFromBase64,
+  getSyntheticBlock,
+} from "./utils";
 
 const txNameToCustomOperationType: Record<string, OperationType> = {
   TOKENASSOCIATE: "ASSOCIATE_TOKEN",
@@ -129,12 +140,14 @@ function processTransfers({
   ledgerAccountId,
   commonData,
   mirrorTokens,
+  stakingAnalysis,
 }: {
   rawTx: HederaMirrorTransaction;
   address: string;
   ledgerAccountId: string;
   commonData: ReturnType<typeof getCommonOperationData>;
   mirrorTokens: HederaMirrorToken[];
+  stakingAnalysis: StakingAnalysis | null;
 }): Operation<HederaOperationExtra>[] {
   const coinOperations: Operation<HederaOperationExtra>[] = [];
   const transfers = rawTx.transfers ?? [];
@@ -146,7 +159,17 @@ function processTransfers({
   const { type, value, senders, recipients } = parseTransfers(transfers, address);
   const { hash, fee, timestamp, blockHeight, blockHash, hasFailed } = commonData;
   const extra = { ...commonData.extra };
-  const operationType = txNameToCustomOperationType[rawTx.name] ?? type;
+  let operationType = txNameToCustomOperationType[rawTx.name] ?? type;
+
+  // update operation type and extra fields if staking analysis is available
+  if (stakingAnalysis) {
+    operationType = stakingAnalysis.operationType;
+    extra.previousStakingNodeId = stakingAnalysis.previousStakingNodeId;
+    extra.targetStakingNodeId = stakingAnalysis.targetStakingNodeId;
+    extra.stakedAmount = new BigNumber(stakingAnalysis.stakedAmount.toString());
+  }
+
+  // each transfer may trigger staking reward claim
   const stakingReward = rawTx.staking_reward_transfers.reduce((acc, transfer) => {
     const transferAmount = new BigNumber(transfer.amount);
 
@@ -256,6 +279,12 @@ export async function listOperations({
   for (const rawTx of mirrorResult.transactions) {
     const commonData = getCommonOperationData(rawTx, useEncodedHash, useSyntheticBlocks);
 
+    // try to distinguish staking operations for CRYPTOUPDATEACCOUNT transactions
+    const stakingAnalysis =
+      rawTx.name === HEDERA_TRANSACTION_NAMES.UpdateAccount
+        ? await analyzeStakingOperation(address, rawTx)
+        : null;
+
     // process token transfers
     const tokenResult = await processTokenTransfers({
       rawTx,
@@ -277,6 +306,7 @@ export async function listOperations({
         ledgerAccountId,
         commonData,
         mirrorTokens,
+        stakingAnalysis,
       });
 
       coinOperations.push(...newCoinOperations);

package/src/logic/utils.test.ts

@@ -20,9 +20,11 @@ import {
   getMockedHTSTokenCurrency,
 } from "../test/fixtures/currency.fixture";
 import { getMockedAccount, getMockedTokenAccount } from "../test/fixtures/account.fixture";
+import { getMockedMirrorAccount } from "../test/fixtures/mirror.fixture";
 import type {
   HederaAccount,
   HederaMemo,
+  HederaMirrorTransaction,
   HederaPreloadData,
   HederaTxData,
   HederaValidator,
@@ -60,6 +62,8 @@ import {
   getChecksum,
   mapIntentToSDKOperation,
   getOperationDetailsExtraFields,
+  calculateAPY,
+  analyzeStakingOperation,
 } from "./utils";
 
 jest.mock("../network/api");
@@ -951,4 +955,113 @@ describe("logic utils", () => {
       ]);
     });
   });
+
+  describe("calculateAPY", () => {
+    it("should calculate APY correctly for a typical reward rate", () => {
+      const result = calculateAPY(3538);
+
+      expect(result).toBeCloseTo(0.01291, 5);
+    });
+
+    it("should return 0 for zero reward rate", () => {
+      const result = calculateAPY(0);
+
+      expect(result).toBe(0);
+    });
+  });
+
+  describe("analyzeStakingOperation", () => {
+    const mockAddress = "0.0.12345";
+    const mockTimestamp = "1762202064.065172388";
+    const mockTx = {
+      consensus_timestamp: mockTimestamp,
+      name: "CRYPTOUPDATEACCOUNT",
+    } as HederaMirrorTransaction;
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it("detects DELEGATE operation when staking starts", async () => {
+      const accountBefore = getMockedMirrorAccount({ staked_node_id: null });
+      const accountAfter = getMockedMirrorAccount({ staked_node_id: 5 });
+
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(accountBefore)
+        .mockResolvedValueOnce(accountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(result).toEqual({
+        operationType: "DELEGATE",
+        previousStakingNodeId: null,
+        targetStakingNodeId: 5,
+        stakedAmount: BigInt(1000),
+      });
+      expect(apiClient.getAccount).toHaveBeenCalledWith(mockAddress, `lt:${mockTimestamp}`);
+      expect(apiClient.getAccount).toHaveBeenCalledWith(mockAddress, `eq:${mockTimestamp}`);
+    });
+
+    it("detects UNDELEGATE operation when staking stops", async () => {
+      const accountBefore = getMockedMirrorAccount({ staked_node_id: 5 });
+      const accountAfter = getMockedMirrorAccount({ staked_node_id: null });
+
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(accountBefore)
+        .mockResolvedValueOnce(accountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(result).toEqual({
+        operationType: "UNDELEGATE",
+        previousStakingNodeId: 5,
+        targetStakingNodeId: null,
+        stakedAmount: BigInt(1000),
+      });
+    });
+
+    it("detects REDELEGATE operation when changing nodes", async () => {
+      const accountBefore = getMockedMirrorAccount({ staked_node_id: 3 });
+      const accountAfter = getMockedMirrorAccount({ staked_node_id: 10 });
+
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(accountBefore)
+        .mockResolvedValueOnce(accountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(result).toEqual({
+        operationType: "REDELEGATE",
+        previousStakingNodeId: 3,
+        targetStakingNodeId: 10,
+        stakedAmount: BigInt(1000),
+      });
+    });
+
+    it("returns null for regular account update (both null)", async () => {
+      const accountBefore = getMockedMirrorAccount({ staked_node_id: null });
+      const accountAfter = getMockedMirrorAccount({ staked_node_id: null });
+
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(accountBefore)
+        .mockResolvedValueOnce(accountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(result).toBeNull();
+    });
+
+    it("returns null when staked node doesn't change", async () => {
+      const accountBefore = getMockedMirrorAccount({ staked_node_id: 5 });
+      const accountAfter = getMockedMirrorAccount({ staked_node_id: 5 });
+
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(accountBefore)
+        .mockResolvedValueOnce(accountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(result).toBeNull();
+    });
+  });
 });

package/src/logic/utils.ts

@@ -15,21 +15,24 @@ import { InvalidAddress } from "@ledgerhq/errors";
 import { getEnv } from "@ledgerhq/live-env";
 import { makeLRUCache, seconds } from "@ledgerhq/live-network/cache";
 import type { Currency, ExplorerView, TokenCurrency } from "@ledgerhq/types-cryptoassets";
-import type { AccountLike, Operation as LiveOperation } from "@ledgerhq/types-live";
+import type { AccountLike, Operation as LiveOperation, OperationType } from "@ledgerhq/types-live";
 import {
   HEDERA_DELEGATION_STATUS,
   HEDERA_OPERATION_TYPES,
   HEDERA_TRANSACTION_MODES,
   SYNTHETIC_BLOCK_WINDOW_SECONDS,
+  TINYBAR_SCALE,
 } from "../constants";
 import { apiClient } from "../network/api";
 import type {
   HederaAccount,
   HederaMemo,
+  HederaMirrorTransaction,
   HederaOperationExtra,
   HederaTxData,
   HederaValidator,
   OperationDetailsExtraField,
+  StakingAnalysis,
   Transaction,
   TransactionStaking,
   TransactionStatus,
@@ -493,3 +496,66 @@ export const hasSpecificIntentData = <Type extends "staking" | "erc20">(
 ): txIntent is Extract<TransactionIntent<HederaMemo, HederaTxData>, { data: { type: Type } }> => {
   return "data" in txIntent && txIntent.data.type === expectedType;
 };
+
+export const calculateAPY = (rewardRateStart: number): number => {
+  const dailyRate = rewardRateStart / 10 ** TINYBAR_SCALE;
+  const annualRate = dailyRate * 365;
+
+  return annualRate;
+};
+
+/**
+ * Hedera uses the AccountUpdateTransaction for multiple purposes, including staking operations.
+ * Mirror node classifies all such transactions under the same name: "CRYPTOUPDATEACCOUNT".
+ *
+ * This function distinguishes between:
+ * - DELEGATE: Account started staking (staked_node_id changed from null to a node ID)
+ * - UNDELEGATE: Account stopped staking (staked_node_id changed from a node ID to null)
+ * - REDELEGATE: Account changed staking node (staked_node_id changed from one node to another)
+ *
+ * The analysis works by:
+ * 1. Fetching the account state BEFORE the transaction (using lt: timestamp filter)
+ * 2. Fetching the account state AFTER the transaction (using eq: timestamp filter)
+ * 3. Comparing the staked_node_id field to determine what changed
+ */
+export const analyzeStakingOperation = async (
+  address: string,
+  mirrorTx: HederaMirrorTransaction,
+): Promise<StakingAnalysis | null> => {
+  const [accountBefore, accountAfter] = await Promise.all([
+    apiClient.getAccount(address, `lt:${mirrorTx.consensus_timestamp}`),
+    apiClient.getAccount(address, `eq:${mirrorTx.consensus_timestamp}`),
+  ]);
+
+  let operationType: OperationType | null = null;
+  const previousStakingNodeId = accountBefore.staked_node_id;
+  const targetStakingNodeId = accountAfter.staked_node_id;
+
+  // stake: node id changed from null -> not null
+  if (previousStakingNodeId === null && targetStakingNodeId !== null) {
+    operationType = "DELEGATE";
+  }
+  // unstake: node id changed from not null -> null
+  else if (previousStakingNodeId !== null && targetStakingNodeId === null) {
+    operationType = "UNDELEGATE";
+  }
+  // restake: node id changed from not null -> different not null
+  else if (
+    previousStakingNodeId !== null &&
+    targetStakingNodeId !== null &&
+    previousStakingNodeId !== targetStakingNodeId
+  ) {
+    operationType = "REDELEGATE";
+  }
+
+  if (!operationType) {
+    return null;
+  }
+
+  return {
+    operationType,
+    previousStakingNodeId,
+    targetStakingNodeId,
+    stakedAmount: BigInt(accountAfter.balance.balance), // always entire balance on Hedera (fully liquid)
+  };
+};

package/src/network/api.test.ts

@@ -124,6 +124,8 @@ describe("getAccountTransactions", () => {
 });
 
 describe("getAccount", () => {
+  const mockAddress = "0.0.1234";
+
   beforeEach(() => {
     jest.resetAllMocks();
   });
@@ -131,7 +133,7 @@ describe("getAccount", () => {
   it("should call the correct endpoint and return account data", async () => {
     mockedNetwork.mockResolvedValueOnce(
       getMockResponse({
-        account: "0.0.1234",
+        account: mockAddress,
         max_automatic_token_associations: 0,
         balance: {
           balance: 1000,
@@ -141,13 +143,29 @@ describe("getAccount", () => {
       }),
     );
 
-    const result = await apiClient.getAccount("0.0.1234");
+    const result = await apiClient.getAccount(mockAddress);
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
 
-    expect(result.account).toEqual("0.0.1234");
-    expect(requestUrl).toContain("/api/v1/accounts/0.0.1234");
+    expect(result.account).toEqual(mockAddress);
+    expect(requestUrl).toContain(`/api/v1/accounts/${mockAddress}?transactions=false`);
     expect(mockedNetwork).toHaveBeenCalledTimes(1);
   });
+
+  it("supports timestamp filter", async () => {
+    const mockAccount = { account: mockAddress, staked_node_id: null };
+    const timestamp = "lt:1762202064.065172388";
+
+    (network as jest.Mock).mockResolvedValueOnce({ data: mockAccount });
+
+    const result = await apiClient.getAccount(mockAddress, timestamp);
+    const requestUrl = mockedNetwork.mock.calls[0][0].url;
+
+    expect(mockedNetwork).toHaveBeenCalledTimes(1);
+    expect(result).toEqual(mockAccount);
+    expect(requestUrl).toContain(
+      `/api/v1/accounts/${mockAddress}?transactions=false&timestamp=${encodeURIComponent(timestamp)}`,
+    );
+  });
 });
 
 describe("getAccountTokens", () => {
@@ -536,17 +554,17 @@ describe("getNodes", () => {
       }),
     );
 
-    const result = await apiClient.getNodes();
+    const result = await apiClient.getNodes({ fetchAllPages: true });
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
 
-    expect(result.map(n => n.node_id)).toEqual([0, 1]);
+    expect(result.nodes.map(n => n.node_id)).toEqual([0, 1]);
     expect(requestUrl).toContain("/api/v1/network/nodes");
     expect(requestUrl).toContain("limit=100");
     expect(requestUrl).toContain("order=desc");
     expect(mockedNetwork).toHaveBeenCalledTimes(1);
   });
 
-  it("should keep fetching if links.next is present and new nodes are returned", async () => {
+  it("should keep fetching if fetchAllPages and links.next is present", async () => {
     mockedNetwork
       .mockResolvedValueOnce(
         getMockResponse({
@@ -567,9 +585,37 @@ describe("getNodes", () => {
         }),
       );
 
-    const result = await apiClient.getNodes();
+    const result = await apiClient.getNodes({ fetchAllPages: true });
 
-    expect(result.map(n => n.node_id)).toEqual([0, 1, 2]);
+    expect(result.nodes.map(n => n.node_id)).toEqual([0, 1, 2]);
     expect(mockedNetwork).toHaveBeenCalledTimes(3);
   });
+
+  it("should paginate if fetchAllPages is not set", async () => {
+    mockedNetwork
+      .mockResolvedValueOnce(
+        getMockResponse({
+          nodes: [
+            { node_id: 0, node_account_id: "0.0.3" },
+            { node_id: 1, node_account_id: "0.0.4" },
+          ],
+          links: { next: "/next-1" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        getMockResponse({
+          nodes: [{ node_id: 2, node_account_id: "0.0.5" }],
+          links: { next: null },
+        }),
+      );
+
+    const result = await apiClient.getNodes({
+      limit: 2,
+      fetchAllPages: false,
+    });
+
+    expect(result.nodes.map(tx => tx.node_id)).toEqual([0, 1]);
+    expect(result.nextCursor).toBe("1");
+    expect(mockedNetwork).toHaveBeenCalledTimes(1);
+  });
 });