Callisto Governance System contract guide

Dexaran
Dexaran
Sep 6, 2019 · 8 min read

The following describes how to submit your proposal or vote for someone else’s proposal through the Governance System smart-contract.

IMPORTANT: This article describes the contract that is still in debugging stage! Governance Contract address may change in the final release.

Final contract address will be confirmed after the Governance System hardfork.

Writing your proposal and asking for funding

First you need to write your proposal text somewhere. You are free to use whatever media resource is available, but I recommend writing proposals in github gists. In this case, proposals are publicly verifiable and accessible. Github gists provide comment threads by default which makes it easier for Cold Stakers to provide their feedback or ask for the clarification of any details. Remember — Cold Stakers are your voters. They are the ones who determine whether you will get funding or not.

I have created an example proposal. It is available here: https://gist.github.com/Dexaran/6782abc23ef137b8710e810792c210c4

Proposal text must include the following items:

  • Proposal name. ASCII symbols only.
  • Abstract (short description of the proposal)
  • Motivation (why proposal is important)
  • Description (detailed description of the implementation and expected results)
  • Payment schedule (how much payment per month and for how long)
  • Payment address (who will receive payments)
  • Proposal name hash (keccak256 hash of the Proposal name)

It is important to provide a valid hash of the proposal name because voters will search this hash in the contract. It is also important that the name of the proposal in the contract matches the name of the proposal in the description text. In case of name mismatch Cold Stakers will not be able to vote for proposal.

The Callisto Team does not determine the proposal form and the contract does not force you to write proposals in this style, but it should be kept in mind that Cold Stakers will review a lot of proposals each month. The more readable proposal description is, the higher the chance that proposal will receive positive votes.

Submitting the proposal to the governance system contract

The governance system contract template is deployed here: 0x590396425Fc45f69568AC02fDA01FDd3ff09EFEA

You can find the contract ABI here.

Cold Staking Emulator contract is deployed at this address on Callisto Mainnet to allow governance system contracts operate as if there is ColdStaking v2 already.

It is necessary to send the proposal submission transaction to the Governance System contract to officially create the proposal and introduce it for voters.

Go to the https://wallet.callisto.network/#contracts tab, copy & paste the contract address into the Contract Address input box, then copy & paste the ABI into the ABI / JSON Interface input box.

Image for post
Image for post

Then click ACCESS button and unlock the wallet you are going to use to submit the proposal. It is important that proposal submission requires a small anti-spam fee and a gas fee to be paid. Make sure the account you are using to send the proposal transaction has enough CLO to pay the fees.

Select the red submit_proposal function from the long list of functions as it is shown in the screenshot below.

Image for post
Image for post

Now its necessary to fill the proposal details.

  • Amount to send : specify a small anti-spam comission to send alongside the proposal transaction. This must be greater than 500 CLO in the real contract. Anything greater than 0 is valid for test contract.
  • _name : ASCII name of the proposal. It is important that this name is case-sensitive and it must not include any extraneous whitespaces. This name must match the proposal name specified in the description and keccak-256 hash of this text name must match the keccak-256 hash specified in the description.
  • _url : provide a link to the gist or other description of the proposal that you have created earlier.
  • _hash : keccak-256 hash of the whole proposal description. This hash is presented for integrity verification reasons. The hash ensures that proposal submitter did not modified the proposal text after the proposal creation.
  • _start : the number of the governance system epoch in which the vote will be held on this proposal. It is important that this number must be greater than the current epoch. get_current_epoch function can be used to identify the number of current governance system epoch. Each epoch lasts for 27 days (1 staking round).
  • _end : the number of the governance system epoch in which the proposal will receive its last payment. This must be greater than _start. Therefore a proposal that is asking for a one-time payment must be submitted at epoch X, voted at epoch X+1 and it will end (and get paid if it was accepted) at epoch X+2.
Image for post
Image for post
  • _destination : address that will receive payment if the proposal will be accepted.
  • _funding : the amount of payment per epoch. If the proposal creator is willing to get 700,000 CLO for two months of work then he needs to set _funding to 350,000 CLO

Here is the example of my proposal settings:

Image for post
Image for post

Reminder: make sure that names match and the provided hash is the exact hash of the matching names.

Image for post
Image for post
Image for post
Image for post

