IDividend
Asset Tokenization Studio Team
IDividend
Writer-side interface for the Dividend domain — exposes the corporate-action lifecycle (setDividend, cancelDividend) plus the per-record reads that consumers need before executing or auditing a dividend.
Inherits IDividendTypes for the shared struct tier (Dividend, RegisteredDividend, DividendFor, DividendAmountFor). Domain events and errors live on this writer interface (not on the shared types tier) so that read-only sibling facets such as IDividendSecurityHolders do not pick up symbols they never emit or revert with — a narrow EIP-165 interfaceId is the goal. Aggregated into the off-chain IAsset umbrella alongside the read-only sibling facets.
Methods
cancelDividend
function cancelDividend(uint256 _dividendId) external nonpayable returns (bool success_)
Cancels a previously scheduled dividend before its execution date is reached.
Restricted to ROLE_CORPORATE_ACTION and gated by the unpaused state. Reverts with DividendAlreadyExecuted if the execution date has passed; otherwise marks the corporate action disabled and emits DividendCancelled.
Parameters
| Name | Type | Description |
|---|---|---|
| _dividendId | uint256 | One-indexed identifier of the dividend to cancel. |
Returns
| Name | Type | Description |
|---|---|---|
| success_ | bool | True if the cancellation was recorded. |
forceCancelDividend
function forceCancelDividend(uint256 _dividendId) external nonpayable returns (bool success_)
Force-cancels a dividend regardless of its execution date.
Restricted to ROLE_CORPORATE_ACTION_FORCE_CANCEL and gated by the unpaused state and onlyMatchingActionType. Marks the corporate action disabled unconditionally — bypasses DividendAlreadyExecuted — and emits DividendForceCancelled.
Parameters
| Name | Type | Description |
|---|---|---|
| _dividendId | uint256 | One-indexed identifier of the dividend to force-cancel. |
Returns
| Name | Type | Description |
|---|---|---|
| success_ | bool | True if the force-cancellation was recorded. |
getDividend
function getDividend(uint256 _dividendId) external view returns (struct IDividendTypes.RegisteredDividend registeredDividend_, bool isDisabled_)
Returns the persisted dividend record together with its cancelled flag.
Reverts via onlyMatchingActionType if dividendId does not resolve to a dividend corporate action.
Parameters
| Name | Type | Description |
|---|---|---|
| _dividendId | uint256 | One-indexed dividend identifier. |
Returns
| Name | Type | Description |
|---|---|---|
| registeredDividend_ | IDividendTypes.RegisteredDividend | Stored dividend parameters bound to their snapshot id. |
| isDisabled_ | bool | True if the dividend has been cancelled. |
getDividendAmountFor
function getDividendAmountFor(uint256 _dividendId, address _account) external view returns (struct IDividendTypes.DividendAmountFor dividendAmountFor_)
Returns the fractional dividend amount payable to a specific holder.
Reverts via onlyMatchingActionType if dividendId does not resolve to a dividend corporate action. Numerator and denominator are only meaningful once recordDateReached is set on the returned struct.
Parameters
| Name | Type | Description |
|---|---|---|
| _dividendId | uint256 | One-indexed dividend identifier. |
| _account | address | Holder address to query. |
Returns
| Name | Type | Description |
|---|---|---|
| dividendAmountFor_ | IDividendTypes.DividendAmountFor | Fractional payable amount for the holder. |
getDividendFor
function getDividendFor(uint256 _dividendId, address _account) external view returns (struct IDividendTypes.DividendFor dividendFor_)
Returns the per-account view of a dividend, including the holder's balance at the record date and the metadata required to compute the payable amount.
Reverts via onlyMatchingActionType if dividendId does not resolve to a dividend corporate action. Balance and decimals fields are only meaningful once recordDateReached is set on the returned struct.
Parameters
| Name | Type | Description |
|---|---|---|
| _dividendId | uint256 | One-indexed dividend identifier. |
| _account | address | Holder address to query. |
Returns
| Name | Type | Description |
|---|---|---|
| dividendFor_ | IDividendTypes.DividendFor | Holder-scoped dividend view. |
getDividendsCount
function getDividendsCount() external view returns (uint256 dividendCount_)
Returns the total number of dividends scheduled under the dividend corporate-action type — cancelled dividends remain in the count.
Returns
| Name | Type | Description |
|---|---|---|
| dividendCount_ | uint256 | Current dividend count. |
initializeDividend
function initializeDividend() external nonpayable
Initialises the dividend capability on the token.
Callable once; subsequent calls revert with FacetAlreadyRegistered. Requires DEFAULT_ADMIN_ROLE. Called by the factory during deployment.
setDividend
function setDividend(IDividendTypes.Dividend _newDividend) external nonpayable returns (uint256 dividendId_)
Parameters
| Name | Type | Description |
|---|---|---|
| _newDividend | IDividendTypes.Dividend | undefined |
Returns
| Name | Type | Description |
|---|---|---|
| dividendId_ | uint256 | undefined |
Events
DividendCancelled
event DividendCancelled(uint256 dividendId, address indexed operator)
Emitted when an operator cancels a previously scheduled dividend.
Cancellation is rejected once the execution date has passed; see DividendAlreadyExecuted.
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | One-indexed identifier of the cancelled dividend. |
operator indexed | address | Address that performed the cancellation. |
DividendForceCancelled
event DividendForceCancelled(uint256 dividendId, address indexed operator)
Emitted when an admin force-cancels a dividend, bypassing date guards.
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | One-indexed identifier of the force-cancelled dividend. |
operator indexed | address | Address that performed the force-cancellation. |
DividendInitialized
event DividendInitialized()
Emitted once when the dividend capability is initialised on a token.
Fires exclusively from initializeDividend.
DividendSet
event DividendSet(bytes32 corporateActionId, uint256 dividendId, address indexed operator, uint256 indexed recordDate, uint256 indexed executionDate, uint256 amount, uint8 amountDecimals)
Emitted when an operator schedules a new dividend corporate action.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | Identifier of the underlying corporate action. |
| dividendId | uint256 | One-indexed dividend identifier within the dividend corporate action type. |
operator indexed | address | Address that scheduled the dividend. |
recordDate indexed | uint256 | Unix timestamp of the snapshot taken to determine eligible holders. |
executionDate indexed | uint256 | Unix timestamp on which the dividend becomes payable. |
| amount | uint256 | Total amount distributed across eligible holders, scaled by amountDecimals. |
| amountDecimals | uint8 | Decimal precision applied to amount. |
Errors
DividendAlreadyExecuted
error DividendAlreadyExecuted(bytes32 corporateActionId, uint256 dividendId)
Reverts when an operator attempts to cancel a dividend whose execution date has already passed.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | Identifier of the underlying corporate action. |
| dividendId | uint256 | One-indexed identifier of the dividend that cannot be cancelled. |
DividendCreationFailed
error DividendCreationFailed()
Reverts when the underlying corporate-action creation step returns the zero id, indicating the dividend could not be persisted.