Fixed Treasury Yield

Identity, claim topics, and trusted issuers are defined in the claims and identity model.

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

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.

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

• 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

• 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

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