Dividend
Asset Tokenization Studio Team
Dividend
Abstract base providing the writer-side dividend lifecycle exposed by DividendFacet (setDividend, cancelDividend) plus the record/per-account read helpers consumers need before executing a dividend.
Thin forwarder over DividendStorageWrapper; holds no storage of its own. All write paths are restricted to ROLE_CORPORATE_ACTION and gated by the unpaused state. Read paths are guarded by onlyMatchingActionType(CORPORATE_ACTION_TYPE_DIVIDEND, dividendId - 1) so an attacker cannot use a non-dividend corporate-action id to read dividend slots.
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; gated by onlyUnpaused and onlyMatchingActionType(CORPORATE_ACTION_TYPE_DIVIDEND, dividendId - 1).
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | undefined |
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; gated by onlyUnpaused and onlyMatchingActionType(CORPORATE_ACTION_TYPE_DIVIDEND, dividendId - 1).
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | undefined |
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 match the dividend corporate-action type at index dividendId - 1.
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | undefined |
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 match the dividend corporate-action type at index dividendId - 1.
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | undefined |
| account | address | undefined |
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 match the dividend corporate-action type at index dividendId - 1.
Parameters
| Name | Type | Description |
|---|---|---|
| dividendId | uint256 | undefined |
| account | address | undefined |
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
AccountHasNoRole
error AccountHasNoRole(address account, bytes32 role)
Thrown when an account does not hold a required role.
Parameters
| Name | Type | Description |
|---|---|---|
| account | address | The account that lacks the role. |
| role | bytes32 | The role that is not held. |
AssetNotOperational
error AssetNotOperational(bytes32 configId, uint256 versionId)
Raised by InitializerStorageWrapper.checkOperational (and the related isConfigVersionOperational helper) when an operation is attempted on a configuration version that has not yet been marked operational.
Parameters
| Name | Type | Description |
|---|---|---|
| configId | bytes32 | Resolver-proxy configuration whose operational status was checked. |
| versionId | uint256 | Configuration version whose operational status was checked. |
Deactivated
error Deactivated()
Thrown when an operation guarded by onlyActivated is attempted on a token whose deactivation flag has already been set.
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.
ExponentOverflow
error ExponentOverflow(uint256 exponent)
Reverts when an exponent would cause 10 ** exponent to overflow uint256.
Thrown by DecimalsLib.checkExponentOverflow when exponent >= 78.
Parameters
| Name | Type | Description |
|---|---|---|
| exponent | uint256 | The exponent that would produce an overflow. |
FacetAlreadyRegistered
error FacetAlreadyRegistered(bytes32 facetId, uint256 lastVersion)
Raised when an initialiser tries to register a facet that already has a non-zero last registered version (i.e. the facet is being re-initialised on a fresh install).
Parameters
| Name | Type | Description |
|---|---|---|
| facetId | bytes32 | Identifier of the offending facet. |
| lastVersion | uint256 | Last version recorded for that facet at the time of the check. |
IsPaused
error IsPaused()
Thrown when an operation that requires the token to be unpaused is attempted while the token is paused (own flag or any external pause contract).
SnapshotIdDoesNotExists
error SnapshotIdDoesNotExists(uint256 snapshotId)
Thrown when the requested snapshot identifier has never been taken on this token.
Parameters
| Name | Type | Description |
|---|---|---|
| snapshotId | uint256 | The unrecognised snapshot identifier that was supplied. |
SnapshotIdNull
error SnapshotIdNull()
Thrown when a snapshot identifier of zero is supplied; zero is reserved and never assigned to a valid snapshot.
UnexpectedError
error UnexpectedError(bytes4 _errorId)
Reverts when an unreachable validation state is detected.
Replaces assertions for defensive handling of logically impossible states.
Parameters
| Name | Type | Description |
|---|---|---|
| _errorId | bytes4 | Identifier of the unexpected validation condition. |
UnrecognizedResolverProxyVersion
error UnrecognizedResolverProxyVersion(bytes8 _resolverProxyVersion)
Thrown when the provided proxy version does not match any BLR compatible standard.
Parameters
| Name | Type | Description |
|---|---|---|
| _resolverProxyVersion | bytes8 | proxy version that is not compatible with the BLR. |
WalletRecovered
error WalletRecovered()
Thrown when attempting to recover a wallet that has already been recovered.
WrongDates
error WrongDates(uint256 firstDate, uint256 secondDate)
Reverts when two date values fail their required ordering constraint.
The expected relationship between both dates is defined by the caller's validation context.
Parameters
| Name | Type | Description |
|---|---|---|
| firstDate | uint256 | First date participating in the failed comparison. |
| secondDate | uint256 | Second date participating in the failed comparison. |
WrongIndexForAction
error WrongIndexForAction(uint256 index, bytes32 actionType)
Thrown when a type-scoped index does not correspond to an existing action.
Parameters
| Name | Type | Description |
|---|---|---|
| index | uint256 | The out-of-range index that was provided. |
| actionType | bytes32 | The action type against which the index was validated. |
WrongTimestamp
error WrongTimestamp(uint256 timeStamp)
Reverts when a scheduled timestamp is not strictly in the future.
Used for shared scheduling validation where the current block time is read through TimeTravelStorageWrapper.
Parameters
| Name | Type | Description |
|---|---|---|
| timeStamp | uint256 | Timestamp rejected for scheduling. |