IAmortization
Asset Tokenization Studio Team
IAmortization
Writer interface for the amortization facet — corporate-action driven token redemption.
Defines the events, errors, structs, and functions used to register, fund, hold, and cancel amortization corporate actions across the token holder set.
Methods
cancelAmortization
function cancelAmortization(uint256 _amortizationID) external nonpayable
Cancels an existing amortization.
Reverts if any token holder still has an active hold for this amortization. All holds must be released via releaseAmortizationHold before cancellation is allowed.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization to cancel. |
forceCancelAmortization
function forceCancelAmortization(uint256 _amortizationID) external nonpayable
Force-cancels an amortization regardless of its execution date.
Restricted to ROLE_CORPORATE_ACTION_FORCE_CANCEL and gated by the unpaused state, onlyWithoutMultiPartition, and onlyMatchingActionType. Marks the corporate action disabled unconditionally — bypasses AmortizationAlreadyExecuted and AmortizationNotActive — and emits AmortizationForceCancelled.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization to force-cancel. |
getActiveAmortizationIds
function getActiveAmortizationIds(uint256 _pageIndex, uint256 _pageLength) external view returns (uint256[] activeIds_)
Retrieves a paginated list of non-cancelled amortization IDs.
Cancelled amortizations (isDisabled=true) are excluded from the result.
Parameters
| Name | Type | Description |
|---|---|---|
| _pageIndex | uint256 | The page index for pagination. |
| _pageLength | uint256 | The number of records per page. |
Returns
| Name | Type | Description |
|---|---|---|
| activeIds_ | uint256[] | Array of amortization IDs that have not been cancelled. |
getAmortization
function getAmortization(uint256 _amortizationID) external view returns (struct IAmortization.RegisteredAmortization registeredAmortization_, bool isDisabled_)
Retrieves a registered amortization by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization to retrieve. |
Returns
| Name | Type | Description |
|---|---|---|
| registeredAmortization_ | IAmortization.RegisteredAmortization | The registered amortization data. |
| isDisabled_ | bool | Whether the amortization is disabled. |
getAmortizationActiveHolders
function getAmortizationActiveHolders(uint256 _amortizationID, uint256 _pageIndex, uint256 _pageLength) external view returns (address[] holders_)
Retrieves a paginated list of token holders that still have an active hold for a given amortization.
Use this to identify which holders must have their hold released before cancelAmortization can succeed.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _pageIndex | uint256 | The page index for pagination. |
| _pageLength | uint256 | The number of holders per page. |
Returns
| Name | Type | Description |
|---|---|---|
| holders_ | address[] | Array of addresses with an active hold for this amortization. |
getAmortizationFor
function getAmortizationFor(uint256 _amortizationID, address _account) external view returns (struct IAmortization.AmortizationFor amortizationFor_)
Retrieves amortization payment information for a specific account.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _account | address | The account address. |
Returns
| Name | Type | Description |
|---|---|---|
| amortizationFor_ | IAmortization.AmortizationFor | Amortization payment information for the specified account. |
getAmortizationHolders
function getAmortizationHolders(uint256 _amortizationID, uint256 _pageIndex, uint256 _pageLength) external view returns (address[] holders_)
Retrieves a paginated list of amortization holders for a specific amortization ID.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _pageIndex | uint256 | The page index for pagination. |
| _pageLength | uint256 | The number of holders per page. |
Returns
| Name | Type | Description |
|---|---|---|
| holders_ | address[] | Array of holder addresses. |
getAmortizationsCount
function getAmortizationsCount() external view returns (uint256 amortizationCount_)
Retrieves the total number of amortizations set for the security.
Cancelled amortizations are included in the count.
Returns
| Name | Type | Description |
|---|---|---|
| amortizationCount_ | uint256 | The total count of registered amortizations. |
getAmortizationsFor
function getAmortizationsFor(uint256 _amortizationID, uint256 _pageIndex, uint256 _pageLength) external view returns (struct IAmortization.AmortizationFor[] amortizationsFor_, address[] holders_)
Retrieves amortization payment information for multiple holders (paginated).
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _pageIndex | uint256 | The page index for pagination. |
| _pageLength | uint256 | The number of records per page. |
Returns
| Name | Type | Description |
|---|---|---|
| amortizationsFor_ | IAmortization.AmortizationFor[] | List of amortization payment information per holder. |
| holders_ | address[] | The holder addresses aligned by index with amortizationsFor_. |
getTotalActiveAmortizationIds
function getTotalActiveAmortizationIds() external view returns (uint256)
Retrieves the total number of non-cancelled amortizations.
Returns
| Name | Type | Description |
|---|---|---|
| _0 | uint256 | The total count of active (non-cancelled) amortization IDs. |
getTotalAmortizationActiveHolders
function getTotalAmortizationActiveHolders(uint256 _amortizationID) external view returns (uint256)
Retrieves the total number of token holders that still have an active hold for a given amortization.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
Returns
| Name | Type | Description |
|---|---|---|
| _0 | uint256 | The total count of holders with an active hold. |
getTotalAmortizationHolders
function getTotalAmortizationHolders(uint256 _amortizationID) external view returns (uint256)
Retrieves the total number of amortization holders for a specific amortization ID.
It is the list of token holders at the snapshot taken at the record date.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
Returns
| Name | Type | Description |
|---|---|---|
| _0 | uint256 | The total number of amortization holders. |
getTotalHoldByAmortizationId
function getTotalHoldByAmortizationId(uint256 _amortizationID) external view returns (uint256)
Retrieves the total amount of tokens locked in holds for a given amortization.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
Returns
| Name | Type | Description |
|---|---|---|
| _0 | uint256 | The total token amount held across all active holds for this amortization. |
initializeAmortization
function initializeAmortization() external nonpayable
Initialises the amortization capability on the token.
Callable once; subsequent calls revert with FacetAlreadyRegistered. Requires DEFAULT_ADMIN_ROLE. Called by the factory during deployment.
isAmortizationHoldAccountingMigrationPending
function isAmortizationHoldAccountingMigrationPending(uint256 _amortizationID) external view returns (bool)
Reports whether an amortization corporate action still needs migrateAmortizationHoldAccounting to be called for it.
Backed by the same raw-LABAF-read helper as the idempotency guard on the migration writer, depending only on labafByAmortizationId == 0 — never on totalHoldByAmortizationId. No role gate, matching the read-only nature of getTotalHoldByAmortizationId.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The one-based identifier of the amortization to inspect. |
Returns
| Name | Type | Description |
|---|---|---|
| _0 | bool | True if the raw labafByAmortizationId is still 0 (never migrated and never regularly synced); false otherwise. |
migrateAmortizationHoldAccounting
function migrateAmortizationHoldAccounting(uint256 _amortizationID, uint256 _total, uint256 _labaf) external nonpayable
One-time, admin-gated repair that seeds totalHoldByAmortizationId and labafByAmortizationId for an amortization corporate action that accumulated holds before LABAF tracking existed on this aggregate.
Restricted to DEFAULT_ADMIN_ROLE. Deliberately carries no onlyOperational, onlyActivated, or onlyUnpaused gate so it can repair state while the token is paused. Reverts with {AmortizationHoldAccountingAlreadyMigrated} if the raw, non-defaulted labafByAmortizationId is already non-zero; with {InvalidAmortizationMigrationLabaf} if _labaf == 0; with {AmortizationMigrationLabafAboveAbaf} if _labaf exceeds the current ABAF; with {AmortizationMigrationTotalAboveSupply} if _total exceeds the token's current total supply. Not gated on disabledAmortizations: a cancelled action can still reach the vulnerable sync path via a later releaseAmortizationHold and must stay migratable. Emits {AmortizationHoldAccountingMigrated} on success.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The one-based identifier of the amortization to migrate. |
| _total | uint256 | The raw totalHoldByAmortizationId value to seed (no lower bound, 0 is valid; MUST NOT exceed the token's current totalSupply()). |
| _labaf | uint256 | The raw labafByAmortizationId value to seed; must satisfy 0 < _labaf <= currentAbaf. |
releaseAmortizationHold
function releaseAmortizationHold(uint256 _amortizationID, address _tokenHolder) external nonpayable
Releases the active hold for a specific token holder in an amortization.
Must be called for every holder with an active hold before cancelAmortization can succeed. Reverts if the holder has no active hold for this amortization.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _tokenHolder | address | The address of the token holder whose hold will be released. |
setAmortization
function setAmortization(IAmortization.Amortization _amortization) external nonpayable returns (bool success_, uint256 amortizationID_)
Parameters
| Name | Type | Description |
|---|---|---|
| _amortization | IAmortization.Amortization | undefined |
Returns
| Name | Type | Description |
|---|---|---|
| success_ | bool | undefined |
| amortizationID_ | uint256 | undefined |
setAmortizationHold
function setAmortizationHold(uint256 _amortizationID, address _tokenHolder, uint256 _tokenAmount) external nonpayable returns (uint256 holdId_)
Creates or replaces the hold for a specific token holder in an amortization.
If the holder already has a pending hold, it is released first.
Parameters
| Name | Type | Description |
|---|---|---|
| _amortizationID | uint256 | The ID of the amortization. |
| _tokenHolder | address | The address of the token holder. |
| _tokenAmount | uint256 | The number of tokens to lock in the hold. |
Returns
| Name | Type | Description |
|---|---|---|
| holdId_ | uint256 | The ID of the newly created hold. |
Events
AmortizationCancelled
event AmortizationCancelled(uint256 amortizationId, address indexed operator)
Emitted when an amortization is cancelled.
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationId | uint256 | Identifier of the cancelled amortization. |
operator indexed | address | Address that performed the cancellation. |
AmortizationForceCancelled
event AmortizationForceCancelled(uint256 amortizationId, address indexed operator)
Emitted when an admin force-cancels an amortization, bypassing date guards.
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationId | uint256 | Identifier of the force-cancelled amortization. |
operator indexed | address | Address that performed the force-cancellation. |
AmortizationHoldAccountingMigrated
event AmortizationHoldAccountingMigrated(bytes32 indexed corporateActionId, uint256 indexed amortizationID, uint256 previousTotal, uint256 previousLabaf, uint256 total, uint256 labaf)
Emitted when the pre-fix hold-accounting state of an amortization corporate action is seeded by migrateAmortizationHoldAccounting.
Carries both the pre-migration stored values and the newly seeded ones so the migration is self-contained for audit purposes.
Parameters
| Name | Type | Description |
|---|---|---|
corporateActionId indexed | bytes32 | Unique identifier grouping related corporate actions. |
amortizationID indexed | uint256 | Identifier of the migrated amortization. |
| previousTotal | uint256 | The raw totalHoldByAmortizationId stored before migration. |
| previousLabaf | uint256 | The raw labafByAmortizationId stored before migration (always 0). |
| total | uint256 | The totalHoldByAmortizationId seeded by this migration. |
| labaf | uint256 | The labafByAmortizationId seeded by this migration. |
AmortizationHoldReleased
event AmortizationHoldReleased(bytes32 indexed corporateActionId, uint256 indexed amortizationID, address indexed tokenHolder, uint256 holdId)
Emitted when a hold is released for a token holder in an amortization.
Parameters
| Name | Type | Description |
|---|---|---|
corporateActionId indexed | bytes32 | Unique identifier grouping related corporate actions. |
amortizationID indexed | uint256 | Identifier of the amortization. |
tokenHolder indexed | address | Address of the token holder whose hold was released. |
| holdId | uint256 | ID of the released hold. |
AmortizationHoldSet
event AmortizationHoldSet(bytes32 indexed corporateActionId, uint256 indexed amortizationID, address indexed tokenHolder, uint256 holdId, uint256 tokenAmount)
Emitted when a hold is created or replaced for a token holder in an amortization.
Parameters
| Name | Type | Description |
|---|---|---|
corporateActionId indexed | bytes32 | Unique identifier grouping related corporate actions. |
amortizationID indexed | uint256 | Identifier of the amortization. |
tokenHolder indexed | address | Address of the token holder. |
| holdId | uint256 | ID of the newly created hold. |
| tokenAmount | uint256 | Amount of tokens locked in the hold. |
AmortizationInitialized
event AmortizationInitialized()
Emitted once when the amortization capability is initialised on a token.
Fires exclusively from initializeAmortization.
AmortizationSet
event AmortizationSet(bytes32 corporateActionId, uint256 amortizationId, address indexed operator, uint256 recordDate, uint256 executionDate)
Emitted when an amortization is created or updated for a security.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | Unique identifier grouping related corporate actions. |
| amortizationId | uint256 | Identifier of the created or updated amortization. |
operator indexed | address | Address that performed the operation. |
| recordDate | uint256 | Date at which token holder balances are snapshotted. |
| executionDate | uint256 | Date at which the amortization payment is executed. |
Errors
AmortizationAlreadyExecuted
error AmortizationAlreadyExecuted(bytes32 corporateActionId, uint256 amortizationId)
Amortization execution failed because the amortization has already been executed.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | The corporate action ID of the already-executed amortization. |
| amortizationId | uint256 | The amortization ID that was already executed. |
AmortizationCreationFailed
error AmortizationCreationFailed()
Amortization creation failed due to an internal failure.
AmortizationHasActiveHolds
error AmortizationHasActiveHolds(bytes32 corporateActionId, uint256 amortizationID)
Thrown when attempting to cancel an amortization that still has active holds.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | The corporate action ID of the amortization. |
| amortizationID | uint256 | The amortization ID that still has pending holds. |
AmortizationHoldAccountingAlreadyMigrated
error AmortizationHoldAccountingAlreadyMigrated(bytes32 corporateActionId, uint256 amortizationID)
Thrown by migrateAmortizationHoldAccounting when the target amortization's raw, non-defaulted labafByAmortizationId is already non-zero.
The migration is a one-time contingency, not a setter; a non-zero raw LABAF means the amortization was already migrated or has already gone through a regular sync.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | Unique identifier grouping related corporate actions. |
| amortizationID | uint256 | The amortization ID that was already migrated. |
AmortizationHoldFailed
error AmortizationHoldFailed(bytes32 corporateActionId, uint256 amortizationID)
Thrown when creating a hold for an amortization fails.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | The corporate action ID of the amortization. |
| amortizationID | uint256 | The amortization ID for which hold creation failed. |
AmortizationHoldNotActive
error AmortizationHoldNotActive(bytes32 corporateActionId, uint256 amortizationID, address tokenHolder)
Thrown when attempting to release a hold that is not active for the given holder.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | The corporate action ID of the amortization. |
| amortizationID | uint256 | The amortization ID. |
| tokenHolder | address | The address of the token holder with no active hold. |
AmortizationMigrationLabafAboveAbaf
error AmortizationMigrationLabafAboveAbaf(uint256 amortizationID, uint256 labaf, uint256 abaf)
Thrown by migrateAmortizationHoldAccounting when _labaf exceeds the current ABAF.
A _labaf above the current ABAF would truncate abaf / labaf to 0 on the next sync.
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationID | uint256 | The amortization ID being migrated. |
| labaf | uint256 | The invalid, out-of-range _labaf supplied by the caller. |
| abaf | uint256 | The current ABAF the supplied _labaf was compared against. |
AmortizationMigrationTotalAboveSupply
error AmortizationMigrationTotalAboveSupply(uint256 amortizationID, uint256 total, uint256 totalSupply)
Thrown by migrateAmortizationHoldAccounting when _total exceeds the token's current total supply.
_An unbounded _total would eventually overflow the checked total _= factor arithmetic on the next resync, permanently bricking amortization hold operations (including release) for that corporate action, since the migration is one-shot.*
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationID | uint256 | The amortization ID being migrated. |
| total | uint256 | The invalid, out-of-range _total supplied by the caller. |
| totalSupply | uint256 | The current total supply that _total was compared against. |
AmortizationNotActive
error AmortizationNotActive(bytes32 corporateActionId, uint256 amortizationID)
Thrown when attempting to operate on a cancelled amortization.
Parameters
| Name | Type | Description |
|---|---|---|
| corporateActionId | bytes32 | The corporate action ID of the amortization. |
| amortizationID | uint256 | The amortization ID. |
InvalidAmortizationHoldAmount
error InvalidAmortizationHoldAmount(uint256 amortizationID)
Thrown when attempting to set a hold with a zero token amount.
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationID | uint256 | The amortization ID. |
InvalidAmortizationMigrationLabaf
error InvalidAmortizationMigrationLabaf(uint256 amortizationID)
Thrown by migrateAmortizationHoldAccounting when _labaf is 0.
A zero _labaf would recreate the very "never held" ambiguity this migration exists to resolve, since the getter defaults a raw 0 to 1 via zeroToOne.
Parameters
| Name | Type | Description |
|---|---|---|
| amortizationID | uint256 | The amortization ID being migrated. |