Fixed Treasury Yield

Fixed Treasury Yield lets a DALP asset pay fixed-rate, period-based coupon payments from a denomination asset treasury. Snapshots from Historical Balances determine each holder's completed-period entitlement. Each holder pulls claimable amounts by calling claimYield().

The claims and identity model defines identity, claim topics, and trusted issuers. Fixed Treasury Yield does not decide investor eligibility. It calculates accrued amounts for balances that already exist on the asset.

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

Operating model

Fixed Treasury Yield is pull-based. DALP calculates what each holder can claim for completed periods, but the holder must submit the transaction. Make funding and allowance coverage visible to operators before you show a claim button.

Interface

The operator sets up the yield schedule when deploying. It covers the rate, start date, end date, interval, denomination asset, and treasury address. The platform emits FixedTreasuryYieldScheduleSet when the configuration is saved. Deploy a new schedule when a programme needs a different rate or period range.

The table below lists the runtime capabilities.

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

Business impact

Holders can claim completed-period yield in proportion to their balance at each interval snapshot. The issuer must keep enough denomination asset in the treasury throughout the yield period. The schedule fixes obligations by the configured rate, interval, and period range.

When the treasury is a wallet, the operator must approve enough denomination asset allowance before holders can claim. As the integrating developer, hide claim controls until the Platform API confirms the capability is attached, at least one interval has completed, and coverage reads show the treasury path is ready.

Distribution is pull-based. The yield contract calculates claimable amounts but does not push payments to holders automatically.

Risks and abuse cases

If the denomination asset balance falls below the total outstanding yield obligation, late claimants may find the treasury depleted. When the treasury is a wallet and the schedule has insufficient denomination asset allowance, holder claims can fail even when the balance covers the obligation. Contract treasuries do not use the wallet allowance approval flow; do not ask a contract treasury to submit the wallet approval step.

A single holder with a large share of supply can claim a large fraction of the funded treasury on first claim. Pull-based amounts that are never claimed remain in the treasury; operators should define an expiry or cleanup policy for long-running programmes. The rate can be configured prior to funding; off-chain monitoring should verify the balance at period start.

Controls and guardrails

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

Deployment input checks

DALP validates the feature deployment input before queuing the transactions. Supply these values in your request:

• denominationAsset and treasury must be non-zero EVM addresses.
• basisPerUnit must be greater than zero, fit within uint256, and the caller must submit it 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

Fixed Treasury Yield cannot calculate yield without Historical Balances checkpoints. Removing Historical Balances while yield is active causes claims to fail.

Deployment on configurable tokens uses two queued transactions: create the capability, then attach it to the token. If the create step returns an asynchronous approval response, DALP returns before queuing the attach step. Do not assume polling the create transaction triggers attachment. Keep holder claim controls hidden until a token read confirms the platform has attached the capability.

The indexer records the aggregate feature row at creation time and refreshes per-period values after the platform attaches the Historical Balances feature. During that short pending window, aggregate reads can exist before the indexer refreshes detailed period rows.

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 timing before queue submission. A call that is certain to fail returns a typed validation error instead of entering the queue.

DALP also checks the effective wallet against completed-period claim state and accrued yield before queue submission. DALP rejects claims 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 call because pre-closure completed periods may still be payable.

If DALP cannot read the schedule, latest indexed chain time, or holder balance views reliably, DALP lets the on-chain claimYield() execution decide. Incomplete off-chain data does not block the holder.

Yield calculated from past intervals remains claimable until the holder claims it. Your application must handle long-tailed claim windows in its UX.

When an operator calls setTreasury() mid-period, future claims draw from the updated address. Fund it before making the change.

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.

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 operator sets the yield schedule.
• FeaturesSet is emitted when the platform attaches the capability to a configurable token.
• YieldClaimed(holder, claimedAmount, fromPeriod, toPeriod, periodAmounts, periodYields, totalYieldPerPeriod) is emitted per claim and serves as the primary signal for treasury drawdown tracking.
• TreasuryUpdated(sender, oldTreasury, newTreasury) is emitted on treasury address update.
• InterestConsumed(holder, amountWad, reason, consumedAt) is emitted when the contract consumes accrued interest for a conversion calculation.
• AccrualClosed(holder, closedAt) is emitted when the contract permanently closes a holder's accrual after a full exit.
• Monitor the treasury denomination asset balance continuously against remaining yield obligations.
• For wallet treasuries, monitor allowance coverage by comparing denominationAssetTreasuryAllowance with requiredAllowance, or by reading allowanceCoveredPercentage from coverage queries.

Dependencies

Historical Balances is required for snapshot-based entitlement calculation. Register it before Fixed Treasury Yield when you enable both together. Keep your claim and monitoring controls hidden until token reads show the platform has attached Fixed Treasury Yield.

The denomination asset is the ERC-20 asset paid as yield, such as a stablecoin or another approved payment asset. The treasury is the address that funds claims. When the treasury is a wallet, it must approve the yield contract 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. Entitlement calculation uses checkpoints from Historical Balances instead of transfer hooks.
• It is compatible with Maturity Redemption. Yield can continue to accrue until maturity, and already claimable amounts survive post-maturity transfer restrictions.
• Historical Balances must be available for snapshot calculation. When the asset also uses rewriting features, order that dependency after those features so snapshots capture final post-rewrite balances.

Change impact

Yield accrual starts from the configured startDate when you enable the feature after launch. Past periods receive no coverage. When you disable mid-period, completed intervals remain claimable and future intervals stop accruing; treasury funds can be withdrawn under the programme's governance rules. After a treasury address update, future claims draw from the new address, so fund it before the switch takes effect. To adjust the rate, deploy a new yield schedule.

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
• Token lifecycle API operations - endpoint summary for deploying and operating token features
• Maturity Redemption - compatible lifecycle feature for bonds