Dividend yield

The dividend-yield token feature pays declared cash distributions to the holders of record on a fixed date. Use it for equity dividends, fund distributions, or any instrument that pays an amount that the issuer declares each time rather than a rate fixed in advance.

For the architecture reference, see Dividend yield.

When it attaches

No system template requires this feature today. To issue an asset with it, publish a custom template that lists dividend yield in its required features. The template must also list historical balances, which supplies the record-date entitlement data; the platform rejects a template that selects one without the other.

What you configure

In the Asset Designer details step, the wizard surfaces:

The amount and the dates are not creation-time settings. You supply them per dividend, after the asset is live.

What you operate

Each dividend runs through the same sequence.

1. Declare. Set the amount per token unit, the ex-date, the record date, the payment date, and the country code. The ex-date must be in the future, the record date after it, and the payment date after that. A claim deadline is optional; without one the platform applies the configured default.
2. Fund the treasury. A top-up transfers the denomination asset from your wallet to the treasury. When the treasury is a wallet, also approve the feature to spend the denomination asset, or every claim fails while the balance still looks correct.
3. Preview the snapshot. After the record date, ask for a snapshot preview. It reports the entitled holder count, the exact total required, the effective funding available right then, and any shortfall. For a wallet treasury that funding figure is the lower of the balance and the approved allowance, so approve before you read it. Close the shortfall before the next step.
4. Record the snapshot. Confirm the preview by repeating its root and totals. This freezes who is paid and how much. The platform rejects a confirmation whose values no longer match, so a stale preview can never be recorded.
5. Settle claims. From the payment date, each entitled holder claims their amount. The platform resolves the proof for them.
6. Close the dividend. After the claim deadline, reclaim the unclaimed value. The deadline alone closes nothing: a holder with a valid proof can still claim until the reclaim runs. The reclaim releases the liability and closes the dividend. No money moves, because the funds never left the treasury.

Servicing runs through the Platform API. See Dividend yield API for the endpoints behind each step.

Operating considerations

• The record date decides who is paid. A holder who sells after the record date and before the payment date keeps the entitlement. Say this clearly in holder communication.
• Cancel is the only repair for a wrong amount or a wrong date, and it works only before the snapshot is recorded. After recording, the amounts are fixed.
• The claim deadline can be extended once per dividend. Keep it for a known operational delay rather than routine use.
• Do not treat the deadline as a claim cut-off in your own tooling. Claims stay payable until governance reclaims, so run the reclaim when you intend the dividend to close.
• The issuer position read splits the outstanding total on the deadline. Keep the treasury funded against both parts, not just the still-claimable one, because a past-deadline entitlement stays payable until the reclaim runs.
• That read counts only what is payable now. A dividend that is recorded but has not reached its payment date has a fixed requirement and shows in neither part, so fund upcoming payment dates from the dividend list as well.
• A dividend can carry at most 16,384 entitled holders. A wider holder base needs a different distribution design.
• Declaring reserves an estimated liability based on the supply at that moment. Recording replaces it with the exact figure. Expect the two to differ when supply changes between the two dates.
• Unclaimed value stays with the issuer after the reclaim. Your accounting policy for stale entitlements is an off-chain decision the platform does not make for you.
• One attached feature carries many dividends over the life of the asset. Declarations do not interfere with each other, but they share one treasury.

Troubleshooting

Read next

• Dividend yield architecture
• Dividend yield API
• Historical balances, the required companion feature
• Interest yield, the continuous-accrual alternative