Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Creating a Poll

This guide walks you through creating a poll from start to finish. Follow the steps in order — most setup mistakes come from two fields that are easy to mix up (block heights and the snapshot height) and from skipping the dust transaction settings. Each of those has a callout so you don't miss it.

Before you start, know these two numbers. Ballot uses two different blockchains, and they have very different block heights. You can see both in the top bar of the app at all times:

If you ever type a 7-digit number into a Bitcoin field, or a 6-digit number into the Snapshot field, you've mixed them up. Keep this table handy.

Chain
Symbol in the top bar
Typical size today
Used for

Bitcoin

₿ (e.g. 184,915)

~6 digits

Voting window — Start & End block

Stacks

the Stacks (STX) logo (e.g. 4,015,914)

~7 digits

Snapshot height (token balances)

What you'll need

  • A Stacks wallet (e.g. Leather or Xverse) connected to Ballot.

  • A little STX to pay the transaction fee when you publish.

  • Your poll question and options ready.

  • (If token-gating) the token/contract you want to gate on and the Stacks block height to snapshot balances at.

  • (If using dust voting) the STX address (and optionally a BTC address) that should receive the dust for each option.

Step 1 — Connect your wallet

  1. Open ballot.gg and click Connect Wallet (top right).

  2. Approve the connection in your wallet.

  3. Once connected, your name/address appears in the top-right menu.

Step 2 — Start a new poll

Click + New Poll (top right, or from the dropdown menu). This opens the poll builder.

Save your work as you go — drafts are not saved automatically. Use the Save Draft button to store your progress. Once saved, you can leave and return to it later from All Polls → your draft → Edit Poll. If you close the builder without saving, unsaved changes are lost.

Step 3 — Add the title and description

  1. Title — the question or subject of your poll (e.g. "Should the treasury fund Project X?").

  2. Description (optional) — context, links, and details. Supports rich text. Keep it clear; voters read this before deciding.

Step 4 — Add the voting options

  1. Add at least two options (e.g. "Yes — In Favor", "No — Not in Favor").

  2. Use + Add option for more.

  3. Each option can later be given its own dust transaction settings (see Step 8).

Step 5 — Choose a voting system

Pick how votes are counted:

Voting system
How it works
Good for

First-Past-The-Post (FPTP)

One choice per voter; most votes wins.

Simple yes/no or single-choice decisions.

Block Voting

Each voter can support multiple options.

Multi-select / approval-style polls.

Quadratic Voting

Voting power scales as the square root of tokens, reducing whale dominance.

Token communities wanting fairer weighting.

Weighted Voting

Voting power is proportional to token/holdings.

Stake-weighted governance.

Step 6 — Set the voting window (⚠️ Bitcoin block heights)

The voting period is defined by two Bitcoin block heights: Start Bitcoin Block Height and End Bitcoin Block Height.

⚠️ Mistake #1 — Don't use the Stacks block height here

These fields are Bitcoin block heights (the ₿ number in the top bar, ~184,915 today — about 6 digits).

A very common mistake is pasting the Stacks height (the Stacks/STX-logo number, ~4,015,914, 7 digits) into Start/End. Ballot will warn you with "This looks like a Stacks block height. Enter a Bitcoin block height." — if you see that, you've used the wrong number.

Rules the builder enforces:

  • Start must be ≥ the current Bitcoin block height.

  • End must be greater than Start.

How to pick the heights (Bitcoin ≈ 1 block / 10 minutes):

Example — a 7-day poll starting now, with the current Bitcoin height at 184,915:

  • Start Bitcoin Block Height = 184915 (now)

  • End Bitcoin Block Height = 184915 + (7 × 144) = 184915 + 1008 = 185923

Tip: You can confirm the current Bitcoin block height in the Ballot top bar (₿ icon) or at mempool.space. The builder shows the approximate dates for the heights you enter so you can sanity-check them.

Step 7 — (Optional) Restrict voting to token holders + set the Snapshot Height

Under "Restrict voting to token holders", you can token-gate the poll so only holders of a specific token/NFT can vote.

  1. Enable token gating.

  2. Choose a token template (e.g. STX, ALEX, a specific NFT collection, or the .btc namespace), or enter a custom token/NFT contract.

  3. Set the Snapshot Block Height.

⚠️ Mistake #3 — The Snapshot Height is a Stacks block height

