CouponSecurityHoldersFacet

Asset Tokenization Studio Team

CouponSecurityHoldersFacet

Diamond facet that exposes coupon security-holder queries via ICouponSecurityHolders, registered under RESOLVER_KEY_COUPON_SECURITY_HOLDERS.

*Consolidates holder-enumeration methods previously part of CouponFacet: getCouponHolders, getCouponsFor, getTotalCouponHolders. Must be registered alongside any Coupon*Facetvariant in all token configurations that include coupon functionality. Exposes 3 selectors and declaresICouponSecurityHolders as its interface ID.*

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

getStaticFunctionSelectors

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

Gets all function selectors of a facet

Returns

Name	Type	Description
_0	bytes4[]	Face functions selectors

getStaticInterfaceIds

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

Gets all interfaces ids of a facet.

Returns

Name	Type	Description
_0	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

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.

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.

CouponNotFound

error CouponNotFound(uint256 couponID)

Reverts when a coupon identifier does not resolve to an existing corporate action.

Parameters

Name	Type	Description
couponID	uint256	The coupon identifier that was not found.

DecimalsTooLarge

error DecimalsTooLarge(uint8 currentDecimals, uint8 newDecimals)

Reverts when the difference between current decimals and new decimals exceeds the maximum value.

Protects decimals amount difference between current and new not te be greater than maximum.

Parameters

Name	Type	Description
currentDecimals	uint8	the current decimals amount.
newDecimals	uint8	the new decimals amount.

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.

GreaterThanMaxUint256

error GreaterThanMaxUint256(uint256 amount, uint8 decimals)

Reverts when multiplying amount by 10 ** decimals would exceed uint256 max.

Thrown by DecimalsLib.calculateDecimalsAdjustment when amount > MAX_UINT256 / 10 ** decimals.

Parameters

Name	Type	Description
amount	uint256	The token amount that cannot be scaled up.
decimals	uint8	The exponent that causes the overflow.

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.

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.