ICouponSecurityHolders
Asset Tokenization Studio Team
ICouponSecurityHolders
Interface for querying the set of security holders associated with a coupon.
Functions revert with WrongIndexForAction (via onlyMatchingActionType) when _couponID does not resolve to an existing coupon corporate action. Holder data is sourced from the snapshot taken at the coupon record date when available; otherwise the current token-holder enumeration is used.
Methods
getCouponHolders
function getCouponHolders(uint256 _couponID, uint256 _pageIndex, uint256 _pageLength) external view returns (address[] holders_)
Returns a paginated list of token holders eligible for a coupon.
Holders are resolved from the snapshot at the coupon record date when one exists; falls back to the live holder list if no snapshot has been taken. Returns an empty array if the record date has not yet been reached.
Parameters
| Name | Type | Description |
|---|---|---|
| _couponID | uint256 | Identifier of the target coupon (1-based index). |
| _pageIndex | uint256 | Zero-based page number for pagination. |
| _pageLength | uint256 | Maximum number of addresses to return per page. |
Returns
| Name | Type | Description |
|---|---|---|
| holders_ | address[] | Ordered array of holder addresses for the requested page. |
getCouponsFor
function getCouponsFor(uint256 _couponID, uint256 _pageIndex, uint256 _pageLength) external view returns (struct ICouponTypes.CouponFor[] couponFor_, address[] holders_)
Returns coupon information for every holder of a given coupon, paginated.
Internally resolves the holder page then retrieves per-holder coupon details. The two returned arrays share the same index: position i of the first corresponds to the same holder in the second.
Parameters
| Name | Type | Description |
|---|---|---|
| _couponID | uint256 | Identifier of the target coupon (1-based index). |
| _pageIndex | uint256 | Zero-based page number for pagination. |
| _pageLength | uint256 | Maximum number of records to return per page. |
Returns
| Name | Type | Description |
|---|---|---|
| couponFor_ | ICouponTypes.CouponFor[] | Per-holder coupon details for the requested page. |
| holders_ | address[] | Holder addresses corresponding to each entry in couponFor_. |
getTotalCouponHolders
function getTotalCouponHolders(uint256 _couponID) external view returns (uint256)
Returns the total number of security holders eligible for a coupon.
Count is taken from the snapshot at the coupon record date when one exists; falls back to the live total if no snapshot has been taken. Returns zero if the record date has not yet been reached.
Parameters
| Name | Type | Description |
|---|---|---|
| _couponID | uint256 | Identifier of the target coupon (1-based index). |
Returns
| Name | Type | Description |
|---|---|---|
| _0 | uint256 | Total number of eligible holders. |
initializeCouponSecurityHolders
function initializeCouponSecurityHolders() external nonpayable
Initialises the coupon security holders capability on the token.
Callable once; subsequent calls revert with FacetAlreadyRegistered. Requires DEFAULT_ADMIN_ROLE. Called by the factory during deployment.
Events
CouponSecurityHoldersInitialized
event CouponSecurityHoldersInitialized()
Emitted once when the coupon security holders capability is initialised on a token.
Fires exclusively from initializeCouponSecurityHolders.