Dividend Yield

Dividend Yield lets a DALP asset pay declared cash distributions to the holders of record on a fixed date. Governance declares an amount per token unit and a date set. After the record date passes, the platform computes the entitlement list, and the feature stores it as a Merkle root. Each entitled holder then claims the exact amount from the treasury in the denomination asset.

The claims and identity model defines identity, claim topics, and trusted issuers. Dividend Yield does not decide investor eligibility. It calculates entitlements for balances that already exist on the asset. Identity is applied twice, at two different moments: a holder whose identity is already lost when the platform computes the record-date entitlement set is left out of that set entirely, and a holder who is in the set but whose identity is no longer verified at claim time has the claim refused. The first case cannot be repaired by later reverification, because the entitlement set is frozen once it is recorded.

On configurable tokens, the app and API submit one operator request to create and attach this capability. The setup specifies the denomination asset, the treasury, and the default claim deadline in days after the payment date. 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.

Each dividend is a separate declaration on the same feature. One attached feature can carry many dividends over the life of the asset.

Operating model

A dividend moves through six states: declared, ex-date active, recorded, payable, paid, and cancelled. The feature derives the ex-date active and payable states from the block timestamp, so no operator call is needed to advance them.

Distribution is pull-based. The feature calculates what each holder of record can claim, but the holder must submit the claim transaction.

Interface

Governance declares each dividend with an amount per token unit, an ex-date, a record date, a payment date, a claim deadline, and a two-character country code. The contract also stores a dividend type code, but the Platform API does not expose it and always declares type 0. The platform emits DividendDeclared with the identifier assigned to that dividend.

Recording the snapshot is a two-step operation on the Platform API. The first call previews the result: it returns the Merkle root, the entitled holder count, the total entitlement, the total required funding, the effective funding available at preview time, and any shortfall. The funding figure is a live read, not a record-date one. For a wallet treasury it is the lower of the treasury balance and the allowance approved to the feature, so an unapproved allowance shows up as a shortfall even when the balance covers the dividend. The second call repeats the root and the totals to confirm them. DALP rejects the confirmation when the echoed values do not match the computed result, so a stale preview can never be recorded.

The table below lists the runtime capabilities.

The dividend list, the state of each dividend, the total outstanding liability, the claim proof of the caller, and the holder position are available as read-only queries.

Business impact

The issuer keeps the money. The feature never holds the denomination asset. Every claim pays straight from the configured treasury, so the treasury balance is the funding position for every open dividend.

Declaration reserves an expected liability that uses the total supply at that moment. Recording the snapshot replaces that estimate with the exact total required for the entitled holders. The difference between the two figures is the accounting effect of supply changes between declaration and the record date.

The record date fixes who is paid. A holder who sells after the record date and before the payment date keeps the entitlement. As the integrating developer, present that to holders clearly, because it is a common source of support questions.

Risks and abuse cases

If the treasury denomination balance falls below the total required funding, late claimants find the treasury short. The snapshot preview reports the effective funding available at preview time and the shortfall, so fund the treasury before you confirm the snapshot rather than after the payment date.

When the treasury is a wallet, the feature pulls the payout with an ERC-20 transfer from that wallet. The treasury must approve enough allowance for the feature, or every claim fails while the balance still looks correct. A treasury that implements the vault payout interface uses its own payout path and needs no wallet approval.

A vault treasury moves the access decision into the treasury contract. The feature calls the vault's payout function and the vault decides who may make it call. A custom implementation that does not restrict the caller to the configured yield feature can be drained by anyone who calls it directly, and a funded balance is no evidence that it is safe. The DALPAsset token itself implements the payout interface and rejects any caller that is not a feature registered on it; prefer it, or review the caller check of a custom vault before you enable claims.

The entitlement set is fixed at the record date and cannot be corrected afterwards. A wrong amount per unit or a wrong date set is repaired only by cancelling before the snapshot is recorded. After the snapshot, the only remaining controls are the single deadline extension and the reclaim.

A dividend can be recorded for at most 16,384 entitled holders. A wider holder base cannot be recorded and needs a different distribution design.

Unclaimed value stays with the issuer. Reclaim closes the liability but moves no money, so the accounting policy for stale entitlements is an off-chain decision that your operations process must state.

Controls and guardrails

Deployment input checks

DALP validates the addresses in the feature deployment input before queuing the transactions. The remaining rules below belong to the contract: on token creation the platform applies them too, but a later attachment queues the request and fails at deployment instead. Supply these values in your request:

• denominationAsset must be a non-zero EVM address.
• treasury must be a non-zero EVM address. When the request omits it, DALP uses the requesting wallet.
• defaultClaimDeadlineDays must be greater than zero. It sets the deadline applied to a declaration that does not carry an explicit one.
• Historical Balances must be part of the same feature set. Attachment fails when the token has no historical balances provider.

Declaration adds a second set of checks on chain:

