@ledgerhq/coin-hedera 1.12.1-nightly.1 → 1.13.0-nightly.3

package/src/{api/mirror.test.ts → network/api.test.ts}

@@ -1,30 +1,25 @@
-import network from "@ledgerhq/live-network/network";
-import { getAccount, getAccountTokens, getAccountTransactions } from "./mirror";
+import network from "@ledgerhq/live-network";
+import { apiClient } from "./api";
+import { getMockResponse } from "../test/fixtures/network.fixture";
 
-jest.mock("@ledgerhq/live-network/network");
+jest.mock("@ledgerhq/live-network");
 const mockedNetwork = jest.mocked(network);
 
-const makeMockResponse = (data: any): Awaited<ReturnType<typeof network>> => ({
-  data,
-  status: 200,
-  statusText: "OK",
-  headers: {},
-  config: {
-    headers: {} as any,
-  },
-});
-
 describe("getAccountTransactions", () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    jest.resetAllMocks();
   });
 
   test("should include 'account.id', 'limit=100' and 'order=desc' query params", async () => {
     mockedNetwork.mockResolvedValueOnce(
-      makeMockResponse({ transactions: [], links: { next: null } }),
+      getMockResponse({ transactions: [], links: { next: null } }),
     );
 
-    await getAccountTransactions("0.0.1234", null);
+    await apiClient.getAccountTransactions({
+      address: "0.0.1234",
+      pagingToken: null,
+      fetchAllPages: true,
+    });
 
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
     expect(requestUrl).toContain("account.id=0.0.1234");
@@ -32,55 +27,106 @@ describe("getAccountTransactions", () => {
     expect(requestUrl).toContain("order=desc");
   });
 
-  test("should keep fetching if links.next is present", async () => {
+  test("should keep fetching if fetchAllPages is set and links.next is present", async () => {
     mockedNetwork
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           transactions: [{ consensus_timestamp: "1" }],
           links: { next: "/next-1" },
         }),
       )
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           transactions: [],
           links: { next: "/next-2" },
         }),
       )
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           transactions: [{ consensus_timestamp: "3" }],
           links: { next: "/next-3" },
         }),
       )
       .mockResolvedValueOnce(
-        makeMockResponse({
-          transactions: [],
+        getMockResponse({
+          transactions: [{ consensus_timestamp: "4" }],
           links: { next: "/next-4" },
         }),
       )
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           transactions: [],
           links: { next: null },
         }),
       );
 
-    const result = await getAccountTransactions("0.0.1234", null);
+    const result = await apiClient.getAccountTransactions({
+      address: "0.0.1234",
+      pagingToken: null,
+      fetchAllPages: true,
+    });
 
-    expect(result).toHaveLength(2);
-    expect(result.map(tx => tx.consensus_timestamp)).toEqual(["1", "3"]);
+    expect(result.transactions).toHaveLength(3);
+    expect(result.transactions.map(tx => tx.consensus_timestamp)).toEqual(["1", "3", "4"]);
+    expect(result.nextCursor).toBeNull();
     expect(mockedNetwork).toHaveBeenCalledTimes(5);
   });
