@ledgerhq/coin-vechain 2.27.0 → 2.28.0

package/src/logic/history/listOperations.unit.test.ts

@@ -0,0 +1,129 @@
+import BigNumber from "bignumber.js";
+import type { Operation as LegacyOperation } from "@ledgerhq/types-live";
+import { getLastBlockHeight, getOperations, getTokenOperations } from "../../network";
+import { listOperations } from "./listOperations";
+
+jest.mock("../../network", () => ({
+  getLastBlockHeight: jest.fn(),
+  getOperations: jest.fn(),
+  getTokenOperations: jest.fn(),
+}));
+
+const ADDRESS = "0x0fe6688548f0C303932bB197B0A96034f1d74dba";
+
+function makeLegacyOp(overrides: Partial<LegacyOperation> = {}): LegacyOperation {
+  return {
+    id: "op1",
+    hash: "0xtx1",
+    type: "OUT",
+    value: new BigNumber("1000000000000000000"),
+    fee: new BigNumber("21000000000000000"),
+    senders: [ADDRESS],
+    recipients: ["0xrecipient"],
+    blockHeight: 100,
+    blockHash: "0xblock",
+    accountId: ADDRESS,
+    date: new Date("2024-01-01T00:00:00Z"),
+    extra: {},
+    ...overrides,
+  } as unknown as LegacyOperation;
+}
+
+describe("listOperations", () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("merges VET and VTHO operations, both asset paths present", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(200);
+    jest.mocked(getOperations).mockResolvedValueOnce([makeLegacyOp({ id: "vet-op", type: "IN" })]);
+    jest
+      .mocked(getTokenOperations)
+      .mockResolvedValueOnce([makeLegacyOp({ id: "vtho-op", type: "IN" })]);
+
+    const page = await listOperations(ADDRESS, { minHeight: 0 });
+
+    expect(page.items).toHaveLength(2);
+    expect(page.items.find(op => op.id === "vet-op")?.asset).toEqual({
+      type: "native",
+      name: "VET",
+    });
+    expect(page.items.find(op => op.id === "vtho-op")?.asset.type).not.toBe("native");
+    expect(page.items.find(op => op.id === "vet-op")?.details?.ledgerOpType).toBe("IN");
+    expect(page.items.find(op => op.id === "vtho-op")?.details?.ledgerOpType).toBe("IN");
+  });
+
+  it("merges VET + VTHO without duplicate operations and resumes one block past the head", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(300);
+    jest
+      .mocked(getOperations)
+      .mockResolvedValueOnce([
+        makeLegacyOp({ id: "vet-1", date: new Date("2024-01-03T00:00:00Z") }),
+        makeLegacyOp({ id: "vet-2", date: new Date("2024-01-01T00:00:00Z") }),
+      ]);
+    jest
+      .mocked(getTokenOperations)
+      .mockResolvedValueOnce([
+        makeLegacyOp({ id: "vtho-1", date: new Date("2024-01-02T00:00:00Z") }),
+      ]);
+
+    const page = await listOperations(ADDRESS, { minHeight: 0 });
+
+    const ids = page.items.map(op => op.id);
+    expect(ids).toHaveLength(3);
+    expect(new Set(ids).size).toBe(ids.length); // no duplicates across the merged VET + VTHO streams
+    expect(ids).toEqual(["vet-1", "vtho-1", "vet-2"]); // merged, sorted by date desc
+    // Cursor resumes at head + 1 so the boundary block is never re-scanned into a duplicate next page.
+    expect(page.next).toBe("301");
+  });
+
+  it("attaches no fee to a native VET operation (VeChain gas is VTHO, avoids inflating the debit)", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(200);
+    const outOp = makeLegacyOp({
+      type: "OUT",
+      value: new BigNumber("1000000000000000000"),
+      fee: new BigNumber("21000000000000000"),
+    });
+    jest.mocked(getOperations).mockResolvedValueOnce([outOp]);
+    jest.mocked(getTokenOperations).mockResolvedValueOnce([]);
+
+    const page = await listOperations(ADDRESS, { minHeight: 0 });
+
+    expect(page.items[0].value).toBe(BigInt("1000000000000000000"));
+    expect(page.items[0].tx.fees).toBe(0n);
+  });
+
+  it("keeps the VTHO gas as the fee on a VTHO (token) operation", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(200);
+    const vthoOut = makeLegacyOp({
+      type: "OUT",
+      value: new BigNumber("5000000000000000000"),
+      fee: new BigNumber("21000000000000000"),
+    });
+    jest.mocked(getOperations).mockResolvedValueOnce([]);
+    jest.mocked(getTokenOperations).mockResolvedValueOnce([vthoOut]);
+
+    const page = await listOperations(ADDRESS, { minHeight: 0 });
+
+    expect(page.items[0].value).toBe(BigInt("5000000000000000000"));
+    expect(page.items[0].tx.fees).toBe(BigInt("21000000000000000"));
+  });
+
+  it("returns an empty page (with a resumable cursor) when the range is already exhausted", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(50);
+
+    const page = await listOperations(ADDRESS, { minHeight: 0, cursor: "100" });
+
+    expect(page.items).toEqual([]);
+    expect(getOperations).not.toHaveBeenCalled();
+    expect(page.next).toBe("100");
+  });
+
+  it("propagates an error from the underlying network call", async () => {
+    jest.mocked(getLastBlockHeight).mockResolvedValueOnce(200);
+    jest.mocked(getOperations).mockRejectedValueOnce(new Error("network down"));
+    jest.mocked(getTokenOperations).mockResolvedValueOnce([]);
+
+    await expect(listOperations(ADDRESS, { minHeight: 0 })).rejects.toThrow("network down");
+  });
+});

