@ledgerhq/coin-hedera 1.16.0-nightly.20251218023953 → 1.16.0-nightly.20251219024040

package/src/logic/utils.test.ts

@@ -9,6 +9,7 @@ import {
   HEDERA_OPERATION_TYPES,
   HEDERA_TRANSACTION_MODES,
   SYNTHETIC_BLOCK_WINDOW_SECONDS,
+  OP_TYPES_EXCLUDING_FEES,
 } from "../constants";
 import { HederaRecipientInvalidChecksum } from "../errors";
 import { apiClient } from "../network/api";
@@ -64,6 +65,7 @@ import {
   getOperationDetailsExtraFields,
   calculateAPY,
   analyzeStakingOperation,
+  calculateUncommittedBalanceChange,
 } from "./utils";
 
 jest.mock("../network/api");
@@ -152,14 +154,16 @@ describe("logic utils", () => {
       expect(getOperationValue({ asset: tokenAsset, operation })).toBe(BigInt(0));
     });
 
-    it("should substract fee from value for native OUT operations", () => {
-      const operation = getMockedOperation({
-        type: "OUT",
-        value: BigNumber(1000),
-        fee: BigNumber(100),
-      });
+    it("should subtract fee from native operations that exclude fees", () => {
+      OP_TYPES_EXCLUDING_FEES.forEach(type => {
+        const operation = getMockedOperation({
+          type,
+          value: BigNumber(1000),
+          fee: BigNumber(100),
+        });
 
-      expect(getOperationValue({ asset: nativeAsset, operation })).toBe(BigInt(900));
+        expect(getOperationValue({ asset: nativeAsset, operation })).toBe(BigInt(900));
+      });
     });
 
     it("should return value for other operations", () => {
@@ -970,6 +974,123 @@ describe("logic utils", () => {
     });
   });
 
+  describe("calculateUncommittedBalanceChange", () => {
+    const mockAddress = "0.0.12345";
+    const mockStartTimestamp = "1762202064.065172388";
+    const mockEndTimestamp = "1762202074.065172388";
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it("should return 0 when there are no transactions in the time range", async () => {
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce([]);
+
+      const result = await calculateUncommittedBalanceChange({
+        address: mockAddress,
+        startTimestamp: mockStartTimestamp,
+        endTimestamp: mockEndTimestamp,
+      });
+
+      expect(result).toEqual(new BigNumber(0));
+      expect(apiClient.getTransactionsByTimestampRange).toHaveBeenCalledTimes(1);
+      expect(apiClient.getTransactionsByTimestampRange).toHaveBeenCalledWith({
+        address: mockAddress,
+        startTimestamp: `gt:${mockStartTimestamp}`,
+        endTimestamp: `lte:${mockEndTimestamp}`,
+      });
+    });
+
+    it("should calculate balance change with mixed incoming and outgoing transfers", async () => {
+      const mockTransactions = [
+        {
+          consensus_timestamp: "1762202065.000000000",
+          transfers: [
+            { account: mockAddress, amount: 2000 },
+            { account: "0.0.98", amount: -2000 },
+          ],
+        },
+        {
+          consensus_timestamp: "1762202070.000000000",
+          transfers: [
+            { account: mockAddress, amount: -500 },
+            { account: "0.0.99", amount: 500 },
+          ],
+        },
+        {
+          consensus_timestamp: "1762202072.000000000",
+          transfers: [
+            { account: mockAddress, amount: 300 },
+            { account: "0.0.100", amount: -300 },
+          ],
+        },
+      ] as HederaMirrorTransaction[];
+
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce(
+        mockTransactions,
+      );
+
+      const result = await calculateUncommittedBalanceChange({
+        address: mockAddress,
+        startTimestamp: mockStartTimestamp,
+        endTimestamp: mockEndTimestamp,
+      });
+
+      expect(result).toEqual(new BigNumber(1800)); // 2000 - 500 + 300
+    });
+
+    it("should ignore transfers for other accounts", async () => {
+      const mockTransactions = [
+        {
+          consensus_timestamp: "1762202065.000000000",
+          transfers: [
+            { account: "0.0.98", amount: 5000 },
+            { account: "0.0.99", amount: -5000 },
+          ],
+        },
+        {
+          consensus_timestamp: "1762202070.000000000",
+          transfers: [
+            { account: mockAddress, amount: 1000 },
+            { account: "0.0.100", amount: -1000 },
+          ],
+        },
+      ] as HederaMirrorTransaction[];
+
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce(
+        mockTransactions,
+      );
+
+      const result = await calculateUncommittedBalanceChange({
+        address: mockAddress,
+        startTimestamp: mockStartTimestamp,
+        endTimestamp: mockEndTimestamp,
+      });
+
+      expect(result).toEqual(new BigNumber(1000));
+    });
+
+    it("should return 0 when timestamps are equal or invalid", async () => {
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce([]);
+
+      const [resultEqual, resultInvalid] = await Promise.all([
+        calculateUncommittedBalanceChange({
+          address: mockAddress,
+          startTimestamp: mockStartTimestamp,
+          endTimestamp: mockStartTimestamp,
+        }),
+        calculateUncommittedBalanceChange({
+          address: mockAddress,
+          startTimestamp: mockEndTimestamp,
+          endTimestamp: mockStartTimestamp,
+        }),
+      ]);
+
+      expect(resultEqual).toEqual(new BigNumber(0));
+      expect(resultInvalid).toEqual(new BigNumber(0));
+    });
+  });
+
   describe("analyzeStakingOperation", () => {
     const mockAddress = "0.0.12345";
     const mockTimestamp = "1762202064.065172388";
@@ -979,13 +1100,14 @@ describe("logic utils", () => {
     } as HederaMirrorTransaction;
 
     beforeEach(() => {
-      jest.clearAllMocks();
+      jest.resetAllMocks();
     });
 
     it("detects DELEGATE operation when staking starts", async () => {
       const accountBefore = getMockedMirrorAccount({ staked_node_id: null });
       const accountAfter = getMockedMirrorAccount({ staked_node_id: 5 });
 
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce([]);
       (apiClient.getAccount as jest.Mock)
         .mockResolvedValueOnce(accountBefore)
         .mockResolvedValueOnce(accountAfter);
@@ -998,6 +1120,7 @@ describe("logic utils", () => {
         targetStakingNodeId: 5,
         stakedAmount: BigInt(1000),
       });
+      expect(apiClient.getAccount).toHaveBeenCalledTimes(2);
       expect(apiClient.getAccount).toHaveBeenCalledWith(mockAddress, `lt:${mockTimestamp}`);
       expect(apiClient.getAccount).toHaveBeenCalledWith(mockAddress, `eq:${mockTimestamp}`);
     });
@@ -1006,6 +1129,7 @@ describe("logic utils", () => {
       const accountBefore = getMockedMirrorAccount({ staked_node_id: 5 });
       const accountAfter = getMockedMirrorAccount({ staked_node_id: null });
 
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce([]);
       (apiClient.getAccount as jest.Mock)
         .mockResolvedValueOnce(accountBefore)
         .mockResolvedValueOnce(accountAfter);
@@ -1024,6 +1148,7 @@ describe("logic utils", () => {
       const accountBefore = getMockedMirrorAccount({ staked_node_id: 3 });
       const accountAfter = getMockedMirrorAccount({ staked_node_id: 10 });
 
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce([]);
       (apiClient.getAccount as jest.Mock)
         .mockResolvedValueOnce(accountBefore)
         .mockResolvedValueOnce(accountAfter);
@@ -1038,6 +1163,51 @@ describe("logic utils", () => {
       });
     });
 
+    it("calculates correct staked amount with uncommitted transactions", async () => {
+      const mockBalance = { balance: 1000000, timestamp: "1762202060.000000000", tokens: [] };
+      const mockAccountBefore = getMockedMirrorAccount({
+        account: mockAddress,
+        staked_node_id: null,
+        balance: mockBalance,
+      });
+      const mockAccountAfter = getMockedMirrorAccount({
+        account: mockAddress,
+        staked_node_id: 5,
+        balance: mockBalance,
+      });
+      const mockTransactionsMissingInBalance = [
+        {
+          consensus_timestamp: `${Math.floor(Number(mockBalance.timestamp)) + 5}.000000000`,
+          transfers: [
+            { account: mockAddress, amount: -100000 },
+            { account: "0.0.98", amount: 100000 },
+          ],
+        },
+      ] as HederaMirrorTransaction[];
+
+      (apiClient.getTransactionsByTimestampRange as jest.Mock).mockResolvedValueOnce(
+        mockTransactionsMissingInBalance,
+      );
+      (apiClient.getAccount as jest.Mock)
+        .mockResolvedValueOnce(mockAccountBefore)
+        .mockResolvedValueOnce(mockAccountAfter);
+
+      const result = await analyzeStakingOperation(mockAddress, mockTx);
+
+      expect(apiClient.getTransactionsByTimestampRange).toHaveBeenCalledTimes(1);
+      expect(apiClient.getTransactionsByTimestampRange).toHaveBeenCalledWith({
+        address: mockAddress,
+        startTimestamp: `gt:${mockAccountBefore.balance.timestamp}`,
+        endTimestamp: `lte:${mockTimestamp}`,
+      });
+      expect(result).toEqual({
+        operationType: "DELEGATE",
+        previousStakingNodeId: null,
+        targetStakingNodeId: 5,
+        stakedAmount: BigInt(900000),
+      });
+    });
+
     it("returns null for regular account update (both null)", async () => {
       const accountBefore = getMockedMirrorAccount({ staked_node_id: null });
       const accountAfter = getMockedMirrorAccount({ staked_node_id: null });

package/src/logic/utils.ts

@@ -22,6 +22,7 @@ import {
   HEDERA_TRANSACTION_MODES,
   SYNTHETIC_BLOCK_WINDOW_SECONDS,
   TINYBAR_SCALE,
+  OP_TYPES_EXCLUDING_FEES,
 } from "../constants";
 import { apiClient } from "../network/api";
 import type {
@@ -69,7 +70,7 @@ export const getOperationValue = ({
     return BigInt(0);
   }
 
-  if (asset.type === "native" && operation.type === "OUT") {
+  if (asset.type === "native" && OP_TYPES_EXCLUDING_FEES.includes(operation.type)) {
     return BigInt(operation.value.toFixed(0)) - BigInt(operation.fee.toFixed(0));
   }
 
@@ -504,6 +505,48 @@ export const calculateAPY = (rewardRateStart: number): number => {
   return annualRate;
 };
 
+/**
+ * Calculates the uncommitted balance change for an account between two timestamps.
+ *
+ * This function handles the timing mismatch between Mirror Node balance snapshots and actual transactions.
+ * Balance snapshots are taken at regular intervals, not at every transaction, so querying by exact timestamp
+ * may return a snapshot from before moment you need.
+ *
+ * @param address - Hedera account ID (e.g., "0.0.12345")
+ * @param startTimestamp - Start of the time range (exclusive, format: "1234567890.123456789")
+ * @param endTimestamp - End of the time range (inclusive, format: "1234567890.123456789")
+ * @returns The net balance change as BigInt (sum of all transfers to/from the account)
+ */
+export const calculateUncommittedBalanceChange = async ({
+  address,
+  startTimestamp,
+  endTimestamp,
+}: {
+  address: string;
+  startTimestamp: string;
+  endTimestamp: string;
+}): Promise<BigNumber> => {
+  if (Number(startTimestamp) >= Number(endTimestamp)) {
+    return new BigNumber(0);
+  }
+
+  const uncommittedTransactions = await apiClient.getTransactionsByTimestampRange({
+    address,
+    startTimestamp: `gt:${startTimestamp}`,
+    endTimestamp: `lte:${endTimestamp}`,
+  });
+
+  // Sum all balance changes from transfers related to this account
+  const uncommittedBalanceChange = uncommittedTransactions.reduce((total, tx) => {
+    const transfers = tx.transfers ?? [];
+    const relevantTransfers = transfers.filter(t => t.account === address);
+    const netChange = relevantTransfers.reduce((sum, t) => sum.plus(t.amount), new BigNumber(0));
+    return total.plus(netChange);
+  }, new BigNumber(0));
+
+  return uncommittedBalanceChange;
+};
+
 /**
  * Hedera uses the AccountUpdateTransaction for multiple purposes, including staking operations.
  * Mirror node classifies all such transactions under the same name: "CRYPTOUPDATEACCOUNT".
@@ -517,6 +560,16 @@ export const calculateAPY = (rewardRateStart: number): number => {
  * 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
+ * 4. Calculating the actual staked amount by replaying uncommitted transactions between
+ *    the latest balance snapshot and the staking operation to handle snapshot timing mismatches
+ *
+ * @performance
+ * Makes 3 API calls per operation:
+ * - account state before
+ * - account state after
+ * - transaction history based on latest balance snapshot
+ *
+ * Batching would complicate code for minimal gain given low staking op frequency.
  */
 export const analyzeStakingOperation = async (
   address: string,
@@ -552,10 +605,19 @@ export const analyzeStakingOperation = async (
     return null;
   }
 
+  // calculate uncommitted balance changes between the last snapshot and the staking tx
+  const uncommittedBalanceChange = await calculateUncommittedBalanceChange({
+    address,
+    startTimestamp: accountAfter.balance.timestamp,
+    endTimestamp: mirrorTx.consensus_timestamp,
+  });
+
+  const actualStakedAmount = uncommittedBalanceChange.plus(accountAfter.balance.balance);
+
   return {
     operationType,
     previousStakingNodeId,
     targetStakingNodeId,
-    stakedAmount: BigInt(accountAfter.balance.balance), // always entire balance on Hedera (fully liquid)
+    stakedAmount: BigInt(actualStakedAmount.toString()), // always entire balance on Hedera (fully liquid)
   };
 };

package/src/network/api.test.ts

@@ -425,14 +425,33 @@ describe("getTransactionsByTimestampRange", () => {
     jest.resetAllMocks();
   });
 
+  it("should include account.id query param if address is provided", async () => {
+    mockedNetwork.mockResolvedValueOnce(
+      getMockResponse({ transactions: [], links: { next: null } }),
+    );
+
+    await apiClient.getTransactionsByTimestampRange({
+      address: "0.0.1234",
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
+
+    const requestUrl = mockedNetwork.mock.calls[0][0].url;
+    expect(requestUrl).toContain("account.id=0.0.1234");
+  });
+
   it("should include correct query params with timestamp range", async () => {
     mockedNetwork.mockResolvedValueOnce(
       getMockResponse({ transactions: [], links: { next: null } }),
     );
 
-    await apiClient.getTransactionsByTimestampRange("1000.000000000", "2000.000000000");
+    await apiClient.getTransactionsByTimestampRange({
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
 
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
+    expect(requestUrl).not.toContain("account.id=");
     expect(requestUrl).toContain("timestamp=gte%3A1000.000000000");
     expect(requestUrl).toContain("timestamp=lt%3A2000.000000000");
     expect(requestUrl).toContain("limit=100");
@@ -444,10 +463,10 @@ describe("getTransactionsByTimestampRange", () => {
       getMockResponse({ transactions: [], links: { next: null } }),
     );
 
-    const result = await apiClient.getTransactionsByTimestampRange(
-      "1000.000000000",
-      "2000.000000000",
-    );
+    const result = await apiClient.getTransactionsByTimestampRange({
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
 
     expect(result).toEqual([]);
     expect(mockedNetwork).toHaveBeenCalledTimes(1);
@@ -464,10 +483,10 @@ describe("getTransactionsByTimestampRange", () => {
       }),
     );
 
-    const result = await apiClient.getTransactionsByTimestampRange(
-      "1000.000000000",
-      "2000.000000000",
-    );
+    const result = await apiClient.getTransactionsByTimestampRange({
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
 
     expect(result.map(tx => tx.consensus_timestamp)).toEqual(["1500.123456789", "1750.987654321"]);
     expect(mockedNetwork).toHaveBeenCalledTimes(1);
@@ -494,10 +513,10 @@ describe("getTransactionsByTimestampRange", () => {
         }),
       );
 
-    const result = await apiClient.getTransactionsByTimestampRange(
-      "1000.000000000",
-      "2000.000000000",
-    );
+    const result = await apiClient.getTransactionsByTimestampRange({
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
 
     expect(result.map(tx => tx.consensus_timestamp)).toEqual([
       "1100.000000000",
@@ -528,10 +547,10 @@ describe("getTransactionsByTimestampRange", () => {
         }),
       );
 
-    const result = await apiClient.getTransactionsByTimestampRange(
-      "1000.000000000",
-      "2000.000000000",
-    );
+    const result = await apiClient.getTransactionsByTimestampRange({
+      startTimestamp: "gte:1000.000000000",
+      endTimestamp: "lt:2000.000000000",
+    });
 
     expect(result.map(tx => tx.consensus_timestamp)).toEqual(["1100.000000000", "1300.000000000"]);
     expect(mockedNetwork).toHaveBeenCalledTimes(3);

package/src/network/api.ts

@@ -262,18 +262,24 @@ async function estimateContractCallGas(
   return new BigNumber(res.data.result);
 }
 
-async function getTransactionsByTimestampRange(
-  startTimestamp: string,
-  endTimestamp: string,
-): Promise<HederaMirrorTransaction[]> {
+async function getTransactionsByTimestampRange({
+  address,
+  startTimestamp,
+  endTimestamp,
+}: {
+  address?: string;
+  startTimestamp: `${string}:${string}`;
+  endTimestamp: `${string}:${string}`;
+}): Promise<HederaMirrorTransaction[]> {
   const transactions: HederaMirrorTransaction[] = [];
   const params = new URLSearchParams({
     limit: "100",
     order: "desc",
+    ...(address && { "account.id": address }),
   });
 
-  params.append("timestamp", `gte:${startTimestamp}`);
-  params.append("timestamp", `lt:${endTimestamp}`);
+  params.append("timestamp", startTimestamp);
+  params.append("timestamp", endTimestamp);
 
   let nextPath: string | null = `/api/v1/transactions?${params.toString()}`;
 

package/src/test/fixtures/account.fixture.ts

@@ -140,6 +140,9 @@ export const MAINNET_TEST_ACCOUNTS = {
     associatedTokenWithoutBalance: "0.0.7243470",
     notAssociatedToken: "0.0.3176721",
   },
+  withQuickBalanceChanges: {
+    accountId: "0.0.10176637",
+  },
   activeStaking: {
     accountId: "0.0.8835924",
     publicKey: "34e26415574250721e8869bd33ea2678c2bbccff5fc70bd8b0ec9239295fd2cf",