Corporate Actions
Overview
Corporate Actions (CAs) are events initiated by an asset issuer that affect the asset or its holders. Polymesh provides a framework for managing various CAs on-chain, automating processes like capital distributions and shareholder voting.
The Polymesh Corporate Actions functionality is primarily handled by three pallets:
corporateAction
: The base layer for initiating CAs, managing record dates, linking documents, and defining core parameters like taxes and target identities.capitalDistribution
: Manages the distribution of benefits (payments, dividends, interest, etc.) linked to a CA. See Capital Distribution.corporateBallot
: Handles on-chain voting linked to a CA. See On-Chain Voting.
Corporate actions may trigger registration or filing requirements with applicable securities regulators or other governmental authorities. Always consult with legal and financial advisors before initiating a corporate action.
Core Concepts
- Corporate Action (CA): An on-chain record representing an event related to a specific asset. Each CA has a unique ID (
CAId
) composed of the asset's internalAssetId
(UUID) and a sequential ID specific to that asset. The sequential ID is automatically assigned when a CA is created, starting at 0 and incrementing for each new CA associated with the same asset. When referencing a CA in API calls, both the asset ID and this local sequential ID are required to uniquely identify the specific corporate action. - Corporate Action Agent (CAA): An identity authorized to manage CAs for an asset. By default, this is the asset issuer, but it can be delegated to another identity as an Agent of the asset.
- Record Date: The specific point in time, defined by a Checkpoint, used to determine holder entitlements (e.g., who receives dividends or can vote).
- CA Kind: The type of corporate action, determining its purpose and associated functionality (e.g.,
IssuerNotice
,Reorganization
,PredictableBenefit
,UnpredictableBenefit
,Other
). - Declaration Date: The date the CA was officially declared by the issuer (off-chain). Recorded for informational purposes.
- Taxes: Optional withholding tax percentages (default and DID-specific) applied to distributions.
- Targets: The set of identities eligible to participate in the CA. By default, all asset holders are targeted, but this can be customized (e.g., include/exclude specific identities).
- Documents: Off-chain documents (e.g., prospectuses, notices) can be linked to a CA for reference.
Corporate Action Lifecycle
1. (Optional) Set Asset-Level Defaults
To simplify repeated CA creation, the CAA can set default configurations at the asset level:
- Default Withholding Tax: Use
corporateAction::set_default_withholding_tax
to set a standard tax rate for distributions related to this asset. - DID-Specific Withholding Tax: Use
corporateAction::set_did_withholding_tax
to set custom tax rates for specific identities. - Default Targets: Use
corporateAction::set_default_targets
to define a standard set of included/excluded identities for CAs of this asset.
When a CA is created, the asset-level defaults (target identities and tax withholding) are copied into the CA structure. Subsequent changes to asset-level defaults will only affect future CAs, not existing ones.
- You can modify asset-level defaults at any time using the functions above
- Changes to defaults don't affect existing CAs or their active distributions
- Once a CA is created, most of its parameters (including targets and tax settings) cannot be modified
- Only the record date can be modified (using
change_record_date
) and only before a distribution starts
This design ensures that ongoing distributions maintain consistent parameters throughout their lifecycle, regardless of changes to asset-level defaults.
2. Initiate Corporate Action
This is the essential first step for any on-chain distribution or voting process. The CAA creates the CA record using corporateAction::initiate_corporate_action
.
Parameters:
asset_id
: The internalAssetId
(UUID) of the target asset.kind
: The type of Corporate Action:PredictableBenefit
/UnpredictableBenefit
: For distributions like dividendsIssuerNotice
: For ballots/votingReorganization
: For reorganization of tokensOther
: For generic uncategorised CAs
decl_date
: The off-chain declaration date (timestamp).details
: Free-form text description (bytes) (max length defined bymaxDetailsLength
).targets
(Optional): Specify target identities if different from the asset default or all holders.default_withholding_tax
(Optional): Override the asset's default tax rate for this CA.withholding_tax
(Optional): Provide DID-specific tax rates for this CA, overriding asset defaults.record_date
(Optional): Specifies the checkpoint to use as the record date. Can be:- An existing Checkpoint ID.
- A future timestamp for a scheduled Checkpoint.
- An existing Checkpoint Schedule ID.
While the record_date
is an optional parameter when initiating a corporate action it is mandatory one is set before attaching a distribution or ballot to the CA.
Effects:
- Creates the CA record on-chain with a unique
CAId
. - Establishes the core parameters (kind, record date, taxes, targets) for subsequent actions like distributions or voting.
3. Attach Specific Functionality (Distribution/Voting)
Once the CA is initiated, specific functionality can be attached based on its kind
:
- For
PredictableBenefit
,UnpredictableBenefit
: Attach a distribution usingcapitalDistribution::distribute
(or use the combinedcorporateAction::initiate_corporate_action_and_distribute
). See Capital Distribution for details. - For
IssuerNotice
: Attach a ballot usingcorporateBallot::attach_ballot
(or use the combinedcorporateAction::initiate_corporate_action_and_ballot
). See On-Chain Voting for details.
For convenience, the corporateAction
pallet provides the initiate_corporate_action_and_distribute
and initiate_corporate_action_and_ballot
extrinsics. These allows the Corporate Action Agent to initiate the CA (providing target AssetId
, etc.) and create the associated distribution or ballot in a single transaction.
4. Manage the Corporate Action (Optional)
After initiation, the CAA can manage certain aspects:
- Change Record Date: Use
corporateAction::change_record_date
to modify the record date before the associated distribution/ballot starts, provided the CAkind
allows it. - Link Documents: Use
corporateAction::link_ca_doc
to link supporting documents to the corporate action. - Remove Corporate Action: Use
corporateAction::remove_ca
to remove a CA, typically after it's completed or if it needs to be cancelled before activation. This will also remove any associated distributions or ballots if they haven't yet started.
Further Reading
📄️ Checkpoint Management
Create and manage snapshots of asset holder balances at specific points in time
📄️ Capital Distribution
Distribute payments to asset holders based on their holdings at a specific point in time
📄️ On-Chain Voting
Manage on-chain voting processes for asset holders