diff --git a/package.json b/package.json index d19b4a0..97dd0aa 100644 --- a/package.json +++ b/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" diff --git a/src/procedures/ApproveErc20.ts b/src/procedures/ApproveErc20.ts index c845d83..6670af8 100644 --- a/src/procedures/ApproveErc20.ts +++ b/src/procedures/ApproveErc20.ts @@ -9,6 +9,15 @@ import { PolymathError } from '../PolymathError'; export class ApproveErc20 extends Procedure { 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; diff --git a/src/procedures/CreateCheckpoint.ts b/src/procedures/CreateCheckpoint.ts index 19e1e20..ac1a780 100644 --- a/src/procedures/CreateCheckpoint.ts +++ b/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 { public type = ProcedureType.CreateCheckpoint; + /** + * Create a Checkpoint on the Security Token and return it + */ public async prepareTransactions() { const { args, context } = this; const { symbol } = args; diff --git a/src/procedures/CreateDividendDistribution.ts b/src/procedures/CreateDividendDistribution.ts index 556e51c..d3d0f7b 100644 --- a/src/procedures/CreateDividendDistribution.ts +++ b/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 { diff --git a/src/procedures/CreateSecurityToken.ts b/src/procedures/CreateSecurityToken.ts index 97e16d8..3f6c07d 100644 --- a/src/procedures/CreateSecurityToken.ts +++ b/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; diff --git a/src/procedures/DisableController.ts b/src/procedures/DisableController.ts index 538a0d5..521eeea 100644 --- a/src/procedures/DisableController.ts +++ b/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 { 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; diff --git a/src/procedures/DisableFeature.ts b/src/procedures/DisableFeature.ts index ba70aeb..1e189fb 100644 --- a/src/procedures/DisableFeature.ts +++ b/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 { 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; diff --git a/src/procedures/EnableCountTransferManager.ts b/src/procedures/EnableCountTransferManager.ts index 38f21e3..80ca6bc 100644 --- a/src/procedures/EnableCountTransferManager.ts +++ b/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 { 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; diff --git a/src/procedures/EnableDividendManager.ts b/src/procedures/EnableDividendManager.ts index 907235e..190c7df 100644 --- a/src/procedures/EnableDividendManager.ts +++ b/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 { 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; diff --git a/src/procedures/EnableGeneralPermissionManager.ts b/src/procedures/EnableGeneralPermissionManager.ts index 2a7297e..75e04a9 100644 --- a/src/procedures/EnableGeneralPermissionManager.ts +++ b/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; diff --git a/src/procedures/EnableGeneralTransferManager.ts b/src/procedures/EnableGeneralTransferManager.ts index df2f887..9521081 100644 --- a/src/procedures/EnableGeneralTransferManager.ts +++ b/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; diff --git a/src/procedures/EnablePercentageTransferManager.ts b/src/procedures/EnablePercentageTransferManager.ts index 2a3fcae..49af404 100644 --- a/src/procedures/EnablePercentageTransferManager.ts +++ b/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; diff --git a/src/procedures/FreezeIssuance.ts b/src/procedures/FreezeIssuance.ts index 5971255..c758392 100644 --- a/src/procedures/FreezeIssuance.ts +++ b/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 { 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; diff --git a/src/procedures/LaunchSimpleSto.ts b/src/procedures/LaunchSimpleSto.ts index 0917afc..038daa6 100644 --- a/src/procedures/LaunchSimpleSto.ts +++ b/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 { 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 { diff --git a/src/procedures/LaunchTieredSto.ts b/src/procedures/LaunchTieredSto.ts index e0f99e0..8485500 100644 --- a/src/procedures/LaunchTieredSto.ts +++ b/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 { 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 { + return tieredStoFactory.update( + TieredSto.generateId({ + securityTokenId: SecurityToken.generateId({ symbol }), + stoType: StoType.Tiered, + address: newStoAddress.result!, + }), + { preIssueAllowed: true } + ); + }, + ], } )({}); } diff --git a/src/procedures/SetDividendsWallet.ts b/src/procedures/SetDividendsWallet.ts index 6c2e00f..b645e3b 100644 --- a/src/procedures/SetDividendsWallet.ts +++ b/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 { 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; diff --git a/src/procedures/SignDisableControllerAck.ts b/src/procedures/SignDisableControllerAck.ts index 08b3901..1ac7dd3 100644 --- a/src/procedures/SignDisableControllerAck.ts +++ b/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 { 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; diff --git a/src/procedures/SignFreezeIssuanceAck.ts b/src/procedures/SignFreezeIssuanceAck.ts index bf2c3b8..708f316 100644 --- a/src/procedures/SignFreezeIssuanceAck.ts +++ b/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 { 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; diff --git a/src/procedures/TransferErc20.ts b/src/procedures/TransferErc20.ts index e4b24ab..1a92f87 100644 --- a/src/procedures/TransferErc20.ts +++ b/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 { 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; diff --git a/src/procedures/UpdateDividendsTaxWithholdingList.ts b/src/procedures/UpdateDividendsTaxWithholdingList.ts index 92309db..31bc8be 100644 --- a/src/procedures/UpdateDividendsTaxWithholdingList.ts +++ b/src/procedures/UpdateDividendsTaxWithholdingList.ts @@ -13,6 +13,10 @@ import { SecurityToken, TaxWithholding } from '../entities'; import { Factories } from '../Context'; const CHUNK_SIZE = 200; + +/** + * @hidden + */ export const updateDividendsTaxWithholdingListResolver = ( factories: Factories, symbol: string, @@ -32,11 +36,21 @@ export const updateDividendsTaxWithholdingListResolver = ( ); }; +/** + * Procedure that modifies dividend tax withholding percentages for holders of the Security Token + */ export class UpdateDividendsTaxWithholdingList extends Procedure< UpdateDividendsTaxWithholdingListProcedureArgs > { public type = ProcedureType.UpdateDividendsTaxWithholdingList; + /** + * Modify tax withholding percentage for shareholders + * + * 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, shareholderAddresses: investors, percentages } = this.args; const { contractWrappers, factories } = this.context; diff --git a/src/procedures/WithdrawTaxes.ts b/src/procedures/WithdrawTaxes.ts index 75f0a7a..9360ee2 100644 --- a/src/procedures/WithdrawTaxes.ts +++ b/src/procedures/WithdrawTaxes.ts @@ -5,6 +5,9 @@ import { PolymathError } from '../PolymathError'; import { DividendDistribution, SecurityToken } from '../entities'; import { Factories } from '../Context'; +/** + * @hidden + */ export const createWithdrawTaxesResolver = ( dividendIndex: number, factories: Factories, @@ -18,9 +21,19 @@ export const createWithdrawTaxesResolver = ( ); }; +/** + * Procedure that allows an issuer to withdraw withheld tax from a Dividend Distribution + */ export class WithdrawTaxes extends Procedure { public type = ProcedureType.WithdrawTaxes; + /** + * Withdraw Tax Withholdings + * + * 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, dividendIndex } = this.args; const { contractWrappers, factories } = this.context;