Skip to main content
Version: 23.0.x

Class: DividendDistribution

api/entities/DividendDistribution.DividendDistribution

Represents a Corporate Action via which an Asset issuer wishes to distribute dividends between a subset of the Asset Holders (targets)

Hierarchy

Properties

asset

asset: FungibleAsset

Asset affected by this Corporate Action

Inherited from

CorporateActionBase.asset

Defined in

api/entities/CorporateActionBase/index.ts:75


currency

currency: string

ticker of the currency in which dividends are being distributed

Defined in

api/entities/DividendDistribution/index.ts:97


declarationDate

declarationDate: Date

date at which the Corporate Action was created

Inherited from

CorporateActionBase.declarationDate

Defined in

api/entities/CorporateActionBase/index.ts:80


defaultTaxWithholding

defaultTaxWithholding: BigNumber

default percentage (0-100) of tax withholding for this Corporate Action

Inherited from

CorporateActionBase.defaultTaxWithholding

Defined in

api/entities/CorporateActionBase/index.ts:96


description

description: string

brief text description of the Corporate Action

Inherited from

CorporateActionBase.description

Defined in

api/entities/CorporateActionBase/index.ts:85


expiryDate

expiryDate: null | Date

date after which dividends can no longer be paid/reclaimed. A null value means the distribution never expires

Defined in

api/entities/DividendDistribution/index.ts:113


id

id: BigNumber

internal Corporate Action ID

Inherited from

CorporateActionBase.id

Defined in

api/entities/CorporateActionBase/index.ts:70


maxAmount

maxAmount: BigNumber

maximum amount of currency to be distributed. Distributions are "first come, first served", so funds can be depleted before every Asset Holder receives their corresponding amount

Defined in

api/entities/DividendDistribution/index.ts:108


origin

origin: NumberedPortfolio | DefaultPortfolio

Portfolio from which the dividends will be distributed

Defined in

api/entities/DividendDistribution/index.ts:92


paymentDate

paymentDate: Date

date starting from which dividends can be paid/reclaimed

Defined in

api/entities/DividendDistribution/index.ts:118


perShare

perShare: BigNumber

amount of currency to pay for each share held by the Asset Holders

Defined in

api/entities/DividendDistribution/index.ts:102


targets

targets: CorporateActionTargets

Asset Holder Identities related to this Corporate action. If the treatment is Exclude, the Identities in the array will not be targeted by the Action, Identities not in the array will be targeted, and vice versa

Inherited from

CorporateActionBase.targets

Defined in

api/entities/CorporateActionBase/index.ts:91


taxWithholdings

taxWithholdings: TaxWithholding[]

percentage (0-100) of tax withholding per Identity. Any Identity not present in this array uses the default tax withholding percentage

Inherited from

CorporateActionBase.taxWithholdings

Defined in

api/entities/CorporateActionBase/index.ts:102


uuid

uuid: string

Inherited from

CorporateActionBase.uuid

Defined in

api/entities/Entity.ts:46

Methods

checkpoint

checkpoint(): Promise<CheckpointSchedule | Checkpoint>

Retrieve the Checkpoint associated with this Dividend Distribution. If the Checkpoint is scheduled and has not been created yet, the corresponding CheckpointSchedule is returned instead

Returns

Promise<CheckpointSchedule | Checkpoint>

Overrides

CorporateActionBase.checkpoint


claim

claim(opts?): Promise<GenericPolymeshTransaction<void, void>>

Claim the Dividends corresponding to the signing Identity

Note

if currency is indivisible, the Identity's share will be rounded down to the nearest integer (after taxes are withheld)

Note

this method is of type NoArgsProcedureMethod, which means you can call claim.checkAuthorization on it to see whether the signing Account and Identity have the required roles and permissions to run it

Parameters

NameType
opts?ProcedureOpts

Returns

Promise<GenericPolymeshTransaction<void, void>>


details

details(): Promise<DividendDistributionDetails>

Retrieve details associated with this Dividend Distribution

Returns

Promise<DividendDistributionDetails>


exists

exists(): Promise<boolean>

Retrieve whether the Distribution exists

Returns

Promise<boolean>

Overrides

CorporateActionBase.exists


getParticipant

getParticipant(args?): Promise<null | DistributionParticipant>

Retrieve an Identity that is entitled to dividends in this Distribution (participant), the amount it is entitled to and whether it has been paid or not

Note

if the Distribution Checkpoint hasn't been created yet, the result will be null. This is because the Distribution participant's corresponding payment cannot be determined without a Checkpoint

Parameters

