feat: add support for percentage restrictions

Author: monitz87

src/entities/SecurityToken/Features.ts

@@ -1,10 +1,11 @@
-import { ModuleName } from '@polymathnetwork/contract-wrappers';
+import { ModuleName, BigNumber } from '@polymathnetwork/contract-wrappers';
 import { SubModule } from './SubModule';
 import {
   EnableGeneralPermissionManager,
   EnableDividendManagers,
   EnableGeneralTransferManager,
   DisableFeature,
+  EnablePercentageTransferManager,
 } from '../../procedures';
 import {
   Feature,
@@ -26,12 +27,14 @@ export interface FeatureStatuses {
   [Feature.Erc20Dividends]: boolean;
   [Feature.EtherDividends]: boolean;
   [Feature.ShareholderCountRestrictions]: boolean;
+  [Feature.PercentageOwnershipRestrictions]: boolean;
 }
 
 type EnableOpts =
   | EnableErc20DividendsOpts
   | EnableEtherDividendsOpts
-  | EnableShareholderCountRestrictionsOpts;
+  | EnableShareholderCountRestrictionsOpts
+  | EnablePercentageOwnershipRestrictionsOpts;
 
 export interface EnableErc20DividendsOpts {
   storageWalletAddress: string;
@@ -45,6 +48,11 @@ export interface EnableShareholderCountRestrictionsOpts {
   maxHolderCount: number;
 }
 
+export interface EnablePercentageOwnershipRestrictionsOpts {
+  maxHolderPercentage: BigNumber;
+  allowPrimaryIssuance?: boolean;
+}
+
 export interface Enable {
   (args: { feature: Feature.Permissions }): Promise<
     TransactionQueue<EnableGeneralPermissionManagerProcedureArgs>
@@ -62,6 +70,10 @@ export interface Enable {
     args: { feature: Feature.ShareholderCountRestrictions },
     opts: EnableShareholderCountRestrictionsOpts
   ): Promise<TransactionQueue<EnableCountTransferManagerProcedureArgs>>;
+  (
+    args: { feature: Feature.PercentageOwnershipRestrictions },
+    opts: EnablePercentageOwnershipRestrictionsOpts
+  ): Promise<TransactionQueue<EnableDividendManagersProcedureArgs>>;
 }
 
 export class Features extends SubModule {
@@ -74,6 +86,7 @@ export class Features extends SubModule {
     Feature.Erc20Dividends,
     Feature.EtherDividends,
     Feature.ShareholderCountRestrictions,
+    Feature.PercentageOwnershipRestrictions,
   ];
 
   /**
@@ -108,6 +121,7 @@ export class Features extends SubModule {
       erc20DividendsEnabled,
       etherDividendsEnabled,
       countTransferManagerEnabled,
+      percentageTransferManagerEnabled,
     ] = await Promise.all(list.map(feature => this.isEnabled({ feature })));
 
     const result: FeatureStatuses = {
@@ -116,6 +130,7 @@ export class Features extends SubModule {
       [Feature.Erc20Dividends]: erc20DividendsEnabled,
       [Feature.EtherDividends]: etherDividendsEnabled,
       [Feature.ShareholderCountRestrictions]: countTransferManagerEnabled,
+      [Feature.PercentageOwnershipRestrictions]: percentageTransferManagerEnabled,
     };
 
     return result;
@@ -186,6 +201,13 @@ export class Features extends SubModule {
         );
         break;
       }
+      case Feature.ShareholderCountRestrictions: {
+        procedure = new EnablePercentageTransferManager(
+          { symbol, ...(opts as EnablePercentageOwnershipRestrictionsOpts) },
+          this.context
+        );
+        break;
+      }
       default: {
         throw new PolymathError({
           code: ErrorCode.FetcherValidationError,
@@ -247,6 +269,9 @@ export class Features extends SubModule {
       case Feature.ShareholderCountRestrictions:
         moduleName = ModuleName.CountTransferManager;
         break;
+      case Feature.PercentageOwnershipRestrictions:
+        moduleName = ModuleName.PercentageTransferManager;
+        break;
       default:
         throw new PolymathError({
           code: ErrorCode.FetcherValidationError,

src/entities/SecurityToken/Restrictions.ts

@@ -1,10 +1,128 @@
-import { ModuleName } from '@polymathnetwork/contract-wrappers';
-import { ErrorCode } from '../../types';
-import { ModifyMaxHolderCount } from '../../procedures';
+import {
+  ModuleName,
+  BigNumber,
+  PercentageTransferManagerEvents,
+} from '@polymathnetwork/contract-wrappers';
+import { keys } from 'lodash';
+import { ErrorCode, PercentageWhitelistEntry } from '../../types';
+import {
+  ModifyMaxHolderCount,
+  ModifyMaxHolderPercentage,
+  ModifyPercentageWhitelist,
+} from '../../procedures';
 import { SubModule } from './SubModule';
 import { PolymathError } from '../../PolymathError';
 
 export class Restrictions extends SubModule {
+  /**
+   * Modify the list of addresses which are exempt from percentage restrictions
+   *
+   * @param entries.address address to modify
+   * @param entries.whitelisted whether the address should be exempt or not
+   */
+  public modifyPercentageWhitelist = async (args: { entries: PercentageWhitelistEntry[] }) => {
+    const procedure = new ModifyPercentageWhitelist(
+      {
+        symbol: this.securityToken.symbol,
+        ...args,
+      },
+      this.context
+    );
+    return procedure.prepare();
+  };
+
+  /**
+   * Retrieve the list of shareholder addresses that are exempt from percentage ownership restrictions
+   */
+  public getPercentageWhitelist = async () => {
+    const {
+      context: { contractWrappers },
+      securityToken,
+    } = this;
+
+    const { symbol } = securityToken;
+
+    const [percentageTransferManagerModule] = await contractWrappers.getAttachedModules(
+      { moduleName: ModuleName.PercentageTransferManager, symbol },
+      { unarchived: true }
+    );
+
+    if (!percentageTransferManagerModule) {
+      throw new PolymathError({
+        code: ErrorCode.FeatureNotEnabled,
+        message: 'You must enable the PercentageOwnershipRestrictions Feature',
+      });
+    }
+
+    const logs = await percentageTransferManagerModule.getLogsAsync({
+      eventName: PercentageTransferManagerEvents.ModifyWhitelist,
+    });
+    const whitelist: {
+      [address: string]: {
+        whitelisted: boolean;
+        blockNumber: number;
+      };
+    } = {};
+
+    logs.forEach(({ args: { _investor, _valid }, blockNumber }) => {
+      const entry = whitelist[_investor];
+
+      if (!entry || !blockNumber || blockNumber >= entry.blockNumber) {
+        whitelist[_investor] = {
+          whitelisted: _valid,
+          blockNumber: blockNumber || -1,
+        };
+      }
+    });
+
+    const addresses = keys(whitelist);
+
+    return addresses.filter(address => whitelist[address].whitelisted);
+  };
+
+  /**
+   * Modify the maximum percentage of the total supply that a single shareholder can own at a given time
+   *
+   * @param maxHolderPercentage limit to the percentage a shareholder can own (i.e. `new BigNumber(55.75)` for 55.75%)
+   */
+  public modifyMaxHolderPercentage = async (args: { maxHolderPercentage: BigNumber }) => {
+    const procedure = new ModifyMaxHolderPercentage(
+      {
+        symbol: this.securityToken.symbol,
+        ...args,
+      },
+      this.context
+    );
+    return procedure.prepare();
+  };
+
+  /**
+   * Retrieve the maximum percentage of the total supply that a single shareholder can own.
+   * Can be modified with `modifyMaxHolderPercentage`
+   */
+  public getMaxHolderPercentage = async () => {
+    const {
+      context: { contractWrappers },
+      securityToken,
+    } = this;
+
+    const { symbol } = securityToken;
+
+    const percentageTransferManagerModule = (await contractWrappers.getAttachedModules(
+      { moduleName: ModuleName.PercentageTransferManager, symbol },
+      { unarchived: true }
+    ))[0];
+
+    if (!percentageTransferManagerModule) {
+      throw new PolymathError({
+        code: ErrorCode.FeatureNotEnabled,
+        message: 'You must enable the PercentageOwnershipRestrictions Feature',
+      });
+    }
+
+    return percentageTransferManagerModule.maxHolderPercentage();
+  };
+
   /**
    * Modify the maximum amount of shareholders allowed to hold the token at once
    *

src/procedures/EnablePercentageTransferManager.ts

@@ -0,0 +1,56 @@
+import { ModuleName, TransactionParams, BigNumber } from '@polymathnetwork/contract-wrappers';
+import { Procedure } from './Procedure';
+import {
+  ProcedureType,
+  PolyTransactionTag,
+  EnablePercentageTransferManagerProcedureArgs,
+  ErrorCode,
+} from '../types';
+import { PolymathError } from '../PolymathError';
+
+export class EnablePercentageTransferManager extends Procedure<
+  EnablePercentageTransferManagerProcedureArgs
+> {
+  public type = ProcedureType.EnablePercentageTransferManager;
+
+  public async prepareTransactions() {
+    const { symbol, maxHolderPercentage, allowPrimaryIssuance = false } = this.args;
+    const { contractWrappers } = this.context;
+
+    let securityToken;
+
+    try {
+      securityToken = await contractWrappers.tokenFactory.getSecurityTokenInstanceFromTicker(
+        symbol
+      );
+    } catch (err) {
+      throw new PolymathError({
+        code: ErrorCode.ProcedureValidationError,
+        message: `There is no Security Token with symbol ${symbol}`,
+      });
+    }
+
+    const tokenAddress = await securityToken.address();
+    const moduleName = ModuleName.PercentageTransferManager;
+
+    const moduleAddress = await contractWrappers.getModuleFactoryAddress({
+      tokenAddress,
+      moduleName,
+    });
+
+    await this.addTransaction<TransactionParams.SecurityToken.AddPercentageTransferManager>(
+      securityToken.addModuleWithLabel,
+      {
+        tag: PolyTransactionTag.EnablePercentageTransferManager,
+      }
+    )({
+      moduleName,
+      address: moduleAddress,
+      archived: false,
+      data: {
+        maxHolderPercentage,
+        allowPrimaryIssuance,
+      },
+    });
+  }
+}

src/procedures/ModifyMaxHolderCount.ts

@@ -9,7 +9,7 @@ import {
 import { PolymathError } from '../PolymathError';
 
 export class ModifyMaxHolderCount extends Procedure<ModifyMaxHolderCountProcedureArgs> {
-  public type = ProcedureType.SetDividendsWallet;
+  public type = ProcedureType.ModifyMaxHolderCount;
 
   public async prepareTransactions() {
     const { symbol, maxHolderCount } = this.args;

src/procedures/ModifyMaxHolderPercentage.ts

@@ -0,0 +1,43 @@
+import { ModuleName } from '@polymathnetwork/contract-wrappers';
+import { Procedure } from './Procedure';
+import {
+  ProcedureType,
+  PolyTransactionTag,
+  ErrorCode,
+  ModifyMaxHolderPercentageProcedureArgs,
+} from '../types';
+import { PolymathError } from '../PolymathError';
+
+export class ModifyMaxHolderPercentage extends Procedure<ModifyMaxHolderPercentageProcedureArgs> {
+  public type = ProcedureType.ModifyMaxHolderPercentage;
+
+  public async prepareTransactions() {
+    const { symbol, maxHolderPercentage } = this.args;
+    const { contractWrappers } = this.context;
+
+    try {
+      await contractWrappers.tokenFactory.getSecurityTokenInstanceFromTicker(symbol);
+    } catch (err) {
+      throw new PolymathError({
+        code: ErrorCode.ProcedureValidationError,
+        message: `There is no Security Token with symbol ${symbol}`,
+      });
+    }
+
+    const percentageTransferManagerModule = (await contractWrappers.getAttachedModules(
+      { moduleName: ModuleName.PercentageTransferManager, symbol },
+      { unarchived: true }
+    ))[0];
+
+    if (!percentageTransferManagerModule) {
+      throw new PolymathError({
+        code: ErrorCode.ProcedureValidationError,
+        message: 'You must enable the PercentageOwnershipRestrictions Feature',
+      });
+    }
+
+    await this.addTransaction(percentageTransferManagerModule.changeHolderPercentage, {
+      tag: PolyTransactionTag.ChangeHolderPercentage,
+    })({ maxHolderPercentage });
+  }
+}