The snapshot is the Stacks block height at which Ballot measures each voter's token balance. Use the Stacks/STX-logo number from the top bar (~4,015,914, 7 digits) — not the Bitcoin height.

  • Set it to a Stacks height at or before when voting opens (commonly the current Stacks height at creation time).

  • It must be a positive whole number.

  • Why it matters: balances are frozen at this height, so tokens bought after the snapshot don't count. Setting it wrong (e.g. 0, a Bitcoin height, or a future height) makes eligibility/turnout incorrect.

What a snapshot does: it prevents last-minute vote-buying — everyone's voting power is whatever they held at the snapshot block, regardless of trades made afterward.

Step 8 — (Optional) Set up dust voting

Dust voting lets people vote by sending a tiny ("dust") on-chain transaction to an address you specify for each option. If you use dust voting, you must configure the dust details for every option — this is the most commonly skipped step.

⚠️ Mistake #2 — Add the dust address and amount for each option

Previously, polls were published with no STX/BTC dust address and no dust amount, which breaks dust voting. For each option, open its dust settings and fill in the required fields below.

For each voting option, click its dust settings and complete:

STX Transaction (required for dust voting):

Field
Required
Notes

Transaction Address

✅ Yes

The STX address that receives the dust when this option is chosen (e.g. ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM).

Amount (STX)

✅ Yes

The dust amount to send. Use the minimum, typically 0.000001 STX.

Bitcoin & PoX (optional) — toggle "Add Bitcoin Dust Settings" to add:

Field
Required
Notes

BTC Address

Optional

Bitcoin address for this option (for PoX-style rewards).

BTC Amount

Optional

e.g. 0.000001 (min step 0.00000001).

Pox Cycles

Optional

Comma-separated cycle numbers, e.g. 112,113,114.

Do this for every option. A dust poll where one option is missing its address/amount will not work correctly. If you are not using dust voting, you can skip this step entirely.

Step 9 — Review and publish

  1. Click Preview to see the poll exactly as voters will.

  2. Run through the pre-publish checklist below.

  3. Click Publish. Approve the contract-deployment transaction in your wallet and pay the small STX fee.

  4. After the transaction confirms, your poll goes live and appears under All Polls. Share the poll link with your community.

Publishing deploys a smart contract to the Stacks blockchain. The voting window (Start/End) and snapshot are written into that contract, so double-check them before publishing. (Title, description, and the start/end/snapshot can still be edited later via Edit Poll, but it's far easier to get them right the first time.)

Pre-publish checklist

Run through this every time — it catches the three most common mistakes:

Quick reference — Bitcoin vs Stacks heights

Start / End block

Snapshot height

Chain

Bitcoin

Stacks

Top-bar symbol

₿

the Stacks (STX) logo

Typical size today

~184,915 (6 digits)

~4,015,914 (7 digits)

What it controls

When voting opens/closes

When token balances are measured

Rule

Start ≥ now, End > Start

Positive integer, at/before start

FAQ & troubleshooting

"This looks like a Stacks block height" error on Start/End. You entered a Stacks height in a Bitcoin field. Replace it with the ₿ value from the top bar (~6 digits). (Mistake #1)

"Start block must be ≥ current Bitcoin block height." Your Start is in the past. Set it to the current Bitcoin height or later.

My token-gated turnout/eligibility looks wrong. Check the Snapshot Height — it must be the Stacks height (the Stacks (STX) logo) and set at/before voting starts. A wrong or future value skews who's eligible. (Mistake #3)

Dust votes aren't being recorded. Make sure every option has a STX Transaction Address and Amount (STX). A missing address or amount on any option breaks dust voting. (Mistake #2)

Can I edit a poll after publishing? Yes — title, description, and the start/end/snapshot heights can be updated via Edit Poll (block-height changes require a wallet transaction). Options and the voting system are fixed once deployed.

Glossary

  • Bitcoin block height — the current length of the Bitcoin chain (~1 block / 10 min). Ballot ties the voting window to it for tamper-proof timing.

  • Stacks block height — the current length of the Stacks chain. Used for the token-balance snapshot.

  • Snapshot — the block height at which voter balances are frozen for eligibility/weighting, preventing last-minute vote-buying.

  • Dust voting — casting a vote via a tiny on-chain transfer to an option-specific address.

  • PoX cycles — Stacks Proof-of-Transfer reward cycles, optionally referenced in Bitcoin dust settings.

PreviousHomeNextVoting system

Last updated