+
+  test("should paginate if fetchAllPages is not set", async () => {
+    mockedNetwork
+      .mockResolvedValueOnce(
+        getMockResponse({
+          transactions: [{ consensus_timestamp: "1" }],
+          links: { next: "/next-1" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        getMockResponse({
+          transactions: [],
+          links: { next: "/next-2" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        getMockResponse({
+          transactions: [{ consensus_timestamp: "3" }],
+          links: { next: "/next-3" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        getMockResponse({
+          transactions: [{ consensus_timestamp: "4" }],
+          links: { next: "/next-4" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        getMockResponse({
+          transactions: [],
+          links: { next: null },
+        }),
+      );
+
+    const result = await apiClient.getAccountTransactions({
+      address: "0.0.1234",
+      pagingToken: null,
+      limit: 2,
+      fetchAllPages: false,
+    });
+
+    expect(result.transactions).toHaveLength(2);
+    expect(result.transactions.map(tx => tx.consensus_timestamp)).toEqual(["1", "3"]);
+    expect(result.nextCursor).toBe("3");
+    expect(mockedNetwork).toHaveBeenCalledTimes(3);
+  });
 });
 
 describe("getAccount", () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    jest.resetAllMocks();
   });
 
   it("should call the correct endpoint and return account data", async () => {
     mockedNetwork.mockResolvedValueOnce(
-      makeMockResponse({
+      getMockResponse({
         account: "0.0.1234",
         max_automatic_token_associations: 0,
         balance: {
@@ -91,7 +137,7 @@ describe("getAccount", () => {
       }),
     );
 
-    const result = await getAccount("0.0.1234");
+    const result = await apiClient.getAccount("0.0.1234");
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
 
     expect(result.account).toEqual("0.0.1234");
@@ -102,12 +148,12 @@ describe("getAccount", () => {
 
 describe("getAccountTokens", () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    jest.resetAllMocks();
   });
 
   it("should return all tokens if only one page is needed", async () => {
     mockedNetwork.mockResolvedValueOnce(
-      makeMockResponse({
+      getMockResponse({
         tokens: [
           { token_id: "0.0.1001", balance: 10 },
           { token_id: "0.0.1002", balance: 20 },
@@ -116,7 +162,7 @@ describe("getAccountTokens", () => {
       }),
     );
 
-    const result = await getAccountTokens("0.0.1234");
+    const result = await apiClient.getAccountTokens("0.0.1234");
     const requestUrl = mockedNetwork.mock.calls[0][0].url;
 
     expect(result.map(t => t.token_id)).toEqual(["0.0.1001", "0.0.1002"]);
@@ -128,19 +174,19 @@ describe("getAccountTokens", () => {
   it("should keep fetching if links.next is present and new tokens are returned", async () => {
     mockedNetwork
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           tokens: [{ token_id: "0.0.1001", balance: 10 }],
           links: { next: "/next-1" },
         }),
       )
       .mockResolvedValueOnce(
-        makeMockResponse({
+        getMockResponse({
           tokens: [{ token_id: "0.0.1002", balance: 20 }],
           links: { next: null },
         }),
       );
 
-    const result = await getAccountTokens("0.0.1234");
+    const result = await apiClient.getAccountTokens("0.0.1234");
 
     expect(result.map(t => t.token_id)).toEqual(["0.0.1001", "0.0.1002"]);
     expect(mockedNetwork).toHaveBeenCalledTimes(2);

package/src/network/api.ts

@@ -0,0 +1,159 @@
+import network from "@ledgerhq/live-network";
+import type { LiveNetworkResponse } from "@ledgerhq/live-network/network";
+import { getEnv } from "@ledgerhq/live-env";
+import { LedgerAPI4xx } from "@ledgerhq/errors";
+import { HederaAddAccountError } from "../errors";
+import type {
+  HederaMirrorAccountTokensResponse,
+  HederaMirrorTransactionsResponse,
+  HederaMirrorAccount,
+  HederaMirrorAccountsResponse,
+  HederaMirrorToken,
+  HederaMirrorTransaction,
+} from "../types";
+
+const getMirrorApiUrl = (): string => getEnv("API_HEDERA_MIRROR");
+
+const fetch = <Result>(path: string) => {
+  return network<Result>({
+    method: "GET",
+    url: `${getMirrorApiUrl()}${path}`,
+  });
+};
+
+async function getAccountsForPublicKey(publicKey: string): Promise<HederaMirrorAccount[]> {
+  let res;
+  try {
+    res = await fetch<HederaMirrorAccountsResponse>(
+      `/api/v1/accounts?account.publicKey=${publicKey}&balance=true&limit=100`,
+    );
+  } catch (e: unknown) {
+    if (e instanceof LedgerAPI4xx) return [];
+    throw e;
+  }
+
+  const accounts = res.data.accounts;
+
+  return accounts;
+}
+
+async function getAccount(address: string): Promise<HederaMirrorAccount> {
+  try {
+    const res = await fetch<HederaMirrorAccount>(`/api/v1/accounts/${address}`);
+    const account = res.data;
+
+    return account;
+  } catch (error) {
+    if (error instanceof LedgerAPI4xx && "status" in error && error.status === 404) {
+      throw new HederaAddAccountError();
+    }
+
+    throw error;
+  }
+}
+
+async function getAccountTransactions({
+  address,
+  pagingToken,
+  limit = 100,
+  order = "desc",
+  fetchAllPages,
+}: {
+  address: string;
+  pagingToken: string | null;
+  limit?: number | undefined;
+  order?: "asc" | "desc" | undefined;
+  fetchAllPages: boolean;
+}): Promise<{ transactions: HederaMirrorTransaction[]; nextCursor: string | null }> {
+  const transactions: HederaMirrorTransaction[] = [];
+  const params = new URLSearchParams({
+    "account.id": address,
+    limit: limit.toString(),
+    order,
+  });
+
+  // keeps old behavior when all pages are fetched
+  const getTimestampDirection = () => {
+    if (fetchAllPages) return "gt";
+    return order === "asc" ? "gt" : "lt";
+  };
+
+  if (pagingToken) {
+    params.append("timestamp", `${getTimestampDirection()}:${pagingToken}`);
+  }
+
+  let nextCursor: string | null = null;
+  let nextUrl: string | null = `/api/v1/transactions?${params.toString()}`;
+
+  // WARNING: don't break the loop when `transactions` array is empty but `links.next` is present
+  // the mirror node API enforces a 60-day max time range per query, even if `timestamp` param is set
+  // see: https://hedera.com/blog/changes-to-the-hedera-operated-mirror-node
+  while (nextUrl) {
+    const res: LiveNetworkResponse<HederaMirrorTransactionsResponse> = await fetch(nextUrl);
+    const newTransactions = res.data.transactions;
+    transactions.push(...newTransactions);
+    nextUrl = res.data.links.next;
+
+    // stop fetching if pagination mode is used and we reached the limit
+    if (!fetchAllPages && transactions.length >= limit) {
+      break;
+    }
+  }
+
+  // ensure we don't exceed the limit in pagination mode
+  if (!fetchAllPages && transactions.length > limit) {
+    transactions.splice(limit);
+  }
+
+  // set the next cursor only if we have more transactions to fetch
+  if (!fetchAllPages && nextUrl) {
+    const lastTx = transactions.at(-1);
+    nextCursor = lastTx?.consensus_timestamp ?? null;
+  }
+
+  return { transactions, nextCursor };
+}
+
+async function getAccountTokens(address: string): Promise<HederaMirrorToken[]> {
+  const tokens: HederaMirrorToken[] = [];
+  const params = new URLSearchParams({
+    limit: "100",
+  });
+
+  let nextUrl: string | null = `/api/v1/accounts/${address}/tokens?${params.toString()}`;
+
+  while (nextUrl) {
+    const res: LiveNetworkResponse<HederaMirrorAccountTokensResponse> = await fetch(nextUrl);
+    const newTokens = res.data.tokens;
+    tokens.push(...newTokens);
+    nextUrl = res.data.links.next;
+  }
+
+  return tokens;
+}
+
+async function getLatestTransaction(): Promise<HederaMirrorTransaction> {
+  const params = new URLSearchParams({
+    limit: "1",
+    order: "desc",
+  });
+
+  const res = await fetch<HederaMirrorTransactionsResponse>(
+    `/api/v1/transactions?${params.toString()}`,
+  );
+  const transaction = res.data.transactions[0];
+
+  if (!transaction) {
+    throw new Error("No transactions found on the Hedera network");
+  }
+
+  return transaction;
+}
+
+export const apiClient = {
+  getAccountsForPublicKey,
+  getAccount,
+  getAccountTokens,
+  getAccountTransactions,
+  getLatestTransaction,
+};

package/src/network/rpc.test.ts

@@ -0,0 +1,68 @@
+import { Client, Transaction, TransactionResponse } from "@hashgraph/sdk";
+import { rpcClient } from "./rpc";
+
+const mockClient = {
+  setMaxNodesPerTransaction: jest.fn().mockReturnThis(),
+  setNetwork: jest.fn().mockReturnThis(),
+} as unknown as Client;
+
+jest.mock("@hashgraph/sdk", () => {
+  return {
+    Transaction: jest.fn(),
+    Client: {
+      forMainnet: jest.fn(() => mockClient),
+    },
+  };
+});
+
+describe("getInstance", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    rpcClient._resetInstance();
+  });
+
+  it("returns cached client instance for multiple calls", () => {
+    const client1 = rpcClient.getInstance();
+    const client2 = rpcClient.getInstance();
+
+    expect(Client.forMainnet).toHaveBeenCalledTimes(1);
+    expect(client1).toBe(mockClient);
+    expect(client2).toBe(client1);
+  });
+});
+
+describe("broadcastTransaction", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    rpcClient._resetInstance();
+  });
+
+  it("executes the transaction using the client", async () => {
+    const expectedResponse = { transactionId: "test-tx-id" } as unknown as TransactionResponse;
+    const mockedExecute = jest.fn().mockResolvedValue(expectedResponse);
+    const mockTransaction = { execute: mockedExecute } as unknown as Transaction;
+
+    const response = await rpcClient.broadcastTransaction(mockTransaction);
+
+    expect(mockedExecute).toHaveBeenCalledTimes(1);
+    expect(mockedExecute).toHaveBeenCalledWith(mockClient);
+    expect(response).toBe(expectedResponse);
+  });
+
+  it("reuses the same client instance for multiple calls", async () => {
+    const mockedExecute1 = jest.fn();
+    const mockedExecute2 = jest.fn();
+
+    const mockTransaction1 = { execute: mockedExecute1 } as unknown as Transaction;
+    const mockTransaction2 = { execute: mockedExecute2 } as unknown as Transaction;
+
+    await rpcClient.broadcastTransaction(mockTransaction1);
+    await rpcClient.broadcastTransaction(mockTransaction2);
+
+    expect(Client.forMainnet).toHaveBeenCalledTimes(1);
+    expect(mockedExecute1).toHaveBeenCalledTimes(1);
+    expect(mockedExecute2).toHaveBeenCalledTimes(1);
+    expect(mockedExecute1).toHaveBeenCalledWith(mockClient);
+    expect(mockedExecute2).toHaveBeenCalledWith(mockClient);
+  });
+});

package/src/network/rpc.ts

@@ -0,0 +1,25 @@
+import type { Transaction as HederaTransaction, TransactionResponse } from "@hashgraph/sdk";
+import { Client } from "@hashgraph/sdk";
+
+function broadcastTransaction(transaction: HederaTransaction): Promise<TransactionResponse> {
+  return transaction.execute(getInstance());
+}
+
+let _hederaClient: Client | null = null;
+
+function getInstance(): Client {
+  _hederaClient ??= Client.forMainnet().setMaxNodesPerTransaction(1);
+
+  return _hederaClient;
+}
+
+// for testing purposes only, used to reset singleton client instance
+function _resetInstance() {
+  _hederaClient = null;
+}
+
+export const rpcClient = {
+  getInstance,
+  broadcastTransaction,
+  _resetInstance,
+};

package/src/network/utils.test.ts

@@ -0,0 +1,175 @@
+import BigNumber from "bignumber.js";
+import type { HederaMirrorCoinTransfer, HederaMirrorTokenTransfer } from "../types";
+import { parseTransfers } from "./utils";
+
+const createMirrorCoinTransfer = (account: string, amount: number): HederaMirrorCoinTransfer => ({
+  account,
+  amount,
+});
+
+const createMirrorTokenTransfer = (
+  account: string,
+  amount: number,
+  tokenId: string,
+): HederaMirrorTokenTransfer => ({
+  token_id: tokenId,
+  account,
+  amount,
+});
+
+describe("parseTransfers", () => {
+  it("should correctly identify an incoming transfer", () => {
+    const userAddress = "0.0.1234";
+    const transfers = [
+      createMirrorCoinTransfer("0.0.5678", -100),
+      createMirrorCoinTransfer(userAddress, 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("IN");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual(["0.0.5678"]);
+    expect(result.recipients).toEqual([userAddress]);
+  });
+
+  it("should correctly identify an outgoing transfer", () => {
+    const userAddress = "0.0.1234";
+    const transfers = [
+      createMirrorCoinTransfer(userAddress, -100),
+      createMirrorCoinTransfer("0.0.5678", 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual([userAddress]);
+    expect(result.recipients).toEqual(["0.0.5678"]);
+  });
+
+  it("should handle multiple senders and recipients", () => {
+    const userAddress = "0.0.1234";
+    const transfers = [
+      createMirrorCoinTransfer("0.0.5678", -50),
+      createMirrorCoinTransfer(userAddress, -50),
+      createMirrorCoinTransfer("0.0.9999", 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(50));
+    expect(result.senders).toEqual(["0.0.1234", "0.0.5678"]);
+    expect(result.recipients).toEqual(["0.0.9999"]);
+  });
+
+  it("should correctly process token transfers", () => {
+    const userAddress = "0.0.1234";
+    const tokenId = "0.0.7777";
+    const transfers = [
+      createMirrorTokenTransfer(userAddress, -10, tokenId),
+      createMirrorTokenTransfer("0.0.5678", 10, tokenId),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(10));
+    expect(result.senders).toEqual([userAddress]);
+    expect(result.recipients).toEqual(["0.0.5678"]);
+  });
+
+  it("should exclude system accounts that are not nodes from recipients", () => {
+    const userAddress = "0.0.1234";
+    const systemAccount = "0.0.500";
+    const transfers = [
+      createMirrorCoinTransfer(userAddress, -100),
+      createMirrorCoinTransfer(systemAccount, 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual([userAddress]);
+    expect(result.recipients).toEqual([]);
+  });
+
+  it("should include node accounts as recipients only if no other recipients", () => {
+    const userAddress = "0.0.1234";
+    const nodeAccount = "0.0.3";
+    const transfers = [
+      createMirrorCoinTransfer(userAddress, -100),
+      createMirrorCoinTransfer(nodeAccount, 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual([userAddress]);
+    expect(result.recipients).toEqual([nodeAccount]);
+  });
+
+  it("should exclude node accounts if there are other recipients", () => {
+    const userAddress = "0.0.1234";
+    const normalAccount = "0.0.5678";
+    const nodeAccount = "0.0.3";
+    const transfers = [
+      createMirrorCoinTransfer(userAddress, -100),
+      createMirrorCoinTransfer(normalAccount, 50),
+      createMirrorCoinTransfer(nodeAccount, 50),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("OUT");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual([userAddress]);
+    expect(result.recipients).toEqual([normalAccount]);
+  });
+
+  it("should handle transactions where user is not involved", () => {
+    const userAddress = "0.0.1234";
+    const transfers = [
+      createMirrorCoinTransfer("0.0.5678", -100),
+      createMirrorCoinTransfer("0.0.9999", 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("NONE");
+    expect(result.value).toEqual(new BigNumber(0));
+    expect(result.senders).toEqual(["0.0.5678"]);
+    expect(result.recipients).toEqual(["0.0.9999"]);
+  });
+
+  it("should handle empty transfers array", () => {
+    const userAddress = "0.0.1234";
+    const transfers: HederaMirrorCoinTransfer[] = [];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("NONE");
+    expect(result.value).toEqual(new BigNumber(0));
+    expect(result.senders).toEqual([]);
+    expect(result.recipients).toEqual([]);
+  });
+
+  it("should reverse the order of senders and recipients", () => {
+    const userAddress = "0.0.1234";
+    const transfers = [
+      createMirrorCoinTransfer("0.0.900", -5),
+      createMirrorCoinTransfer("0.0.5678", -95),
+      createMirrorCoinTransfer(userAddress, 100),
+    ];
+
+    const result = parseTransfers(transfers, userAddress);
+
+    expect(result.type).toBe("IN");
+    expect(result.value).toEqual(new BigNumber(100));
+    expect(result.senders).toEqual(["0.0.5678", "0.0.900"]);
+    expect(result.recipients).toEqual([userAddress]);
+  });
+});

package/src/network/utils.ts

@@ -0,0 +1,58 @@
+import BigNumber from "bignumber.js";
+import { AccountId } from "@hashgraph/sdk";
+import type { Operation, OperationType } from "@ledgerhq/types-live";
+import type { HederaMirrorTokenTransfer, HederaMirrorCoinTransfer } from "../types";
+
+function isValidRecipient(accountId: AccountId, recipients: string[]): boolean {
+  if (accountId.shard.eq(0) && accountId.realm.eq(0)) {
+    // account is a node, only add to list if we have none
+    if (accountId.num.lt(100)) {
+      return recipients.length === 0;
+    }
+
+    // account is a system account that is not a node, do NOT add
+    if (accountId.num.lt(1000)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function parseTransfers(
+  mirrorTransfers: (HederaMirrorCoinTransfer | HederaMirrorTokenTransfer)[],
+  address: string,
+): Pick<Operation, "type" | "value" | "senders" | "recipients"> {
+  let value = new BigNumber(0);
+  let type: OperationType = "NONE";
+
+  const senders: string[] = [];
+  const recipients: string[] = [];
+
+  for (const transfer of mirrorTransfers) {
+    const amount = new BigNumber(transfer.amount);
+    const accountId = AccountId.fromString(transfer.account);
+
+    if (transfer.account === address) {
+      value = amount.abs();
+      type = amount.isNegative() ? "OUT" : "IN";
+    }
+
+    if (amount.isNegative()) {
+      senders.push(transfer.account);
+    } else if (isValidRecipient(accountId, recipients)) {
+      recipients.push(transfer.account);
+    }
+  }
+
+  // NOTE: earlier addresses are the "fee" addresses
+  senders.reverse();
+  recipients.reverse();
+
+  return {
+    type,
+    value,
+    senders,
+    recipients,
+  };
+}