maintainer Michael Allan
Votorola is software for hosting open, continuous polls. This guide covers the use of its mail interface.
Rough draft, out of date. The development of the mail interface lags behind the web interface.
Every poll has its own mailbox. If you know its address, you can cast a vote.
Send a message to the poll for Mayor <v-Tor/p/m@zelea.com>, saying who you wish to vote for. For instance, send a message consisting of the single line:
vote iray@prattslanding.ca
You can vote for anyone you choose. When your vote reaches the vote-server, it responds with a challenge.
[-- Attachment #1: Confirmation Request --]
[-- Type: text/plain, Encoding: 7bit, Size: 0.4K --]
Did you recently send mail (original headers attached) to the
vote-server at zelea.com?
If yes, you did, please confirm by:
Replying to this message
or
Sending a blank message to
v-confirm-1241938979.10978.50372c@zelea.com
If not, please ignore this message. Do not reply.
The original mail is on hold. If you do not reply within 7 days,
it will be deleted.
[-- Attachment #2: Original Message Headers --]
[-- Type: text/rfc822-headers, Encoding: 7bit, Size: 1.0K --]
Return-Path: <mike@zelea.com>
Delivered-To: v-service@zelea.com
Received: (qmail 10973 invoked by uid 1006) ...
~ ~ ~
The vote-server is verifying that it was in fact you who sent the email message containing the vote. Anyone can send a message claiming to originate from your email address, but only you can receive mail at that address. When you reply to the challenge, the vote-server will know that it can trust your original message. In future, we will support signed email, as an alternative to challenge/response authentication.
Reply as instructed. The vote-server then acknowledges your original message, and confirms your vote:
To voter mike@zelea.com, in reply to your message dated Sun, 10 May 2009
03:05:49 -0400.
> vote iray@prattslanding.ca
Mayor of Toronto
You were voting for: nobody
You are now voting for: iray@prattslanding.ca
mike@zelea.com
|
|
X
The trace is cut short, because of voter ineligibility. Voter mike@zelea.com
is attempting to vote for iray@prattslanding.ca, but the vote does not count,
because mike@zelea.com is ineligible to vote in this poll. The problem is as
follows: Voter not registered. Register has no information on voter
mike@zelea.com.
The final recipient of the vote is nobody. The vote trace (above) is a
projection based on the latest count. It includes subsequent changes made by
mike@zelea.com, but excludes the changes of other voters. The changes of all
voters will be included in the next count.
------------------------------------------------------------------------------
Older trace, from latest count:
mike@zelea.com
(empty trace, nothing to show)
The vote trace (above) is from the latest count: snap-2009-59-1 /
readyCount-1. It excludes subsequent changes made by voters.
The vote-server replies with two vote traces. The second is from the most recent full count, of all the votes. We hadn't cast a vote at that time (of course, since this is our first vote), so the trace is empty.
The first trace is the one that matters. It acknowledges the vote, but informs us that it doesn't count. In order for it to count, we must register.
The voter register for the demonstration is v-register@zelea.com. Send it a message with these commands:
set name My Name set residence 172 Main Street, M1M 1A1 set link http://mysite.ca/~me/
The vote-server responds once again with a challenge. Reply to the challenge, and it answers:
> set name My Name Old value: none New value: My Name > set residence 172 Main Street, M1M 1A1 Old value: none New value: 172 Main Street, M1M 1A1 > set link http://mysite.ca/~me/ Old value: none New value: http://mysite.ca/~me/
These items are all optional, except for the residential address. It is required for eligibility purposes, in this particular poll. Without it, your vote will not count.
A single registration will suffice for all polls, at all jurisdictional levels. Registration alone will not make you eligible for all polls — your eligibility for each will depend on your residential address, and other particulars — but you only have to register once for all polls.
Send this simple message to the poll v-Tor/p/m@zelea.com:
vote
The response might be:
> vote
Mayor
You are voting for: iray@prattslanding.ca
mike@zelea.com
My Name
http://mysite.ca/~me/
|
| 1
|
V
iray@prattslanding.ca ---> holding 1
The final recipient of the vote is iray@prattslanding.ca. The vote trace
(above) is a projection based on the results of the last count. It includes
subsequent changes made by mike@zelea.com, but excludes the changes of other
voters. The changes of all voters will be included in the next count.
~ ~ ~
That's somewhat better. Your vote is now being counted. However, it appears that your candidate is unaware of the poll. She has received no votes except yours (1), and has cast no vote of her own. So she probably hasn't registered either. We may be able to pre-register her, in that case.
Send another message to v-register@zelea.com:
set name Indira Ray --alter=iray@prattslanding.ca set link http://prattslanding.ca/~iray/ --alter=iray@prattslanding.ca
The vote-server responds once again with a challenge. Reply to the challenge, and it answers:
> set name Indira Ray --alter=iray@prattslanding.ca Old value: none New value: Indira Ray > set link http://prattslanding.ca/~iray/ --alter=iray@prattslanding.ca Old value: none New value: http://prattslanding.ca/~iray/
It worked, which means she hadn't registered herself (as we thought). If she had, then the commands would have been rejected. Instead they were accepted and a copy of the response was forwarded to her, along with her standing in the polls. [Actually not. Bootstrap notification of nominees has yet to be coded. If you wish to communicate with the candidate, you must send an email of your own.]
Suppose it is a day later, and you wish to see how your vote is doing. Again, send this simple message to the poll v-Tor/p/m@zelea.com:
vote
This time, the response might be:
> vote
Mayor
You are voting for: iray@prattslanding.ca
mike@zelea.com
My Name
http://mysite.ca/~me/
|
| 1
|
V
iray@prattslanding.ca ---> holding 1
Indira Ray
http://prattslanding.ca/~iray/
|
|
X
The trace is cut short, because of voter ineligibility. Voter
iray@prattslanding.ca is attempting to vote for marion@iquorum.net, but the
vote does not count, because iray@prattslanding.ca is ineligible to vote in
this poll. The problem is as follows: Address unknown. The register has
no residential address for voter iray@prattslanding.ca.
The final recipient of the vote is iray@prattslanding.ca. The vote trace
(above) is from the last count: snap-2008-04-24 / readyCount-2008-04-24. It
excludes subsequent changes made by voters.
Apparently she has tried to cast a vote. But it doesn't count, because she is not yet fully registered. Suppose we help by sending her an email message, explaining how to set her residential address; or even offering to set it ourselves, with her permission.
Another day goes by, and you check how your vote is doing. This time, the response from the vote-server might be:
> vote
Mayor
You are voting for: iray@prattslanding.ca
mike@zelea.com
My Name
http://mysite.ca/~me/
|
| 1
|
V
iray@prattslanding.ca
Indira Ray
http://prattslanding.ca/~iray/
|
| 2
|
| __
| /
|/ 8
|
V
marion@iquorum.net
Marion Hewitt
http://iquorum.net/members/marion.htm
|
| 11
|
| __
| /
|/ 30
|
V
raychong@kmail.com
Raymond Chong
http://charterhouse.ca/ray.xht
|
| 42
|
| __
| /
|/ 216
|
V
alison.roberts@corona.ca ---> holding 258
Alison Roberts
http://corona.ca/~alison.roberts/
The final recipient of the vote is alison.roberts@corona.ca. The vote trace
(above) is from the last count: snap-2008-04-24-02 / readyCount-2008-04-24.
It excludes subsequent changes made by voters.
The voting mechanism here is a delegate cascade.
Votorola is deployed in a network of deployment areas, one for each local region (city, county, and so forth). Each deployment area runs a vote-server that stores the voter data, and provides interfaces for user access. For the examples below, we'll use Toronto's vote-server.
Send a message to Toronto <v@zelea.com>. Any message will do. For instance, send an empty message.
The vote-server responds:
In reply to your message dated Fri, 16 May 2008 06:54:31 -0400.
You sent an empty message, having no content of type text/plain. For help,
please send a message containing the single command:
help
Let's try as it suggests:
help
It responds:
In reply to your message dated Sun, 10 May 2009 03:25:53 -0400.
> help
City of Toronto
===============
Service: mail meta-service
Access: City of Toronto <v@zelea.com>
Welcome to the vote-server for Toronto (alpha test prototype). It hosts
primary elections for City Council, local members of the Legislative Assembly
of Ontario, and local members of the House of Commons, Parliament of Canada.
An upcoming beta will extend voting to city bylaws, plans and policies.
This vote-server provides multiple voter services. The service which generated
this message (mail) is the meta-service for the whole vote-server. Other
services include polls, and a voter register. They will be listed farther
below. First, we describe the few commands that are recognized by this
service. [Note, this service is rate limited. If you send it too many
messages, it will stop replying for a while.]
Below are the commands recognized by this service. Command syntax is
summarized using these typographic conventions:
item literal, just type 'item' as shown
ITEM variable, subtitute your own value for 'ITEM'
[item] optional, type 'item' or nothing
a | b choice, type either 'a' or 'b'
hello
-----
Say hello to the service.
hello
hello TEXT
The service replies 'hello'. Any TEXT arguments are ignored. This
command is used for testing.
help
----
Request general information on the service, and instructions on using it.
help
The service replies with information and instructions.
To request help for a specific command, try 'COMMAND --help'.
version
-------
Ask what version of software the vote-server is running.
version
The service replies with the version.
How To Communicate with the Vote-Server
=======================================
To communicate with the vote-server, simply send email messages. In
return, it sends replies.
Your messages may contain commands. Commands are typically sent in order
to request information (such as poll counts), or to change information
(such as changing a vote). Commands are typically sent one at a time, but
you may also send multiple commands. To send multiple commands use blank
lines to separate them. For example:
hello this is one command
hello this is
a second command
hello this a third command
When the vote-server receives your message it will first attempt to verify
your identity. It does this by sending a challenge. After you reply to
the challenge it will reply to your message.
Listed below are the voter services that are provided. Each service has
its own address. To obtain further instructions, pick a service, and send
it a message consisting of the command:
help
Polls on the Vote-Server
========================
Tor/p/m
Mayor of Toronto
v-Tor/p/m@zelea.com
Other Services
==============
register
Voter Register
v-register@zelea.com
mail
City of Toronto
v@zelea.com
(this is the service that created the help message you are currently
reading)
The demo vote-server offers two primary types of service (aside its meta-service): a voter register, and polls. We can get further instructions from each. First the register:
Send a help message directly to Voter Register <v-register@zelea.com>.
help
It responds with a challenge, as we saw before. Reply to the challenge, and then it answers our help request, and details the commands it recognizes. Some were already described for the vote-server (above), so we won't repeat them. The commands below are exclusive to the register:
> help
Voter Register <v-register@zelea.com>
==============
This is the open voter register for the City of Toronto (alpha
demonstration).
Below are the commands recognized by this service (register). Command
syntax is summarized using these typographic conventions:
item literal, just type 'item' as shown
ITEM variable, subtitute your own value for 'ITEM'
[item] optional, type 'item' or nothing
a | b choice, type either 'a' or 'b'
doubt
-----
Cast doubt on another voter.
doubt VOTER-EMAIL [REASON]
doubt [--alter VOTER-EMAIL]
If an entry in the voter list appears to contain false information, then
you may mark it as such by casting doubt on the voter. For example:
doubt falseVoter@domain.dom nobody lives at 7 Turncott, the building
is empty
You must be in the voter list yourself before your doubt will reach the
other voter. When it does reach her, it will not affect her own inclusion
in the list, nor her eligibility to vote in the polls. It will only
serve to indicate your suspicion that her entry in the register is false.
Other voters may then consider whether or not to withdraw their trust from
her.
To recall who you are doubting, simply send:
doubt
The service replies, identifying the doubted voters:
You are casting doubt on 1 voter(s).
falseVoter@domain.dom
nobody lives at 7 Turncott, the building is empty
Or, to see where another voter has cast doubt, send:
doubt --alter VOTER-EMAIL
To cast doubt on additional voters, use the 'doubt' command repeatedly.
To withdraw it, use 'undoubt'.
If your registration comes to be doubted by several voters, then you may
wish to attach a note of explanation to it, as a defence. See the command
"set note". [There is currently no easy way to discover who is doubting
you, or to view registration details, except through the web interface.
This will be corrected in the beta-two release.]
set
---
Set the value of a register attribute.
set [--alter VOTER-EMAIL] name|residence|link|note VALUE
The attributes that may be set are:
name
set name James Madison
Your proper name. This attribute is optional, and may be left unset.
residence
set residence 14 Rappahannock Lane, 22485
Your primary residential address. This attribute is required to
establish your eligibility to vote in specific electoral
districts. You may cast a vote in any poll, but whether it
counts or not will usually depend on the value of this attribute. The
postal code should come last.
link
set link http://~jim/emontpelier.net
A web link in standard URI format, pointing to further information
about you. This attribute is optional, and may be left unset.
note
set note My Internet connection may be down, but I'm still
here.
A short note explaining or commenting on your registration. This
attribute is optional, and may be left unset.
Under certain conditions, you may be able to set the attributes of a
registrant other than yourself, by using the --alter option. You may set
the attributes of another registrant, in this way, only if none were
previously set by the registrant. (Once a registrant sets or resets a
single attribute in the register, she assumes exclusive control of all
attributes.)
set --alter muller@wintermere.nz link http://~muller@wintermere.nz
All attributes in the register are in public view. Once set, you may alter a
attribute's value with another 'set' command, or erase it with 'unset'.
[There is currently no easy way to view your register settings. This will
be corrected in the beta release.]
trust
-----
Extend trust to another voter.
trust VOTER-EMAIL
trust [--alter VOTER-EMAIL]
To be eligible to vote, you must have the trust of other voters in your
neighbourhood. A sufficient number of them (themselves trusted) must
extend their trust to you. Only then will your registration be included
in the voter list, and your votes included in the poll counts. The
exact amount of trust you require will usually be specified in the voter
list. [The list is currently posted only in the web interface.] The list
is also a helpful resource for locating suitable neighbours prior to
requesting their trust (by email, telephone, and so forth).
Trust usually has a limited range, restricting it to the local
neighbourhood. The range is usually symmetric (the direction does not
matter). So, before requesting trust *from* a neighbour, you may wish to
test your range by extending your own trust *to* that neighbour. To
extend your trust, use the 'trust' command. For example:
trust myNeighbour@somewhere.net
If you cannot obtain trust because too few voters are registered in your
neighbourhood, then you must contact your local registrar. [Detailed
instructions will be provided in future releases.]
To recall who you are trusting, simply send:
trust
The service replies, identifying the recipients of your trust:
You are trusting 1 voter(s).
myNeighbour@somewhere.net
Or, to see the recipients of another voter's trust, send:
trust --alter VOTER-EMAIL
To extend trust to additional voters, use the 'trust' command repeatedly.
To withdraw it, use 'untrust'.
[There is currently no easy way to discover your own trust level, or to
see who is extending trust to you, except through the web interface. This
will be corrected in the beta-two release.]
undoubt
-------
Withdraw doubt that was previously cast on another voter
undoubt VOTER-EMAIL
The service replies, confirming the withdrawal:
You were casting doubt on 1 voter(s).
You are now casting doubt on 0 voter(s).
If you change your mind later, and wish to re-cast your doubt, use the
'doubt' command.
unset
-----
Unset the value of a register attribute, erasing it.
unset [--alter VOTER-EMAIL] name|residence|link|note
For example:
unset link
The service replies, confirming the erasure:
Old value: http://~muller@wintermere.nz
New value: none
If you change your mind later, and wish to set a value once again, use the
'set' command.
Under certain conditions, you may be able to erase the attributes of a
registrant other than yourself by using the --alter option. See the 'set'
command for details.
untrust
-------
Withdraw trust that was previously extended to another voter
untrust VOTER-EMAIL
The service replies, confirming the withdrawal:
You were trusting 1 voter(s).
You are now trusting 0 voter(s).
If you change your mind later, and wish to re-extend your trust, use the
'trust' command.
Send a help message to the poll for Mayor of Toronto <v-Tor/p/m@zelea.com>.
help
Reply to the challenge as usual, and the poll answers, detailing the commands it recognizes. The following commands are exclusive to polls:
> help
Mayor of Toronto <v-Tor/p/m@zelea.com>
================
This is an election for the Mayor of Toronto.
Below are the commands recognized by this service (Tor/p/m). Command
syntax is summarized using these typographic conventions:
item literal, just type 'item' as shown
ITEM variable, subtitute your own value for 'ITEM'
[item] optional, type 'item' or nothing
a | b choice, type either 'a' or 'b'
unvote
------
Withdraw a vote from a poll.
unvote
The service replies, confirming the withdrawal:
Mayor of Toronto
You were voting for: mychoice@somewhere.net
You are now voting for: nobody
If you change your mind later, and wish to vote again, use the 'vote'
command.
vote
----
Cast a vote in a poll.
vote CANDIDATE-EMAIL
vote [--alter VOTER-EMAIL]
You can vote for anyone you choose. All you need is a person's email
address. For example:
vote myChoice@somewhere.net
To recall who you last voted for, simply send:
vote
The service replies, identifying the recipient of your vote:
Mayor of Toronto
You are voting for: myChoice@somewhere.net
If that person also casts a vote, then your vote is carried with it.
Whoever gets that person's vote also get yours. And so on. Your vote is
carried until it reaches someone who does not vote. This is called a
'delegate cascade'. At the end of the cascade, votes accumulate to reveal
the favoured candidates.
A trace of the cascade is included in the reply, so you can follow the
path of your vote, and see who ultimately receives it. Or you can mark
the vote as non-cascading, so it stays put until you change it:
vote --cascade no (however, this option is not yet implemented)
To see how another voter is voting, send:
vote --alter VOTER-EMAIL
To change your vote, send another 'vote' command. Or withdraw it
altogether using 'unvote'.
[There is currently no easy way to see who is voting for you, or to view
the overall results. This will be corrected for the beta release.]
Please report bugs to the mailing list.
Copyright 2007-2008, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.