• The amount per token unit must be greater than zero.
• The ex-date must be in the future.
• The record date must be after the ex-date, and the payment date after the record date.
• The claim deadline must not be earlier than the payment date.

Failure modes and edge cases

Dividend Yield cannot compute an entitlement set without Historical Balances. Attachment fails when no provider is available, and removing Historical Balances while dividends are open breaks the snapshot step.

The snapshot cannot be recorded before the record date, and the platform cannot compute it before the record-date block reaches finality. Until then the preview reports that it is waiting for finality and returns no root. A confirmation submitted in that window is rejected instead of queued.

A declaration that is not yet readable in the Ledger Index cannot be previewed. The Platform API returns a retryable error rather than computing against incomplete data, so retry the preview rather than treating it as a failure.

A claim fails when the dividend is cancelled or closed, or when the payment date has not passed. It also fails when the proof does not match the recorded root, when that leaf is already claimed, or when the identity of the claimant is no longer verified. A holder already marked as a lost identity when the platform computes the entitlement set never gets a leaf, so there is no proof to present. A holder who is in the set but loses verification before claiming has the claim refused at that point. The two checks are separate, and only the second one is repaired by reverifying before the claim.

The claim deadline does not close claims by itself. Passing it only lets governance reclaim, and a valid proof is still payable until that reclaim runs. Do not block a claim in your application because the deadline has passed; the dividend is closed by the reclaim, and only then do the remaining entitlements stop being claimable. Show the deadline to holders well before it passes, because the reclaim can follow at any time after it.

Cancellation is only possible before the snapshot is recorded. After recording, a cancel call is rejected.

The claim tracker records both the leaf and the amount, so a repeated claim on the same leaf is rejected even when the amount differs.

Auditability and operational signals

• DividendDeclared(dividendId, amountPerShare, exDate, recordDate, paymentDate, claimDeadline, divType, country) is emitted for each declaration and carries the full date set.
• DividendRecorded(dividendId, merkleRoot, totalEntitled, totalRequired, tracker) is emitted when the entitlement set is frozen. totalRequired is the exact funding obligation for that dividend.
• DividendClaimed(holder, dividendId, amount) is emitted per claim and is the primary signal for treasury drawdown tracking.
• DividendCancelled(dividendId) is emitted when a declaration is withdrawn before recording.
• DividendReclaimed(dividendId, amount, treasury) is emitted when governance closes a dividend after the claim deadline. The amount is the released liability, not a transfer.
• ClaimDeadlineExtended(dividendId, oldDeadline, newDeadline) is emitted on the single permitted extension.
• FeatureAttached(token, schedule) is emitted when the platform attaches the capability and resolves the historical balances provider.
• Monitor the total outstanding liability against the treasury denomination balance. The issuer statistics query reports what is payable now, split on whether the claim deadline has passed. Fund against the total of both parts, because the deadline moves an entitlement into the reclaimable side without making it unpayable. Add the recorded dividends whose payment date has not arrived: their funding requirement is already fixed and the query does not count them yet.
• The holder position query is a claim history: it totals what a holder has claimed across every dividend. The per-dividend proof query reports the recorded entitlement and its proof, unchanged by claims or reclaims. No read tells you whether one holder has claimed one dividend, so plan your application around that: an entitlement is not evidence that it is still claimable, and the contract is what rejects a spent claim.

Dependencies

Historical Balances is required. The entitlement set is computed from balances at the record-date block, so register Historical Balances in the same feature set. Attachment fails without it.

The denomination asset is the ERC-20 asset paid as the dividend, such as a stablecoin or another approved payment asset. The treasury is the address that funds every claim. When the treasury is a wallet, it must approve the feature to spend the payout asset. When the treasury implements the vault payout interface, the feature calls that interface instead. The payout mode is resolved once when the feature is configured.

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.
• Order Historical Balances after any rewriting feature so that record-date snapshots capture final post-rewrite balances.
• It is compatible with Maturity Redemption. A recorded dividend stays claimable after maturity restrictions apply to transfers.
• It can run beside Fixed Treasury Yield or Interest Yield on the same asset. The features keep separate liabilities, so plan the treasury funding for the total of all of them.

Change impact

Attaching the feature after launch has no retroactive effect. The first dividend you can pay is the first one you declare, and its record date must be in the future.

Changing the amount per unit or any date of a live dividend is not possible. Cancel before the snapshot is recorded and declare again.

The default claim deadline in days applies to new declarations that do not carry an explicit deadline. It does not move the deadline of a dividend that is already declared.

The treasury address is fixed for the feature at configuration time. Plan the funding path before you attach the feature.

See also

• Token Features Catalog - return to the full feature catalog and the yield comparison
• Historical Balances - required dependency
• Fixed Treasury Yield - rate-based alternative for periodic coupons
• Interest Yield - continuous accrual alternative
• Token lifecycle API operations - endpoint summary for deploying and operating token features