# Maturity Redemption

Source: https://docs.settlemint.com/docs/architects/architecture/components/token-features/maturity-redemption
How DALP handles bond maturity redemption: operator maturity actions, treasury funding and allowance readiness, indexed solvency signals, and holder redemption after maturity.



Maturity Redemption gives a bond-style token a controlled end state. Before maturity, holders can transfer tokens normally. At maturity, an authorised operator moves the token into its matured state. After that, ordinary transfers stop and holders redeem tokens for the denomination asset at the configured face value.

Architects and operators use this feature to make maturity explicit: the date alone does not end the instrument, and holders can only redeem once an authorised maturity action has moved the token into its redemption state. DALP enforces the token-state transition and records maturity and redemption events; the issuer still operates the cash, treasury, investor-notice, accounting, and legal-register processes around that token state. For a fixed-income creation walkthrough, see [Create a bond](/docs/operators/user-guides/asset-creation/create-bond).

<Mermaid
  chart="flowchart TD
    A[Bond active before maturity] --> B{Maturity date reached?}
    B -->|No| A
    B -->|Yes| C[Authorised operator calls mature]
    A -->|Emergency role| D[Operator calls matureEarly]
    C --> E[Post-maturity redemption state]
    D --> E
    E --> F[Ordinary transfers stop]
    E --> G[Holder redeems token amount]
    G --> H[Feature burns tokens and pays denomination asset from treasury]"
/>

## Lifecycle model [#lifecycle-model]

Maturity Redemption separates the bond date, the operator action, and the holder payout. The date defines when scheduled maturity is allowed. The operator action records that the bond has matured. The holder payout burns redeemed tokens and pays denomination asset from treasury.

| Phase            | What happens                                                                                                                | User impact                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Pre-maturity     | The token is active. Transfers follow the normal feature and compliance stack.                                              | Holders can transfer tokens when the rest of the asset configuration allows it.                    |
| Maturity trigger | An authorised operator calls `mature()` after the scheduled date, or an emergency operator calls `matureEarly()` before it. | The token enters the redemption state. This transition is irreversible.                            |
| Post-maturity    | The feature blocks ordinary transfers and enables holder redemption.                                                        | Holders use the redemption action to burn tokens and receive the denomination asset from treasury. |

Maturity does not fire by itself when the date arrives. An off-chain operator process or authorised user must trigger the transition. Until that happens, normal transfer behaviour continues.

## Interface capabilities [#interface-capabilities]

| Capability                     | Who can call                        | Inputs                         | Effect                                                           | Emits                                 | Notes                                                                                       |
| ------------------------------ | ----------------------------------- | ------------------------------ | ---------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
| Trigger maturity               | `GOVERNANCE_ROLE`                   | None                           | Transitions token to the matured state                           | `Matured`                             | Only after the configured maturity date                                                     |
| Trigger early maturity         | `EMERGENCY_ROLE`                    | None                           | Forces the matured state before the scheduled date               | `MaturedEarly`                        | Emergency path only                                                                         |
| Redeem tokens                  | Token holder with redeem permission | Amount to redeem               | Burns tokens and transfers denomination asset from treasury      | `Redeemed`                            | Only available after maturity                                                               |
| Approve treasury allowance     | Treasury wallet                     | Allowance amount in base units | Lets the feature spend denomination asset from a wallet treasury | ERC-20 `Approval`                     | Only the treasury wallet can approve                                                        |
| Set treasury address           | `GOVERNANCE_ROLE`                   | Treasury address               | Redirects future redemption payouts                              | `TreasuryUpdated`                     | Fund and verify the new treasury before holders redeem                                      |
| Block transfers after maturity | Automatic transfer hook             | Transfer attempt               | Reverts non-redemption transfers                                 | None, because the transaction reverts | Burns, mints, forced transfers, and feature-invoked updates can still pass through the hook |

## Operator responsibilities [#operator-responsibilities]

The issuer or operator must prepare four things before holders can redeem reliably:

1. The token must be moved into the matured state with `mature()` after the configured maturity date, or with `matureEarly()` through the emergency path.
2. The configured treasury must hold enough denomination asset to cover expected redemptions.
3. If the treasury is a wallet, that wallet must approve the maturity-redemption feature to spend the denomination asset.
4. The operator should check indexed balance, allowance, and treasury classification before announcing that redemption is available.

A wallet treasury and a contract treasury behave differently. A wallet treasury pays through ERC-20 `transferFrom`, so the feature needs allowance from the wallet. A contract treasury uses the treasury contract's own payout controls, so the wallet-approval route is not valid for it. The dapp hides the approval action unless the connected wallet is the configured wallet treasury and the bond-status response shows an allowance gap for a wallet treasury.

Only the configured treasury wallet can submit the allowance approval. Custodians, admins, and other token roles cannot approve on behalf of that wallet because ERC-20 allowance belongs to the account that owns the funds.

