ds-chief

Summary

This contract provides a way to elect a "chief" contract via approval voting. This may be combined with another contract, such as DSAuthority, to elect a ruleset for a smart contract system.

Voters lock up voting tokens to give their votes weight. The voting mechanism is approval voting. Users get IOU tokens any time they lock voting tokens, which is useful for secondary governance mechanisms. The IOU tokens may not be exchanged for the locked tokens except by someone who has actually locked funds in the contract, and only up to the amount they have locked.

Note on Chiefs

Though anthropocentric language is used throughout this document when referring to the "chief," you should keep in mind that addresses can represent contracts as well as people. Thus, ds-chief works just as well as a method for selecting code for execution as it does for realizing political processes. For example, ds-chief could conceivably be used as a multisignature contract with token-weighted voting governing another set of smart contracts using ds-auth with ds-roles. In this scenario, "candidates" would consist of contracts mutating the state of the smart contract set under governance. Such a contract being elected "chief" would be granted all permissions to execute whatever changes necessary. ds-chief could also be used within such a contract set in conjunction with a proxy contract like ds-proxy or a name resolution system like ENS for the purpose of voting in new versions of contracts.

Why an IOU Token?

The IOU token allows for chaining governance contracts. An arbitrary number of DSChief, DSPrism, or other contracts of that kind may essentially use the same governance token by accepting the IOU token of the DSChief contract before it as a governance token. E.g., given three DSChief contracts, chiefA, chiefB, and chiefC, with chiefA.GOV being the MKR token, setting chiefB.GOV to chiefA.IOU and chiefC.GOV to chiefB.IOU allows all three contracts to essentially run using a common pool of MKR.

Approval Voting

Approval voting is when each voter selects which candidates they approve of, with the top n "most approved" candidates being elected. Each voter can cast up to n + k votes, where k is some non-zero positive integer. This allows voters to move their approval from one candidate to another without needing to first withdraw support from the candidate being replaced. Without this, moving approval to a new candidate could result in a less-approved candidate moving momentarily into the set of elected candidates.

In the case of ds-chief, n is 1.

In addition, ds-chief weights votes according to the quantity of a voting token they've chosen to lock up in the DSChief or DSChiefApprovals contract.

It's important to note that the voting token used in a ds-chief deployment must be specified at the time of deployment and cannot be changed afterward.

Notice for Client Implementations

If you are writing a frontend for this smart contract, please note that the address[] parameters passed to the etch and vote functions must be byte-ordered sets. E.g., [0x0, 0x1, 0x2, ...] is valid, [0x1, 0x0, ...] and [0x0, 0x0, 0x1, ...] are not. This ordering constraint allows the contract to cheaply ensure voters cannot multiply their weights by listing the same candidate on their slate multiple times.

APIs

There are two contracts in ds-chief: DSChiefApprovals and DSChief, which inherits from DSChiefApprovals.

DSChiefApprovals provides the following public properties:

• slates: A mapping of bytes32 to address arrays. Represents sets of candidates. Weighted votes are given to slates.
• votes: A mapping of voter addresses to the slate they have voted for.
• approvals: A mapping of candidate addresses to their uint weight.
• deposits: A mapping of voter addresses to uint number of tokens locked.
• GOV: DSToken used for voting.
• IOU: DSToken issued in exchange for locking GOV tokens.
• hat: Contains the address of the current "chief."
• MAX_YAYS: Maximum number of candidates a slate can hold.

Most of the functions are decorated with the the note modifier from ds-note, meaning that they fire a standardized event when called. Additionally, one custom event is also provided:

• Etch(bytes32 indexed slate): Fired when a slate is created.

Its public functions are as follows:

DSChiefApprovals(DSToken GOV_, DSToken IOU_, uint MAX_YAYS_)

The constructor. Sets GOV, IOU, and MAX_YAYS.

lock(uint wad)

Charges the user wad GOV tokens, issues an equal amount of IOU tokens to the user, and adds wad weight to the candidates on the user's selected slate. Fires a LogLockFree event.

free(uint wad)

Charges the user wad IOU tokens, issues an equal amount of GOV tokens to the user, and subtracts wad weight from the candidates on the user's selected slate. Fires a LogLockFree event.

etch(address[] yays) returns (bytes32 slate)

Save a set of ordered addresses and return a unique identifier for it.

vote(address[] yays) returns (bytes32 slate)

Save a set of ordered addresses as a slate, moves the voter's weight from their current slate to the new slate, and returns the slate's identifier.

vote(bytes32 slate)

Removes voter's weight from their current slate and adds it to the specified slate.

lift(address whom)

Checks the given address and promotes it to chief if it has more weight than the current chief.

DSChief is a combination of DSRoles from the ds-roles package and DSChiefApprovals. It can be used in conjunction with ds-auth to govern smart contract systems.

Its public functions are as follows:

DSChief(DSToken GOV_, DSToken IOU_, uint MAX_YAYS_)

The constructor. Sets GOV, IOU, and MAX_YAYS.

setOwner(address owner_)

Reverts the transaction. Overridden from DSAuth.

setAuthority(DSAuthority authority_)

Reverts the transaction. Overridden from DSAuth.

isUserRoot(address who) constant returns (bool)

Returns true if the given address is the chief.

setRootUser(address who, bool enabled)

Reverts the transaction. Overridden from DSRoles.

DSRoles

See ds-roles for inherited features.