# Maturity Redemption

Source: https://docs.settlemint.com/docs/architecture/components/token-features/maturity-redemption
Bond maturity lifecycle feature for DALPAsset. Manages the pre-maturity, mature, and post-maturity states. Post-maturity transfers are blocked; holders redeem tokens for a denomination asset at face value.



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

| Capability                    | Who can call      | Inputs                              | On-chain effect                                          | Emits             | Notes                                  |
| ----------------------------- | ----------------- | ----------------------------------- | -------------------------------------------------------- | ----------------- | -------------------------------------- |
| Trigger maturity              | `GOVERNANCE_ROLE` | None                                | Transitions token to matured state                       | `Matured`         | Only after maturity date; irreversible |
| Trigger early maturity        | `EMERGENCY_ROLE`  | None                                | Forces matured state before scheduled date               | `MaturedEarly`    | Emergency use only                     |
| Redeem tokens                 | Token holder      | Amount to redeem                    | Burns tokens; transfers denomination asset from treasury | `Redeemed`        | Only available post-maturity           |
| Approve treasury allowance    | Treasury wallet   | Allowance amount in base units      | Lets the feature spend denomination asset from treasury  | ERC-20 `Approval` | Wallet treasuries only                 |
| Set treasury address          | `GOVERNANCE_ROLE` | Treasury address                    | Redirects redemption payouts                             | `TreasuryUpdated` | Fund treasury before maturity          |
| Block transfers post-maturity | Automatic (hook)  | Triggered on every transfer attempt | Reverts non-redemption transfers                         | None (reverts)    | Fail-closed via `canUpdate`            |

***

## Business impact [#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 [#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 [#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 [#controls--guardrails]

| Role              | Actions                                                   | Recommended guardrail                                                             |
| ----------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `GOVERNANCE_ROLE` | `setTreasury()` — set denomination asset treasury address | Multi-sig; audit all changes; fund treasury before calling `mature()`             |
| Treasury wallet   | approve denomination-asset allowance for the feature      | Approve enough allowance for the expected redemption volume before holders redeem |
| `GOVERNANCE_ROLE` | `mature()` — transition to post-maturity state            | Time-lock or multi-sig to prevent premature maturity                              |
| `EMERGENCY_ROLE`  | `matureEarly()` — emergency early maturity trigger        | Emergency use only; requires documented justification                             |

***

## Failure modes & edge cases [#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 [#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 [#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 [#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 [#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 [#see-also]

* [Token Features Catalog](/docs/architecture/components/token-features) — return to the full feature catalog
* [Fixed Treasury Yield](/docs/architecture/components/token-features/fixed-treasury-yield) — coupon payments compatible with maturity
* [Compliance Modules](/docs/architecture/security/compliance) — transfer enforcement layer