Corporate actions
Record approved corporate event terms on an issued asset, preview the holder allocations, and confirm execution.
This workflow records the terms of an approved corporate actionA Corporate Action pays a coupon, a dividend, or a matured redemption straight to token holders, turning an issuer's announced terms into an on-chain payout.Read the concept against an issued asset, then runs the mechanism that applies it to holders. It does not decide what the event is, its economics, or who approves it; those decisions happen in your institution's own process, outside the Console, before you open this screen. What you decide here is narrower. You choose which approved event to record. You judge whether the computed preview matches what was approved. You decide whether to confirm or abort. A partial redemption adds one decision inside the Console: a second operator approves or rejects its previewed plan before anyone can confirm it.
The Console groups thirteen event types under "Manage Asset" as "Corporate actions", listed as fourteen entries because a stock split appears once per direction.
- Cash dividend
- Bond coupon
- Distribution
- Bonus issue
- Rights issue
- Decrease of capital
- Stock split
- Reverse split
- Spin-off
- Maturity redemption
- Partial redemption
- Conversion
- Buyback
- Coordinated distribution
Visibility and selectability depend on three independent checks.
The first check is what the asset carries: its attached features and its instrument capital. The asset type plays no part. A cash dividend needs dividend-yield attached; the menu names it "Cash dividend" on share capital and "Distribution" on any other asset, since both are the same payout. A bond coupon needs fixed-treasury-yield. A maturity redemption, a partial redemption, and a bond coupon paid in tokens need maturity-redemption. A conversion needs the conversion feature, so a SAFE or a warrant offers it. A bonus issue and a rights issue need share capital. A decrease of capital, a stock split, a spin-off, a buyback, and a stock dividend or distribution paid in tokens need share capital or unit capital. Shares carry share capital; fund units and real-estate fractions carry unit capital; a SAFE, a warrant, a bond, or a deposit carries neither. An event the asset cannot run is not listed.
The second check is your role. An event that passes the first check but exceeds your permission stays listed, greyed out, showing "You do not have the role required for this Corporate Action." That message names no specific role; check the list under Before you start, below.
The third check applies only to the seven types that change token supply.
- Bonus issue
- Rights issue
- Decrease of capital
- Stock split, in either direction
- Spin-off
- Partial redemption
- Buyback
These seven are blocked while the asset is paused, showing "The token is paused. Please unpause it to perform this action." A pause never blocks the other six: cash dividend, distribution, bond coupon, maturity redemption, conversion, and coordinated distribution. The three in-kind entries, "Stock dividend", "Bond coupon paid in tokens" and "Distribution paid in tokens", are the exception: they change supply, so a pause blocks them too.
The thirteen types take one of three shapes, and the shape decides what you see rather than the event's name.
A bond coupon, a maturity redemption, and a conversion are program links. Recording one completes the event and sends you to the program that already serves it, the yield tab, the maturity tab, or the conversion tab. Recording a maturity redemption also matures the bond on chain, so the record completes only when that transaction lands. It is refused before the maturity date and once the bond has already matured, and the redemption treasury must already hold the full payout. Holders then redeem their own tokens; nothing is paid to them automatically. No preview, confirm, or abort appears, because a holder claims against that program whenever they choose; there is no batch for the Console to push and nothing for a preview to compute.
A cash dividend and a distribution are declarations. Record stores the terms and already declares the dividend on chain. Preview then computes the holder allocations, and Confirm commits the reviewed snapshot. The two carry identical terms and differ only in the vehicle they run on.
A coordinated distribution is a declaration that pays every share class of a multi-class instrument from one pool, at one record date. It is listed only on the share class that carries both the distribution-waterfall and dividend-yield features. It asks for a pool amount instead of an amount per share, the three dates, and an optional issuer-event determination; the pool is paid in the class's dividend asset. A class that admits only holders with an investor classification, such as Professional investor, needs each holder to carry that verification before they can receive units of the class. Only an issuer your system trusts for that topic can add it, so the asset issuer needs that trust first: a user with the "Verification policy manager" role grants it in Platform settings > Compliance > Trusted issuers. Record stores the terms and declares nothing yet. Preview is available once the record date has passed on chain. It declares one dividend per class and, once each class's snapshot is ready, shows the split per class in the order the waterfall pays and every holder of every class with the amount they can claim. A class the pool does not reach shows as not reached. A second operator approves that plan. Before you confirm, the sheet shows the pool, your wallet's balance in the dividend asset, and how much your wallet lets the waterfall spend. When that approval is below the pool, select "Approve pool spending" and sign; when the balance is below the pool, send the missing amount to your wallet first. If the sheet cannot read your balance or approval, it still offers "Approve pool spending", which approves the whole pool. Confirm funds the instrument's waterfall once from the executing wallet and records each class's snapshot in rank order, which is when holders can claim. While the funding or a class record is still queued, the run stays open and offers "Confirm" again; select it after the transaction settles to finish the run. If the funding transaction fails, no money moves and the run goes back to approved, so select "Confirm" again to fund it. Aborting the run cancels its class dividends. A rejected plan or an expired approval also ends the run, but leaves its class dividends declared; open the run from "Corporate action history" and select "Cancel class dividends" to cancel them. See Coordinated distributions across share classes for the checks confirm runs and when abort is allowed.
A preview has nobody to pay until each class has holders, and the classes a "Dual-Class Share Structure" issuance creates refuse a mint until their compliance rules admit the recipient. The controlling class carries an identity allow list that starts empty unless you added identities during issuance, so every mint fails with "Compliance check failed" until the recipient's identity is on that list. Add the identity to the allow list the issuance installed rather than adding a second allow-list rule, because a mint must pass every installed rule. The economic class requires each recipient to hold a KYC claim and a "Professional Investor" claim from a trusted issuer. See Identity allow list and Claim expiry.
The seven supply-changing types are staged batch runs. They share one lifecycle: terms, draft, preview, confirm, then execution across the holder book, with abort available while it runs. A partial redemption adds a second operator's approval between preview and confirm.
"Stock dividend", "Bond coupon paid in tokens" and "Distribution paid in tokens" pay holders in new units of the asset instead of cash. A stock dividend is the in-kind form of a cash dividend on an equity. Each is a staged batch run: it asks for a numerator, a denominator, and an optional record date, mints the floored ratio amount to every holder, and takes the asset's in-flight slot. A stock dividend or a distribution paid in tokens needs no attached feature, only share or unit capital. A bond coupon paid in tokens needs the maturity-redemption feature. The platform has no step that takes minted units back, so it also waits for a second operator's approval between preview and confirm, the same way a partial redemption does. Leave the record date empty to count holders at the moment you preview.
Order is enforced by the interface, not by an error message. Confirm does not exist as an affordance until a preview has rendered, so you cannot reach it early and be refused. Preview is the route to confirm, which is also your only chance to compare the computed allocation against the approval before it reaches holders.
Confirm applies the reviewed allocation. For cash dividends and distributions, Record has already made an on-chain declaration; Confirm commits the dividend snapshot, and holders claim payment afterward. Once a supply change applies to a holder, that change stands. Abort stops further execution from being dispatched. Transactions already submitted can still settle, so check the reconciled holder results afterward. Holders already applied keep their change exactly as it stands; abort does not reach backward. Every sheet states "Abort cannot undo applied changes. There is no rollback." before you record, not only at the moment you abort. Read it as a property of the whole workflow, not a warning tied to one button.
Steps
Choose the event
Open "Manage Asset" and choose the event from its group; the Console lists the entries the asset can run, in the order shown above. An event missing from the list means the asset lacks the feature or the capital it needs. The token features catalog describes the features behind the events: dividend yield for a cash dividend or distribution, fixed treasury yield for a coupon, maturity redemption, conversion, and the distribution waterfall with dividend yield for a coordinated distribution. That check happens before your role is even considered, so a missing event is not something a different role would fix: attach the feature from the asset's Features tab, or issue the asset from a template that declares the capital.
An entry that appears but sits disabled says why on the entry itself, rather than leaving you to work it out. Each visible locked entry names a role restriction, a pause, or another composition already in flight, together with the required remedy. Where the reason is a run already in flight, the entry links straight to that run's progress instead of naming it and stopping there.
The sheet also opens with a readiness strip: whether the asset is paused, whether you hold the permission, whether another run is in flight, and how many holders are in the book. These are facts the page already knows. Indexer coverage for a past record date is not among them, because the platform only reports it when a preview runs, so it surfaces there instead.
Screen equivalent: the "Manage Asset" menu groups the supported event types, and the asset overview carries the event history table below it.
Enter terms and record the event
Complete every field the sheet shows with the approved terms; which fields appear depends on the event's shape, not one generic form.
Enter amounts in the display units named by the field. A dividend's amount per share uses the denomination asset's decimals; supply allocations use the issued token's units. The Console converts display amounts to base units. Do not convert the amount yourself. Doing so applies the decimal conversion twice and overstates the declaration by a factor of 10 raised to the applicable decimal count.
A cash dividend asks for an amount per share, a country code, and its three dates: ex-date, record date, and payment date. You enter all three. The Console rejects a set whose order is wrong rather than reordering it: the record date cannot come before the ex-date, and the payment date cannot come before the record date. Dates may fall on the same day. A cash dividend also asks whether it is a regular or a special dividend. A special dividend is a one-off distribution, and its dates may lie in the past as long as the token's historical balances cover the record date. The sheet shows the date after which unclaimed amounts can be reclaimed.
Withholding is applied off-platform. The platform computes no per-holder withholding, and the country code selects no withholding rate: it is stored on the declaration for reference only. Enter the amount per share net of any withholding the issuer applies off-platform, because every entitled holder is paid the amount exactly as declared.
A ratio event (bonus issue, stock split, spin-off, rights issue) asks for a numerator and a denominator. A rights issue takes one of exactly two paths, direct allotment or an existing token sale, and nothing else. A spin-off also requires a child token, chosen from the organisation's empty tokens; a candidate that already holds supply is listed with the reason it cannot be used. A direct-allotment rights issue and a spin-off also offer an optional record date. Leave it empty to count holders at the moment you preview. A set date can be previewed once it is reached. After the first minute, the token needs historical balances, and preview then counts the holders as they were at that date.
A decrease of capital, a partial redemption, and a buyback open a holder-book editor rather than a single address field. The three send the same announced holder list and share one editor. It seeds itself from the current holder book, so you select the holders the approval covers, prefill them pro rata from one declared total, then edit or exclude individual rows. Export the rows to CSV, edit them outside the Console, and import them back when the approval is easier to reconcile in a spreadsheet. The editor will not enable preview until the allocated amounts balance against the declared total.
A partial redemption can also pay cash for the burned units. Select "Add a cash payment" above the editor, choose the "Denomination asset" from the indexed tokens, and enter the "Price per token" paid for one whole redeemed token. The redeemed token cannot pay its own redemption. The "Paying treasury" is the active smart account, which pays every holder and must hold enough of the denomination asset before confirm. Without an active smart-account custody account the Console cannot add a cash payment, so choose one first. Leave the box clear for a burn with no cash.
A bond coupon, a maturity redemption, and a conversion need no extra fields beyond the standing notice that abort leaves applied holders in place with no rollback. Selecting the button both records the event and finishes it, then sends you to the program that serves it.
Select the button named for the event to record it. For the ten other types, preview and abort become available after recording. Recording a cash dividend or distribution also declares its obligation on chain. Abort does not remove that declaration. Confirm becomes available only after a preview has rendered and the required acknowledgements are complete.
Preview, then confirm execution
The preview renders in the sheet itself, not in the history table. It leads with the aggregate the approval is usually written against: the entitled holder count, the totals, and the remainder. The per-holder allocation table sits below it, paged, so a large holder book does not bury the summary. Preview calculates allocations without changing holder balances. A cash declaration already exists on chain after recording.
Two cases are called out rather than left for you to spot. A holder whose entitlement floors to zero is surfaced as a warning you have to acknowledge before you continue. A funding shortfall renders as a funded-against-declared comparison with its own acknowledgement; it never hard-blocks you, because proceeding underfunded is sometimes the approved decision. Where an earlier run under the same snapshot identity already applied to a holder, that holder is listed as excluded with the reuse as the stated reason, and the entitled count excludes them.
Fund the treasury with the required denomination asset before previewing again, unless the approval explicitly permits a shortfall. Each preview reads the treasury balance freshly, so a stale shortfall does not carry forward once you have topped up.
Select "Confirm" only when the preview matches the approval. For a cash dividend or distribution, Confirm sends the previewed Merkle root and totals. A supply-changing action confirms its stored allocation without those dividend-only fields. If confirmation finds snapshot drift in a staged supply run, the platform aborts that run. Review its final state and use a new or supported follow-up run with a fresh preview. A transfer after a fixed record date does not by itself change that historical snapshot.
A partial redemption shows no "Confirm" after preview. The sheet reads "Waiting for a second operator", and the record holds the asset's in-flight slot. A second operator opens the record from "Corporate action history" and reads the plan. For a redemption that pays cash, the "Cash leg" panel shows the denomination asset, the price per token, the paying treasury, and any funding shortfall. The second operator then selects "Approve" or "Reject". A rejection needs a reason, ends the action, and keeps the reason on the record. The platform refuses an approval while the previewed plan shows a funding shortfall, and it refuses any decision made more than 72 hours after the last preview; that record ends aborted. While the record waits, the operator who recorded it can select "Preview allocations" again, for example after funding the treasury, to refresh the plan without recording a new action. The new preview replaces the plan, clears any earlier decision, and restarts the decision window: 72 hours from that preview, or until the election deadline when that is later. The sheet's "Decide by" line shows when the window closes and moves forward with each preview. Other operators do not see that button, because whoever ran the last preview cannot then decide the record. After approval the sheet reads "Approved" and "Confirm" becomes available. If the plan changes before confirm, the platform clears the approval, so preview again and ask for a new one.
The sheet then stays open through execution. It shows live progress from the record: per-state counts, the transaction hashes that have landed, and a count of settled chunks. If no chunk settles for a while it says so, rather than leaving you to guess whether it stalled. Acceptance of the request is not settlement, so the sheet does not close on it; it closes when the record reaches a terminal status, and only after it has observed the change from non-terminal to terminal. Reopening an already settled record keeps its details visible.
Screen equivalent: the history row shows the preview's snapshot, remainder, funding shortfall, holder counts.
Recording an event is the fork point. Ten of the thirteen event types unlock Preview allocations, and Confirm appears only once a preview has rendered. The other three, bond coupon, maturity redemption, and conversion, complete the moment you record one, and no Preview, Confirm, or Abort button ever appears for them. Reopen an unfinished record from "Corporate action history" to continue it.
Troubleshooting
The event is not listed
The asset lacks the feature or the capital the event needs. Attach the feature from the asset's Features tab, or check the instrument capital its template declares, before changing permissions.
The event is listed but cannot be selected
The entry can be disabled by a permission, pause, or an in-flight composition. Follow the reason shown on the entry. If you see "You do not have the role required for this Corporate Action.", your role does not cover this event; check the role list under Before you start, above. If you see "The token is paused. Please unpause it to perform this action.", that only appears for the seven supply-changing types described above, and only while the asset is paused. Fix: request the required role, or confirm whether the approved intervention permits an unpause. Cash dividend, distribution, bond coupon, maturity redemption, and conversion never show the pause message; a pause does not block them.
No preview or confirm button appears after recording
Signal: the sheet closes right after you record, and no "Preview allocations", "Confirm", or "Abort" button ever showed. Cause: this is expected for a bond coupon, a maturity redemption, and a conversion; each completes the moment you record it, since each is a holder-initiated claim against a program the asset already exposes, not a Console-driven batch. Fix: nothing further to do in this workflow. Confirm the record landed by checking "Corporate action history".
Preview shows a funding shortfall
Signal: the "Funding shortfall" column in the preview snapshot is non-zero. Cause: the treasury does not hold enough of the denomination asset to cover the computed entitlement. Fix: transfer enough of the denomination asset to the configured treasury address, then select "Preview allocations" again. Do not select "Confirm" against a shortfall; each new preview reads the current treasury balance, so a stale shortfall does not carry forward once you have topped up.
Confirmation reports snapshot drift
A staged supply run is aborted when confirmation finds that the remaining snapshot allocations differ from the preview. Check the run's status and applied holders before starting a supported follow-up or a new run. Compare its fresh preview with the approved terms. Do not retry confirmation on an aborted record.
A run stops after some holders
Signal: the "Holders" column in history shows a nonzero remaining count and the status has not moved past "executing" for longer than expected. Cause: processing stopped partway, or an abort landed mid-run. This applies to the seven supply-changing types. Fix: reopen the row, which stays resumable until it completes or aborts, and compare the applied, skipped, and remaining counts against the approval before you decide to retry or abort. Open the skipped-holder list for the per-holder detail: each row carries the planned amount, the holder state, and the transaction that was attempted. No reason code is recorded, because the platform stores holder state rather than causes, so a skip the list does not explain has to be investigated outside the Console. A follow-up run under the original terms retries only the holders that did not apply. Abort leaves already-applied holders exactly as they are; it does not roll them back.
A run has stopped settling chunks
Signal: the sheet reports that no chunk has settled for a while. Cause: execution has gone quiet; the Console tells you rather than leaving a progress display that stops moving. Fix: inspect the pending transaction hashes and platform health while keeping the run record available. The notice alone does not establish whether execution is progressing. Request acceptance does not mean settlement. A stalled notice does not mean the run completed. Do not start another composition on this asset while one is in flight; the menu blocks overlapping runs.
Preview will not enable on a holder-book event
Signal: on a decrease of capital, a partial redemption, or a buyback, the holder-book editor is filled in but "Preview allocations" stays disabled. Cause: the allocated amounts do not balance against the declared total. The editor holds preview back until they do, rather than sending an unbalanced set to the platform. Fix: prefill pro rata from the declared total, or adjust the rows until the difference the editor shows reaches zero. Excluding a row removes its amount from the allocation, so an exclusion changes the balance too.
Frequently asked questions
Is a reverse split a different workflow from a stock split?
No. A reverse split is a stock split recorded with the ratio direction set to reverse instead of forward; both share the same numerator and denominator fields and the same event underneath, just with the direction flipped. The Console lists the two separately in the event menu so the direction you intend is unambiguous before you record it, but every later step treats them the same way.
What does the "First pass" caveat on every event sheet mean?
Every event sheet in this workflow carries the same caveat, marking scope this first release does not cover, regardless of which event type you are recording. If your approved event depends on any of those mechanics, confirm with your institution's process that this workflow still covers what was approved before you record it. The wording is exact: "First pass has no atomic rebase, market halt, rights instrument, capital-account ledger, or cash remainder."
Can I record a stock split or buyback while another one is already running on this asset?
No. Bonus issue, rights issue, decrease of capital, stock split in either direction, spin-off, partial redemption, buyback, a stock dividend, and a bond coupon or distribution paid in tokens share one in-flight slot per asset. Until one of them completes or aborts, including while it waits for approval, the others are disabled in the menu and say so, with a link to the run that holds the slot; the same block stops primitive mint and burn on that token. Maturity redemption, conversion, and a dividend, bond coupon or distribution paid in cash never hit this limit.
Does the platform withhold tax on a cash dividend or distribution?
No. Withholding is applied off-platform, so declare the net amount. The platform computes no per-holder withholding and keeps no gross-versus-net record: the amount per share you declare is the amount every entitled holder is paid. The country code on the declaration is recorded for reference and selects no withholding rate, so changing it changes no payout.
Can I edit an event's terms after I record it?
No. The Console exposes nothing to edit a stored record; there is no operation to change terms once a record exists. If the terms are wrong before you confirm, abort the record and create it again with the correct terms. If some holders already applied under the wrong terms, abort stops the remaining ones, but a fresh record does not automatically repair the applied changes. Review the applied holders and use a supported follow-up or a separately approved corrective action.
Yield & maturity
Operate the yield schedule and maturity redemption already configured on an issued asset, and fund the treasury that pays them.
Asset lifecycle
How an asset changes hands after issuance: a first sale at a fixed price, order book trading, multi-party settlement at agreed amounts, and governance votes.