Maturity Redemption

Maturity Redemption implements the lifecycle for bond-type instruments. Before maturity, tokens transfer normally. After maturity, non-redemption transfers are blocked and holders redeem tokens for a denomination asset at the configured face value.

Use this reference when you need the feature capabilities, treasury readiness signals, and failure modes for post-maturity redemption.

---

Interface (capabilities)

Maturity Redemption implements a three-phase state machine: pre-maturity (normal transfers), mature (governance-triggered transition), and post-maturity (transfers blocked, redemption enabled).

---

Business impact

• Holders: Pre-maturity: normal transfer behavior. Post-maturity: transfers blocked; must call redeem(amount) to receive denomination asset at face value. Tokens are burned on redemption.
• Issuer: Must fund the configured treasury with sufficient denomination asset before or at maturity. For treasuries controlled by a wallet, the treasury also needs to approve the maturity-redemption feature to spend the denomination asset. Underfunded or under-approved treasuries block redemptions.
• Economics: State machine with three states: pre-maturity → mature (triggered by GOVERNANCE_ROLE) → post-maturity (redemption window). Token supply decreases as holders redeem.

---

Treasury allowance and status signals

Use GET /api/v2/tokens/{tokenAddress}/stats/bond-status before and after treasury operations to track maturity-redemption readiness. The response separates treasury balance coverage from allowance coverage:

• denominationAssetBalanceAvailable and denominationAssetBalanceRequired show how much denomination asset the treasury holds versus how much is required for redemption.
• coveredPercentage shows balance coverage. It does not prove the feature can pull funds from a wallet treasury.
• denominationAssetTreasuryAllowance shows the allowance the treasury has granted to the maturity-redemption feature on the denomination asset.
• allowanceCoveredPercentage shows how much of the required redemption volume is covered by that allowance.
• treasuryIsContract is true for contract treasuries, false for wallet treasuries, and null while classification is still catching up.
• treasuryAddress and featureAddress identify the configured treasury and maturity-redemption feature when one is attached.

For wallet treasuries, call POST /api/v2/tokens/{tokenAddress}/maturity-redemption/treasury-allowance from the treasury wallet to approve the feature to spend the denomination asset. The approve amount is submitted in base units. Contract treasuries cannot use this wallet-approval route; manage their denomination-asset approvals through the treasury contract's own controls.

Holders redeem matured tokens through POST /api/v2/tokens/{tokenAddress}/maturity-redemption/redemptions. The request takes the token amount to redeem. The API calculates the payout with the feature contract, checks wallet-treasury allowance before queuing the transaction, and returns the standard queued mutation response.

These status values are indexer-backed. A confirmed treasury top-up, treasury change, approval transaction, or redemption can briefly read as the previous value until indexing catches up. Treat treasuryIsContract: null as a wait-and-retry state rather than showing an approval or redemption action that may fail.

---

Risks & abuse cases

• Underfunded treasury at maturity: If the denomination asset treasury does not hold sufficient balance to cover all outstanding tokens at face value, redemptions will revert for holders who try to redeem when funds run out.
• mature() called too early: GOVERNANCE_ROLE can call mature() before the scheduled maturity date. Premature maturity blocks transfers unexpectedly. Use time-locked governance for mature() calls.
• Partial redemption cliff: Holders who do not redeem during the redemption window (if one is defined) may lose access. Define a clear redemption window and communicate it to holders.
• Treasury address change: setTreasury() can redirect redemption payouts. Audit all treasury address changes.

---

Controls & guardrails

---

Failure modes & edge cases

• Redemption revert on empty or unavailable treasury funds: If treasury is depleted, later redemptions revert. For wallet treasuries, redemptions can also revert when the denomination-asset allowance is below the amount the feature needs to pull. First redeemers get paid; last redeemers may not if treasury balance or allowance is insufficient.
• mature() not called at scheduled date: Maturity does not trigger automatically. An off-chain process must call mature() at the correct time. Missed maturity date means normal transfers continue past the intended date.
• Face value misconfiguration: Face value is set at deployment. A misconfigured face value cannot be changed post-deployment (immutable by design).

---

Auditability & operational signals

• Matured(maturityDate, denominationAsset, faceValue) — emitted when mature() is called.
• MaturedEarly(triggeredBy, timestamp) — emitted when matureEarly() is called.
• Redeemed(holder, tokenAmount, denominationAmount) — emitted per redemption. Monitor for redemption volume and treasury drawdown rate.
• Treasury balance and allowance monitoring: track denomination asset balance in treasury and, for wallet treasuries, the allowance granted to the maturity-redemption feature; alert when either side falls below the required redemption volume.

---

Dependencies

• Denomination asset (ERC-20) — the asset paid to holders on redemption (e.g., USDC, stablecoin). Must be deployed and accessible.
• Treasury (wallet or contract) — must hold sufficient denomination asset at maturity. Treasury address set via setTreasury(); wallet treasuries must also approve the maturity-redemption feature to spend the denomination asset.
• Off-chain process — must call mature() at the scheduled maturity date.

---

Compatibility & ordering notes

• supportsRewriting = false — does not modify amounts. Post-maturity transfer blocking is enforced via canUpdate() (reverts for all non-redemption transfers).
• Order first in the feature array (transfer restriction). Must run before fee features.
• Compatible with Fixed Treasury Yield: both can be active simultaneously for coupon-paying bonds. Yield is pull-based and independent of maturity state.
• Compliance modules run before features — compliance can block transfers pre-maturity; Maturity Redemption blocks post-maturity regardless.

---

Change impact

• Enable at deployment: Must be configured at deployment with face value and maturity parameters. Cannot be added post-deployment without these parameters.
• Disable before maturity: Can be removed without effect (no redemption has occurred).
• Disable after mature() is called: Transfer blocking ceases; holders can no longer redeem. Do not disable post-maturity without a redemption alternative.
• Treasury address change: Effective for all future redemptions. Existing redemption transactions in-flight complete at old treasury.

---

See also

• Token Features Catalog — return to the full feature catalog
• Fixed Treasury Yield — coupon payments compatible with maturity
• Compliance Modules — transfer enforcement layer