package/src/logic/index.ts

@@ -0,0 +1,11 @@
+export * from "./account/getBalance";
+export * from "./history/getBlock";
+export * from "./history/getBlockInfo";
+export * from "./history/lastBlock";
+export * from "./history/listOperations";
+export * from "./transaction/broadcast";
+export * from "./transaction/combine";
+export * from "./transaction/craftTransaction";
+export * from "./transaction/estimateFees";
+export * from "./validateAddress";
+export * from "./validateIntent";

package/src/logic/transaction/broadcast.msw.test.ts

@@ -0,0 +1,23 @@
+import { http, HttpResponse } from "msw";
+import { server, TEST_VECHAIN_ENDPOINT } from "../../test/msw.mock";
+import { broadcast } from "./broadcast";
+
+const SUBMIT_URL = `${TEST_VECHAIN_ENDPOINT}/transactions`;
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe("broadcast via MSW", () => {
+  it("submits the signed raw transaction and returns the transaction id", async () => {
+    server.use(http.post(SUBMIT_URL, () => HttpResponse.json({ id: "0xtxid" })));
+
+    expect(await broadcast("0xaabbcc")).toBe("0xtxid");
+  });
+
+  it("throws on an HTTP 200 whose body carries no transaction id (never swallows an error body)", async () => {
+    server.use(http.post(SUBMIT_URL, () => HttpResponse.json({})));
+
+    await expect(broadcast("0xaabbcc")).rejects.toThrow("Expected an ID to be returned");
+  });
+});

package/src/logic/transaction/broadcast.ts

@@ -0,0 +1,10 @@
+import type { BroadcastConfig } from "@ledgerhq/coin-module-framework/api/types";
+import { submit } from "../../network";
+import type { VechainSDKTransaction } from "../../types";
+
+// Submit a signed tx (hex from combine) via Thor POST /transactions.
+export async function broadcast(tx: string, _broadcastConfig?: BroadcastConfig): Promise<string> {
+  const encoded = Uint8Array.from(Buffer.from(tx.replace(/^0x/, ""), "hex"));
+
+  return submit({ encoded } as VechainSDKTransaction);
+}

