Skip to main content

IScheduledBalanceAdjustment

Asset Tokenization Studio Team

IScheduledBalanceAdjustment

Interface for scheduled balance adjustment corporate actions on tokenised assets.

Scheduled balance adjustments enqueue operations to multiply every token holder's balance by factor / 10^decimals at a future date. Tasks are managed through ScheduledTasksStorageWrapper and corporate-action records through BalanceAdjustmentOps.

Methods​

cancelScheduledBalanceAdjustment​

function cancelScheduledBalanceAdjustment(uint256 _balanceAdjustmentID) external nonpayable returns (bool success_)

Cancels a previously scheduled balance adjustment.

Caller must hold ROLE_CORPORATE_ACTION. The token must not be paused. Emits ScheduledBalanceAdjustmentCancelled on success.

Parameters​

NameTypeDescription
_balanceAdjustmentIDuint256Identifier of the scheduled adjustment to cancel.

Returns​

NameTypeDescription
success_boolTrue if the cancellation succeeded.

forceCancelScheduledBalanceAdjustment​

function forceCancelScheduledBalanceAdjustment(uint256 _balanceAdjustmentID) external nonpayable returns (bool success_)

Force-cancels a balance adjustment regardless of its execution date.

Restricted to ROLE_CORPORATE_ACTION_FORCE_CANCEL and gated by the unpaused state and notZeroValue. Marks the corporate action disabled unconditionally — bypasses BalanceAdjustmentAlreadyExecuted — and emits ScheduledBalanceAdjustmentForceCancelled.

Parameters​

NameTypeDescription
_balanceAdjustmentIDuint256Identifier of the scheduled adjustment to force-cancel.

Returns​

NameTypeDescription
success_boolTrue if the force-cancellation succeeded.

getBalanceAdjustmentCount​

function getBalanceAdjustmentCount() external view returns (uint256 balanceAdjustmentCount_)

Returns the total number of balance adjustments ever scheduled, including cancelled ones.

Returns​

NameTypeDescription
balanceAdjustmentCount_uint256Total count of corporate-action balance adjustment records.

getPendingBalanceAdjustmentCount​

function getPendingBalanceAdjustmentCount(bool _includeDisabled) external view returns (uint256)

Returns the number of pending scheduled balance adjustments in the task queue.

Reads directly from ScheduledTasksStorageWrapper; excludes already-executed tasks.

Parameters​

NameTypeDescription
_includeDisabledboolWhen true, tasks belonging to cancelled corporate actions are counted; when false, only active tasks are counted.

Returns​

NameTypeDescription
_0uint256Count of pending balance adjustment tasks.

getScheduledBalanceAdjustment​

function getScheduledBalanceAdjustment(uint256 _balanceAdjustmentID) external view returns (struct IScheduledBalanceAdjustment.ScheduledBalanceAdjustment balanceAdjustment_, bool isDisabled_)

Returns the parameters and disabled state of a previously scheduled balance adjustment.

Reverts if the corporate action type stored at index _balanceAdjustmentID - 1 does not match CORPORATE_ACTION_TYPE_BALANCE_ADJUSTMENT.

Parameters​

NameTypeDescription
_balanceAdjustmentIDuint256Identifier of the scheduled adjustment to query.

Returns​

NameTypeDescription
balanceAdjustment_IScheduledBalanceAdjustment.ScheduledBalanceAdjustmentStruct containing executionDate, factor, and decimals.
isDisabled_boolTrue if the adjustment has been cancelled or already executed.

getScheduledBalanceAdjustments​

function getScheduledBalanceAdjustments(uint256 _pageIndex, uint256 _pageLength, bool _includeDisabled) external view returns (struct ScheduledTask[] scheduledBalanceAdjustment_)

Returns a paginated slice of pending scheduled balance adjustment tasks.

Reads from ScheduledTasksStorageWrapper. Tasks are ordered by insertion index.

Parameters​

NameTypeDescription
_pageIndexuint256Zero-based page number.
_pageLengthuint256Maximum number of tasks to return per page.
_includeDisabledboolWhen true, tasks belonging to cancelled corporate actions are included; when false, only active tasks are returned.

Returns​

NameTypeDescription
scheduledBalanceAdjustment_ScheduledTask[]Array of ScheduledTask structs for the requested page.

initializeScheduledBalanceAdjustment​

function initializeScheduledBalanceAdjustment() external nonpayable

Initialises the scheduled balance adjustment capability on the token.

Callable once; subsequent calls revert with FacetAlreadyRegistered. Requires DEFAULT_ADMIN_ROLE. Called by the factory during deployment.

setScheduledBalanceAdjustment​

function setScheduledBalanceAdjustment(IScheduledBalanceAdjustment.ScheduledBalanceAdjustment _newBalanceAdjustment) external nonpayable returns (uint256 balanceAdjustmentID_)

Parameters​

NameTypeDescription
_newBalanceAdjustmentIScheduledBalanceAdjustment.ScheduledBalanceAdjustmentundefined

Returns​

NameTypeDescription
balanceAdjustmentID_uint256undefined

Events​

ScheduledBalanceAdjustmentCancelled​

event ScheduledBalanceAdjustmentCancelled(uint256 balanceAdjustmentId, address indexed operator)

Emitted when a previously scheduled balance adjustment is cancelled.

Parameters​

NameTypeDescription
balanceAdjustmentIduint256Sequential identifier of the cancelled adjustment.
operator indexedaddressAddress that performed the cancellation.

ScheduledBalanceAdjustmentForceCancelled​

event ScheduledBalanceAdjustmentForceCancelled(uint256 balanceAdjustmentId, address indexed operator)

Emitted when an admin force-cancels a balance adjustment, bypassing date guards.

Parameters​

NameTypeDescription
balanceAdjustmentIduint256Sequential identifier of the force-cancelled adjustment.
operator indexedaddressAddress that performed the force-cancellation.

ScheduledBalanceAdjustmentInitialized​

event ScheduledBalanceAdjustmentInitialized()

Emitted once when the scheduled balance adjustment capability is initialised on a token.

Fires exclusively from initializeScheduledBalanceAdjustment.

ScheduledBalanceAdjustmentSet​

event ScheduledBalanceAdjustmentSet(bytes32 corporateActionId, uint256 balanceAdjustmentId, address indexed operator, uint256 indexed executionDate, uint256 factor, uint256 decimals)

Emitted when a balance adjustment is successfully scheduled.

Parameters​

NameTypeDescription
corporateActionIdbytes32On-chain identifier of the associated corporate action record.
balanceAdjustmentIduint256Sequential identifier of the scheduled adjustment.
operator indexedaddressAddress that scheduled the adjustment.
executionDate indexeduint256Unix timestamp at which the adjustment will be executed.
factoruint256Numerator of the adjustment ratio.
decimalsuint256Denominator exponent; effective ratio = factor / 10^decimals.

Errors​

BalanceAdjustmentAlreadyExecuted​

error BalanceAdjustmentAlreadyExecuted(bytes32 corporateActionId, uint256 balanceAdjustmentId)

Reverts when attempting to cancel or re-execute an adjustment that has already run.

Parameters​

NameTypeDescription
corporateActionIdbytes32Identifier of the corporate action that was already executed.
balanceAdjustmentIduint256Identifier of the balance adjustment that was already executed.

BalanceAdjustmentCreationFailed​

error BalanceAdjustmentCreationFailed()

Reverts when the underlying storage layer fails to create a corporate action record.