Merge branch 'beta' into docs/set-dividends-wallet-procedure

Author: shuffledex

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymathnetwork/sdk",
-  "version": "2.0.1-beta.98",
+  "version": "2.0.1-beta.103",
   "description": "A Javascript SDK for interacting with the Polymath network for the browser and Node.js",
   "bugs": {
     "url": "https://github.com/PolymathNetwork/polymath-sdk/issues"

src/PolymathBase.ts

@@ -37,7 +37,7 @@ import { range, flatten } from 'lodash';
 import P from 'bluebird';
 import semver from 'semver';
 import { PolymathError } from './PolymathError';
-import { ErrorCode, SecurityTokenRole } from './types';
+import { ErrorCode, SecurityTokenRole, ShareholderBalance } from './types';
 import { ZERO_ADDRESS } from './utils/constants';
 
 interface GetModuleAddressesByNameParams {
@@ -160,11 +160,6 @@ interface GetModuleFactoryAddressArgs {
   tokenAddress: string;
 }
 
-export interface ShareholderBalance {
-  balance: BigNumber;
-  address: string;
-}
-
 export interface BaseCheckpoint {
   index: number;
   totalSupply: BigNumber;

src/entities/Checkpoint.ts

@@ -5,33 +5,68 @@ import { DividendDistribution } from './DividendDistribution';
 import { ShareholderBalance, ErrorCode } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Properties that uniquely identify a Checkpoint
+ */
 export interface UniqueIdentifiers {
+  /**
+   * security token UUID
+   */
   securityTokenId: string;
+  /**
+   * numerical index of the checkpoint. The higher the index, the more recent the checkpoint
+   */
   index: number;
 }
 
+/**
+ * Check if the provided value is of type [[UniqueIdentifiers]]
+ */
 function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers {
   const { securityTokenSymbol, index } = identifiers;
 
   return typeof securityTokenSymbol === 'string' && typeof index === 'number';
 }
 
+/**
+ * Checkpoint constructor parameters
+ */
 export interface Params {
+  /**
+   * dividend distributions associated to this checkpoint
+   */
   dividendDistributions: DividendDistribution[];
+  /**
+   * symbol of the security token
+   */
   securityTokenSymbol: string;
+  /**
+   * shareholder balances at this specific Checkpoint
+   */
   shareholderBalances: ShareholderBalance[];
   totalSupply: BigNumber;
   createdAt: Date;
 }
 
+/**
+ * Represents a snapshot of the Security Token's supply and Shareholder balances at a certain point in time
+ */
 export class Checkpoint extends Entity<Params> {
+  /**
+   * Generate the Checkpoint's UUID from its identifying properties
+   */
   public static generateId({ securityTokenId, index }: UniqueIdentifiers) {
     return serialize('checkpoint', {
       securityTokenId,
       index,
     });
   }
 
+  /**
+   * Unserialize string to Checkpoint object
+   *
+   * @param serialize - checkpoint serialized representation
+   */
   public static unserialize(serialized: string) {
     const unserialized = unserialize(serialized);
 
@@ -47,20 +82,32 @@ export class Checkpoint extends Entity<Params> {
 
   public uid: string;
 
+  /**
+   * dividend distributions associated to this snapshot
+   */
   public dividendDistributions: DividendDistribution[];
 
   public securityTokenSymbol: string;
 
   public securityTokenId: string;
 
+  /**
+   * numerical index of the checkpoint associated to this snapshot
+   */
   public index: number;
 
+  /**
+   * shareholder balances at this specific checkpoint
+   */
   public shareholderBalances: ShareholderBalance[];
 
   public totalSupply: BigNumber;
 
   public createdAt: Date;
 
+  /**
+   * Create a new Chekpoint instance
+   */
   constructor(params: Params & UniqueIdentifiers) {
     super();
 
@@ -84,6 +131,9 @@ export class Checkpoint extends Entity<Params> {
     this.uid = Checkpoint.generateId({ securityTokenId, index });
   }
 
+  /**
+   * Convert entity to a POJO (Plain Old Javascript Object)
+   */
   public toPojo() {
     const {
       uid,
@@ -108,6 +158,9 @@ export class Checkpoint extends Entity<Params> {
     };
   }
 
+  /**
+   * Hydrate the entity
+   */
   public _refresh(params: Partial<Params>) {
     const {
       dividendDistributions,

src/entities/DividendDistribution.ts

@@ -6,11 +6,23 @@ import { PushDividendPayment, WithdrawTaxes, PullDividendPayment } from '../proc
 import { Context } from '../Context';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Properties that uniquely identify a Dividend Distribution
+ */
 export interface UniqueIdentifiers {
+  /**
+   * security token UUID
+   */
   securityTokenId: string;
+  /**
+   * ordered index of the distribution
+   */
   index: number;
 }
 
+/**
+ * Check if the provided value is of type [[UniqueIdentifiers]]
+ */
 function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers {
   const { securityTokenId, checkpointId, index } = identifiers;
 
@@ -21,31 +33,69 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers
   );
 }
 
+/**
+ * Dividend Distribution constructor parameters
+ */
 export interface Params {
   securityTokenSymbol: string;
   checkpointId: string;
+  /**
+   * date at which the dividend was created
+   */
   created: Date;
+  /**
+   * date after which dividend can be claimed
+   */
   maturity: Date;
+  /**
+   * date until which dividend can be claimed
+   */
   expiry: Date;
+  /**
+   * dividend amount
+   */
   amount: BigNumber;
+  /**
+   * amount of dividend claimed so far
+   */
   claimedAmount: BigNumber;
+  /**
+   * total supply at the associated checkpoint
+   */
   totalSupply: BigNumber;
+  /**
+   * true if expiry has passed and issuer has reclaimed remaining dividend
+   */
   reclaimed: boolean;
   totalWithheld: BigNumber;
   totalWithheldWithdrawn: BigNumber;
   shareholders: DividendShareholderStatus[];
   name: string;
+  /**
+   * symbol of the currency in which this dividend distribution is being paid
+   */
   currency: string | null;
 }
 
+/**
+ * Class used to manage the dividend distribution functionality
+ */
 export class DividendDistribution extends Entity<Params> {
+  /**
+   * Generate the Dividend Distribution's UUID from its identifying properties
+   */
   public static generateId({ securityTokenId, index }: UniqueIdentifiers) {
     return serialize('dividend', {
       securityTokenId,
       index,
     });
   }
 
+  /**
+   * Unserialize string to a Dividend Distribution object representation
+   *
+   * @param serialize - Dividend Distribution's serialized representation
+   */
   public static unserialize(serialized: string) {
     const unserialized = unserialize(serialized);
 
@@ -95,6 +145,9 @@ export class DividendDistribution extends Entity<Params> {
 
   protected context: Context;
 
+  /**
+   * Create a new Dividend Distribution instance
+   */
   constructor(params: Params & UniqueIdentifiers, context: Context) {
     super();
 
@@ -186,6 +239,9 @@ export class DividendDistribution extends Entity<Params> {
     return procedure.prepare();
   };
 
+  /**
+   * Convert entity to POJO (Plain Old Javascript Object)
+   */
   public toPojo() {
     const {
       uid,
@@ -228,6 +284,9 @@ export class DividendDistribution extends Entity<Params> {
     };
   }
 
+  /**
+   * Hydrate the Dividend Distribution entity
+   */
   public _refresh(params: Partial<Params>) {
     const {
       securityTokenSymbol,

src/entities/SecurityToken/Controller.ts

@@ -8,9 +8,14 @@ import {
   SignDisableControllerAck,
 } from '../../procedures';
 
+/**
+ * Namespace that handles all Controller related functionality
+ */
 export class Controller extends SubModule {
   /**
    * Set the address of the Security Token's Controller. The controller may perform forced transfers
+   *
+   * @param args.controller - security token's controller address
    */
   public modifyController = async (args: { controller: string }) => {
     const { controller } = args;
@@ -23,7 +28,7 @@ export class Controller extends SubModule {
   /**
    * Permanently disable controller functionality
    *
-   * @param signature optional signed data. If not passed, signing will be requested when the transaction queue is run. The data can be generated beforehand by the token owner calling `signDisableAck`
+   * @param args.signature - optional signed data. If not passed, signing will be requested when the transaction queue is run. The data can be generated beforehand by the token owner calling `signDisableAck`
    */
   public disable = async (args?: { signature?: string }) => {
     const { symbol } = this.securityToken;
@@ -35,11 +40,11 @@ export class Controller extends SubModule {
    * Perform a forced transfer of tokens from one address to another. You must be the
    * Security Token's controller to do this
    *
-   * @param amount amount of tokens to be transferred
-   * @param from address from which to transfer tokens
-   * @param to address that will receive the tokens
-   * @param reason optional message to describe why the transfer occurred
-   * @param data optional data used to validate the transfer
+   * @param args.amount - amount of tokens to be transferred
+   * @param args.from - address from which to transfer tokens
+   * @param args.to - address that will receive the tokens
+   * @param args.reason - optional message to describe why the transfer occurred
+   * @param args.data - optional data used to validate the transfer
    */
   public transfer = async (args: {
     amount: BigNumber;
@@ -64,10 +69,10 @@ export class Controller extends SubModule {
    * This operation is subject to transfer restrictions and the amount is limited by the token holder's balance.
    * `balanceOf(tokenHolder)` tokens) and potentially also need to respect other transfer restrictions.
    *
-   * @param amount of tokens to be redeemed
-   * @param address of the token holder
-   * @param reason optional message to describe why the redemption occurred
-   * @param data optional data used to validate the transfer
+   * @param args.amount - amount of tokens to be redeemed
+   * @param args.address - address of the token holder
+   * @param args.reason - optional message to describe why the redemption occurred
+   * @param args.data - optional data used to validate the transfer
    */
   public redeem = async (args: {
     amount: BigNumber;
@@ -85,7 +90,7 @@ export class Controller extends SubModule {
   /**
    * Generate a signature string that can be used to permanently disable the Security Token's controller functionality
    *
-   * Note that only the owner's signature is valid for this operation
+   * **Note that only the owner's signature is valid for this operation**
    */
   public signDisableAck = async () => {
     const { symbol } = this.securityToken;