The corporate actions catalogue is one collection, /, that names thirteen lifecycle event types and applies each through one of four mechanisms: a chunked mint or burn against a holder snapshot, a declared dividend, a link to an attached program, or one pool split across share classes. Use this page to look up which mechanism a type uses and what a status or a holder-state value means. For the create, preview, confirm, and abort sequence itself, read Corporate actions. For request and response fields, use the v2 API explorer.
Type directory
Seven composition types share a computed or announced holder snapshot: bonusIssue, rightsIssue, capitalDecrease, stockSplit, spinOff, partialRedemption, and buyback orchestrate a chunked mint or burn against it, and they share the in-flight limit. A cashDividend or distribution paid in cash stores allocations for its linked dividend snapshot instead. Creating either record already declares the dividend on chain, and Confirm later commits the reviewed snapshot. A bond coupon paid in cash and a conversion complete on create, and a maturity redemption reads redemptionOpen when its mature() transaction lands, then completed once every holder has redeemed. coordinatedDistribution stores no holder allocations: it is raised on the share class that carries the distribution-waterfall feature and pays every class of the instrument, as Coordinated distributions across share classes describes.
Status lifecycle
The second operator's decision applies once the organisation turns on the corporate-actions row of its approval policy. Until then, or while no second operator can staff it, the record confirms without a decision and approval.waiver names the reason. Turning the row on, or adding an approver, puts a waived record back under the gate when it is confirmed, except a cashDividend or distribution paid in cash, which keeps its waiver. A rejected or expired approval ends the record aborted, through releasing when it marked custodial contracts, and its approval.state reads denied or expired. See Approve or reject a plan.
A completed dividend or program-link record does not mean holders have claimed. Holders claim through the attached feature.
Snapshot drift refuses confirm with CORPORATE_ (DALP-12056) and leaves the record open, so abort it before you raise another action on the token. A refusal before execution applies nothing. A rights-issue close refused during its burn keeps the shares it minted, so raise a follow-up with followsUpOn instead of a new close. A staged supply run whose batch reverts or stops after sending ends aborted. A batch the transaction queue never accepted is handed back, and the next confirm sends it again. An aborted run cannot resume or roll back applied holders. A follow-up composition can link to it with followsUpOn, so preview excludes holders already applied in the linked sequence. See Corporate actions for retry and reconciliation behaviour.
In-flight limit
A token accepts only one composition-type record in flight at a time. A record is in flight until it reaches completed or aborted, so a record waiting for approval holds the slot. The same limit blocks primitive mint and burn on that token while the record is in flight. A cashDividend, bondCoupon or distribution paid in kind (payment) is a composition for this limit. maturityRedemption, conversion, and a cashDividend, bondCoupon or distribution paid in cash do not count toward it.
A coordinatedDistribution has its own limit, across the instrument rather than the token: an instrument accepts one open coordinated distribution at a time. While it is open, no cash cashDividend or distribution can be created on any of the instrument's share classes, and it cannot be created while one of them is open. A completed or aborted run stays visible in the asset's in-flight strip while a class waits for reclaim or release, and leaves it once nothing waits. Each class on the record reports state (it adds releasing and released), dividend, and recovery, and the split reports distributionId. Reclaim and release a class's money describes the two routes that act on them. Once a class is reclaimed or released, the platform keeps a record of each holder that class owed and did not pay. Holders a class did not pay describes how to list that record and mark a holder paid off-chain.
Holder state
The record's holders field is an array, empty before an allocation is stored. Each entry contains holder, amount and state, and optionally transactionHash, direction (burn or mint), classToken, balance, residual and roundingAdjustment.
Composition amounts use token base units. Cash-dividend and distribution amounts use denomination-asset base units. For those two types, applied records commitment of the dividend snapshot, not the holder's later payment claim. The record has no separate per-holder skip-reason field. When a batch stopped before reaching some holders, snapshot.batchFailure carries the reason the transaction queue gave and the unreached holders.
Derive counts from these states when presenting progress. Do not treat the array as an aggregate count object.
Stock split direction
stockSplit takes a direction of forward or reverse. Forward mints floor(balance × numerator / denominator) − balance to each holder when that delta is positive. Reverse burns balance − floor(balance × numerator / denominator). Both directions apply through chunked mint or burn, never an atomic on-chain rebase, so the token must stay unpaused for the entire run: see How a stock split applies.
These formulas use the default fractionPolicy, floor, which drops the part of each result below one base unit of the token. A reverse split can set fractionPolicy to wholeShareFloor, which drops the part below one whole share, so a holder whose result is less than one share ends with none. roundUpToOne rounds the same way, but a holder whose result is more than zero and less than one share ends with exactly one share. If that holder held less than one whole share before the split, the platform mints the difference, so one reverse split run can burn from some holders and mint to others. A forward split refuses wholeShareFloor and roundUpToOne, because it only mints and cannot take back the part of a holding below one whole share.
Cash in lieu pays each holder for the part of the holding that a reverse split does not convert to a whole share. Send denominationAsset, pricePerUnit and payingTreasury together, with a fractionPolicy of wholeShareFloor or roundUpToOne. denominationAsset is the ERC-3643 token indexed in the platform that pays, such as a deposit token. pricePerUnit is the cash for one whole pre-split share, in base units of that token, and must be greater than zero. payingTreasury is the smart-account wallet that pays and the wallet the confirm runs from. Each unit of up to ten holders is burned and paid in one transaction, so a holder is burned and paid together or not at all. A holder's cash is the pre-split shares the split did not convert, times pricePerUnit, rounded down to one base unit of denominationAsset. A holder rounded up to one share is paid nothing, and so is a holder whose cash rounds down to zero.
Confirm is refused while the treasury holds less than the total cash. It is also refused when the confirm does not run from payingTreasury, when that wallet is not a smart wallet, when denominationAsset is the split token or is not an ERC-3643 token indexed in the platform, or when the token charges a burn fee. Every other ratio event, including a forward split, a bonus issue, a spin-off and a rights issue, pays no cash for a fraction: each result is rounded down and the remainder is dropped.
What the catalogue does not do
The catalogue has no atomic on-chain rebase, no instrument halt, and no capital-account ledger. The only cash it pays for a fraction is cash in lieu on a reverse split, as Stock split direction describes.
Tradable rights, cash legs and issuer calls
A rights issue with path: "tradable" mints rights into an existing rights token and names a payee, the account that receives every exercise payment and the exercised rights. The payee must be an account registered to the organisation's on-chain identity on the token's network, such as one of the organisation's executor wallets. It cannot be a member's wallet, another organisation's account, an unregistered account, an account on another network, or the wallet the rights issue is declared from. The payee is part of the approved plan, is checked again at every exercise, and an account that does not qualify or cannot receive them is refused with CORPORATE_. Holders trade the rights on the venue and exercise whole rights during the subscription period with POST /api/, paying the subscription price in the denomination asset. After the period ends, a rights issue with path: "close" mints one new share for every exercised right to the exercising holders and, once those shares have landed, burns every right, the exercised ones and the lapsed ones, in the same approved confirm. Its plan lists the rights it burns as snapshot.rightsBurn, and a second operator approves it before confirm when the organisation turns on the approval. A holder who exercised every right can also apply for excess shares with POST .../, paying into escrow with the organisation's operations signer. The close allots the lapsed rights to those applicants pro-rata to excess demand, rounded down to whole shares, mints the allotted shares with the exercised ones, and in the same confirm pays the payee for them and refunds the rest. Its plan lists each applicant in snapshot.rightsExcess. The Console close review shows the same list as an Excess applications table to the operator and the approver. See Apply for excess shares. A partial redemption may declare a cash leg: each unit of up to ten holders is paid on the denomination asset and burned in one smart-account transaction, so a holder is settled whole or left untouched, and a unit that fails ends the run aborted with the remaining holders still open for a second run. A cash leg needs a smart-account executor. A buyback takes the same cash leg, and every buyback, with or without one, needs a second operator's approval before confirm when the organisation turns on the approval. A buyback sent with call: "all" and no holders is an issuer call: preview reads the holder book and burns every holder's full balance, and the cash leg is required. Confirm is refused with CORPORATE_ if any holder's balance moved since preview, so the call always covers all holders and never some. When the token's metadata records a firstCallDate, confirm is refused with CORPORATE_ before that date. A longStopDate in the metadata opens the call on that date when it comes first, so every holder can be redeemed on the long-stop date whatever the first call date says. It counts only when the token recorded it as immutable at issuance, with the first call date. A long-stop date added later, or one that can still be edited, leaves the call protected until the first call date. A calendar date (YYYY-MM-DD) starts that day in UTC, and a value that is neither a calendar date nor a date and time with a UTC offset is refused the same way.
Next steps
- Corporate actions for the create, preview, confirm, and abort sequence and the stock split pause caution.
- Corporate actions in the Console for the same catalogue driven from screens.