Introduction to 'Voting Process' for Programmers

System Contract Part #2 - Voting Process

<p dir="auto">In eos network, <a href="https://github.com/EOSIO/eos/tree/slim/contracts/eosio.system" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link"><strong>eosio.system contract enable users to 1) stake tokens, and then vote on producers (or worker proposals), 2) proxy their voting influence to other users, 3) register producers, 4) claim producer rewards, 5) delegate resources (net, cpu & ram) and push other necessary actions to keep blockchain system running. <p dir="auto">In this series, we will go through What is the contract, What are included in the contract and How the contract can be used. <p dir="auto">Our last post discussed the <a href="https://steemit.com/blockchain/@eosiosg/system-contract-part-1-block-producer-rewards" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link"><strong>'Block Producer Rewards', in this article we will talk about voting process. <p dir="auto">In this article, we will be discussing detailed flows/steps on <strong>Producer Registration, <strong>Token Staking, <strong>Voting on BP , and <strong>Changing/Withdrawing Vote successively. <p dir="auto"><em>All codes present are based on commit of <a href="https://github.com/EOSIO/eos/commit/44e7d3ef2503d7bc45afc18f04f0289ed26cfdd7" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">44e7d3e <h2>TL;DR: <ul> <li><strong>Token holders have to stake with their tokens on net and cpu for voting <li><strong>On voting, all staked assets will convert to <code>x amount of weighted votes, which can be used to vote up to 30 producers and each selected producer will get <code>x amount of votes repectively <li><strong>Refunding process takes up to 3 days to reflect the unstaked tokens in available token balance <li><strong>Newer votes possess higher voting weights <p dir="auto"><img src="https://images.hive.blog/768x0/https://steemitimages.com/DQmSUwAR8m8Bcqsqox7n2z5cd8iyY3Z1rDDLNeBgqiH7RLo/voting.png" alt="voting.png" srcset="https://images.hive.blog/768x0/https://steemitimages.com/DQmSUwAR8m8Bcqsqox7n2z5cd8iyY3Z1rDDLNeBgqiH7RLo/voting.png 1x, https://images.hive.blog/1536x0/https://steemitimages.com/DQmSUwAR8m8Bcqsqox7n2z5cd8iyY3Z1rDDLNeBgqiH7RLo/voting.png 2x" /> <h2>Producer Registration <p dir="auto"><strong>Accounts should register themselves as producer first before they can be voted. This process is done by pushing a <code>system_contract::regproducer action. <ul> <li>The core logic code below is to insert or replace producers' configurations (i.e. public key & parameters) into <code>producerinfo table. <pre><code>void system_contract::regproducer( const account_name producer, const eosio::public_key& producer_key, const std::string& url ) { //, const eosio_parameters& prefs ) { ... if ( prod != _producers.end() ) { if( producer_key != prod->producer_key ) { _producers.modify( prod, producer, [&]( producer_info& info ){ info.producer_key = producer_key; }); } } else { _producers.emplace( producer, [&]( producer_info& info ){ info.owner = producer; info.total_votes = 0; info.producer_key = producer_key; }); } } <p dir="auto">*<em>This part of code is under rapid development, we will keep updating it if significant changes are found. <h2>Token Staking <p dir="auto"><strong>Token holders can only vote after they have staked their tokens on net and cpu. Staking process is done by pushing a <code>system_contract::delegatebw action. Inside <code>delegatebw action, voter's tokens are staked and cannot be transferred until refunded. <ol> <li><p dir="auto">If a user has not staked before, insert a record for this account in the table <code>deltable. If a user has staked, add newly amount to the existing amount. <li><p dir="auto">Set resource limits for stake receiver. Transfer corresponding amount as stake to a public account <code>eosio. <pre><code> void system_contract::delegatebw( account_name from, account_name receiver, asset stake_net_quantity, asset stake_cpu_quantity ) { require_auth( from ); ... set_resource_limits( tot_itr->owner, tot_itr->ram_bytes, tot_itr->net_weight.amount, tot_itr->cpu_weight.amount ); if( N(eosio) != from) { INLINE_ACTION_SENDER(eosio::token, transfer)( N(eosio.token), {from,N(active)}, { from, N(eosio), asset(total_stake), std::string("stake bandwidth") } ); } <p dir="auto"><br /> <li><p dir="auto">Update voter's staked amount. <ul> <li>Find the voter from <code>voters table, if not exist, insert a new record of this voter. <li>Add newly delegated stake into the voter's <code>staked attribute. <li>Call <code>voteproducer action to update vote results. This means if the push sender has voted before, on new <code>delegatebw action, votes will be updated for last voting producers (or lasting voting proxy). <pre><code>... print( "voters \n" ); auto from_voter = _voters.find(from); if( from_voter == _voters.end() ) { print( " create voter \n" ); from_voter = _voters.emplace( from, [&]( auto& v ) { v.owner = from; v.staked = uint64_t(total_stake); print( " vote weight: ", v.last_vote_weight, "\n" ); }); } else { _voters.modify( from_voter, 0, [&]( auto& v ) { v.staked += uint64_t(total_stake); print( " vote weight: ", v.last_vote_weight, "\n" ); }); } print( "voteproducer\n" ); if( from_voter->producers.size() || from_voter->proxy ) { voteproducer( from, from_voter->proxy, from_voter->producers ); } } // delegatebw <p dir="auto">****Note that user can also delegate net & cpu to other accounts, making resource transfer to be possible. We will talk about user resources in depth in the upcoming blog.*** <h2>Vote On Producer / Proxy <p dir="auto"><strong>Stake holders (token holders who have their tokens staked) can vote for producers (or proxy, who will vote on behalf of push sender), all stakes will convert to weighted x votes and then add up to 30 producers by x votes. <h4>Vote producer <p dir="auto">*<em>Leaving <code>proxy arguments to be empty <ol> <li><p dir="auto">Validation: <ul> <li>Producers to be vote must be given in order; <li>Producers to be vote must be registered; <li>Producers to be vote must be active. <li><p dir="auto">Calculate current vote weight based on the following formula: <p dir="auto"><img src="https://images.hive.blog/768x0/https://latex.codecogs.com/png.latex?%5CLARGE%20%24%24votes%20%3D%20stakes%5Ctimes%7B2%5E%7B%7Bcurrent%5C_timestamp%5C_in%5C_second%5Cover%20604800%20%28seconds%5C_per%5C_week%29%5Ctimes%2052%20%7D%7D%20%5Csimeq%20ax%5Ctimes%20stakes%7D%24%24" alt="equation" srcset="https://images.hive.blog/768x0/https://latex.codecogs.com/png.latex?%5CLARGE%20%24%24votes%20%3D%20stakes%5Ctimes%7B2%5E%7B%7Bcurrent%5C_timestamp%5C_in%5C_second%5Cover%20604800%20%28seconds%5C_per%5C_week%29%5Ctimes%2052%20%7D%7D%20%5Csimeq%20ax%5Ctimes%20stakes%7D%24%24 1x, https://images.hive.blog/1536x0/https://latex.codecogs.com/png.latex?%5CLARGE%20%24%24votes%20%3D%20stakes%5Ctimes%7B2%5E%7B%7Bcurrent%5C_timestamp%5C_in%5C_second%5Cover%20604800%20%28seconds%5C_per%5C_week%29%5Ctimes%2052%20%7D%7D%20%5Csimeq%20ax%5Ctimes%20stakes%7D%24%24 2x" /> <p dir="auto">*<em>The weight increasing could be treated as a linear growing with time within a short period. <p dir="auto">If the voter is a proxy, <code>proxied_vote_weight of the voter will also be updated. <ol> <li><p dir="auto">Reduce <code>last_vote_weight (if ever), and then add current vote weight. <ul> <li>Create a relation between voting producer and vote weight. <li>Deduct last voting weight from voting producers. <li>Add each voting producer's vote weight by the new weight. <pre><code>void system_contract::voteproducer( const account_name voter_name, const account_name proxy, const std::vector<account_name>& producers ) { require_auth( voter_name ); ... boost::container::flat_map<account_name, double> producer_deltas; for( const auto& p : voter->producers ) { producer_deltas[p] -= voter->last_vote_weight; } if( new_vote_weight >= 0 ) { for( const auto& p : producers ) { producer_deltas[p] += new_vote_weight; } } ... } <p dir="auto"><br /> <li><p dir="auto">Record voting results. <ul> <li>Modify <code>voters table, update vote weight & voting producers (or proxy) respectively. <li>Modify <code>producerinfo table, update producer's votes. <pre><code> ... _voters.modify( voter, 0, [&]( auto& av ) { print( "new_vote_weight: ", new_vote_weight, "\n" ); av.last_vote_weight = new_vote_weight; av.producers = producers; av.proxy = proxy; print( " vote weight: ", av.last_vote_weight, "\n" ); }); for( const auto& pd : producer_deltas ) { auto pitr = _producers.find( pd.first ); if( pitr != _producers.end() ) { _producers.modify( pitr, 0, [&]( auto& p ) { p.total_votes += pd.second; eosio_assert( p.total_votes >= 0, "something bad happened" ); eosio_assert( p.active(), "producer is not active" ); }); } } } <h4>Vote proxy <p dir="auto">*<em>Leaving <code>producers arguments to be empty <blockquote> <p dir="auto">An account marked as a proxy can vote with the weight of other accounts which have selected it as a proxy. Other accounts must refresh their voteproducer to update the proxy's weight. <ol> <li>Validation: <ul> <li>Proxy to be vote must have registered to be a proxy by pushing action <code>system_contract::regproxy. <li>Proxy and producers cannot be voted at the same time. <li>Calculate current vote weight, same as above. <li>Update proxy's vote weight <ul> <li>Deduct last voting weight from the voting proxy. <li>Add each voting proxy's vote weight by the new amount. <pre><code> ... if( voter->proxy != account_name() ) { auto old_proxy = _voters.find( voter->proxy ); _voters.modify( old_proxy, 0, [&]( auto& vp ) { vp.proxied_vote_weight -= voter->last_vote_weight; print( " vote weight: ", vp.last_vote_weight, "\n" ); }); } if( proxy != account_name() && new_vote_weight > 0 ) { auto new_proxy = _voters.find( voter->proxy ); eosio_assert( new_proxy != _voters.end() && new_proxy->is_proxy, "invalid proxy specified" ); _voters.modify( new_proxy, 0, [&]( auto& vp ) { vp.proxied_vote_weight += new_vote_weight; print( " vote weight: ", vp.last_vote_weight, "\n" ); }); } <h2>Changing/Withdrawing Vote <p dir="auto"><img src="https://images.hive.blog/768x0/https://steemitimages.com/DQmdHpd6UohD1CtiQR5iLudxjmBVcBZdDRp6UYx9k9m5r54/undelegating.png" alt="undelegating.png" srcset="https://images.hive.blog/768x0/https://steemitimages.com/DQmdHpd6UohD1CtiQR5iLudxjmBVcBZdDRp6UYx9k9m5r54/undelegating.png 1x, https://images.hive.blog/1536x0/https://steemitimages.com/DQmdHpd6UohD1CtiQR5iLudxjmBVcBZdDRp6UYx9k9m5r54/undelegating.png 2x" /> <h4>Votes Change <p dir="auto">Voters are able to change voted producers (or proxy) by <strong>pushing <code>voteproducer actions again, details have been discussed in the previous section. <h4>Votes Withdraw (Unstake) <p dir="auto"><strong>Voters can withdraw their votes by pushing by pushing <code>system_contract::undelegatebw actions with any amount that is no bigger than the net & cpu been staked & delegated. Undelegated stakes will be available for <code>system_contract::refund after 3 days. <ol> <li>Decrease refunding amount from voter's <code>staked column of <code>voter table. <li>Update <code>totals_tbl table and update resource limits for the account. <li>Create refund request. <ul> <li>Update <code>refunds table with unstaked amount <li>If user undelegate many times within a short period of time, the last undelegating time will be recorded (this time will be used for calculating the available refunding time). <pre><code> void system_contract::undelegatebw( account_name from, account_name receiver, asset unstake_net_quantity, asset unstake_cpu_quantity ) { ... auto req = refunds_tbl.find( from ); if ( req != refunds_tbl.end() ) { refunds_tbl.modify( req, 0, [&]( refund_request& r ) { r.amount += unstake_net_quantity + unstake_cpu_quantity; r.request_time = now(); }); } else { refunds_tbl.emplace( from, [&]( refund_request& r ) { r.owner = from; r.amount = unstake_net_quantity + unstake_cpu_quantity; r.request_time = now(); }); } ... <li>Create (or replace) a deferred <code>system_contract::refund transaction & update voting results. <ul> <li>Push a deferred transaction. <li><code>refund_delay = 3*24*3600, i.e. 3 days. <li>Call <code>voteproducer to deduct corresponding votes from voted producers. <pre><code> ... eosio::transaction out; out.actions.emplace_back( permission_level{ from, N(active) }, _self, N(refund), from ); out.delay_sec = refund_delay; out.send( from, receiver ); const auto& fromv = _voters.get( from ); if( fromv.producers.size() || fromv.proxy ) { voteproducer( from, fromv.proxy, fromv.producers ); } } // undelegatebw <h2>Conclusion <ol> <li>Token owner can only vote after they <strong>staked their tokens on net & cpu. <li>During voting action, all stakes of the voter will convert into x weighted votes, and every voted producer (up to 30) is going to get <strong>equivalent x weighted votes. <li><strong>Newer votes count more than older votes, the weight grows approximately linearly. <li>Users can undelegate their stakes and have to wait up to <strong>3 days before they can re-allocate this amount of tokens. <p dir="auto"><em>In the next article, we are going to talk about some detailed implementation about <strong>user resources, including delegate cpu & net, buy & sell ram, new account, producer voting and proxy related stuff. <p dir="auto"><strong>Stay tuned with <a href="http://eosio.sg/" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">eosio.sg: <a href="https://t.me/eosiosg" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">Telegram, <a href="https://medium.com/@eosiosg" target="_blank" rel="nofollow noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">Medium.