package/src/logic/transaction/broadcast.unit.test.ts

@@ -0,0 +1,26 @@
+import { submit } from "../../network";
+import { broadcast } from "./broadcast";
+
+jest.mock("../../network", () => ({ submit: jest.fn() }));
+
+describe("broadcast", () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("decodes the hex raw transaction and delegates to submit", async () => {
+    jest.mocked(submit).mockResolvedValueOnce("0xtxid");
+
+    const id = await broadcast("0xaabbcc");
+
+    expect(id).toBe("0xtxid");
+    const [passed] = jest.mocked(submit).mock.calls[0];
+    expect(Array.from(passed.encoded as Uint8Array)).toEqual([0xaa, 0xbb, 0xcc]);
+  });
+
+  it("propagates an error from submit", async () => {
+    jest.mocked(submit).mockRejectedValueOnce(new Error("vechain: broadcast rejected"));
+
+    await expect(broadcast("0xaabbcc")).rejects.toThrow("vechain: broadcast rejected");
+  });
+});

package/src/logic/transaction/combine.ts

@@ -0,0 +1,10 @@
+import type { VechainSDKTransactionBody } from "../../types";
+import { VechainSDKTransaction } from "../../types";
+
+// Attach the signature to the crafted body and return the signed, hex-encoded tx for broadcast.
+export function combine(tx: string, signature: string): string {
+  const body = JSON.parse(tx) as VechainSDKTransactionBody;
+  const signed = VechainSDKTransaction.of(body, Buffer.from(signature, "hex"));
+
+  return `0x${Buffer.from(signed.encoded).toString("hex")}`;
+}

package/src/logic/transaction/combine.unit.test.ts

@@ -0,0 +1,37 @@
+import { combine } from "./combine";
+import type { VechainSDKTransactionBody } from "../../types";
+
+const BODY: VechainSDKTransactionBody = {
+  chainTag: 74,
+  blockRef: "0x00000000aabbccdd",
+  expiration: 18,
+  clauses: [{ to: "0x02961B92B8D20A4ea12f1f1CeFA74Dd7B4355A86", value: "0x1", data: "0x" }],
+  gas: 21000,
+  maxFeePerGas: 1000,
+  maxPriorityFeePerGas: 100,
+  dependsOn: null,
+  nonce: "0x1a2b3c4d5e6f7890",
+};
+
+describe("combine", () => {
+  it("returns a hex-encoded signed transaction", () => {
+    const signature = "aa".repeat(65);
+
+    const signed = combine(JSON.stringify(BODY), signature);
+
+    expect(signed).toMatch(/^0x[0-9a-f]+$/);
+  });
+
+  it("produces a different (longer) payload than the unsigned body JSON, reflecting the signature", () => {
+    const signature = "bb".repeat(65);
+
+    const signed = combine(JSON.stringify(BODY), signature);
+
+    expect(signed.length).toBeGreaterThan(0);
+    expect(signed).not.toBe(JSON.stringify(BODY));
+  });
+
+  it("throws on a malformed transaction payload", () => {
+    expect(() => combine("not-json", "aa".repeat(65))).toThrow();
+  });
+});

package/src/logic/transaction/craftTransaction.ts

