> 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-voting.md). # Shareholder voting Running shareholder votes on-chain with the Governance contract, and the delays that protect changes to a company's configuration. Two separate processes decide things on Selcier. **Shareholder governance** is token holders voting on matters their share class lets them vote on, and it runs through the `Governance` contract. **Configuration governance** is the process for changing the contracts themselves, meaning rules, multipliers, upgrades and recoveries, and it is built around the `IssuerTimelock`. ## Running a vote ### What goes into a proposal Proposals are created by the company, in the [Console](/the-platform/issuer-console.md) or with `POST /v1/proposals`, using these fields. | Field | Contents | | --------------- | ------------------------------------------------------------------------------------------------------ | | `shareTokens` | The voting share classes, 8 at most | | `snapshotBlock` | The Robinhood Chain L2 block where voting power gets measured, which has to be in the past at creation | | `endsAt` | The closing time for voting | | `quorumBps` | The least participation accepted, measured against eligible voting power in basis points | | `options` | How many choices exist, 2 to 16, such as For, Against and Abstain | | `binding` | Whether the outcome binds or merely advises | | `documentHash` | The proposal document, as anchored | `ProposalCreated(proposalId, snapshotBlock, endsAt)` marks each new one. ### How voting power is calculated Power equals the holder's balance at the snapshot block times the multiplier of each share token, as read at proposal creation. Votes are therefore counted in shares and not in tokens. Snapshot blocks come from the ArbSys precompile as L2 block numbers, since `block.number` on Arbitrum chains follows L1 and advances far more slowly. The snapshot has two effects: tokens acquired afterward carry no votes, and moving shares between wallets cannot produce a second vote. Votes attach to shares whether or not those shares can be transferred, so frozen tokens, unvested tokens and tokens inside a holding period all count. Escrow is the exception: at the snapshot block, tokens in an open Liquidity Window order sit in the window contract's balance, so they bring no votes. ### Delegating a vote Voting power can pass to a second verified identity. A fund might do this with its investment committee. This can be done in Portfolio or on-chain through `delegate(delegatee)`. Delegation is checkpointed, which means each proposal judges it as of its own snapshot block. | Position at the snapshot | How the vote is cast | | ------------------------ | -------------------------------------------------------------------------------------------- | | Holder had no delegate | The holder calls `castVote` | | Holder had a delegate | The holder cannot vote directly on that proposal | | Acting as a delegate | `castVoteFor(proposalId, option, delegators)` covers those who had delegated at the snapshot | Whichever path applies, no holder's weight counts twice. ### From ballot to result Voting happens in [Portfolio](/the-platform/holder-portfolio.md) with sponsored gas, and every ballot emits `VoteCast(proposalId, voter, support, weight)`. After `endsAt`, finalizing is open to anyone. `ProposalFinalized(proposalId, result)` then gives the outcome, either the winning option's index or `255` (`NO_QUORUM`) where quorum fell short. The [Explorer](/the-platform/public-explorer.md) displays the totals, the weight per option and each `VoteCast` event, all of it public. Who stands behind a voting wallet is not shown. ### Binding or advisory Each proposal is marked one way or the other by the company, within what the share class terms permit. A binding result goes on record on-chain, and the company follows through using its normal controls, for instance by scheduling a multiplier change. An advisory result captures how holders feel. `Governance` does not execute anything itself in either case. ## Guarding configuration changes Rule changes and token upgrades pass through the `IssuerTimelock`, a timelocked multi-sig that always counts the company among its signers. Recoveries and multiplier changes are delayed by the share token itself, and only the timelock can alter those two delay settings. Selcier has no means of changing a company's configuration unilaterally. | Change | Lowest allowed delay | Delay by default | Who enforces it | | ---------------------------- | -------------------- | ---------------- | -------------------------- | | Wallet recovery | 48 hours | 72 hours | Share token | | New multiplier | 48 hours | 48 hours | Share token | | Rule module added or dropped | 24 hours | 24 hours | `IssuerTimelock` | | Upgrade of token logic | 7 days | 7 days | `IssuerTimelock` | | Pause or unpause | Immediate | Immediate | No one, it applies at once | Delays can go up at the company's choice, but none can drop below the minimum. From the moment an action is queued until it runs, it sits in public view on-chain, so holders can see what is coming. Only pausing skips the wait, because it must be usable in the middle of an incident. It halts transfers and moves no tokens. ## Permissions at a glance | Task | Who can do it | | ------------------------------ | --------------------------------------- | | Open a vote | `ISSUER_ADMIN` | | Cast a ballot | Holders | | Close out a finished vote | Anyone | | Suggest a configuration change | `ISSUER_ADMIN` | | Sign off a recovery | `ISSUER_ADMIN`, `REGISTRAR`, `OPERATOR` | | Halt a share token | `ISSUER_ADMIN`, `REGISTRAR` | A recovery requires any two of its three approving roles. [Access control](/under-the-hood/access-control.md) documents the complete permission model. {% hint style="info" %} The `OPERATOR` role belongs to Selcier and exists so that companies and holders can skip holding ETH for gas: it sends transactions for them. Casting votes, moving holder tokens and executing configuration changes on its own are all outside its powers. {% 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-voting.md?ask=&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.