> For the complete documentation index, see [llms.txt](https://docs.selcier.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.selcier.xyz/fundamentals/shareholder-events.md).

# Shareholder events

What each shareholder event looks like on-chain, from stock splits to company exits, and where the multiplier, the DistributionVault and the registrar come in.

On Selcier, a corporate action is a transaction. A contract schedules or carries it out, events record it for anyone to read, and a document anchored in the `DisclosureRegistry` stands behind it. Four kinds are described here: splits, distributions (dividends among them), conversions between share classes, and exits.

## Splits, forward and reverse

The ERC-8056 multiplier does this work. `uiMultiplier()` on a share token reports how many shares one token represents, scaled by `1e18`. Moving that number revalues every balance in shares while the raw balances stay exactly as they were.

| Event                 | What 1,000 tokens then equal | Multiplier movement |
| --------------------- | ---------------------------- | ------------------- |
| No change             | 1,000 shares                 | Stays at `1e18`     |
| 2-for-1 split         | 2,000 shares                 | `1e18` to `2e18`    |
| 1-for-4 reverse split | 500 shares                   | `2e18` to `0.5e18`  |

Nothing that holds tokens is disturbed, because no raw balance moves, and that protects pool reserves and open orders as much as lots and vesting schedules.

### Steps in a split

1. In the [Console](/the-platform/issuer-console.md), the company proposes the multiplier and attaches the board resolution, whose hash gets anchored with `DocumentAnchored`.
2. The change is scheduled on the share token with `scheduleMultiplier`, and the token itself enforces a 48-hour delay, a setting that only the `IssuerTimelock` can alter. `MultiplierScheduled(newMultiplier, effectiveAt)` is emitted.
3. A company that pauses the token around `effectiveAt` also stops the `ValuationOracle` from taking new values. Its last value stands until the unpause.
4. From `effectiveAt`, `uiMultiplier()` returns the new figure. Anyone can then call `applyMultiplier` to finalize it, and that call is what emits `UIMultiplierUpdated(oldMultiplier, newMultiplier)`.
5. An adjusted Reference Valuation goes out and the oracle resumes.

Anyone turning a token balance into a share count should read `uiMultiplier()` every time. [Supporting Selcier tokens](/build-on-selcier/supporting-selcier-tokens.md) covers this for integrators.

## Paying holders: dividends and distributions

The `DistributionVault` handles all cash going back to holders, be it a dividend, a special distribution or sale proceeds.

1. **Fund.** The company deposits USDG or any other ERC-20 and names a **record block** that has already passed. The number is an L2 block on Robinhood Chain, as reported by the ArbSys precompile. As many as 20 accounts can be left out, treasury shares and the `LiquidityWindow` escrow being typical. `DistributionFunded(distributionId, asset, amount, recordBlock)` records the deposit.
2. **Calculate.** A holder's portion is their record-block balance divided by the eligible supply, and the eligible supply is total supply less the excluded balances.
3. **Claim.** A holder calls `claim(distributionId)`, or Portfolio uses `claimFor` to do so for them, paying the holder with sponsored gas. `DistributionClaimed(distributionId, holder, amount)` accompanies every claim.

This is a pull model. The company never pushes a payment to each wallet: holders collect what they are owed, so cost stays low and the audit trail stays complete at any holder count.

| If you are wondering                                       | The short answer                                                                                                                                                        |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Are frozen tokens paid?                                    | They are, since a freeze stops transfers and leaves entitlements alone.                                                                                                 |
| Does an expired identity claim cost a holder their payout? | No. The entitlement stands, and the vault runs no identity check when it pays. A distribution paid in a share token still has to pass that token's own transfer checks. |
| What becomes of amounts nobody claims?                     | They stay available. A company may set a claim deadline no sooner than 12 months out, and what remains after it goes back to the treasury.                              |
| Must payment be in cash?                                   | No. Any ERC-20 placed in the vault works, another share token included.                                                                                                 |

[Send a payout to holders](/walkthroughs/send-a-payout.md) has the full procedure.

## Moving between classes: conversions

Certain events shift holders from one share class into another, as when preferred becomes common. The `REGISTRAR` carries this out in a single transaction as a burn on one share token and a mint on the other, using the ratio in the class terms.

* For each holder, the source token emits `SharesRedeemed(from, amount, ref)`.
* For each holder, the destination token emits `SharesIssued(to, amount, ref)`.
* A shared `ref` links the two events, which lets anyone follow a conversion across classes.

In the destination class the shares appear as fresh lots dated at the mint. Any holding period there therefore runs from the conversion, not from the original acquisition.

## Leaving the private market: exits

### Going public

A listing turns tokenized shares into the listed security. The company has two paths. Tokens can become conventional shares at the listing venue, or the public shares can stay inside a tokenized program. Either way, the conversion leaves `SharesRedeemed` events that point to the conversion record.

### Being acquired

Purchase consideration reaches holders through the `DistributionVault`. It is deposited as a distribution tied to a record block. Once holders have claimed, the registrar burns the tokens. All of it, funding through final burn, can be followed on-chain.

## Comparing the actions

| Action                 | Main events                                  | Effect on the token                     | Waiting period                                   |
| ---------------------- | -------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
| Split or reverse split | `MultiplierScheduled`, `UIMultiplierUpdated` | Oracle only                             | 48 hours                                         |
| Dividend               | `DistributionFunded`, `DistributionClaimed`  | Stays live                              | None, with the company choosing the record block |
| Conversion             | `SharesRedeemed`, `SharesIssued`             | Paused throughout, as a rule            | Company's choice                                 |
| Payout on acquisition  | `DistributionFunded`, `SharesRedeemed`       | Paused once the record block is reached | Company's choice                                 |

{% hint style="info" %}
An anchored document sits behind each of these actions. To test one, find its hash through the event in the [Explorer](/the-platform/public-explorer.md), then match that hash against the version the company shares in Portfolio.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.selcier.xyz/fundamentals/shareholder-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.