Merge branch 'beta' into docs/reclaim-funds-procedure

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymathnetwork/sdk",
-  "version": "2.0.1-beta.103",
+  "version": "2.0.1-beta.108",
   "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/procedures/ApproveErc20.ts

@@ -9,6 +9,15 @@ import { PolymathError } from '../PolymathError';
 export class ApproveErc20 extends Procedure<ApproveErc20ProcedureArgs> {
   public type = ProcedureType.ApproveErc20;
 
+  /**
+   * Approve spend of an ERC20 token by another wallet. The token in question defaults to POLY if no address is supplied
+   *
+   * Note that if the amount has already been approved, the spending approval transaction will not be added to the queue and the procedure will return
+   *
+   * Note that the procedure will fail if the owner's token balance is less than the amount being approved.
+   * The only exception to this is when approving a POLY spend on a testnet.
+   * If that is the case, an extra transaction will be submitted to request the missing amount of tokens from the faucet
+   */
   public async prepareTransactions() {
     const { amount, spender, tokenAddress } = this.args;
     const { contractWrappers, currentWallet } = this.context;

src/procedures/CreateCheckpoint.ts

@@ -11,16 +11,24 @@ import { findEvents } from '../utils';
 import { SecurityToken, Checkpoint } from '../entities';
 import { Factories } from '../Context';
 
+/**
+ * @hidden
+ */
 export const createRefreshSecurityTokenFactoryResolver = (
   factories: Factories,
   securityTokenId: string
 ) => async () => {
   return factories.securityTokenFactory.refresh(securityTokenId);
 };
-
+/**
+ * Procedure to create a Checkpoint on a Security Token
+ */
 export class CreateCheckpoint extends Procedure<CreateCheckpointProcedureArgs, Checkpoint> {
   public type = ProcedureType.CreateCheckpoint;
 
+  /**
+   * Create a Checkpoint on the Security Token and return it
+   */
   public async prepareTransactions() {
     const { args, context } = this;
     const { symbol } = args;

src/procedures/CreateDividendDistribution.ts

@@ -16,12 +16,24 @@ import { PolymathError } from '../PolymathError';
 import { findEvents } from '../utils';
 import { SecurityToken, DividendDistribution } from '../entities';
 
+/**
+ * Procedure to create a Dividend Distribution on a Security Token.
+ * The funds to be distributed as dividends will come from the current user's wallet
+ */
 export class CreateDividendDistribution extends Procedure<
   CreateDividendDistributionProcedureArgs,
   DividendDistribution
 > {
   public type = ProcedureType.CreateDividendDistribution;
 
+  /**
+   * - Approve spend of the amount that will be distributed
+   * - Create a Dividend Distribution for said amount
+   * - Set tax withholding percentages (if supplied)
+   * - Return the newly created Dividend Distribution
+   *
+   * Note that this procedure will fail if the ERC20 Dividends Feature has not been enabled
+   */
   public async prepareTransactions() {
     const { args, context } = this;
     const {

src/procedures/CreateSecurityToken.ts

@@ -1,5 +1,4 @@
 import { FeeType, TransactionParams } from '@polymathnetwork/contract-wrappers';
-
 import { Procedure } from './Procedure';
 import { ApproveErc20 } from './ApproveErc20';
 import {
@@ -11,12 +10,24 @@ import {
 import { PolymathError } from '../PolymathError';
 import { SecurityToken } from '../entities';
 
+/**
+ * Procedure that creates a new Security Token on the Polymath ecosystem
+ */
 export class CreateSecurityToken extends Procedure<
   CreateSecurityTokenProcedureArgs,
   SecurityToken
 > {
   public type = ProcedureType.CreateSecurityToken;
 
+  /**
+   * - Approve spending the required POLY to pay the Security Token launch fee
+   * - Create the new Security Token
+   *
+   * Note that this procedure will fail if:
+   * - The Security Token symbol hasn't been reserved
+   * - The Security Token symbol has already been reserved by another issuer
+   * - The Security Token already been launched
+   */
   public async prepareTransactions() {
     const { args, context } = this;
     const { name, symbol, detailsUrl = '', divisible, treasuryWallet } = args;

src/procedures/DisableController.ts

@@ -7,9 +7,20 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that permanently disables a Security Token's controller functionality. This requires the Security Token's owner to send signed data in acknowledgement
+ */
 export class DisableController extends Procedure<DisableControllerProcedureArgs> {
   public type = ProcedureType.DisableController;
 
+  /**
+   * - If no signature acknowledgement data (optional) is appended to the procedure arguments, the procedure itself will request the user's signature or sign the data in place if the client was instanced with a private key
+   * - Disable the Security Token's controller functionality
+   *
+   * Note that this procedure will fail if:
+   * - The current user is not the owner of the Security Token
+   * - The controller has already been previously disabled
+   */
   public async prepareTransactions() {
     const { signature, symbol } = this.args;
     const { contractWrappers, currentWallet } = this.context;

src/procedures/DisableFeature.ts

@@ -8,9 +8,15 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure to disable a Feature on a Security Token
+ */
 export class DisableFeature extends Procedure<DisableFeatureProcedureArgs> {
   public type = ProcedureType.DisableFeature;
 
+  /**
+   * Disable the Feature by archiving the attached module that corresponds to that Feature
+   */
   public async prepareTransactions() {
     const { symbol, moduleName } = this.args;
     const { contractWrappers } = this.context;

src/procedures/EnableCountTransferManager.ts

@@ -8,9 +8,15 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that enables Count Restrictions on a Security Token. This allows setting a number of maximum token holders. Any token transfer that would result in the amount of token holders to exceed this maximum will fail
+ */
 export class EnableCountTransferManager extends Procedure<EnableCountTransferManagerProcedureArgs> {
   public type = ProcedureType.EnableCountTransferManager;
 
+  /**
+   * Enable Count Restrictions on the Security Token and set the supplied max holder count
+   */
   public async prepareTransactions() {
     const { symbol, maxHolderCount } = this.args;
     const { contractWrappers } = this.context;

src/procedures/EnableDividendManager.ts

@@ -8,9 +8,15 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that enables Dividends on a Security Token
+ */
 export class EnableDividendManager extends Procedure<EnableDividendManagerProcedureArgs> {
   public type = ProcedureType.EnableDividendManager;
 
+  /**
+   * Enable Dividends on the Security Token and set a wallet address where reclaimed dividends and withheld tax will be stored
+   */
   public async prepareTransactions() {
     const { symbol, storageWalletAddress } = this.args;
     const { contractWrappers } = this.context;

src/procedures/EnableGeneralPermissionManager.ts

@@ -8,11 +8,17 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that enables Permissions on a Security Token
+ */
 export class EnableGeneralPermissionManager extends Procedure<
   EnableGeneralPermissionManagerProcedureArgs
 > {
   public type = ProcedureType.EnableGeneralPermissionManager;
 
+  /**
+   * Enable Permissions on the Security Token
+   */
   public async prepareTransactions() {
     const { symbol } = this.args;
     const { contractWrappers } = this.context;

src/procedures/EnableGeneralTransferManager.ts

@@ -8,11 +8,17 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that enables Shareholders (specifically the KYC whitelist) on a Security Token. This comes enabled by default
+ */
 export class EnableGeneralTransferManager extends Procedure<
   EnableGeneralTransferManagerProcedureArgs
 > {
   public type = ProcedureType.EnableGeneralTransferManager;
 
+  /**
+   * Enable Shareholders on the Security Token
+   */
   public async prepareTransactions() {
     const { symbol } = this.args;
     const { contractWrappers } = this.context;

src/procedures/EnablePercentageTransferManager.ts

@@ -8,11 +8,19 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that enables Percentage Ownership Restictions on a Security Token. This allows setting a maximum percentage of the total supply that a single shareholder can own. Any token transfer that would result in a single shareholder owning more than the allowed percentage will fail
+ */
 export class EnablePercentageTransferManager extends Procedure<
   EnablePercentageTransferManagerProcedureArgs
 > {
   public type = ProcedureType.EnablePercentageTransferManager;
 
+  /**
+   * Enable Percentage Ownership restrictions and set the max ownership percentage and whether primary issuance is exempted from said restrictions
+   *
+   * Note: Primary issuance exemption is disallowed by default unless otherwise specified
+   */
   public async prepareTransactions() {
     const { symbol, maxHolderPercentage, allowPrimaryIssuance = false } = this.args;
     const { contractWrappers } = this.context;

src/procedures/FreezeIssuance.ts

@@ -7,9 +7,20 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that permanently freezes issuance of a Security Token. This requires the Security Token's owner to send signed data in acknowledgement
+ */
 export class FreezeIssuance extends Procedure<FreezeIssuanceProcedureArgs> {
   public type = ProcedureType.FreezeIssuance;
 
+  /**
+   * - If no signature acknowledgement data (optional) is appended to the procedure arguments, the procedure itself will request the user's signature or sign the data in place if the client was instanced with a private key
+   * - Freeze the issuance of the Security Token
+   *
+   * Note this procedure will fail if:
+   * - The current user is not the owner of the Security Token
+   * - Issuance has already been frozen
+   */
   public async prepareTransactions() {
     const { signature, symbol } = this.args;
     const { contractWrappers, currentWallet } = this.context;

src/procedures/LaunchSimpleSto.ts

@@ -20,9 +20,22 @@ import { TransferErc20 } from './TransferErc20';
 import { SecurityToken, SimpleSto } from '../entities';
 import { findEvents } from '../utils';
 
+/**
+ * Procedure that launches a Simple STO
+ */
 export class LaunchSimpleSto extends Procedure<LaunchSimpleStoProcedureArgs, SimpleSto> {
   public type = ProcedureType.LaunchSimpleSto;
 
+  /**
+   * - Transfer the necessary amount of POLY to the Security Token to cover the STO's setup fee
+   * - Launch the Simple STO
+   * - Allow pre-issuing (if applicable)
+   * - Return the newly created STO
+
+   * Notes:
+   * - Pre-issuing defaults to false
+   * - Pre-issuing can only be enabled on a version 3.1 (or greater) Simple STO. Attempting to do so in versions 3.0 or lower will cause the procedure to fail
+   */
   public async prepareTransactions() {
     const { args, context } = this;
     const {

src/procedures/LaunchTieredSto.ts

@@ -20,9 +20,23 @@ import { findEvents, isValidAddress } from '../utils';
 import { SecurityToken, TieredSto } from '../entities';
 import { ZERO_ADDRESS } from '../utils/constants';
 
+/**
+ * Procedure that launches a Tiered STO
+ */
 export class LaunchTieredSto extends Procedure<LaunchTieredStoProcedureArgs, TieredSto> {
   public type = ProcedureType.LaunchTieredSto;
 
+  /**
+   * - Transfer the necessary amount of POLY to the Security Token to cover the STO's setup fee
+   * - Launch the Tiered STO
+   * - Allow pre-issuing (if applicable, defaults to false)
+   * - Return the newly created STO
+   *
+   * Note that this procedure will fail if:
+   * - The supplied custom currency oracle addresses corresponding to the selected fund raise currencies are invalid
+   * - Raising in Stable Coin and not providing stable coin addresses
+   * - Attempting to allow pre-issuing on a version 3.0 STO
+   */
   public async prepareTransactions() {
     const { args, context } = this;
     const {
@@ -258,6 +272,18 @@ export class LaunchTieredSto extends Procedure<LaunchTieredStoProcedureArgs, Tie
         },
         {
           tag: PolyTransactionTag.AllowPreMinting,
+          resolvers: [
+            () => {
+              return tieredStoFactory.update(
+                TieredSto.generateId({
+                  securityTokenId: SecurityToken.generateId({ symbol }),
+                  stoType: StoType.Tiered,
+                  address: newStoAddress.result!,
+                }),
+                { preIssueAllowed: true }
+              );
+            },
+          ],
         }
       )({});
     }

src/procedures/SetDividendsWallet.ts

@@ -8,9 +8,19 @@ import {
 } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that modifies the wallet address where reclaimed dividends and withheld taxes are kept
+ */
 export class SetDividendsWallet extends Procedure<SetDividendsWalletProcedureArgs> {
   public type = ProcedureType.SetDividendsWallet;
 
+  /**
+   * Change the dividends storage wallet address
+   *
+   * Note that this procedure will fail if:
+   * - The Security Token doesn't exist
+   * - The Dividends Feature hasn't been enabled
+   */
   public async prepareTransactions() {
     const { symbol, address } = this.args;
     const { contractWrappers } = this.context;

src/procedures/SignDisableControllerAck.ts

@@ -2,9 +2,15 @@ import { Procedure } from './Procedure';
 import { ProcedureType, ErrorCode, SignDisableControllerAckProcedureArgs } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that signs an acknowledgement to permanently disable a Security Token's Controller functionality
+ */
 export class SignDisableControllerAck extends Procedure<SignDisableControllerAckProcedureArgs> {
   public type = ProcedureType.SignDisableControllerAck;
 
+  /**
+   * Sign data to confirm the intent of permanently disabling the Security Token's Controller functionality
+   */
   public async prepareTransactions() {
     const { symbol } = this.args;
     const { contractWrappers } = this.context;

src/procedures/SignFreezeIssuanceAck.ts

@@ -2,9 +2,15 @@ import { Procedure } from './Procedure';
 import { ProcedureType, ErrorCode, SignFreezeIssuanceAckProcedureArgs } from '../types';
 import { PolymathError } from '../PolymathError';
 
+/**
+ * Procedure that signs an acknowledgement to permanently freeze issuance of a Security Token
+ */
 export class SignFreezeIssuanceAck extends Procedure<SignFreezeIssuanceAckProcedureArgs> {
   public type = ProcedureType.SignFreezeIssuanceAck;
 
+  /**
+   * Sign data to confirm the intent of permanently disabling issuance of the Security Token
+   */
   public async prepareTransactions() {
     const { symbol } = this.args;
     const { contractWrappers } = this.context;

src/procedures/TransferErc20.ts

@@ -5,6 +5,9 @@ import { PolymathError } from '../PolymathError';
 import { Erc20TokenBalance } from '../entities';
 import { Factories } from '~/Context';
 
+/**
+ * @hidden
+ */
 export const createTransferErc20Resolver = (
   factories: Factories,
   tokenAddress: string,
@@ -24,6 +27,14 @@ export const createTransferErc20Resolver = (
 export class TransferErc20 extends Procedure<TransferErc20ProcedureArgs> {
   public type = ProcedureType.TransferErc20;
 
+  /**
+   * Transfer an ERC20 token to another wallet. The token in question defaults to POLY if no address is supplied
+
+   * Note that the procedure will fail if:
+   * - The owner's token balance is less than the amount being transferred. The only exception to this is when transferring POLY on a testnet.
+   * If that is the case, an extra transaction will be submitted to request the missing amount of tokens from the faucet
+   * - The token being transferred is a Security Token. In that case, the corresponding Security Token transfer procedures should be used
+   */
   public async prepareTransactions() {
     const { amount, receiver, tokenAddress } = this.args;
     const { contractWrappers, currentWallet, factories } = this.context;