# Fixed Treasury Yield

Source: https://docs.settlemint.com/docs/architecture/components/token-features/fixed-treasury-yield
Fixed-rate yield paid to token holders at periodic intervals from a treasury. Holders claim completed-period yield, and Historical Balances supplies the snapshot data used for entitlement calculation.



Identity, claim topics, and trusted issuers are defined in the [claims and identity model](/docs/architecture/concepts/claims-and-identity).

Fixed Treasury Yield calculates completed-period yield for DALPAsset holders from historical balance snapshots. A holder calls `claimYield()` to pull the available amount from the configured denomination asset treasury. Unclaimed yield stays in the treasury until claimed.

On configurable tokens, the app and API submit one operator action to create and attach this feature. The configuration sets the denomination asset, basis per token unit, treasury, start date, end date, rate, and interval. DALP queues feature deployment first. When that deployment settles during the request, DALP attaches the predicted feature address to the token so the feature appears in token feature reads after indexing catches up.

## Interface [#interface]

The yield schedule is configured when the feature is deployed. The configuration includes the rate, start date, end date, interval, denomination asset, and treasury address. The feature emits `FixedTreasuryYieldScheduleSet` when that schedule is set.

Runtime capabilities are:

| Capability                     | Who can call                   | Inputs                                     | On-chain effect                                      | Emits              | Notes                                                |
| ------------------------------ | ------------------------------ | ------------------------------------------ | ---------------------------------------------------- | ------------------ | ---------------------------------------------------- |
| Deploy and attach feature      | `GOVERNANCE_ROLE`              | Schedule configuration and treasury        | Creates the feature and attaches it to the token     | `FeaturesSet`      | Configurable tokens only                             |
| Claim accrued yield            | Token holder                   | None, claims all completed periods         | Transfers denomination asset from treasury to holder | `YieldClaimed`     | Pull-based. Unclaimed yield stays in treasury        |
| Set treasury address           | `GOVERNANCE_ROLE`              | Treasury address                           | Redirects future yield payouts                       | `TreasuryUpdated`  | Fund the new treasury before changing                |
| Approve treasury allowance     | Treasury wallet                | Allowance amount in base units             | Allows the yield schedule to spend payout assets     | ERC-20 `Approval`  | Wallet treasuries only                               |
| Consume interest on conversion | Automatic, on burn or redeem   | Principal amount and context               | Deducts accrued interest for conversion calculation  | `InterestConsumed` | Only active when paired with Conversion              |
| Close accrual on full exit     | Automatic, hook on burn/redeem | Triggered when holder balance reaches zero | Stops future yield accrual for holder                | `AccrualClosed`    | Pre-closure completed periods may still be claimable |

Accrued yield, the period schedule, the current period, and unclaimed totals are available as read-only queries.

## Business impact [#business-impact]

* **Holders:** Completed-period yield is claimable in proportion to the holder's balance at each interval snapshot.
* **Issuer:** The issuer must keep enough denomination asset in the treasury throughout the yield period. Yield obligations are fixed by the configured rate, interval, and period range.
* **Treasury wallet operator:** When the treasury is a wallet, the operator must approve enough denomination asset allowance for the yield schedule before holders claim yield.
* **Economics:** Distribution is pull-based. The contract calculates claimable yield, but it does not push payments to every holder automatically.

## Risks and abuse cases [#risks-and-abuse-cases]

* **Underfunded treasury:** If the treasury denomination asset balance falls below the total outstanding yield obligation, late claimants may find the treasury depleted.
* **Missing wallet allowance:** If the treasury is a wallet and the yield schedule has insufficient denomination asset allowance, holder claims can fail even when the treasury balance is funded.
* **Contract treasury path:** Contract treasuries do not use the wallet allowance approval flow. Integrations should not ask a contract treasury to submit the wallet approval step.
* **Large holding concentration:** A single holder with a large share of supply can claim a large fraction of the funded treasury on first claim.
* **Unclaimed yield accumulates:** Pull-based yield that is never claimed remains in the treasury. Operators should define an expiry or cleanup policy for long-running programmes.
* **Rate configured but not funded:** The yield rate can be set without the treasury being funded. Off-chain monitoring should verify treasury funding before the yield period begins.

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

