# Coordinated distributions

Source: https://docs.settlemint.com/docs/api-reference/guides/coordinated-distribution
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](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions).

## Coordinated distributions across share classes [#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-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 [#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-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](https://docs.settlemint.com/docs/api-reference/guides/corporate-action-approval#approve-or-reject-a-partial-redemption)).

### Confirm, resume, and abort [#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 [#reclaim-and-release-a-classs-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 [#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.