A coordinated distribution pays every share class of a multi-class instrument from one pool at one record date. It follows the create, preview, and confirm sequence in Corporate actions.
Coordinated distributions across share classes
Raise coordinatedDistribution on the class token carrying the distribution-waterfall feature. The waterfall splits the pool across classes by rank and contribution basis (sharing pro rata within the same rank). Tokens that are not part of a multi-class instrument or lack distribution-waterfall are refused.
Create and validation rules
Create accepts poolAmount (base units of the waterfall's payout asset), denominationAsset, ordered dates (exDate, recordDate, paymentDate, optional claimDeadline on or after paymentDate), optional ISO 3166-1 alpha-2 countryCode (normalised to uppercase, so GB works and UK is refused), and optional determinationKind (to apply an active issuer-event priority order). Create stores a drafted record and locks the instrument's payout slot against other cash dividends or distributions.
Create allows a poolAmount exceeding the wallet's balance because confirm checks funding.
Waterfall distribution netting
By default, priority rows subtract only returned capital from a class's contribution basis. To subtract all prior distributions instead, a governance wallet calls POST /api/ with determinationKind (keccak-256 hash from priorityRows), role, and nets.
- Locked once a distribution is funded under that row (
409 DISTRIBUTION_). Unknown rows or roles returnWATERFALL_ NETTING_ LOCKED 400 DISTRIBUTION_orWATERFALL_ UNKNOWN_ PRIORITY_ ROW DISTRIBUTION_.WATERFALL_ UNKNOWN_ CLASS_ ROLE - For waterfalls upgraded after prior distributions were funded, any account can call
POST /api/(v2/ tokens/ {asset Id}/ features/ distribution- waterfall/ allocation- sync maxDistributions) to fold earlier distributions into running totals.
Preview and approval
Preview requires the recordDate to have passed on chain (409 CORPORATE_, DALP-12051) and requires denominationAsset to accept a transfer into the waterfall (DALP-). If a waterfall's identity registration or compliance bypass was removed, governance calls ensurePoolReceiver on the factory (waterfalls deployed without an identity revert WaterfallHasNoIdentity and must be replaced).
Preview computes coordinatedSplit (ordinary and optional priority legs per class), declares one class dividend per funded class (cancelling any stale class dividends if the split moved), and waits for each class snapshot. Resend preview while snapshot-not-ready persists. If gas is insufficient, preview returns 400 TRANSACTION_ (DALP-14062) naming data.transactionId.
Once all snapshots complete, the record moves to previewed with every holder tagged by classToken, ready for second-operator approval (Approve or reject a plan).
Confirm, resume, and abort
Before confirming, approve the waterfall to spend at least poolAmount via POST /api/ (amount sets the full allowance). Confirm refuses execution if recordDate is unreached, claimDeadline passed, the waterfall split drifted, a class dividend or snapshot changed, another unrecorded dividend exists on a class, the transfer is blocked, or the caller lacks governance on any class.
Confirm funds the waterfall once and records each class snapshot in rank order, marking the action completed once every class is open for claims. While funding or class recording is queued (executing), read applied and each applied via the transaction status route or stream, then resend confirm to advance. Failed funding transactions return the record to approved so the next confirm retries funding.
Abort cancels all unrecorded class dividends, including on a record ended by rejection or expiry (check applied and appliedSplit.fundingSent). Abort is permitted after funding (leaving open classes claimable until their deadline) but refused while a class record or funding transaction is in flight.
Reclaim and release a class's money
Inspect appliedSplit.legs[] for each class's state (including releasing and released), dividend (feature address and dividendId), recovery (state, remaining, funder, claimDeadline), and distributionId:
- Reclaim unclaimed class dividend:
POST /api/(v2/ tokens/ {asset Id}/ features/ dividend- yield/ dividends/ {dividend Id}/ reclaim v2/token/reclaimDividend, passing the class token asassetIdandfeatureAddressas a query parameter) afterclaimDeadline. - Release residual waterfall funds:
POST /api/(v2/ tokens/ {asset Id}/ corporate- actions/ {corporate Action Id}/ legs/ {class Token}/ release v2/) returns remaining class funds in the waterfall to the funder once holders can no longer claim. Failed releases can be retried.token/ release Corporate Action Leg
Both routes require the class token's governance role and wallet verification on session calls.
Holders a class did not pay
Once a class closes (reclaimed, paid, or released), DALP records every unpaid entitlement for off-chain settlement:
Both write routes require wallet verification on session calls.