feat(security token): implement securityToken.investorCount

src/api/entities/SecurityToken/__tests__/index.ts

@@ -1,5 +1,5 @@
 import { Balance } from '@polkadot/types/interfaces';
-import { bool } from '@polkadot/types/primitive';
+import { bool, u64 } from '@polkadot/types/primitive';
 import BigNumber from 'bignumber.js';
 import {
   AssetIdentifier,
@@ -533,4 +533,52 @@ describe('SecurityToken class', () => {
       expect(queue).toBe(expectedQueue);
     });
   });
+
+  describe('method: investorCount', () => {
+    let investorCountPerAssetStub: sinon.SinonStub;
+    let investorCount: number;
+    let rawInvestorCount: u64;
+
+    beforeAll(() => {
+      investorCount = 10;
+      rawInvestorCount = dsMockUtils.createMockU64(investorCount);
+    });
+
+    beforeEach(() => {
+      investorCountPerAssetStub = dsMockUtils.createQueryStub(
+        'statistics',
+        'investorCountPerAsset'
+      );
+    });
+
+    test('should return the amount of unique investors that hold the Security Token', async () => {
+      const ticker = 'TICKER';
+      const context = dsMockUtils.getContextInstance();
+      const securityToken = new SecurityToken({ ticker }, context);
+
+      investorCountPerAssetStub.resolves(rawInvestorCount);
+
+      const result = await securityToken.investorCount();
+
+      expect(result).toBe(investorCount);
+    });
+
+    test('should allow subscription', async () => {
+      const ticker = 'TICKER';
+      const context = dsMockUtils.getContextInstance();
+      const securityToken = new SecurityToken({ ticker }, context);
+      const unsubCallback = 'unsubCallBack';
+
+      investorCountPerAssetStub.callsFake(async (_, cbFunc) => {
+        cbFunc(rawInvestorCount);
+        return unsubCallback;
+      });
+
+      const callback = sinon.stub();
+      const result = await securityToken.investorCount(callback);
+
+      expect(result).toBe(unsubCallback);
+      sinon.assert.calledWithExactly(callback, investorCount);
+    });
+  });
 });

src/api/entities/SecurityToken/index.ts

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { SecurityToken as MeshSecurityToken } from 'polymesh-types/types';
+import { Counter,SecurityToken as MeshSecurityToken } from 'polymesh-types/types';
 
 import {
   Context,
@@ -31,6 +31,7 @@ import {
   identityIdToString,
   stringToTicker,
   tickerToDid,
+  u64ToBigNumber,
 } from '~/utils/conversion';
 import { createProcedureMethod, padString } from '~/utils/internal';
 
@@ -372,4 +373,43 @@ export class SecurityToken extends Entity<UniqueIdentifiers> {
    *   Default Portfolio instead
    */
   public redeem: ProcedureMethod<RedeemTokenParams, void>;
+
+  /**
+   * Retrieve the amount of unique investors that hold this Security Token
+   *
+   * @note this takes into account the Scope ID of Investor Uniqueness Claims. If an investor holds balances
+   *   of this token in two or more different Identities, but they all have Investor Uniqueness Claims with the same
+   *   Scope ID, then they will only be counted once for the purposes of this result
+   *
+   * @note can be subscribed to
+   */
+  public investorCount(): Promise<number>;
+  public investorCount(callback: SubCallback<number>): Promise<UnsubCallback>;
+
+  // eslint-disable-next-line require-jsdoc
+  public async investorCount(callback?: SubCallback<number>): Promise<number | UnsubCallback> {
+    const {
+      context: {
+        polymeshApi: {
+          query: { statistics },
+        },
+      },
+      context,
+      ticker,
+    } = this;
+
+    const rawTicker = stringToTicker(ticker, context);
+
+    const assembleResult = (value: Counter): number => u64ToBigNumber(value).toNumber();
+
+    if (callback) {
+      return statistics.investorCountPerAsset(rawTicker, count => {
+        callback(assembleResult(count));
+      });
+    }
+
+    const result = await statistics.investorCountPerAsset(stringToTicker(ticker, context));
+
+    return u64ToBigNumber(result).toNumber();
+  }
 }