## API actions [#api-actions]

| Action                            | Route                                                                       | Who signs                      | Purpose                                                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Trigger scheduled maturity        | `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/maturations`        | Authorised governance operator | Move the token into post-maturity state after the configured maturity date.                                                     |
| Trigger early maturity            | `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/early-maturations`  | Authorised emergency operator  | Move the token into post-maturity state before the configured maturity date. Use only under the programme's incident procedure. |
| Set treasury                      | `PATCH /api/v2/tokens/{tokenAddress}/maturity-redemption/treasury`          | Authorised governance operator | Change the treasury address used for future redemption payouts.                                                                 |
| Top up treasury                   | `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/top-ups`            | Any funding wallet             | Transfer denomination asset from the caller's wallet into the configured treasury.                                              |
| Approve wallet-treasury allowance | `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/treasury-allowance` | Treasury wallet                | Approve the feature to pull denomination asset from a wallet treasury.                                                          |
| Redeem tokens                     | `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/redemptions`        | Token holder                   | Burn the holder's tokens and pay denomination asset at face value.                                                              |

Amounts are submitted in base units of the relevant token. For example, the redemption amount is the token amount to burn, and the allowance or top-up amount is the denomination-asset amount in its smallest unit.

## Treasury readiness signals [#treasury-readiness-signals]

Use `GET /api/v2/tokens/{tokenAddress}/stats/bond-status` before and after treasury operations. The response separates treasury balance, treasury allowance, treasury classification, feature address, and indexer readiness. This matters because a funded treasury can still fail wallet-treasury redemptions when allowance is missing, and a valid allowance does not mean the treasury has funds.

| Field                                | Meaning                                                                                               | Operator use                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `denominationAssetBalanceAvailable`  | Denomination asset balance held by the configured treasury                                            | Confirms whether the treasury has funds available for redemption         |
| `denominationAssetBalanceRequired`   | Denomination asset required to redeem the outstanding token supply at face value                      | Sets the target balance for full coverage                                |
| `coveredPercentage`                  | Balance coverage percentage                                                                           | Shows balance readiness only, not allowance readiness                    |
| `denominationAssetTreasuryAllowance` | ERC-20 allowance from treasury to the maturity-redemption feature                                     | Shows whether a wallet treasury has authorised the feature to pull funds |
| `allowanceCoveredPercentage`         | Allowance coverage percentage                                                                         | Shows whether allowance covers the required redemption volume            |
| `treasuryIsContract`                 | `true` for a contract treasury, `false` for a wallet treasury, `null` while classification is pending | Determines whether wallet allowance applies                              |
| `solvencyKnown`                      | Whether the indexer has computed the bond-status solvency row                                         | Distinguishes real zero balances from a temporary unknown state          |
| `treasuryAddress`                    | Current maturity-redemption treasury                                                                  | Identifies the payout source                                             |
| `featureAddress`                     | Maturity-redemption feature contract                                                                  | Identifies the spender for wallet allowance                              |

These values are indexer-backed. A confirmed top-up, treasury change, allowance approval, or redemption can briefly show the previous value while the indexer catches up. Treat `solvencyKnown: false` as "coverage is not known yet", not as an empty treasury. Treat `treasuryIsContract: null` as a wait-and-retry state. In both cases, the UI should avoid sending approval or redemption actions that the API already knows may fail.

## Holder redemption UX [#holder-redemption-ux]

A holder can see the redemption action when the connected wallet has a redeemable token balance and the wallet has the redeem action permission. Before maturity, the action remains visible but disabled with a maturity-specific reason. After maturity, it can still be disabled by treasury or token state:

| Condition                                | Holder-facing result                                                           |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| Token is not mature                      | Redemption stays unavailable until the maturity transition has been triggered. |
| `solvencyKnown` is `false`               | The UI shows that treasury verification is still in progress.                  |
| Wallet treasury allowance is zero        | The UI explains that treasury allowance is insufficient.                       |
| Treasury balance is unavailable or empty | The UI explains that treasury funds are missing.                               |
| Token is paused                          | Redemption is blocked by the paused token state.                               |

The redemption request is `POST /api/v2/tokens/{tokenAddress}/maturity-redemption/redemptions`. The request supplies the token amount to redeem. The API resolves the feature address, checks wallet-treasury allowance when the treasury is a wallet, queues the redemption transaction, and returns the standard queued mutation response.

If a wallet treasury has only partial allowance, the UI can still open the redemption flow. The API calculates the payout for the requested amount and rejects the request when the allowance is below that payout. This keeps partial coverage honest: a small redemption may fit while a larger one does not.

For a first-time holder, the sequence is: wait until the issuer has triggered maturity, confirm the redemption action is available for the connected wallet, enter the token amount to redeem, and submit the queued transaction. The payout depends on the configured face value and the denomination asset, not on market price.

