AmortizationFacet

Asset Tokenization Studio Team

AmortizationFacet

Diamond facet that exposes amortization schedule management to the proxy.

Selectors exposed: - initializeAmortization - setAmortization - cancelAmortization - forceCancelAmortization - getAmortization - getAmortizationFor - getAmortizationsFor - getAmortizationsCount - getAmortizationHolders - getTotalAmortizationHolders - setAmortizationHold - releaseAmortizationHold - getAmortizationActiveHolders - getTotalAmortizationActiveHolders - getActiveAmortizationIds - getTotalActiveAmortizationIds - getTotalHoldByAmortizationId - migrateAmortizationHoldAccounting - isAmortizationHoldAccountingMigrationPending

Methods

cancelAmortization

function cancelAmortization(uint256 _amortizationID) external nonpayable

Cancels an existing amortization.

Requires no active amortization holds for the specified corporate action.

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; gated by onlyUnpaused, onlyWithoutMultiPartition, and onlyMatchingActionType(CORPORATE_ACTION_TYPE_AMORTIZATION, _amortizationID - 1).

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_.

getStaticFunctionSelectors

function getStaticFunctionSelectors() external pure returns (bytes4[] staticFunctionSelectors_)

Gets all function selectors of a facet

Returns

Name	Type	Description
staticFunctionSelectors_	bytes4[]	Face functions selectors

getStaticInterfaceIds

function getStaticInterfaceIds() external pure returns (bytes4[] staticInterfaceIds_)

Gets all interfaces ids of a facet.

Returns

Name	Type	Description
staticInterfaceIds_	bytes4[]	Face interface ids

getStaticResolverKey

function getStaticResolverKey() external pure returns (bytes32 staticResolverKey_)

Gets the static resolver key

Returns

Name	Type	Description
staticResolverKey_	bytes32	Static resolver key

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.

Registers the amortization facet as ready and can only be executed once by an admin.

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; carries no onlyOperational, onlyActivated, or onlyUnpaused gate so it can repair state while the token is paused.

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.

Releases a holder-specific amortization hold for a valid amortization action.

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.

Creates or updates a positive holder-specific hold for a valid amortization action.

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.

Transfer

event Transfer(address indexed from, address indexed to, uint256 value)

Emitted whenever tokens move between accounts, are minted, or are burned.

Parameters

Name	Type	Description
from indexed	address	Source account (zero address on mint).
to indexed	address	Destination account (zero address on burn).
value	uint256	Amount of tokens transferred.

TransferByPartition

event TransferByPartition(bytes32 indexed fromPartition, address operator, address indexed from, address indexed to, uint256 value, bytes data, bytes operatorData)

Emitted when tokens are transferred from one partition to another or within the same partition.

Parameters

Name	Type	Description
fromPartition indexed	bytes32	Source partition.
operator	address	Address that initiated the transfer.
from indexed	address	Token holder whose balance decreased.
to indexed	address	Recipient whose balance increased.
value	uint256	Token quantity transferred.
data	bytes	Caller-supplied data.
operatorData	bytes	Operator-supplied data.

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.

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.

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.

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.

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.

InvalidPartition

error InvalidPartition(address account, bytes32 partition)

Thrown when an account does not hold or is not associated with the specified partition.

Parameters

Name	Type	Description
account	address	Address that was checked.
partition	bytes32	Partition that was not found for the account.

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).

NotAllowedInMultiPartitionMode

error NotAllowedInMultiPartitionMode()

Thrown when a single-partition operation is attempted on a multi-partition token.

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.