Corporate actions catalog reference

The corporate actions catalog is one collection, /tokens/{assetId}/corporate-actions, that names thirteen lifecycle event types and applies each through one of four mechanisms. 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 directoryCopy Anchor Link

Nine 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 cashDividend and distribution store allocations for their linked dividend snapshot. Creating either record already declares the dividend on chain; Confirm later commits the reviewed snapshot. The seven composition types share the in-flight limit below. Both composition types and the yield-linked pair can store holder allocations; a bond coupon and a conversion complete on create, and a maturity redemption completes when its mature() transaction lands. 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 lifecycleCopy Anchor Link

A rejected or expired approval ends the record aborted; its approval.state reads denied or expired. See Approve or reject a partial redemption.

A completed dividend record does not mean every holder has claimed payment. A completed program-link record does not mean holders have claimed either; claims occur through the attached feature.

Snapshot drift aborts a staged supply run. 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 behavior.

In-flight limitCopy Anchor Link

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 (paymentKind: "inKind") is a composition for this limit. maturityRedemption, conversion, and a cashDividend, bondCoupon or distribution paid in cash never hit 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.

Holder stateCopy Anchor Link

The record's holders field is an array, empty before an allocation is stored. Each entry contains holder, amount, state, and an optional transactionHash.

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.

Derive counts from these states when presenting progress. Do not treat the array as an aggregate count object.

Stock split directionCopy Anchor Link

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 Stock split: chunked mint or burn, never an atomic rebase.

Scope this catalog does not coverCopy Anchor Link

The catalog has no atomic on-chain rebase, no market halt, no separate rights instrument, no capital-account ledger, and no cash remainder. 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 a buyback that declares one needs a second operator's approval before confirm. 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_ACTION_SNAPSHOT_DRIFT 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_ACTION_CALL_PROTECTED before that 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 stepsCopy Anchor Link

• Corporate actions for the create, preview, confirm, and abort sequence and the stock split pause caution.
• Corporate actions for the same catalog driven from the Console.