Coupon

Asset Tokenization Studio Team

Coupon

Abstract base of the unified coupon writer surface exposed by CouponFacet for every security rate variant (standard, fixed-rate, KPI-linked, SPT). Provides the shared coupon lifecycle (setCoupon, cancelCoupon) plus the per-record reads consumers need before executing a coupon.

Thin forwarder over CouponStorageWrapper; holds no storage of its own. Write paths are restricted to ROLE_CORPORATE_ACTION and gated by the unpaused state. Read paths are guarded by onlyMatchingActionType(CORPORATE_ACTION_TYPE_COUPON, _couponID - 1). The rate-variant invariants and rate resolution live in CouponStorageWrapper.setCoupon (write-path mirror of getCoupon's read-path dispatch via InterestRateStorageWrapper.is<Variant>Initialized()). Emits ICoupon.CouponSet / ICoupon.CouponCancelled inline after the underlying storage call returns, per the writer-abstract emit-site rule.

Methods

cancelCoupon

function cancelCoupon(uint256 _couponID) external nonpayable returns (bool success_)

Cancels a previously scheduled coupon before its execution date is reached.

Restricted to ROLE_CORPORATE_ACTION; gated by onlyUnpaused and onlyMatchingActionType(CORPORATE_ACTION_TYPE_COUPON, _couponID - 1).

Parameters

Name	Type	Description
_couponID	uint256	One-indexed identifier of the coupon to cancel.

Returns

Name	Type	Description
success_	bool	True if the cancellation was recorded.

forceCancelCoupon

function forceCancelCoupon(uint256 _couponID) external nonpayable returns (bool success_)

Force-cancels a coupon regardless of its execution date.

Restricted to ROLE_CORPORATE_ACTION_FORCE_CANCEL; gated by onlyUnpaused and onlyMatchingActionType(CORPORATE_ACTION_TYPE_COUPON, _couponID - 1).

Parameters

Name	Type	Description
_couponID	uint256	One-indexed identifier of the coupon to force-cancel.

Returns

Name	Type	Description
success_	bool	True if the force-cancellation was recorded.

getCoupon

function getCoupon(uint256 _couponID) external view returns (struct ICouponTypes.RegisteredCoupon registeredCoupon_, bool isDisabled_)

Returns the persisted coupon record together with its cancelled flag.

Reverts via onlyMatchingActionType if _couponID does not match the coupon corporate-action type at index _couponID - 1.

Parameters

Name	Type	Description
_couponID	uint256	One-indexed coupon identifier.

Returns

Name	Type	Description
registeredCoupon_	ICouponTypes.RegisteredCoupon	Stored coupon parameters bound to their snapshot id.
isDisabled_	bool	True if the coupon has been cancelled.

getCouponAmountFor

function getCouponAmountFor(uint256 _couponID, address _account) external view returns (struct ICouponTypes.CouponAmountFor couponAmountFor_)

Returns the fractional coupon amount payable to a specific holder.

Reverts via onlyMatchingActionType if _couponID does not match the coupon corporate-action type at index _couponID - 1.

Parameters

Name	Type	Description
_couponID	uint256	One-indexed coupon identifier.
_account	address	Holder address to query.

Returns

Name	Type	Description
couponAmountFor_	ICouponTypes.CouponAmountFor	Fractional payable amount for the holder.

getCouponCount

function getCouponCount() external view returns (uint256 couponCount_)

Returns the total number of coupons scheduled under the coupon corporate-action type — cancelled coupons remain in the count.

Returns

Name	Type	Description
couponCount_	uint256	Current coupon count.

getCouponFor

function getCouponFor(uint256 _couponID, address _account) external view returns (struct ICouponTypes.CouponFor couponFor_)

Returns the per-account view of a coupon, including the holder balance at the record date and the metadata required to compute the payable amount.

Reverts via onlyMatchingActionType if _couponID does not match the coupon corporate-action type at index _couponID - 1.

Parameters

Name	Type	Description
_couponID	uint256	One-indexed coupon identifier.
_account	address	Holder address to query.

Returns

Name	Type	Description
couponFor_	ICouponTypes.CouponFor	Holder-scoped coupon view.

initializeCoupon

function initializeCoupon() external nonpayable

Initialises the coupon capability on the token.

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

setCoupon

function setCoupon(ICouponTypes.Coupon _newCoupon) external nonpayable returns (uint256 couponID_)

Parameters

Name	Type	Description
_newCoupon	ICouponTypes.Coupon	undefined

Returns

Name	Type	Description
couponID_	uint256	undefined

Events

CouponCancelled

event CouponCancelled(uint256 indexed couponId, address indexed operator)

Emitted when an operator cancels a previously scheduled coupon.

Cancellation is rejected once the execution date has passed; see CouponAlreadyExecuted.

Parameters

Name	Type	Description
couponId indexed	uint256	One-indexed identifier of the cancelled coupon.
operator indexed	address	Address that performed the cancellation.

CouponForceCancelled

event CouponForceCancelled(uint256 indexed couponId, address indexed operator)

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

Parameters

Name	Type	Description
couponId indexed	uint256	One-indexed identifier of the force-cancelled coupon.
operator indexed	address	Address that performed the force-cancellation.

CouponInitialized

event CouponInitialized()

Emitted once when the coupon capability is initialised on a token.

Fires exclusively from initializeCoupon.

CouponSet

event CouponSet(bytes32 indexed corporateActionId, uint256 indexed couponId, address indexed operator, ICouponTypes.Coupon coupon)

Emitted when an operator schedules a new coupon corporate action.

Parameters

Name	Type	Description
corporateActionId indexed	bytes32	Identifier of the underlying corporate action.
couponId indexed	uint256	One-indexed coupon identifier within the coupon corporate action type.
operator indexed	address	Address that scheduled the coupon.
coupon	ICouponTypes.Coupon	The coupon parameters captured at scheduling time.

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.

CouponAlreadyExecuted

error CouponAlreadyExecuted(bytes32 corporateActionId, uint256 couponId)

Reverts when an operator attempts to cancel a coupon whose execution date has already passed.

Parameters

Name	Type	Description
corporateActionId	bytes32	Identifier of the underlying corporate action.
couponId	uint256	One-indexed identifier of the coupon that cannot be cancelled.

CouponCreationFailed

error CouponCreationFailed()

Reverts when the underlying corporate-action creation step returns the zero id, indicating the coupon could not be persisted.

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.

CouponRatePending

error CouponRatePending(uint256 couponID)

Reverts when at least one coupon is still awaiting rate resolution.

Raised by CouponStorageWrapper.checkPendingCoupons, used to guard InterestRate::setCouponRateType so a KPI-linked coupon cannot be left permanently unresolved by switching the rate type away before its scheduled listing has persisted a resolved rate.

Parameters

Name	Type	Description
couponID	uint256	One-indexed identifier of the first pending coupon found.

Deactivated

error Deactivated()

Thrown when an operation guarded by onlyActivated is attempted on a token whose deactivation flag has already been set.

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.

InterestRateIsFixed

error InterestRateIsFixed()

Thrown when setRate is called on a token whose rate has been locked.

InterestRateIsKpiLinked

error InterestRateIsKpiLinked()

Reverts when a KPI-linked rate variant is supplied with non-pending or non-zero rate parameters, which the variant requires for dynamic computation.

InterestRateIsStandard

error InterestRateIsStandard()

Reverts when a standard rate variant is supplied with pending rate parameters.

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

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.