A governance vote puts a proposed change in front of a token's holders and records their weighted ballots on-chain. On a vote about a token you hold, you cast a ballot weighted by your activated voting power at the vote's record date. A vote that passes changes the token only when someone executes it, through a timelock, a contract that enforces a waiting period between approval and execution. Holders of the Governance role on the token create, queue, execute and cancel votes. Corporate Action explains how the changes a vote can carry, such as a new yield schedule or maturing the token, fit into a tokenised security's broader lifecycle.
A vote records a holder decision. It does not stop a role holder from changing the same parameter directly on the token's management screens, with no vote and no delay. Any holder of the Governance role on the token can cancel a vote while it is Pending or “Queued”, including one the holders approved. A holder of the System manager role can replace the governor and timelock code for every token at once, with no vote and no delay.
Ballot weight comes from voting power, a per-holder balance the vote reads as of its record date, a future moment the creator picks. A holder's own ballot carries weight only if their voting power is activated, and not delegated away, before that date. A holder who delegated away can delegate back to themselves at any time, but the change counts only for a vote whose record date falls after the delegation.
The votes list, with one row for each vote on an asset you hold.
Steps
Open the votes list
In the Console, open Wealth and select “Votes” in the sidebar. The page lists the votes on assets you hold, with a “Next action” column naming the step each vote is waiting on. When it is your turn to vote, the column holds a “Cast vote” button that opens the vote with the cast sheet, and the status dot is amber. When you had no voting power at the record date, the column says so. In the Investor portal, a vote that has not started yet says “Activate voting power” there while you have not activated voting power on its token. Opening a vote from any list lands on the same vote page, where you cast a ballot when you hold the token and manage the vote when you can.
Accounts that manage votes also see the tabs On my holdings, “All votes” and “Insights”, and the “Create vote” button in the page header. “All votes” lists every vote across tokens next to the polls. The “All votes” list shows each vote's title and mode, its status, “Voting deadline” and “Next action”. The token, the proposer and the creation date are columns you can switch on in the table's view options.
The token's Governance tab carries the same list scoped to that token, the “Delegate…” action under “Your delegate”, the “Attach voting power” control when the token has no voting power yet, and the voting-power distribution. Delegating needs no token role, the same rule as “Delegate voting power” in the asset's “Actions” menu: until your identity is registered, both are disabled, and the “Governance” tab links the reason to your identity steps.
Cast a ballot
A ballot cannot be changed once cast. Select the vote in the list, or Cast vote in its “Next action” column. While your account can act, the “Your eligibility” card says so. When your account cannot act, the card names the reason instead. The reasons are: voting not open yet, power delegated away, power not activated while the record date is still ahead, no voting power at the record date, a ballot already cast, or a vote already closed. For an account that holds none of the token and had no voting power at the record date, the card reads “You do not hold” followed by the token symbol and “, so you cannot vote on this proposal.” When you had no voting power at the record date, the card gives that date and says you can activate voting power to vote on future proposals. An account that manages votes and holds the token sees the card next to the manager controls.
Select Cast vote and choose For, Against, or Abstain on a Resolution, or one option on a Multi-option vote, with an optional reason. The reason is recorded with your ballot and appears beside your address in the vote's ballots table. Abstain counts towards quorum and never towards the approval threshold. The results update as more ballots arrive, and the token's votes list then shows “Ballot cast” as that vote's next action instead of “Cast vote”.
In the Investor portal, the sheet also checks the ballot with the platform once you choose. A refusal shows its reason in the sheet and Review stays off. The check does not submit or sign anything, and the platform checks again when you sign.
On a poll, which collects signed ballots off-chain and never queues or executes, a holder casts a poll ballot from Actions or with “Vote” on the poll's page. The ballot is a signed message, never a transaction. It names the poll, the network, the token, your address, the option you chose and a hash of the poll's definition. A self-custody wallet asks you to sign it, and a wallet the platform manages signs it through its custody signer. The platform stores the signed ballot off-chain and accepts one ballot per wallet. When none of your wallets held voting power at the poll's record date, the poll's page offers no “Vote” and says you cannot vote in this poll. Polls have their own table on the “All votes” tab. An account that manages votes, with the Governance role on the poll's token, ends a poll with “Close poll”. On an open poll, closing ends voting and recounts every ballot at the record-date balance. On a poll that has not opened yet, nobody has voted, so closing cancels it. A closed poll cannot be reopened.
Create a vote
Select Create vote in the header of the Votes page. The wizard has four steps. “Proposal” sets the token, the “Vote mode”, a title and description, and optional “Supporting documents”: up to 20 files of up to 25 MB each, in PDF, JPEG, PNG, WebP, Word or Excel format. Choose “Resolution” for a yes or no decision that can also carry executable changes, “Multi-option resolution” when holders pick between two or more named options, and “Poll” only for an off-chain signal that decides nothing on-chain. A token without the voting-power feature cannot receive a vote. The wizard offers “Attach voting power” in place when you hold the Governance role, and names the role to ask an administrator for when you do not.
The first step, “Proposal”, with the token, the “Vote mode”, a title and a description.
Ballot defines the named options for a Multi-option vote or a Poll, at least two. Each option must differ from the others, ignoring case and surrounding spaces: a repeated option is marked on its field, for example “Option 3 repeats Option 1”, and the wizard does not continue until you change it. For a Resolution vote it instead composes what the vote carries from a catalogue, such as a new supply cap or a revised fee rate. Leave the list empty for a plain resolution that decides without changing the token. “Set metadata” takes a key and a value in plain text, such as a fee rate written as you want holders to read it. The Console stores that text on the token, so you never encode it yourself. Tick “Lock this value so it cannot change later” to make the entry permanent once the vote executes. A vote cannot set a key that is already locked on the token, a key that the token keeps off chain, or a key that an earlier action in the same vote locks: the field says so under the key, and the step does not continue until you change it. Set an off-chain key from the token's Metadata tab instead. The step checks that the timelock already holds the authority those changes need and offers “Grant governance role to timelock” if not. Only a permission manager on the token can grant it, so ask one before you create the vote.
Rules and timing sets the record date, the voting period, quorum, the approval threshold and the execution delay. A governor is the on-chain contract that receives every vote for a token and enforces its rules.
- The record date must sit at least 24 hours and at most 90 days ahead, and voting power counts only as it stands at that moment, so a later record date gives holders more time to activate.
- The voting period is 1, 3, 7, 14 or 30 days, with 7 as the default.
- Quorum (%) is a percentage of the token's entire supply of voting units at the record date, where 100 equals that whole supply, and it starts at 5. Only activated voting power can vote, which is why the step shows the activated share and warns when the quorum you typed exceeds it. When the first vote for a token is created in the Console, its governor gets a 5% quorum floor, and the network then refuses every vote on that token below 5%, the first vote included. A first vote created through the Platform API can set a different floor. For a resolution or a multi-option resolution, a quorum below 5% or above 100% shows “Enter a quorum from 5% to 100%.” under the field once you leave it, and the step stays blocked until you correct it. The floor does not apply to a poll, which is counted off-chain. The sentence that says when the vote passes appears only while the quorum and the approval threshold are within range.
- Approval threshold (%) is the share of For plus Against that For must reach, so 100 there means unanimous agreement between the two, not the whole supply. A threshold of 0 keeps a simple majority, where For only has to beat Against. The approval threshold you set on the first vote for a token becomes that token's floor: a later vote can set a higher threshold, never a lower one. A holder of the Governance role can raise the floor with a direct call to the token's governor contract. The Console has no control for it. A Multi-option vote passes on quorum alone, so the threshold does not decide it, and the help under the field says so. On a token's first vote it still sets the floor.
- The execution delay is 1, 2, 7, 14 or 30 days, the waiting period holders get between approval and execution.
Review and sign shows every setting before you confirm and create the vote. Each action is listed with its settings in words, so a “Set metadata” action shows its key, its value as text and whether it is locked. Creating a vote for a token that has no governor yet deploys the governor and timelock pair first, then submits the vote. The review step says so when that applies.
When the network refuses the vote, the page names the condition that failed, such as a record date that is already past on the network's clock, and tells you what to change. The network's clock can differ from your computer's. “Back to review” returns you to the wizard with your settings kept, and “Details” shows the error code to quote to support.
Manage an existing vote
Actions on a vote's page holds three more controls, filtered by the vote's status, and each one opens a wallet-verification dialog before it runs. The menu appears for accounts that manage votes. “Cancel vote” also needs the Governance role on the vote's token for the wallet that signs, so it is hidden without it. Queueing cannot be undone and does not change the token. Only execution changes it.
Queueing schedules a Succeeded vote on the timelock. Select “Queue for execution”. The vote moves to “Queued” and its delay starts counting from that moment, using whichever is longer of the delay you set when creating the vote or the timelock's own minimum. The vote's details card shows the resulting “Earliest execution” moment.
Executing carries out everything a Queued vote holds, in one transaction, and it cannot be undone. Until the chain's clock reaches the “Earliest execution” moment, “Execute” is greyed out. Choosing it shows “Executable from” with that moment instead of a verification dialog. Select it once the delay has passed. If execution fails, the vote stays at “Queued”, so nothing partially applies. The Console decodes the revert reason when it can. When it cannot, usually because the node it queried has pruned older transaction history, it shows the raw value and states that history is unavailable. “Retry execution” and “Cancel vote” both stay available from that failure until a retry is submitted. An execute that reaches the timelock before the delay has passed fails with a message that the delay has not passed yet, and “Retry execution” stays hidden until the “Earliest execution” moment. A corrective change needs another authorised operation, which can be a new governance vote.
Cancelling closes a vote for good, and any holder of the Governance role on the token can do it, including someone other than its creator. Select Cancel vote on a “Pending” or a “Queued” vote. The confirmation states that cancelling cannot be undone. A vote that is “Active” or already “Succeeded” cannot be cancelled directly. Wait for it to close on its own, or, once it reaches “Queued”, cancel it there.
Vote statuses
Quorum is the minimum share of voting power that must take part for a vote to count. The Console shows one of seven statuses on every vote.
- Pending means the record date has not arrived and voting has not opened.
- Active means holders can cast ballots now.
- Succeeded means voting closed with quorum reached. For a Resolution vote it also means For finished ahead of Against and any configured approval threshold was met. A Multi-option vote succeeds on quorum alone, and its winning option is read from the tallies.
- Defeated means voting closed short of quorum or short of the threshold, and it is final: no queue or execute control ever appears on a Defeated vote again.
- Queued means a Succeeded vote is scheduled on the timelock, counting down its execution delay.
- Executed means the vote's changes were carried out, and it is closed for good.
- “Canceled” means a Pending or Queued vote was cancelled, and it is closed for good.
A Queued vote does not expire. It stays ready to execute until someone executes or cancels it.
A vote moves from Pending to Active, Succeeded, Queued and Executed, or ends as Defeated or Cancelled, and final states never change.
Troubleshooting
A vote is heading towards Defeated on quorum
The results panel shows quorum progress against the total voting power recorded at the record date. If turnout is short of that number as the deadline nears, the vote is on track to close as Defeated. Nothing you do after the record date changes who counts towards quorum. If you created the vote, the only way to make the same change again is a new vote with a later record date, so more holders can activate their voting power first.
A Resolution vote reaches quorum but still shows Defeated
Quorum counts every ballot cast, Abstain included. The approval threshold works differently: it weighs only For against Against, and Abstain never counts towards it. A vote can clear quorum and still fail because For did not beat Against, or because For fell short of the configured threshold share. Check the approval-threshold progress on the results panel, not only quorum, when a vote you expected to pass does not.
A Queued vote sits without executing
Nothing but an execute or a cancel moves a vote out of Queued. Check the “Earliest execution” moment on the details card. Before it arrives, “Execute” in “Actions” is greyed out, and choosing it shows “Executable from” with that moment. If you expected someone else to act after that moment, ask whoever holds the Governance role on that token.
Execute fails or shows an undecoded value
Whether or not the Console can decode the revert reason, the vote stays at Queued and nothing has partially applied. Correct whatever the reason names, if you can, and select “Retry execution”, or select Cancel vote instead if the vote should not run at all.
Cast vote is not available
The Your eligibility card names the reason: voting has not opened yet, power delegated away, power not activated while the record date is still ahead, no voting power at the record date, a ballot already cast, or a vote already closed.
Create vote is not visible, or creation is blocked
The “All votes” and “Insights” tabs and the Create vote control appear only for organisation owners and administrators, accounts with the “Asset manager” or “Permission manager” system role, and Governance role holders. A permission manager on the token can grant the Governance role. Creating a vote for a token then needs the Governance role on that token. A token without the voting-power feature needs it attached first, which needs the same role. A composed change the timelock cannot run also blocks creation, and granting that authority to the timelock is a call for a permission manager on the token, so ask one when the wizard reports the authority as missing.
Frequently asked questions
Does executing a plain resolution or a Multi-option vote change the token?
No. Only a Resolution vote that carries changes from the catalogue changes the token when it executes. A plain resolution with nothing composed, and every Multi-option vote, carries nothing executable: queueing and executing it completes the vote's lifecycle through the timelock and fixes the recorded outcome, but no token parameter moves. Acting on a multi-option result, or on a plain resolution, means an administrator applying the decision through the token's management screens, or a follow-up Resolution vote that carries the change.
Can a vote created outside the Console appear in the list?
Yes. A vote submitted directly to a token's governor still appears in the votes list and on its own detail page, marked with a Created externally badge. Its description is shown exactly as recorded on-chain, and it carries no Console-managed title, rich text, or document links. The same statuses, ballots, and manage controls apply to it as to a vote created in the wizard.
Does voting lock my tokens, or stop me from selling?
No. Casting a ballot locks no tokens. Your weight is your voting power as it stood at the record date, so a later sale or delegation does not change the weight of a vote whose record date has passed.
How do I export the ballots for an audit?
Open the vote from “All votes” and select Export CSV. The export carries the vote's summary: status, mode, the quorum and approval-threshold settings, and the required and recorded totals. A resolution's totals are For, Against, and Abstain. A multi-option vote lists each option with its number, its name, and its votes. Each ballot follows as a row with the voter address, their choice, the weight the ballot counted, the voter's weight at the record date, whether the voter's balance is frozen, their reason, when it was cast, and the name of the option it chose. On a multi-option vote the choice reads option, next to the option's number. The export button sits next to the “Actions” menu, so it needs the same access.
Does delegating voting power move my tokens?
No. Delegation assigns your voting weight to another address so the delegate can vote on your behalf. Your token balance does not move. The voting power feature keeps that weight, with its own checkpoints. Reclaim the weight at any time by delegating back to yourself, which removes it from the previous delegate.
What happens when two options tie on a Multi-option vote?
The results panel reports the leading option while voting runs and the winning option once it closes. On an equal top count it states that the leading options are tied instead of naming a winner. Because a Multi-option vote succeeds on quorum alone and carries nothing executable, a tie does not block anything on-chain: the vote still closes as Succeeded when quorum was met, and whoever acts on the result decides how to break the tie.
API routes
An equivalent create, cast, queue, execute, and cancel flow is available outside the Console. See the API explorer for the request and response shapes, or CLI commands for the command-line equivalent.