feat(sdk-coin-icp): refactor account balance and fee retrieval to use IcpAgent class

Ticket: Win-5302

Author: mohd-kashif

modules/sdk-coin-icp/src/icp.ts

@@ -25,7 +25,6 @@ import { Principal } from '@dfinity/principal';
 import axios from 'axios';
 import BigNumber from 'bignumber.js';
 import { createHash, Hash } from 'crypto';
-import { HttpAgent, replica } from 'ic0';
 import * as mpc from '@bitgo/sdk-lib-mpc';
 
 import {
@@ -41,12 +40,12 @@ import {
   SigningPayload,
   IcpTransactionExplanation,
   TransactionHexParams,
-  ACCOUNT_BALANCE_CALL,
   UnsignedSweepRecoveryTransaction,
 } from './lib/iface';
 import { TransactionBuilderFactory } from './lib/transactionBuilderFactory';
 import utils from './lib/utils';
 import { auditEcdsaPrivateKey } from '@bitgo/sdk-lib-mpc';
+import { IcpAgent } from './lib/icpAgent';
 
 /**
  * Class representing the Internet Computer (ICP) coin.
@@ -262,52 +261,24 @@ export class Icp extends BaseCoin {
    * @returns Promise resolving to the account balance as a string.
    * @throws Error if the balance could not be fetched.
    */
-  protected async getAccountBalance(publicKeyHex: string): Promise<string> {
-    try {
-      const principalId = utils.getPrincipalIdFromPublicKey(publicKeyHex).toText();
-      return await this.getBalanceFromPrincipal(principalId);
-    } catch (error: any) {
-      throw new Error(`Unable to fetch account balance: ${error.message || error}`);
-    }
-  }
-
-  /**
-   * Fetches the account balance for a given principal ID.
-   * @param principalId - The principal ID of the account.
-   * @returns Promise resolving to the account balance as a string.
-   * @throws Error if the balance could not be fetched.
-   */
-  protected async getBalanceFromPrincipal(principalId: string): Promise<string> {
-    try {
-      const agent = this.createAgent(); // TODO: WIN-5512: move to a ICP agent file WIN-5512
-      const ic = replica(agent, { local: true });
-
-      const ledger = ic(Principal.fromUint8Array(LEDGER_CANISTER_ID).toText());
-      const subaccountHex = '0000000000000000000000000000000000000000000000000000000000000000';
-
-      const account = {
-        owner: Principal.fromText(principalId),
-        subaccount: [utils.hexToBytes(subaccountHex)],
-      };
-
-      const balance = await ledger.call(ACCOUNT_BALANCE_CALL, account);
-      return balance.toString();
-    } catch (error: any) {
-      throw new Error(`Error fetching balance for principal ${principalId}: ${error.message || error}`);
-    }
+  protected async getAccountBalance(publicKeyHex: string): Promise<BigNumber> {
+    const principalId = utils.getPrincipalIdFromPublicKey(publicKeyHex).toText();
+    const agent = new IcpAgent(this.getPublicNodeUrl());
+    return agent.getBalance(principalId);
   }
 
   /**
-   * Creates a new HTTP agent for communicating with the Internet Computer.
-   * @param host - The host URL to connect to (defaults to the public node URL).
-   * @returns An instance of HttpAgent.
+   * Retrieves the current transaction fee data from the ICP public node.
+   *
+   * This method creates an instance of `IcpAgent` using the public node URL,
+   * then queries the node for the current fee information.
+   *
+   * @returns A promise that resolves to a `BigNumber` representing the current transaction fee.
+   * @throws Will propagate any errors encountered while communicating with the ICP node.
    */
-  protected createAgent(host: string = this.getPublicNodeUrl()): HttpAgent {
-    return new HttpAgent({
-      host,
-      fetch,
-      verifyQuerySignatures: false,
-    });
+  protected async getFeeData(): Promise<BigNumber> {
+    const agent = new IcpAgent(this.getPublicNodeUrl());
+    return await agent.getFee();
   }
 
   private getBuilderFactory(): TransactionBuilderFactory {
@@ -415,9 +386,9 @@ export class Icp extends BaseCoin {
       }
 
       const senderAddress = await this.getAddressFromPublicKey(publicKey);
-      const balance = new BigNumber(await this.getAccountBalance(publicKey));
-      const feeData = new BigNumber(utils.feeData());
-      const actualBalance = balance.plus(feeData); // gas amount returned from gasData is negative so we add it
+      const balance = await this.getAccountBalance(publicKey);
+      const feeData = await this.getFeeData();
+      const actualBalance = balance.minus(feeData);
       if (actualBalance.isLessThanOrEqualTo(0)) {
         throw new Error('Did not have enough funds to recover');
       }

modules/sdk-coin-icp/src/lib/icpAgent.ts

@@ -0,0 +1,92 @@
+import { Principal } from '@dfinity/principal';
+import { HttpAgent, replica, AgentCanister } from 'ic0';
+import { Utils } from './utils';
+import { ACCOUNT_BALANCE_CALL, LEDGER_CANISTER_ID, ICRC1_FEE_KEY, METADATA_CALL, DEFAULT_SUBACCOUNT } from './iface';
+import BigNumber from 'bignumber.js';
+
+export class IcpAgent {
+  private readonly utils: Utils;
+  private readonly host: string;
+
+  constructor(host: string) {
+    this.host = host;
+    this.utils = new Utils();
+  }
+
+  /**
+   * Creates a new HTTP agent for communicating with the Internet Computer.
+   * @returns An instance of HttpAgent.
+   */
+  private createAgent(): HttpAgent {
+    return new HttpAgent({
+      host: this.host,
+      fetch,
+      verifyQuerySignatures: false,
+    });
+  }
+
+  /**
+   * Retrieves an instance of the ledger canister agent.
+   *
+   * This method creates a new agent using `createAgent()`, initializes a replica interface
+   * with the agent (configured for local use), and returns an `AgentCanister` instance
+   * for the ledger canister identified by `LEDGER_CANISTER_ID`.
+   *
+   * @returns {AgentCanister} An agent interface for interacting with the ledger canister.
+   */
+  private getLedger(): AgentCanister {
+    const agent = this.createAgent();
+    const ic = replica(agent, { local: true });
+    return ic(Principal.fromUint8Array(LEDGER_CANISTER_ID).toText());
+  }
+
+  /**
+   * Fetches the account balance for a given principal ID.
+   * @param principalId - The principal ID of the account.
+   * @returns Promise resolving to the account balance as a string.
+   * @throws Error if the balance could not be fetched.
+   */
+  public async getBalance(principalId: string): Promise<BigNumber> {
+    try {
+      if (!principalId) {
+        throw new Error('Principal ID is required');
+      }
+      const ledger = this.getLedger();
+      const account = {
+        owner: Principal.fromText(principalId),
+        subaccount: [this.utils.hexToBytes(DEFAULT_SUBACCOUNT)],
+      };
+
+      const balance = await ledger.call(ACCOUNT_BALANCE_CALL, account);
+      return BigNumber(balance);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Error fetching balance for principal ${principalId}: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Fetches the transaction fee from the ledger.
+   * @returns Promise resolving to the transaction fee as a string.
+   * @throws Error if the fee could not be fetched.
+   */
+  public async getFee(): Promise<BigNumber> {
+    try {
+      const ledger = this.getLedger();
+      const metadata = await ledger.call(METADATA_CALL);
+
+      const feeEntry = metadata.find(
+        (entry): entry is [string, { Nat: string }] => entry[0] === ICRC1_FEE_KEY && entry[1]?.Nat !== undefined
+      );
+
+      if (!feeEntry) {
+        throw new Error(`${ICRC1_FEE_KEY} metadata not found or invalid format`);
+      }
+
+      return BigNumber(feeEntry[1].Nat);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Error fetching transaction fee: ${errorMessage}`);
+    }
+  }
+}

modules/sdk-coin-icp/src/lib/iface.ts

@@ -10,6 +10,9 @@ export const ROOT_PATH = 'm/0';
 export const ACCOUNT_BALANCE_CALL = 'icrc1_balance_of';
 export const PUBLIC_NODE_REQUEST_ENDPOINT = '/api/v3/canister/';
 export const DEFAULT_MEMO = 0; // default memo value is 0
+export const ICRC1_FEE_KEY = 'icrc1:fee';
+export const METADATA_CALL = 'icrc1_metadata';
+export const DEFAULT_SUBACCOUNT = '0000000000000000000000000000000000000000000000000000000000000000'; // default subaccount value is 0x
 
 export enum RequestType {
   CALL = 'call',

modules/sdk-coin-icp/src/lib/utils.ts

@@ -45,11 +45,10 @@ export class Utils implements BaseUtils {
   }
 
   /**
-   * gets the gas data of this transaction.
+   * gets the fee data of this transaction.
    */
-  //TODO WIN-4242: to moved to a config and eventually to an API for dynamic value
   feeData(): string {
-    return '-10000';
+    return '-10000'; // fee is static for ICP transactions as per ICP documentation
   }
 
   /**

modules/sdk-coin-icp/test/unit/transactionBuilder/transactionRecover.ts

@@ -6,8 +6,10 @@ import { TestBitGo } from '@bitgo/sdk-test';
 import { BitGoAPI } from '@bitgo/sdk-api';
 import nock from 'nock';
 import { Icp } from '../../../src/index';
+import { IcpAgent } from '../../../src/lib/icpAgent';
 import { RecoveryOptions, LEDGER_CANISTER_ID } from '../../../src/lib/iface';
 import { Principal } from '@dfinity/principal';
+import BigNumber from 'bignumber.js';
 
 describe('ICP transaction recovery', async () => {
   let bitgo;
@@ -38,6 +40,12 @@ describe('ICP transaction recovery', async () => {
     broadcastResponse = Buffer.from(testData.PublicNodeApiBroadcastResponse, 'hex');
   });
 
+  beforeEach(function () {
+    // Common stubs for IcpAgent
+    sinon.stub(IcpAgent.prototype, 'getBalance').resolves(BigNumber(1000000000));
+    sinon.stub(IcpAgent.prototype, 'getFee').resolves(BigNumber(10000));
+  });
+
   afterEach(function () {
     recoveryParams = {
       userKey: testData.WRWRecovery.userKey,
@@ -64,7 +72,6 @@ describe('ICP transaction recovery', async () => {
     });
 
     const body = testData.RecoverySignedTransactionWithDefaultMemo;
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
     nock(nodeUrl).post(broadcastEndpoint, body).reply(200, broadcastResponse);
     const recoverTxn = await icp.recover(recoveryParams);
     recoverTxn.id.should.be.a.String();
@@ -85,7 +92,6 @@ describe('ICP transaction recovery', async () => {
     });
 
     const body = testData.RecoverySignedTransactionWithMemo;
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
     nock(nodeUrl).post(broadcastEndpoint, body).reply(200, broadcastResponse);
     recoveryParams.memo = testData.MetaDataWithMemo.memo;
     const recoverTxn = await icp.recover(recoveryParams);
@@ -105,8 +111,6 @@ describe('ICP transaction recovery', async () => {
       ingressEndTime: testData.MetaDataWithMemo.ingress_end,
     });
 
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
-
     const unsignedSweepRecoveryParams = {
       bitgoKey:
         '0310768736a005ea5364e1b5b5288cf553224dd28b2df8ced63b72a8020478967f05ec5bce1f26cd7eb009a4bea445bb55c2f54a30f2706c1a3747e8df2d288829',
@@ -129,8 +133,6 @@ describe('ICP transaction recovery', async () => {
       ingressEndTime: testData.MetaDataWithMemo.ingress_end,
     });
 
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
-
     const unsignedSweepRecoveryParams = {
       bitgoKey: 'testKey',
       recoveryDestination: testData.Accounts.account2.address,
@@ -152,16 +154,13 @@ describe('ICP transaction recovery', async () => {
       ingressEndTime: testData.MetaDataWithMemo.ingress_end,
     });
 
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
-
     const unsignedSweepRecoveryParams = {
       recoveryDestination: testData.Accounts.account2.address,
     };
     await icp.recover(unsignedSweepRecoveryParams).should.rejectedWith('Error during ICP recovery: missing bitgoKey');
   });
 
   it('should fail to recover if broadcast API fails', async () => {
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('1000000000');
     nock(nodeUrl).post(broadcastEndpoint).reply(500, 'Internal Server Error');
     recoveryParams.memo = 0;
     await icp
@@ -172,7 +171,10 @@ describe('ICP transaction recovery', async () => {
   });
 
   it('should fail to recover txn if balance is low', async () => {
-    sinon.stub(icp, 'getBalanceFromPrincipal').returns('10');
+    // Override the default balance stub for this specific test
+    sinon.restore();
+    sinon.stub(IcpAgent.prototype, 'getBalance').resolves(BigNumber(10));
+    sinon.stub(IcpAgent.prototype, 'getFee').resolves(BigNumber(10000));
     nock(nodeUrl).post(broadcastEndpoint).reply(200, broadcastResponse);
     await icp
       .recover(recoveryParams)