# CW3 Spec: MultiSig/Voting Contracts
CW3 is a specification for voting contracts based on CosmWasm.
It is an extension of CW1 (which served as an immediate 1 of N multisig).
In this case, no key can immediately execute, but only propose
a set of messages for execution. The proposal, subsequent
approvals, and signature aggregation all happen on chain.
There are at least 3 different cases we want to cover in this spec:
- K of N immutible multisig. One key proposes a set of messages,
after K-1 others approve it, it can be executed with the
multisig address.
- K of N flexible, mutable multisig. Like above, but with
multiple contracts. One contract stores the group, which is
referenced from multiple multisig contracts (which in turn
implement cw3). One cw3 contracts is able to update the
group content (maybe needing 67% vote). Other cw3 contracts
may hold tokens, staking rights, etc with various execution
thresholds, all controlled by one group. (Group interface
and updating them will be defined in a future spec, likely cw4).
This should fit in this interface (possibly with some
extensions for pieces, but the usage should look the
same externally):
- Token weighted voting. People lock tokens in a contract
for voting rights. There is a vote threshold to execute
messages. The voting set is dynamic. This has a similar
"propose, approve, execute" flow, but we will need to
support clear YES/NO votes and quora not just absolute
thresholds.
The common denominator is that they allow you to propose
arbitrary `CosmosMsg` to a contract, and allow a series
of votes/approvals to determine if it can be executed,
as well as a final step to execute any approved proposal once.
## Base
The following interfaces must be implemented for all cw3
contracts. Note that updating the members of the voting
contract is not contained here (one approach is defined in cw4).
Also, how to change the threshold rules (if at all) is not
standardized. Those are considered admin tasks, and the common
API is designed for standard usage, as that is where we can
standardize the most tooling without limiting more complex
governance controls.
### Messages
`Propose{title, description, msgs, earliest, latest}` - This accepts
`Vec<CosmosMsg>` and creates a new proposal. This will return
an auto-generated ID in the `Data` field (and the logs) that
can be used to reference the proposal later.
If the Proposer is a valid voter on the proposal, this will imply a Yes vote by
the Proposer for a faster workflow, especially useful in eg. 2 of 3
or 3 of 5 multisig, we don't need to propose in one block, get result,
and vote in another block.
Earliest and latest are optional and can request the first
and last height/time that we can try `Execute`. For a vote,
we may require at least 2 days to pass, but no more than 7.
This is optional and even if set, may be modified by the contract
(overriding or just enforcing min/max/default values).
Many implementations will want to restrict who can propose.
Maybe only people in the voting set. Maybe there is some
deposit to be made along with the proposal. This is not
in the spec but left open to the implementation.
`Vote{proposal_id, vote}` - Given a proposal_id, you can
vote yes, no, abstain or veto. Each signed may have a
different "weight" in the voting and they apply their
entire weight on the vote.
Many contracts (like typical
multisig with absolute threshold) may consider veto and
abstain as no and just count yes votes. Contracts with quora
may count abstain towards quora but not yes or no for threshold.
Some contracts may give extra power to veto rather than a
simple no, but this may just act like a normal no vote.
`Execute{proposal_id}` - This will check if the voting
conditions have passed for the given proposal. If it has
succeeded, the proposal is marked as `Executed` and the
messages are dispatched. If the messages fail (eg out of gas),
this is all reverted and can be tried again later with
more gas.
`Close{proposal_id}` - This will check if the voting conditions
have failed for the given proposal. If so (eg. time expired
and insufficient votes), then the proposal is marked `Failed`.
This is not strictly necessary, as it will only act when
it is impossible the contract would ever be executed,
but can be triggered to provide some better UI.
### Queries
`Threshold{}` - This returns information on the rules needed
to declare a contract a success. What percentage of the votes
and how they are tallied.
`Proposal{proposal_id}` - Returns the information set when
creating the proposal, along with the current status.
`ListProposals{start_after, limit}` - Returns the same info
as `Proposal`, but for all proposals along with pagination.
Starts at proposal_id 1 and accending.
`ReverseProposals{start_before, limit}` - Returns the same info
as `Proposal`, but for all proposals along with pagination.
Starts at latest proposal_id and descending. (Often this
is what you will want for a UI)
`Vote{proposal_id, voter}` - Returns how the given
voter (HumanAddr) voted on the proposal. (May be null)
`ListVotes{proposal_id, start_after, limit}` - Returns the same info
as `Vote`, but for all votes along with pagination.
Returns the voters sorted by the voters' address in
lexographically ascending order.
## Voter Info
Information on who can vote is contract dependent. But
we will work on a common API to display some of this.
`Voter { address }` - returns voting power (weight) of this address, if any
`ListVoters { start_after, limit }` - list all eligable voters