Submit the transaction and make sure that it was successful. Here is my transaction: https://explorer2.callisto.network/tx/0x1e3d05358676ca2bcdb755dc69d74f1237533d9f807d43567e7cbdccd428d259

Transaction consumes 300,000–400,000 gas. The amount of gas is greater for proposals with longer names and URLs.

Voting for an existing proposal through the contract

First of all you need to know proposal’s hash (or name that can be used to calculate the hash) to find the proposal in the contract. For that reason we will feature all the active proposals in one place so that it will be easier for Cold Stakers to find proposals.

Then a Cold Staker must become voter to gain the right to vote for proposals.

Go to the https://wallet.callisto.network/#contracts tab, copy & paste the contract address into the Contract Address input box, then copy & paste the ABI into the ABI / JSON Interface input box exactly as it was described in the Submitting proposal section.

Click the red become_voter function from the function list. Then click WRITE button and send the transaction. After the transaction confirmation the contract will recognize a new voter. Only Cold Stakers can become voters and only with the address that is used for staking (however each staker can use multiple addresses if he is using them all for Staking; each address will have as much weight as the frozen deposit in the staking contract).

Image for post
Image for post

Now its time to find the proposal to vote. Click the blue proposals function from the contract function list (second from the top by default). Copy & paste the proposal name hash (keccak256) into the bytes32 input box and click the READ button. Proposal details will be displayed as it is shown at the screenshot below:

Image for post
Image for post

Open the proposal URL and read the details carefully. Ask the proposal creator for the explanation if something is not clear enough.

Cold Stakers have at least 1 full staking round (27 days) to investigate each proposal. Once you decided if the proposal is worth voting FOR or AGAINST it — it’s time to cast the vote to the contract.

Choose the cast_vote function and fill the proposal name and vote code. Proposal name determines which proposal will receive your vote and _vote_code is 0 (FOR),1 (AGAINST) or 2 (ABSTAIN).

Image for post
Image for post

IMPORTANT: ABSTAIN vote should be used when you have read the proposal text but you are not sure if the proposal is worth accepting or not. You MUST vote for each proposal that you read and you MUST read every proposal that is submitted for the current epoch if you are a voter.

Becoming a voter and not voting for proposals makes it harder for proposals to reach the minimal limit of 50% votes to get accepted.

Last update:

After the last update at 9/10/2019 it is possible to track proposal names by ID. proposal_names function of the contract will return a name of the proposal which corresponds to the queried ID, thus if there are three proposals in the contract in total then proposal_names[0] will return the name hash of the first proposal, proposals_names[1] will return the name hash of the second proposal and proposals_names[2] will return the name hash of the last proposal. This name hashes could be used to check proposal details through the proposals[ name hash ] option of the contract.

After voting

A user can track a progress of voting for a certain proposal. It is necessary to select the proposals option in smart-contract functions list and copy&paste the proposal name hash.

votes_for / votes_against / votes_abstain are the voting weights that were used to vote on this proposal.

Voting results can be calculated 27 days after the start of voting epoch of the proposal. This will not happen automatically, so the proposal submitter must call the evaluate_proposal function to get payment if the proposal is accepted.

Some facts to note

It is possible to submit more than one proposal per epoch for a user.

Voters must vote for every proposal that is votable during the current epoch. A full voting weight of a voter will be assigned to each proposal he voted.

Example

Alice has 10 CLO staked

Bob has 15 CLO staked

Carol has 20 CLO staked

There are three proposals proposal_0 and proposal_1 votable at the current epoch.

Voting proposal_0

Alice -> FOR

Bob -> FOR

Carol -> AGAINST

proposal_0.FOR = Alice.weight + Bob.weight = 10 + 15 = 25 CLO

proposal_0.AGAINST = Carol.weight = 20 CLO

Proposal_0 will be accepted and it will receive funding because the total weight of votes FOR is greater than a total weight of votes AGAINST.

Voting proposal_1

Alice -> FOR

Bob -> AGAINST

Carol -> AGAINST

proposal_1.FOR = Alice.weight = 10 CLO

proposal_1.AGAINST = Bob.weight + Carol.weight = 35 CLO

Despite the fact that Alice, Bob and Carol voted for the previous proposal, their weight remains unchanged. It doesn’t matter how many proposals they voted — their vote will always have as much weight as the amount of CLO they have at Cold Staking.

proposal_1 will not receive funding.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store