> For the complete documentation index, see [llms.txt](https://docs.ballot.gg/ballot.gg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ballot.gg/ballot.gg/creating-a-poll.md).

# 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](https://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):**

```
blocks needed = minutes ÷ 10
             = hours × 6
             = days × 144
```

**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](https://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:

* [ ] **Title & options** are correct, and there are **at least two** options.
* [ ] **Voting system** matches your intent (FPTP / Block / Quadratic / Weighted).
* [ ] **Start / End are BITCOIN block heights** (₿, \~6 digits) — *not* the Stacks height. Start ≥ current Bitcoin height, End > Start. *(Mistake #1)*
* [ ] The **dates** shown for your Start/End heights look right.
* [ ] *(If token-gated)* **Snapshot Height is the STACKS block height** (the Stacks (STX) logo, \~7 digits), a positive whole number, at or before voting starts. *(Mistake #3)*
* [ ] *(If dust voting)* **Every option** has a **STX dust address** *and* a **dust amount** (≈ `0.000001` STX); BTC dust fields added if needed. *(Mistake #2)*
* [ ] You **previewed** the poll and it looks correct.

***

### 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.