## Failure modes and edge cases [#failure-modes-and-edge-cases]

| Failure mode                                   | What happens                                                                                                                                   | Recovery path                                                                                                                   |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Treasury balance is too low                    | Redemptions revert when the treasury cannot pay the requested payout. Early redeemers can be paid while later redeemers fail if funds run out. | Top up the treasury and wait for bond-status values to update.                                                                  |
| Wallet treasury allowance is too low           | The API rejects wallet-treasury redemptions when allowance is below the calculated payout.                                                     | The treasury wallet approves enough allowance for the expected redemption volume.                                               |
| Treasury classification is pending             | The approve and redeem routes reject the action until the indexer classifies the treasury.                                                     | Wait for indexing to catch up and retry.                                                                                        |
| `mature()` is not called at the scheduled date | The token remains in pre-maturity state and ordinary transfer behaviour continues.                                                             | Trigger maturity through the authorised operator process.                                                                       |
| `mature()` is called too early                 | The on-chain call reverts.                                                                                                                     | Use `matureEarly()` only through the emergency role and process.                                                                |
| Face value is wrong                            | Redemption economics use the configured face value.                                                                                            | Redeploy or provide an external remediation path. The feature does not change face value after deployment.                      |
| Treasury address changes                       | Redemption transactions use the treasury configured when the transaction executes, including transactions that were queued before the change.  | Pause redemption operations during treasury rotation, then verify funding, allowance, and classification before holders redeem. |

## Controls and guardrails [#controls-and-guardrails]

| Role              | Action                                               | Guardrail                                                                                                                      |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GOVERNANCE_ROLE` | `setTreasury()`                                      | Use multi-signature approval or equivalent governance, then verify funding and classification before holders redeem.           |
| Treasury wallet   | Approve denomination-asset allowance for the feature | Approve enough allowance for the expected redemption volume. Use base units and only sign from the configured treasury wallet. |
| `GOVERNANCE_ROLE` | `mature()`                                           | Trigger only when the configured maturity date has arrived. The chain rejects an early scheduled maturity call.                |
| `EMERGENCY_ROLE`  | `matureEarly()`                                      | Reserve for documented emergency procedures before the scheduled date. Once the scheduled date has arrived, use `mature()`.    |

## Auditability and operational signals [#auditability-and-operational-signals]

Maturity Redemption emits events when the token matures, matures early, redeems, or changes treasury. Use those events with the bond-status response to reconcile:

* `Matured(maturityDate, triggeredBy)` records the scheduled maturity transition.
* `MaturedEarly(originalMaturityDate, actualMaturityDate, triggeredBy)` records the emergency maturity transition.
* `Redeemed(holder, tokenAmount, payoutAmount)` records each redemption.
* `TreasuryUpdated(sender, oldTreasury, newTreasury)` records treasury changes.
* ERC-20 `Approval` events from the treasury to the feature feed the allowance value used by bond-status monitoring.

Monitor balance coverage and allowance coverage together. Balance without allowance can still block wallet-treasury redemptions. Allowance without balance does not create funds.

## Dependencies [#dependencies]

* Denomination asset: the ERC-20 asset paid to holders on redemption. It must be deployed and accessible on the same EVM network as the token.
* Treasury: a wallet or contract that holds denomination asset for redemption.
* Operator process: an authorised process or user that calls `mature()` at the scheduled time.
* Indexer: the bond-status response depends on indexed balance, allowance, treasury classification, and solvency state.

## Compatibility and ordering notes [#compatibility-and-ordering-notes]

* `supportsRewriting = false`: the feature does not rewrite transfer amounts.
* The feature must run before fee features because it enforces the post-maturity transfer restriction.
* Fixed Treasury Yield can be active on the same bond. Yield claims are pull-based and independent of the maturity state.
* Compliance modules can block transfers before maturity. Maturity Redemption blocks ordinary transfers after maturity regardless of compliance outcome.
* Forced recovery, forced transfer, mint, and burn flows have their own role controls. Treat post-maturity as a holder-redemption state, not a trading state.

## Change impact [#change-impact]

* Enable at deployment with face value and maturity parameters.
* Removing the feature before maturity removes the future redemption lifecycle.
* Removing the feature after maturity stops transfer blocking and removes the redemption path. Do not remove it after maturity without a replacement redemption process.
* Treasury changes affect future redemption calls.

## See also [#see-also]

* [Token features catalog](/docs/architects/architecture/components/token-features): return to the full feature catalog.
* [Fixed Treasury Yield](/docs/architects/architecture/components/token-features/fixed-treasury-yield): understand coupon payments that can coexist with maturity.
* [Compliance modules](/docs/compliance-security/security/compliance): understand the transfer enforcement layer before maturity.
* [Create a bond](/docs/operators/user-guides/asset-creation/create-bond): create a fixed-income asset that can include maturity-redemption behaviour.