Skip to main content

Coordinated distributions across share classes

Pay every share class of a multi-class instrument from one pool at one record date through the API, and settle the money and holders a class did not pay.

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.

Invalid input
Where checked
Refusal
poolAmount zero or negative
Create, preflight, quote, commit
400 REQUEST_INVALID (poolAmount: or terms.poolAmount:)
Invalid countryCode
Create, preflight, quote, commit
400 REQUEST_INVALID (countryCode: or terms.countryCode:)
denominationAsset mismatches waterfall asset
Create (400 REQUEST_INVALID), quote & commit once record date and class bindings pass (409 CORPORATE_ACTION_PROGRAM_MISSING)
Preflight does not read the waterfall
Dates out of order
Create, quote, preview, commit
400 CORPORATE_ACTION_DATES_OUT_OF_ORDER (DALP-12183)
claimDeadline already passed on chain
Quote, preview, confirm
409 CORPORATE_ACTION_CLAIM_DEADLINE_PASSED (DALP-12184)

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/v2/tokens/{assetId}/features/distribution-waterfall/distribution-netting with determinationKind (keccak-256 hash from priorityRows), role, and nets.

  • Locked once a distribution is funded under that row (409 DISTRIBUTION_WATERFALL_NETTING_LOCKED). Unknown rows or roles return 400 DISTRIBUTION_WATERFALL_UNKNOWN_PRIORITY_ROW or DISTRIBUTION_WATERFALL_UNKNOWN_CLASS_ROLE.
  • For waterfalls upgraded after prior distributions were funded, any account can call POST /api/v2/tokens/{assetId}/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_ACTION_SNAPSHOT_NOT_READY, DALP-12051) and requires denominationAsset to accept a transfer into the waterfall (DALP-14016 waterfall-cannot-receive). 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_QUEUE_FUNDING_REQUIRED (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/v2/tokens/{assetId}/features/distribution-waterfall/treasury-allowance (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 appliedSplit.fundingRequestId and each appliedSplit.legs[].requestId 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 appliedSplit.classDividendsOpen 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/{assetId}/features/dividend-yield/dividends/{dividendId}/reclaim (v2/token/reclaimDividend, passing the class token as assetId and featureAddress as a query parameter) after claimDeadline.
  • Release residual waterfall funds: POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/legs/{classToken}/release (v2/token/releaseCorporateActionLeg) returns remaining class funds in the waterfall to the funder once holders can no longer claim. Failed releases can be retried.

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:

Route (operation)
Role
Behaviour
GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements (v2/token/listUnpaidEntitlements)
governance or auditor
Paginates unpaid holders (page[limit] 1 to 200, default 50, and page[offset]) with classToken, holder, amount, reason (unclaimed or lost-identity), recordedAt, payment, reopens, and pendingClasses (closed classes still indexing).
POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements/{entryId}/paid (v2/token/markUnpaidEntitlementPaid)
governance
Records off-chain payment with paymentReference (sets paidAt, paidBy, reference). Refuses duplicate marks and never deletes entries.
POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements/{entryId}/reopen (v2/token/reopenUnpaidEntitlementPayment)
governance
Clears an erroneous mark using reason (1 to 500 chars) and matching paidAt, appending the cleared mark to reopens. Refusals: CORPORATE_ACTION_ENTRY_NOT_PAID and CORPORATE_ACTION_ENTRY_MARK_CHANGED.

Both write routes require wallet verification on session calls.