@ledgerhq/coin-hedera 1.13.0-nightly.2 → 1.13.0-nightly.3

package/src/logic/utils.test.ts

@@ -0,0 +1,432 @@
+import BigNumber from "bignumber.js";
+import { createHash } from "crypto";
+import { Transaction } from "@hashgraph/sdk";
+import type { AssetInfo } from "@ledgerhq/coin-framework/api/types";
+import { getCryptoCurrencyById } from "@ledgerhq/cryptoassets/currencies";
+import { InvalidAddress } from "@ledgerhq/errors";
+import { HEDERA_TRANSACTION_MODES, SYNTHETIC_BLOCK_WINDOW_SECONDS } from "../constants";
+import { apiClient } from "../network/api";
+import { getMockedOperation } from "../test/fixtures/operation.fixture";
+import { getMockedTokenCurrency } from "../test/fixtures/currency.fixture";
+import { getMockedAccount, getMockedTokenAccount } from "../test/fixtures/account.fixture";
+import {
+  serializeSignature,
+  deserializeSignature,
+  serializeTransaction,
+  deserializeTransaction,
+  getOperationValue,
+  getMemoFromBase64,
+  sendRecipientCanNext,
+  isValidExtra,
+  isTokenAssociationRequired,
+  isAutoTokenAssociationEnabled,
+  isTokenAssociateTransaction,
+  getTransactionExplorer,
+  checkAccountTokenAssociationStatus,
+  safeParseAccountId,
+  getSyntheticBlock,
+} from "./utils";
+import { HederaRecipientInvalidChecksum } from "../errors";
+
+jest.mock("../network/api");
+
+describe("utils", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("signature serialization", () => {
+    it("should serialize a signature to base64", () => {
+      const signature = new Uint8Array([1, 2, 3, 4, 5]);
+      const serialized = serializeSignature(signature);
+
+      expect(serialized).toBe("AQIDBAU=");
+    });
+
+    it("should deserialize a base64 signature to Uint8Array", () => {
+      const base64Signature = "AQIDBAU=";
+      const deserialized = deserializeSignature(base64Signature);
+
+      expect(deserialized).toEqual(Buffer.from([1, 2, 3, 4, 5]));
+    });
+  });
+
+  describe("transaction serialization", () => {
+    beforeEach(() => {
+      jest.spyOn(Transaction, "fromBytes");
+    });
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    it("should serialize a transaction to hex", () => {
+      const mockTransaction = {
+        toBytes: jest.fn().mockReturnValue(Buffer.from([10, 20, 30, 40, 50])),
+      } as unknown as Transaction;
+
+      const serialized = serializeTransaction(mockTransaction);
+
+      expect(serialized).toBe("0a141e2832");
+      expect(mockTransaction.toBytes).toHaveBeenCalled();
+    });
+
+    it("should deserialize a hex string to a Transaction", () => {
+      const mockTransaction = { id: "mock-transaction-id" };
+      (Transaction.fromBytes as jest.Mock).mockReturnValue(mockTransaction);
+
+      const hexTransaction = "0a141e2832";
+      const deserialized = deserializeTransaction(hexTransaction);
+
+      const hexTransactionBuffer = Buffer.from([10, 20, 30, 40, 50]);
+      expect(Transaction.fromBytes).toHaveBeenCalledTimes(1);
+      expect(Transaction.fromBytes).toHaveBeenCalledWith(hexTransactionBuffer);
+      expect(deserialized).toBe(mockTransaction);
+    });
+  });
+});
+
+describe("getOperationValue", () => {
+  const nativeAsset: AssetInfo = { type: "native" };
+  const tokenAsset: AssetInfo = { type: "hts", assetReference: "0.0.1234" };
+
+  it("should return 0 for FEES operations", () => {
+    const operation = getMockedOperation({
+      type: "FEES",
+      value: BigNumber(0),
+      fee: BigNumber(100),
+    });
+
+    expect(getOperationValue({ asset: nativeAsset, operation })).toBe(BigInt(0));
+    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),
+    });
+
+    expect(getOperationValue({ asset: nativeAsset, operation })).toBe(BigInt(900));
+  });
+
+  it("should return value for other operations", () => {
+    const operationOut = getMockedOperation({
+      type: "OUT",
+      value: BigNumber(500),
+      fee: BigNumber(20),
+    });
+
+    const operationIn = getMockedOperation({
+      type: "IN",
+      value: BigNumber(800),
+      fee: BigNumber(30),
+    });
+
+    expect(getOperationValue({ asset: tokenAsset, operation: operationOut })).toBe(BigInt(500));
+    expect(getOperationValue({ asset: tokenAsset, operation: operationIn })).toBe(BigInt(800));
+    expect(getOperationValue({ asset: nativeAsset, operation: operationIn })).toBe(BigInt(800));
+  });
+
+  describe("getMemoFromBase64", () => {
+    it("decodes a simple base64 string", () => {
+      expect(getMemoFromBase64("YnJkZw==")).toBe("brdg");
+    });
+
+    it("decodes an empty string", () => {
+      expect(getMemoFromBase64("")).toBe("");
+    });
+
+    it("decodes a base64 string with spaces", () => {
+      const input = Buffer.from("hello world", "utf-8").toString("base64");
+      expect(getMemoFromBase64(input)).toBe("hello world");
+    });
+
+    it("decodes special characters", () => {
+      const input = Buffer.from("😀✨", "utf-8").toString("base64");
+      expect(getMemoFromBase64(input)).toBe("😀✨");
+    });
+
+    it("returns null for bad input", () => {
+      expect(getMemoFromBase64(undefined)).toBeNull();
+      expect(getMemoFromBase64(null as unknown as string)).toBeNull();
+      expect(getMemoFromBase64({} as unknown as string)).toBeNull();
+      expect(getMemoFromBase64(10 as unknown as string)).toBeNull();
+    });
+  });
+
+  describe("getTransactionExplorer", () => {
+    test("Tx explorer URL is converted from hash to consensus timestamp", async () => {
+      const explorerView = getCryptoCurrencyById("hedera").explorerViews[0];
+      expect(explorerView).toEqual({
+        tx: expect.any(String),
+        address: expect.any(String),
+      });
+
+      const mockedOperation = getMockedOperation({
+        extra: { consensusTimestamp: "1.2.3.4" },
+      });
+
+      const newUrl = getTransactionExplorer(explorerView, mockedOperation);
+      expect(newUrl).toBe("https://hashscan.io/mainnet/transaction/1.2.3.4");
+    });
+
+    test("Tx explorer URL is based on transaction id if consensus timestamp is not available", async () => {
+      const explorerView = getCryptoCurrencyById("hedera").explorerViews[0];
+      expect(explorerView).toEqual({
+        tx: expect.any(String),
+        address: expect.any(String),
+      });
+
+      const mockedOperation = getMockedOperation({
+        extra: { transactionId: "0.0.1234567-123-123" },
+      });
+
+      const newUrl = getTransactionExplorer(explorerView, mockedOperation);
+      expect(newUrl).toBe("https://hashscan.io/mainnet/transaction/0.0.1234567-123-123");
+    });
+  });
+
+  describe("isTokenAssociateTransaction", () => {
+    test("returns correct value based on tx.properties", () => {
+      expect(
+        isTokenAssociateTransaction({ mode: HEDERA_TRANSACTION_MODES.TokenAssociate } as any),
+      ).toBe(true);
+      expect(isTokenAssociateTransaction({ mode: HEDERA_TRANSACTION_MODES.Send } as any)).toBe(
+        false,
+      );
+      expect(isTokenAssociateTransaction({} as any)).toBe(false);
+    });
+  });
+
+  describe("isAutoTokenAssociationEnabled", () => {
+    test("returns value based on isAutoTokenAssociationEnabled flag", () => {
+      expect(
+        isAutoTokenAssociationEnabled({
+          hederaResources: { isAutoTokenAssociationEnabled: true },
+        } as any),
+      ).toBe(true);
+
+      expect(
+        isAutoTokenAssociationEnabled({
+          hederaResources: { isAutoTokenAssociationEnabled: false },
+        } as any),
+      ).toBe(false);
+
+      expect(isAutoTokenAssociationEnabled({} as any)).toBe(false);
+    });
+  });
+
+  describe("isTokenAssociationRequired", () => {
+    test("should return false if token is already associated (token account exists)", () => {
+      const mockedTokenCurrency = getMockedTokenCurrency();
+      const mockedTokenAccount = getMockedTokenAccount(mockedTokenCurrency);
+      const mockedAccount = getMockedAccount({ subAccounts: [mockedTokenAccount] });
+
+      expect(isTokenAssociationRequired(mockedAccount, mockedTokenCurrency)).toBe(false);
+    });
+
+    test("should return false if auto token associations are enabled", () => {
+      const mockedTokenCurrency = getMockedTokenCurrency();
+      const mockedAccount = getMockedAccount({
+        subAccounts: [],
+        hederaResources: {
+          maxAutomaticTokenAssociations: -1,
+          isAutoTokenAssociationEnabled: true,
+        },
+      });
+
+      expect(isTokenAssociationRequired(mockedAccount, mockedTokenCurrency)).toBe(false);
+    });
+
+    test("should return true if token is not associated and auto associations are disabled", () => {
+      const mockedTokenCurrency = getMockedTokenCurrency();
+      const mockedAccount = getMockedAccount({ subAccounts: [] });
+
+      expect(isTokenAssociationRequired(mockedAccount, mockedTokenCurrency)).toBe(true);
+    });
+
+    test("should return false if token is undefined", () => {
+      const mockedAccount = getMockedAccount({ subAccounts: [] });
+
+      expect(isTokenAssociationRequired(mockedAccount, undefined)).toBe(false);
+    });
+
+    test("should return false for legacy accounts without subAccounts or hederaResources", () => {
+      const mockedTokenCurrency = getMockedTokenCurrency();
+      const mockedAccount = getMockedAccount();
+
+      delete mockedAccount.subAccounts;
+      delete mockedAccount.hederaResources;
+
+      expect(isTokenAssociationRequired(mockedAccount, mockedTokenCurrency)).toBe(true);
+    });
+  });
+
+  describe("isValidExtra", () => {
+    test("returns true for object and false for invalid types", () => {
+      expect(isValidExtra({ some: "value" })).toBe(true);
+      expect(isValidExtra(null)).toBe(false);
+      expect(isValidExtra(undefined)).toBe(false);
+      expect(isValidExtra("string")).toBe(false);
+      expect(isValidExtra(123)).toBe(false);
+      expect(isValidExtra([])).toBe(false);
+    });
+  });
+
+  describe("sendRecipientCanNext", () => {
+    test("handles association warnings", () => {
+      expect(sendRecipientCanNext({ warnings: {} } as any)).toBe(true);
+      expect(sendRecipientCanNext({ warnings: { missingAssociation: new Error() } } as any)).toBe(
+        false,
+      );
+      expect(
+        sendRecipientCanNext({ warnings: { unverifiedAssociation: new Error() } } as any),
+      ).toBe(false);
+    });
+  });
+
+  describe("checkAccountTokenAssociationStatus", () => {
+    const accountId = "0.0.1234";
+    const tokenId = "0.0.5678";
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+      // reset LRU cache to make sure all tests receive correct mocks from mockedGetAccount
+      checkAccountTokenAssociationStatus.clear(`${accountId}-${tokenId}`);
+    });
+
+    test("returns true if max_automatic_token_associations === -1", async () => {
+      (apiClient.getAccount as jest.Mock).mockResolvedValueOnce({
+        account: accountId,
+        max_automatic_token_associations: -1,
+        balance: {
+          balance: 0,
+          timestamp: "",
+          tokens: [],
+        },
+      });
+
+      const result = await checkAccountTokenAssociationStatus(accountId, tokenId);
+      expect(result).toBe(true);
+    });
+
+    test("returns true if token is already associated", async () => {
+      (apiClient.getAccount as jest.Mock).mockResolvedValueOnce({
+        account: accountId,
+        max_automatic_token_associations: 0,
+        balance: {
+          balance: 1,
+          timestamp: "",
+          tokens: [{ token_id: tokenId, balance: 1 }],
+        },
+      });
+
+      const result = await checkAccountTokenAssociationStatus(accountId, tokenId);
+      expect(result).toBe(true);
+    });
+
+    test("returns false if token is not associated", async () => {
+      (apiClient.getAccount as jest.Mock).mockResolvedValueOnce({
+        account: accountId,
+        max_automatic_token_associations: 0,
+        balance: {
+          balance: 1,
+          timestamp: "",
+          tokens: [{ token_id: "0.0.9999", balance: 1 }],
+        },
+      });
+
+      const result = await checkAccountTokenAssociationStatus(accountId, tokenId);
+      expect(result).toBe(false);
+    });
+
+    test("supports addresses with checksum", async () => {
+      const addressWithChecksum = "0.0.9124531-xrxlv";
+
+      (apiClient.getAccount as jest.Mock).mockResolvedValueOnce({
+        account: accountId,
+        max_automatic_token_associations: 0,
+        balance: {
+          balance: 1,
+          timestamp: "",
+          tokens: [{ token_id: "0.0.9999", balance: 1 }],
+        },
+      });
+
+      await checkAccountTokenAssociationStatus(addressWithChecksum, tokenId);
+      expect(apiClient.getAccount).toHaveBeenCalledTimes(1);
+      expect(apiClient.getAccount).toHaveBeenCalledWith("0.0.9124531");
+    });
+  });
+
+  describe("safeParseAccountId", () => {
+    test("returns account id and no checksum for valid address without checksum", () => {
+      const [error, result] = safeParseAccountId("0.0.9124531");
+
+      expect(error).toBeNull();
+      expect(result?.accountId).toBe("0.0.9124531");
+      expect(result?.checksum).toBeNull();
+    });
+
+    test("returns account id and checksum for valid address with correct checksum", () => {
+      const [error, result] = safeParseAccountId("0.0.9124531-xrxlv");
+
+      expect(error).toBeNull();
+      expect(result?.accountId).toBe("0.0.9124531");
+      expect(result?.checksum).toBe("xrxlv");
+    });
+
+    test("returns error for valid address with incorrect checksum", () => {
+      const [error, accountId] = safeParseAccountId("0.0.9124531-invld");
+
+      expect(error).toBeInstanceOf(HederaRecipientInvalidChecksum);
+      expect(accountId).toBeNull();
+    });
+
+    test("returns error for invalid address format", () => {
+      const [error, accountId] = safeParseAccountId("not-a-valid-address");
+
+      expect(error).toBeInstanceOf(InvalidAddress);
+      expect(accountId).toBeNull();
+    });
+  });
+
+  describe("getSyntheticBlock", () => {
+    it("calculates correct blockHeight and blockHash for typical timestamp, with default block window", () => {
+      const consensusTimestamp = "1760523159.854347000";
+      const blockWindowSeconds = SYNTHETIC_BLOCK_WINDOW_SECONDS;
+      const expectedSeconds = Math.floor(Number(consensusTimestamp));
+      const expectedBlockHeight = Math.floor(expectedSeconds / blockWindowSeconds);
+      const expectedBlockHash = createHash("sha256")
+        .update(expectedBlockHeight.toString())
+        .digest("hex");
+
+      const result = getSyntheticBlock(consensusTimestamp);
+
+      expect(result.blockHeight).toBe(expectedBlockHeight);
+      expect(result.blockHash).toBe(expectedBlockHash);
+    });
+
+    it("supports custom blockWindowSeconds", () => {
+      const consensusTimestamp = "1760523159.854347000";
+      const blockWindowSeconds = 3600;
+      const expectedSeconds = Math.floor(Number(consensusTimestamp));
+      const expectedBlockHeight = Math.floor(expectedSeconds / blockWindowSeconds);
+      const expectedBlockHash = createHash("sha256")
+        .update(expectedBlockHeight.toString())
+        .digest("hex");
+
+      const result = getSyntheticBlock(consensusTimestamp, blockWindowSeconds);
+
+      expect(result.blockHeight).toBe(expectedBlockHeight);
+      expect(result.blockHash).toBe(expectedBlockHash);
+    });
+
+    it("throws error for invalid consensusTimestamp", () => {
+      expect(() => getSyntheticBlock("not_a_number")).toThrow();
+      expect(() => getSyntheticBlock("")).toThrow();
+    });
+  });
+});