@@ -0,0 +1,137 @@
+import { BigNumber } from "bignumber.js";
+import type {
+  CraftedTransaction,
+  FeeEstimation,
+  TransactionIntent,
+} from "@ledgerhq/coin-module-framework/api/index";
+import {
+  calculateClausesVet,
+  calculateClausesVtho,
+  generateNonce,
+  parseAddress,
+} from "../../common-logic";
+import { estimateGas } from "../../common-logic/estimateGas";
+import { getThorClient } from "../../common-logic/getThorClient";
+import { getAccount, getBlockRef } from "../../network";
+import { MAINNET_CHAIN_TAG } from "../../types";
+import type { VechainSDKTransactionBody, VechainSDKTransactionClause } from "../../types";
+
+const EXPIRATION = 18;
+
+type GasFeeParams = {
+  gas: number;
+  maxFeePerGas: number;
+  maxPriorityFeePerGas: number;
+};
+
+function isTokenAsset(intent: TransactionIntent): boolean {
+  return intent.asset.type !== "native";
+}
+
+async function resolveAmount(intent: TransactionIntent, isToken: boolean): Promise<BigNumber> {
+  if (!intent.useAllAmount) {
+    return new BigNumber(intent.amount.toString());
+  }
+
+  const { balance, energy } = await getAccount(intent.sender);
+  return new BigNumber((isToken ? energy : balance) || "0");
+}
+
+async function resolveGasFees(
+  clauses: VechainSDKTransactionClause[],
+  sender: string,
+  customFees?: FeeEstimation,
+): Promise<GasFeeParams> {
+  const custom = customFees?.parameters as Partial<GasFeeParams> | undefined;
+
+  // Fast path: a full override covers every field, so skip the network round trip entirely.
+  if (
+    custom?.gas !== undefined &&
+    custom.maxFeePerGas !== undefined &&
+    custom.maxPriorityFeePerGas !== undefined
+  ) {
+    return {
+      gas: Number(custom.gas),
+      maxFeePerGas: Number(custom.maxFeePerGas),
+      maxPriorityFeePerGas: Number(custom.maxPriorityFeePerGas),
+    };
+  }
+
+  const gasResult = await estimateGas(clauses, sender);
+  const thorClient = getThorClient();
+  const body = await thorClient.transactions.buildTransactionBody(clauses, gasResult.totalGas, {});
+
+  // Partial override: apply each provided field individually over the estimate, so e.g. a
+  // gas-only override is honoured instead of being discarded by an all-or-nothing check. Coerce
+  // every field to a JS number: the generic coin-framework hands fee parameters back as bigint,
+  // and a bigint here reaches `JSON.stringify(body)` below, which cannot serialize it.
+  return {
+    gas: Number(custom?.gas ?? gasResult.totalGas),
+    maxFeePerGas: Number(custom?.maxFeePerGas ?? body.maxFeePerGas ?? "0"),
+    maxPriorityFeePerGas: Number(custom?.maxPriorityFeePerGas ?? body.maxPriorityFeePerGas ?? "0"),
+  };
+}
+
+// Craft an unsigned single-clause Thor tx (VET transfer, or VIP-180 transfer for VTHO). The returned
+// transaction is the JSON VechainSDKTransactionBody that combine() parses back — keep them in sync.
+export async function craftTransaction(
+  intent: TransactionIntent,
+  customFees?: FeeEstimation,
+): Promise<CraftedTransaction> {
+  if (!intent.recipient) {
+    throw new Error("vechain: recipient is required");
+  }
+  // Validate sender up front: it is used for I/O (getAccount, estimateGas) below, so a malformed
+  // value should fail clearly here instead of after a wasted network round trip.
+  if (!parseAddress(intent.sender)) {
+    throw new Error("vechain: invalid sender address");
+  }
+
+  const isToken = isTokenAsset(intent);
+  let amount = await resolveAmount(intent, isToken);
+  if (amount.lte(0)) {
+    throw new Error("vechain: transaction amount must be positive");
+  }
+
+  let clauses = isToken
+    ? await calculateClausesVtho(intent.recipient, amount)
+    : await calculateClausesVet(intent.recipient, amount);
+
+  const [{ gas, maxFeePerGas, maxPriorityFeePerGas }, blockRef] = await Promise.all([
+    resolveGasFees(clauses, intent.sender, customFees),
+    getBlockRef(),
+  ]);
+
+  const fee = new BigNumber(maxFeePerGas).times(gas);
+
+  if (intent.useAllAmount && isToken) {
+    amount = amount.minus(fee);
+    if (amount.lte(0)) {
+      throw new Error("vechain: VTHO balance too low to cover the transaction gas fee");
+    }
+    clauses = await calculateClausesVtho(intent.recipient, amount);
+  }
+
+  const body: VechainSDKTransactionBody = {
+    chainTag: MAINNET_CHAIN_TAG,
+    blockRef,
+    expiration: EXPIRATION,
+    clauses,
+    gas,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    dependsOn: null,
+    nonce: generateNonce(),
+  };
+
+  return {
+    transaction: JSON.stringify(body),
+    details: {
+      fee: fee.toFixed(0),
+      gas,
+      maxFeePerGas,
+      maxPriorityFeePerGas,
+      isTokenAccount: isToken,
+    },
+  };
+}

