Fixed Treasury Yield

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.

Use this page as the reference for the feature's public capabilities, dependencies, failure modes, and audit signals.

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:

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

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

• 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

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.

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

• FixedTreasuryYieldScheduleSet(startDate, endDate, rate, interval, periodEndTimestamps, denominationAsset, treasury) is emitted once when the yield schedule is configured.
• 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

• 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

• 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

• 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

• Token Features Catalog - return to the full feature catalog
• Historical Balances - required dependency
• Yield coverage statistics - API fields for treasury funding and allowance monitoring
• Maturity Redemption - compatible lifecycle feature for bonds