package/src/logic/utils.ts

@@ -0,0 +1,255 @@
+import BigNumber from "bignumber.js";
+import { createHash } from "crypto";
+import invariant from "invariant";
+import { AccountId, Transaction as HederaSDKTransaction } from "@hashgraph/sdk";
+import { AssetInfo, TransactionIntent } from "@ledgerhq/coin-framework/api/types";
+import { findCryptoCurrencyById } from "@ledgerhq/cryptoassets/currencies";
+import { getFiatCurrencyByTicker } from "@ledgerhq/cryptoassets/fiats";
+import cvsApi from "@ledgerhq/live-countervalues/api/index";
+import { InvalidAddress } from "@ledgerhq/errors";
+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 {
+  HEDERA_OPERATION_TYPES,
+  HEDERA_TRANSACTION_MODES,
+  SYNTHETIC_BLOCK_WINDOW_SECONDS,
+} from "../constants";
+import { apiClient } from "../network/api";
+import type {
+  HederaAccount,
+  HederaOperationExtra,
+  Transaction,
+  TransactionStatus,
+  TransactionTokenAssociate,
+} from "../types";
+import { rpcClient } from "../network/rpc";
+import { HederaRecipientInvalidChecksum } from "../errors";
+
+export const serializeSignature = (signature: Uint8Array) => {
+  return Buffer.from(signature).toString("base64");
+};
+
+export const deserializeSignature = (signature: string) => {
+  return Buffer.from(signature, "base64");
+};
+
+export const serializeTransaction = (tx: HederaSDKTransaction) => {
+  return Buffer.from(tx.toBytes()).toString("hex");
+};
+
+export const deserializeTransaction = (tx: string) => {
+  return HederaSDKTransaction.fromBytes(Buffer.from(tx, "hex"));
+};
+
+export const getOperationValue = ({
+  asset,
+  operation,
+}: {
+  asset: AssetInfo;
+  operation: LiveOperation<HederaOperationExtra>;
+}) => {
+  if (operation.type === "FEES") {
+    return BigInt(0);
+  }
+
+  if (asset.type === "native" && operation.type === "OUT") {
+    return BigInt(operation.value.toFixed(0)) - BigInt(operation.fee.toFixed(0));
+  }
+
+  return BigInt(operation.value.toFixed(0));
+};
+
+// this utils extracts the bodyBytes from a Hedera Transaction that are required for signing
+// hardcoded `.get(0)` is here because we are always using single node account id
+// this is because we want to avoid "signing" loop for users, as described here:
+// https://github.com/LedgerHQ/ledger-live/pull/72/commits/1e942687d4301660e43e0c4b5419fcfa2733b290
+export const getHederaTransactionBodyBytes = (tx: HederaSDKTransaction) => {
+  const bodyBytes = tx._signedTransactions.get(0)?.bodyBytes;
+  invariant(bodyBytes, "hedera: tx body bytes are missing");
+  return bodyBytes;
+};
+
+export const mapIntentToSDKOperation = (txIntent: TransactionIntent) => {
+  if (txIntent.type === HEDERA_TRANSACTION_MODES.TokenAssociate) {
+    return HEDERA_OPERATION_TYPES.TokenAssociate;
+  }
+
+  if (txIntent.type === HEDERA_TRANSACTION_MODES.Send && txIntent.asset.type !== "native") {
+    return HEDERA_OPERATION_TYPES.TokenTransfer;
+  }
+
+  return HEDERA_OPERATION_TYPES.CryptoTransfer;
+};
+
+export const getMemoFromBase64 = (memoBase64: string | undefined): string | null => {
+  try {
+    if (memoBase64 === undefined) return null;
+
+    return Buffer.from(memoBase64, "base64").toString("utf-8");
+  } catch {
+    return null;
+  }
+};
+
+// NOTE: convert from the non-url-safe version of base64 to the url-safe version (that the explorer uses)
+export function base64ToUrlSafeBase64(data: string): string {
+  // Might be nice to use this alternative if .nvmrc changes to >= Node v14.18.0
+  // base64url encoding option isn't supported until then
+  // Buffer.from(data, "base64").toString("base64url");
+
+  return data.replace(/\//g, "_").replace(/\+/g, "-");
+}
+
+export const getTransactionExplorer = (
+  explorerView: ExplorerView | null | undefined,
+  operation: LiveOperation,
+): string | undefined => {
+  const extra = isValidExtra(operation.extra) ? operation.extra : null;
+
+  return explorerView?.tx?.replace(
+    "$hash",
+    extra?.consensusTimestamp ?? extra?.transactionId ?? "0",
+  );
+};
+
+export const isTokenAssociateTransaction = (tx: Transaction): tx is TransactionTokenAssociate => {
+  return tx.mode === HEDERA_TRANSACTION_MODES.TokenAssociate;
+};
+
+export const isAutoTokenAssociationEnabled = (account: AccountLike) => {
+  const hederaAccount = "hederaResources" in account ? (account as HederaAccount) : null;
+
+  return hederaAccount?.hederaResources?.isAutoTokenAssociationEnabled ?? false;
+};
+
+export const isTokenAssociationRequired = (
+  account: AccountLike,
+  token: TokenCurrency | null | undefined,
+) => {
+  const subAccounts = !!account && "subAccounts" in account ? account.subAccounts ?? [] : [];
+  const isTokenAssociated = subAccounts.some(item => item.token.id === token?.id);
+
+  return !!token && !isTokenAssociated && !isAutoTokenAssociationEnabled(account);
+};
+
+export const isValidExtra = (extra: unknown): extra is HederaOperationExtra => {
+  return !!extra && typeof extra === "object" && !Array.isArray(extra);
+};
+
+// disables the "Continue" button in the Send modal's Recipient step during token transfers if:
+// - the recipient is not associated with the token
+// - the association status can't be verified
+export const sendRecipientCanNext = (status: TransactionStatus) => {
+  const { missingAssociation, unverifiedAssociation } = status.warnings;
+
+  return !missingAssociation && !unverifiedAssociation;
+};
+
+// note: this is currently called frequently by getTransactionStatus; LRU cache prevents duplicated requests
+export const getCurrencyToUSDRate = makeLRUCache(
+  async (currency: Currency) => {
+    try {
+      const [rate] = await cvsApi.fetchLatest([
+        {
+          from: currency,
+          to: getFiatCurrencyByTicker("USD"),
+          startDate: new Date(),
+        },
+      ]);
+
+      invariant(rate, "no value returned from cvs api");
+
+      return new BigNumber(rate);
+    } catch {
+      return null;
+    }
+  },
+  currency => currency.ticker,
+  seconds(3),
+);
+
+export const checkAccountTokenAssociationStatus = makeLRUCache(
+  async (address: string, tokenId: string) => {
+    const [parsingError, parsingResult] = safeParseAccountId(address);
+
+    if (parsingError) {
+      throw parsingError;
+    }
+
+    const addressWithoutChecksum = parsingResult.accountId;
+    const mirrorAccount = await apiClient.getAccount(addressWithoutChecksum);
+
+    // auto association is enabled
+    if (mirrorAccount.max_automatic_token_associations === -1) {
+      return true;
+    }
+
+    const isTokenAssociated = mirrorAccount.balance.tokens.some(token => {
+      return token.token_id === tokenId;
+    });
+
+    return isTokenAssociated;
+  },
+  (accountId, tokenId) => `${accountId}-${tokenId}`,
+  seconds(30),
+);
+
+export const safeParseAccountId = (
+  address: string,
+): [Error, null] | [null, { accountId: string; checksum: string | null }] => {
+  const currency = findCryptoCurrencyById("hedera");
+  const currencyName = currency?.name ?? "Hedera";
+
+  try {
+    const accountId = AccountId.fromString(address);
+
+    // verify checksum if present
+    // FIXME: migrate to EntityIdHelper methods once SDK is upgraded:
+    // https://github.com/hiero-ledger/hiero-sdk-js/blob/main/src/EntityIdHelper.js#L197
+    // https://github.com/hiero-ledger/hiero-sdk-js/blob/main/src/EntityIdHelper.js#L446
+    const checksum: string | null = address.split("-")[1] ?? null;
+    if (checksum) {
+      const client = rpcClient.getInstance();
+      const recipientWithChecksum = accountId.toStringWithChecksum(client);
+      const expectedChecksum = recipientWithChecksum.split("-")[1];
+
+      if (checksum !== expectedChecksum) {
+        return [new HederaRecipientInvalidChecksum(), null];
+      }
+    }
+
+    const result = {
+      accountId: accountId.toString(),
+      checksum,
+    };
+
+    return [null, result];
+  } catch (err) {
+    return [new InvalidAddress("", { currencyName }), null];
+  }
+};
+
+/**
+ * Calculates a synthetic block height based on Hedera consensus timestamp.
+ *
+ * @param consensusTimestamp - Hedera consensus timestamp
+ * @param blockWindowSeconds - Duration of one synthetic block in seconds (default: 10)
+ * @returns Deterministic synthetic block (height and hash)
+ */
+export function getSyntheticBlock(
+  consensusTimestamp: string,
+  blockWindowSeconds = SYNTHETIC_BLOCK_WINDOW_SECONDS,
+) {
+  const seconds = Math.floor(Number(consensusTimestamp));
+
+  if (Number.isNaN(seconds) || seconds === 0) {
+    throw new Error(`Invalid consensus timestamp: ${consensusTimestamp}`);
+  }
+
+  const blockHeight = Math.floor(seconds / blockWindowSeconds);
+  const blockHash = createHash("sha256").update(blockHeight.toString()).digest("hex");
+  const blockTime = new Date(seconds * 1000);
+
+  return { blockHeight, blockHash, blockTime };
+}