package/src/logic/transaction/craftTransaction.unit.test.ts

@@ -0,0 +1,217 @@
+import { VTHO_ADDRESS } from "@vechain/sdk-core";
+import type { TransactionIntent } from "@ledgerhq/coin-module-framework/api/index";
+import { calculateClausesVet, calculateClausesVtho, parseAddress } from "../../common-logic";
+import { estimateGas } from "../../common-logic/estimateGas";
+import { getThorClient } from "../../common-logic/getThorClient";
+import { setCoinConfig } from "../../config";
+import { getAccount, getBlockRef } from "../../network";
+import { craftTransaction } from "./craftTransaction";
+
+jest.mock("../../common-logic", () => ({
+  calculateClausesVet: jest.fn(),
+  calculateClausesVtho: jest.fn(),
+  generateNonce: jest.fn(() => "0xnonce"),
+  parseAddress: jest.fn(() => true),
+}));
+jest.mock("../../common-logic/estimateGas", () => ({ estimateGas: jest.fn() }));
+jest.mock("../../common-logic/getThorClient", () => ({ getThorClient: jest.fn() }));
+jest.mock("../../network", () => ({ getAccount: jest.fn(), getBlockRef: jest.fn() }));
+
+const SENDER = "0x0fe6688548f0C303932bB197B0A96034f1d74dba";
+const RECIPIENT = "0x02961B92B8D20A4ea12f1f1CeFA74Dd7B4355A86";
+
+const NATIVE_INTENT: TransactionIntent = {
+  intentType: "transaction",
+  type: "send",
+  sender: SENDER,
+  recipient: RECIPIENT,
+  amount: 1_000_000_000_000_000_000n,
+  asset: { type: "native" },
+};
+
+const TOKEN_INTENT: TransactionIntent = {
+  ...NATIVE_INTENT,
+  asset: { type: "token", assetReference: VTHO_ADDRESS },
+};
+
+function mockBuildTransactionBody() {
+  return {
+    transactions: {
+      buildTransactionBody: jest
+        .fn()
+        .mockResolvedValue({ maxFeePerGas: "1000", maxPriorityFeePerGas: "100" }),
+    },
+  };
+}
+
+describe("craftTransaction", () => {
+  beforeEach(() => {
+    jest
+      .mocked(calculateClausesVet)
+      .mockResolvedValue([{ to: RECIPIENT, value: "0x1", data: "0x" }]);
+    jest
+      .mocked(calculateClausesVtho)
+      .mockResolvedValue([{ to: VTHO_ADDRESS, value: 0, data: "0xdata" }]);
+    jest.mocked(estimateGas).mockResolvedValue({ totalGas: 21000 } as never);
+    jest.mocked(getThorClient).mockReturnValue(mockBuildTransactionBody() as never);
+    jest.mocked(getBlockRef).mockResolvedValue("0xblockref12345678");
+    setCoinConfig(() => ({ status: { type: "active" } }));
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("crafts a native VET transaction using calculateClausesVet", async () => {
+    const crafted = await craftTransaction(NATIVE_INTENT);
+
+    expect(calculateClausesVet).toHaveBeenCalled();
+    expect(calculateClausesVtho).not.toHaveBeenCalled();
+    const body = JSON.parse(crafted.transaction);
+    expect(body.clauses).toEqual([{ to: RECIPIENT, value: "0x1", data: "0x" }]);
+    expect(body.gas).toBe(21000);
+    expect(body.nonce).toBe("0xnonce");
+    expect(crafted.details?.isTokenAccount).toBe(false);
+  });
+
+  it("crafts with the mainnet chainTag (74)", async () => {
+    const crafted = await craftTransaction(NATIVE_INTENT);
+
+    const body = JSON.parse(crafted.transaction);
+    expect(body.chainTag).toBe(74);
+  });
+
+  it("crafts a VTHO transaction using calculateClausesVtho", async () => {
+    const crafted = await craftTransaction(TOKEN_INTENT);
+
+    expect(calculateClausesVtho).toHaveBeenCalled();
+    expect(calculateClausesVet).not.toHaveBeenCalled();
+    expect(crafted.details?.isTokenAccount).toBe(true);
+  });
+
+  it("computes the fee as maxFeePerGas * gas", async () => {
+    const crafted = await craftTransaction(NATIVE_INTENT);
+
+    expect(crafted.details?.fee).toBe((1000 * 21000).toString());
+  });
+
+  it("uses the account balance for the sent asset when useAllAmount is set", async () => {
+    jest.mocked(getAccount).mockResolvedValueOnce({
+      balance: "0x1000",
+      energy: "0x2000",
+      hasCode: false,
+    });
+
+    await craftTransaction({ ...NATIVE_INTENT, useAllAmount: true, amount: 0n });
+
+    expect(getAccount).toHaveBeenCalledWith(SENDER);
+    expect(calculateClausesVet).toHaveBeenCalledWith(RECIPIENT, expect.any(Object));
+  });
+
+  it("uses custom fee parameters instead of re-estimating gas when provided", async () => {
+    await craftTransaction(NATIVE_INTENT, {
+      value: 5000n,
+      parameters: { gas: 30000, maxFeePerGas: 50, maxPriorityFeePerGas: 5 },
+    });
+
+    expect(estimateGas).not.toHaveBeenCalled();
+  });
+
+  it("applies a partial fee override (gas only) over the estimate instead of discarding it", async () => {
+    const crafted = await craftTransaction(NATIVE_INTENT, {
+      value: 0n,
+      parameters: { gas: 30000 },
+    });
+
+    expect(estimateGas).toHaveBeenCalled();
+    const body = JSON.parse(crafted.transaction);
+    expect(body.gas).toBe(30000);
+    expect(body.maxFeePerGas).toBe(1000);
+    expect(body.maxPriorityFeePerGas).toBe(100);
+  });
+
+  it("coerces bigint fee parameters to numbers so the body stays JSON-serializable", async () => {
+    // The generic coin-framework hands fee parameters back as bigint; JSON.stringify cannot
+    // serialize a bigint, so craftTransaction must coerce them to numbers before building the body.
+    const crafted = await craftTransaction(NATIVE_INTENT, {
+      value: 5000n,
+      parameters: { gas: 30000n, maxFeePerGas: 50n, maxPriorityFeePerGas: 5n },
+    } as never);
+
+    const body = JSON.parse(crafted.transaction);
+    expect(body.gas).toBe(30000);
+    expect(body.maxFeePerGas).toBe(50);
+    expect(body.maxPriorityFeePerGas).toBe(5);
+    expect(typeof body.gas).toBe("number");
+  });
+
+  it("throws when the recipient is missing", async () => {
+    await expect(craftTransaction({ ...NATIVE_INTENT, recipient: "" })).rejects.toThrow(
+      "vechain: recipient is required",
+    );
+  });
+
+  it("throws when the sender is not a valid address", async () => {
+    jest.mocked(parseAddress).mockReturnValueOnce(false);
+
+    await expect(craftTransaction({ ...NATIVE_INTENT, sender: "0xbad" })).rejects.toThrow(
+      "vechain: invalid sender address",
+    );
+  });
+
+  it("throws when the resolved amount is not positive", async () => {
+    await expect(craftTransaction({ ...NATIVE_INTENT, amount: 0n })).rejects.toThrow(
+      "vechain: transaction amount must be positive",
+    );
+  });
+
+  it("reserves the VTHO gas fee for a max VTHO send (amount = energy - fee)", async () => {
+    jest
+      .mocked(getAccount)
+      .mockResolvedValueOnce({ balance: "0x0", energy: "0x5F5E100", hasCode: false });
+
+    await craftTransaction({ ...TOKEN_INTENT, useAllAmount: true, amount: 0n });
+
+    const calls = jest.mocked(calculateClausesVtho).mock.calls;
+    expect(calls).toHaveLength(2);
+    expect(calls[calls.length - 1][1].toString()).toBe("79000000");
+  });
+
+  it("throws when the VTHO balance cannot cover the max-send gas fee", async () => {
+    jest
+      .mocked(getAccount)
+      .mockResolvedValueOnce({ balance: "0x0", energy: "0x3E8", hasCode: false });
+
+    await expect(
+      craftTransaction({ ...TOKEN_INTENT, useAllAmount: true, amount: 0n }),
+    ).rejects.toThrow("vechain: VTHO balance too low to cover the transaction gas fee");
+  });
+
+  it("crafts a dust native amount (1 wei)", async () => {
+    const crafted = await craftTransaction({ ...NATIVE_INTENT, amount: 1n });
+
+    expect(calculateClausesVet).toHaveBeenCalledWith(RECIPIENT, expect.any(Object));
+    expect(JSON.parse(crafted.transaction).gas).toBe(21000);
+  });
+
+  it("reserves the fee at the max-VTHO boundary, leaving exactly 1 wei", async () => {
+    jest
+      .mocked(getAccount)
+      .mockResolvedValueOnce({ balance: "0x0", energy: "21000001", hasCode: false });
+
+    await craftTransaction({ ...TOKEN_INTENT, useAllAmount: true, amount: 0n });
+
+    const calls = jest.mocked(calculateClausesVtho).mock.calls;
+    expect(calls[calls.length - 1][1].toString()).toBe("1");
+  });
+
+  it("throws at the max-VTHO boundary where energy exactly equals the fee", async () => {
+    jest
+      .mocked(getAccount)
+      .mockResolvedValueOnce({ balance: "0x0", energy: "21000000", hasCode: false });
+
+    await expect(
+      craftTransaction({ ...TOKEN_INTENT, useAllAmount: true, amount: 0n }),
+    ).rejects.toThrow("vechain: VTHO balance too low to cover the transaction gas fee");
+  });
+});

package/src/logic/transaction/estimateFees.ts

@@ -0,0 +1,32 @@
+import type { FeeEstimation, TransactionIntent } from "@ledgerhq/coin-module-framework/api/index";
+import { parseAddress } from "../../common-logic";
+import { craftTransaction } from "./craftTransaction";
+
+// Estimate VTHO gas by crafting the unsigned tx and reading back its settled fee/gas parameters.
+export async function estimateFees(
+  intent: TransactionIntent,
+  customFeesParameters?: FeeEstimation["parameters"],
+): Promise<FeeEstimation> {
+  if (!intent.recipient || !parseAddress(intent.recipient)) {
+    return { value: 0n, parameters: {} };
+  }
+
+  const estimationIntent =
+    !intent.useAllAmount && intent.amount <= 0n ? { ...intent, amount: 1n } : intent;
+
+  const { details } = await craftTransaction(
+    estimationIntent,
+    customFeesParameters ? { value: 0n, parameters: customFeesParameters } : undefined,
+  );
+
+  const fee = typeof details?.fee === "string" ? details.fee : "0";
+
+  return {
+    value: BigInt(fee),
+    parameters: {
+      gas: details?.gas,
+      maxFeePerGas: details?.maxFeePerGas,
+      maxPriorityFeePerGas: details?.maxPriorityFeePerGas,
+    },
+  };
+}