types — voting / governance

import "github.com/populist/protocol/types"

Transaction type constants

Wire-format discriminators used in Tx.Type. These are the only valid values; any other value is rejected by tx.Tx.Validate.

Constant	Value	Purpose
TxTypePollCreate	1	Create a new poll
TxTypeBallotCast	2	Cast an anonymous ballot
TxTypePollClose	3	Close a poll and finalize the tally
TxTypeRegisterValidator	4	Add or remove a consensus validator
TxTypeConfirmReceipt	5	Voter confirms receipt post-close

Voting method constants

Constant	Value	Description
VotingMethodPlurality	"plurality"	Voter selects exactly one option
VotingMethodApproval	"approval"	Voter selects any non-empty subset
VotingMethodRanked	"ranked"	Voter ranks options in preference order

Poll

A poll definition in canonical state.

type Poll struct {
    PollID       string   // unique identifier
    PollHash     string   // deterministic hash of poll parameters
    Question     string
    Options      []string
    VotingMethod string   // "plurality" | "approval" | "ranked"
    StartTime    int64    // Unix timestamp
    EndTime      int64    // Unix timestamp
    Status       string   // "pending" | "open" | "closed"
    CreatedAt    int64    // Unix timestamp
}

VoteRecord (List 1)

An anonymous vote direction. No identity field.

ballot_id = H(BallotNonce) is random and unlinkable to the voter's identity_hash.

type VoteRecord struct {
    BallotID  string   // H(BallotNonce) — no identity encoded
    PollID    string
    Choices   []string // 1 element for plurality; subset for approval; ordered for ranked
    Timestamp int64
    Height    int64
}

VoterRecord (List 2)

A verified participation record. No choice field.

identity_hash = ZK nullifier = MiMC(person_secret, poll_id).

type VoterRecord struct {
    PollID       string
    IdentityHash string // ZK nullifier
    Height       int64
}

Tally

The finalized tally for a closed poll, including the managed tally signature for independent verification.

type Tally struct {
    PollID          string
    VotingMethod    string
    Counts          map[string]int64 // option → count
    TotalVotes      int64
    ConfirmedCount  int64            // voters who confirmed receipt post-close
    VoteMerkleRoot  []byte           // root of sorted ballot_ids (List 1)
    VoterMerkleRoot []byte           // root of sorted identity_hashes (List 2)
    Signature       []byte           // managed signer ECDSA signature
    PublicKey       []byte           // DER-encoded verifying key
    FinalizedAt     int64
    Height          int64
}

To verify the tally signature independently, use verify.VerifyECDSA.

ConfirmRecord

Records that a voter acknowledged their receipt after poll close.

type ConfirmRecord struct {
    PollID       string
    IdentityHash string // ZK nullifier
    Height       int64
}

Stored in state.State.confirms keyed as "pollID:identityHash".

Error types

Type	When returned
ErrorInvalidPoll	Poll not found, wrong status, or malformed parameters
ErrorDuplicateVote	identity_hash already present in voterRegistry for this poll