| Role              | Actions                                                    | Recommended guardrail                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GOVERNANCE_ROLE` | `setTreasury()` to set the denomination asset treasury     | Fund the new treasury before future claims draw from the treasury                                                                                                              |
| Treasury wallet   | Approve denomination asset allowance for the yield feature | Before showing the approval action, read `denominationAssetTreasuryAllowance`, `requiredAllowance`, `allowanceCoveredPercentage`, and `treasuryIsContract` from yield coverage |

The rate is part of the configured yield schedule. If a programme needs a different rate, deploy a new yield configuration rather than treating the live schedule as a mutable payment instruction.

### Deployment input checks [#deployment-input-checks]

The feature deployment input is validated before DALP queues the transactions:

* `denominationAsset` and `treasury` must be non-zero EVM addresses.
* `basisPerUnit` must be greater than zero, fit within `uint256`, and be submitted in denomination asset base units.
* `rate` must be at least one basis point.
* `startDate` and `endDate` must be future timestamps, and `endDate` must be after `startDate`.
* `interval` must be one of the supported DALP time intervals.

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

* **Historical Balances not active:** Fixed Treasury Yield cannot calculate yield without Historical Balances checkpoints. If Historical Balances is removed while yield is active, yield claims can fail.
* **Feature not attached yet:** Feature deployment on configurable tokens uses two queued transactions: create the feature, then attach it to the token. If the create transaction returns an asynchronous approval response, DALP returns before the attach transaction is queued. Do not assume polling the create transaction attaches the feature. Keep holder claim actions hidden until a token feature read confirms the feature is attached.
* **Attachment timing:** The indexer records the aggregate feature row at creation time and refreshes per-period values after the Historical Balances feature is attached. During that short pending window, aggregate reads can exist before detailed period rows are refreshed.
* **First period not complete:** A holder cannot claim until at least one configured interval has elapsed from the schedule start date. When indexed schedule data is reliable, DALP checks schedule timing before queue submission. A claim that is certain to fail returns a typed validation error instead of entering the queue.
* **Holder has no claimable yield:** DALP also checks the effective wallet against completed-period claim state and accrued yield before queue submission. Claims are rejected when all completed periods are already claimed, the holder has zero claimable accrual, or consumed interest fully offsets the accrued amount. Closed accrual does not automatically reject a claim because pre-closure completed periods may still be payable.
* **Preflight is conservative:** If DALP cannot read the schedule, latest indexed chain time, or holder yield views reliably, DALP lets the on-chain `claimYield()` execution decide. Incomplete off-chain data does not block the holder.
* **Yield period ended but unclaimed:** Yield calculated from past intervals remains claimable until claimed. Platforms must handle long-tailed claim windows in their UX.
* **Treasury address change mid-period:** If `setTreasury()` is called mid-period, future claims draw from the new treasury. Ensure the new treasury is funded before changing.
* **Wallet treasury allowance not ready:** For wallet treasuries, claims require the yield schedule to have sufficient denomination asset allowance. Read `denominationAssetTreasuryAllowance`, `requiredAllowance`, `allowanceCoveredPercentage`, and `treasuryIsContract` from `GET /api/v2/tokens/{tokenAddress}/stats/yield-coverage` before prompting the treasury wallet to approve allowance. Prompt only when `treasuryIsContract` is `false` and either `denominationAssetTreasuryAllowance` is lower than `requiredAllowance` or `allowanceCoveredPercentage` is below full coverage. If `treasuryIsContract` is `true`, do not show the wallet approval flow. If `treasuryIsContract` is `null`, treasury classification is still catching up; do not trigger the wallet approval flow yet, and retry the coverage read later.
* **Zero-balance holder at snapshot:** Holders with zero balance at an interval snapshot receive zero yield for that interval regardless of balance at other times in the period.

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

* `FixedTreasuryYieldScheduleSet(startDate, endDate, rate, interval, periodEndTimestamps, denominationAsset, treasury)` is emitted once when the yield schedule is configured.
* `FeaturesSet` is emitted when the feature is attached to a configurable token.
* `YieldClaimed(holder, claimedAmount, fromPeriod, toPeriod, periodAmounts, periodYields, totalYieldPerPeriod)` is emitted per claim and is the primary signal for treasury drawdown tracking.
* `TreasuryUpdated(sender, oldTreasury, newTreasury)` is emitted on treasury address change.
* `InterestConsumed(holder, amountWad, reason, consumedAt)` is emitted when accrued interest is consumed for conversion calculation.
* `AccrualClosed(holder, closedAt)` is emitted when a holder's yield accrual is permanently closed after full exit.
* Treasury denomination asset balance should be monitored continuously against remaining yield obligations.
* Treasury allowance coverage should be monitored for wallet treasuries by comparing `denominationAssetTreasuryAllowance` with `requiredAllowance`, or by relying on `allowanceCoveredPercentage` from yield coverage reads.

## Dependencies [#dependencies]

* **Historical Balances feature:** required for snapshot-based entitlement calculation. Register Historical Balances before Fixed Treasury Yield when enabling both features together.
* **Denomination asset:** the ERC-20 asset paid as yield, such as a stablecoin or another approved payment asset.
* **Treasury:** the address that funds claims. If the treasury is a wallet, it must approve the yield schedule to spend the payout asset.

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

* `supportsRewriting = false`. The feature does not rewrite transfers.
* The feature does not restrict mint, burn, transfer, or redeem operations. Yield uses Historical Balances snapshots instead of transfer hooks.
* It is compatible with Maturity Redemption. Yield can continue to accrue until maturity, and post-maturity transfer restrictions do not invalidate already claimable yield.
* Historical Balances must be available for the yield feature to calculate holder and supply snapshots. When the asset also uses rewriting features, order Historical Balances after those features so snapshots capture final post-rewrite balances.

## Change impact [#change-impact]

* **Enable after launch:** Yield accrual starts from the configured `startDate`. Past periods are not retroactively covered.
* **Disable mid-period:** Existing claimable yield for completed intervals remains claimable, while future intervals stop accruing. Treasury funds can be withdrawn according to the programme's governance rules.
* **Treasury address change:** Future claims draw from the new treasury. Fund the new treasury before the change affects claims.
* **Rate change:** Deploy a new yield configuration for a different rate.

## See also [#see-also]

* [Token Features Catalog](/docs/architecture/components/token-features) - return to the full feature catalog
* [Historical Balances](/docs/architecture/components/token-features/historical-balances) - required dependency
* [Yield coverage statistics](/docs/developer-guides/api-integration/yield-coverage-statistics) - API fields for treasury funding and allowance monitoring
* [Token lifecycle API operations](/docs/developer-guides/api-integration/token-lifecycle) - endpoint summary for deploying and operating token features
* [Maturity Redemption](/docs/architecture/components/token-features/maturity-redemption) - compatible lifecycle feature for bonds