NameTypeDescription
args?Object-
args.identitystring | Identitydefaults to the signing Identity

Returns

Promise<null | DistributionParticipant>


getParticipants

getParticipants(): Promise<DistributionParticipant[]>

Retrieve a comprehensive list of all Identities that are entitled to dividends in this Distribution (participants), the amount they are entitled to and whether they have been paid or not

Note

this request can take a lot of time with large amounts of Asset Holders

Note

if the Distribution Checkpoint hasn't been created yet, the result will be an empty array. This is because the Distribution participants cannot be determined without a Checkpoint

Returns

Promise<DistributionParticipant[]>


getPaymentHistory

getPaymentHistory(opts?): Promise<ResultSet<DistributionPayment>>

Retrieve the payment history for this Distribution

Note

uses the middleware V2

Note

supports pagination

Parameters

NameType
optsObject
opts.size?BigNumber
opts.start?BigNumber

Returns

Promise<ResultSet<DistributionPayment>>


getWithheldTax

getWithheldTax(): Promise<BigNumber>

Retrieve the amount of taxes that have been withheld up to this point in this Distribution

Note

uses the middlewareV2

Returns

Promise<BigNumber>


isEqual

isEqual(entity): boolean

Determine whether this Entity is the same as another one

Parameters

NameType
entityEntity<unknown, unknown>

Returns

boolean

Inherited from

CorporateActionBase.isEqual


linkDocuments

linkDocuments(args, opts?): Promise<GenericPolymeshTransaction<void, void>>

Link a list of documents to this corporate action

Note

any previous links are removed in favor of the new list

Note

this method is of type ProcedureMethod, which means you can call linkDocuments.checkAuthorization on it to see whether the signing Account and Identity have the required roles and permissions to run it

Parameters

NameType
argsLinkCaDocsParams
opts?ProcedureOpts

Returns

Promise<GenericPolymeshTransaction<void, void>>

Inherited from

CorporateActionBase.linkDocuments


modifyCheckpoint

modifyCheckpoint(args, opts?): Promise<GenericPolymeshTransaction<void, void>>

Modify the Distribution's Checkpoint

Note

this method is of type ProcedureMethod, which means you can call modifyCheckpoint.checkAuthorization on it to see whether the signing Account and Identity have the required roles and permissions to run it

Parameters

NameType
argsModify<ModifyCaCheckpointParams, { checkpoint: InputCaCheckpoint }>
opts?ProcedureOpts

Returns

Promise<GenericPolymeshTransaction<void, void>>

Overrides

CorporateActionBase.modifyCheckpoint


pay

pay(args, opts?): Promise<GenericPolymeshTransaction<void, void>>

Transfer the corresponding share of the dividends to a list of Identities

Note

due to performance issues, we do not validate that the distribution has enough remaining funds to pay the corresponding amount to the supplied Identities

Note

if currency is indivisible, the Identity's share will be rounded down to the nearest integer (after taxes are withheld)

Note

this method is of type ProcedureMethod, which means you can call pay.checkAuthorization on it to see whether the signing Account and Identity have the required roles and permissions to run it

Parameters

NameType
argsPayDividendsParams
opts?ProcedureOpts

Returns

Promise<GenericPolymeshTransaction<void, void>>


reclaimFunds

reclaimFunds(opts?): Promise<GenericPolymeshTransaction<void, void>>

Reclaim any remaining funds back to the origin Portfolio. This can only be done after the Distribution has expired

Note

withheld taxes are also reclaimed in the same transaction

Note

required roles:

  • Origin Portfolio Custodian

Note

this method is of type NoArgsProcedureMethod, which means you can call reclaimFunds.checkAuthorization on it to see whether the signing Account and Identity have the required roles and permissions to run it

Parameters

NameType
opts?ProcedureOpts

Returns

Promise<GenericPolymeshTransaction<void, void>>


toHuman

toHuman(): HumanReadable

Return the Dividend Distribution's static data

Returns

HumanReadable

Overrides

CorporateActionBase.toHuman


generateUuid

Static generateUuid<Identifiers>(identifiers): string

Generate the Entity's UUID from its identifying properties

Type parameters

Name
Identifiers

Parameters

NameType
identifiersIdentifiers

Returns

string

Inherited from

CorporateActionBase.generateUuid


unserialize

Static unserialize<Identifiers>(serialized): Identifiers

Unserialize a UUID into its Unique Identifiers

Type parameters

Name
Identifiers

Parameters

NameTypeDescription
serializedstringUUID to unserialize

Returns

Identifiers

Inherited from

CorporateActionBase.unserialize