Election Contract

The Election contract is essentially used for voting for Block Producers.

AnnounceElection

To be a block producer, a user should first register to be a candidate and lock some token as a deposit. If the data center is not full, the user will be added in automatically and get one weight (10 weight limited) for sharing bonus in the future.

rpc AnnounceElection (google.protobuf.Empty) returns (google.protobuf.Empty) {}

QuitElection

A candidate is able to quit the election provided he is not currently elected. If you quit successfully, the candidate will get his locked tokens back and will not receive anymore bonus.

rpc QuitElection (google.protobuf.Empty) returns (google.protobuf.Empty) {}

Vote

Used for voting for a candidate to be elected. The tokens you vote with will be locked until the end time. According to the number of token you voted and its lock time, you can get corresponding weight for sharing the bonus in the future.

rpc Vote (VoteMinerInput) returns (google.protobuf.Empty) {}
message VoteMinerInput {
string candidate_pubkey = 1;
sint64 amount = 2;
google.protobuf.Timestamp end_timestamp = 3;
}

VoteMinerInput:

  • candidate pubkey: candidate public key.

  • amount: amount token to vote.

  • end timestamp: before which, your vote works.

ChangeVotingOption

Before the end time, you are able to change your vote target to other candidates.

rpc ChangeVotingOption (ChangeVotingOptionInput) returns google.protobuf.Empty){}
message ChangeVotingOptionInput {
aelf.Hash vote_id = 1;
string candidate_pubkey = 2;
}

ChangeVotingOptionInput:

  • voting vote id: transaction id.

  • candidate pubkey: new candidate public key.

Withdraw

After the lock time, your locked tokens will be unlocked and you can withdraw them.

rpc Withdraw (aelf.Hash) returns (google.protobuf.Empty) {}
message Hash
{
bytes value = 1;
}

Hash:

  • value: transaction id.

view methods

For reference, you can find here the available view methods.

GetCandidates

Gets all candidates' public keys.

rpc GetCandidates (google.protobuf.Empty) returns (PubkeyList) {}
message PubkeyList {
repeated bytes value = 1;
}

returns:

  • value public key array of candidates

GetVotedCandidates

Gets all candidates whose number of votes is greater than 0.

rpc GetVotedCandidates (google.protobuf.Empty) returns (PubkeyList) {}
message PubkeyList {
repeated bytes value = 1;
}

returns:

  • value public key array of candidates.

GetCandidateInformation

Gets a candidate's information. If the candidate does not exist, it will return a candidate without any information.

rpc GetCandidateInformation (google.protobuf.StringValue) returns (CandidateInformation) {}
message StringValue {
string value = 1;
}
message CandidateInformation {
string pubkey = 1;
repeated sint64 terms = 2;
sint64 produced_blocks = 3;
sint64 missed_time_slots = 4;
sint64 continual_appointment_count = 5;
aelf.Hash announcement_transaction_id = 6;
bool is_current_candidate = 7;
}

StringValue:

  • value: public key (hexadecimal string) of the candidate.

returns:

  • pubkey: public key (represented by an hexadecimal string).

  • terms: indicates in which terms the candidate participated.

  • produced blocks: the number of blocks the candidate has produced.

  • missed time slots: the time slot for which the candidate failed to produce blocks.

  • continual appointment count: the time the candidate continue to participate in the election.

  • announcement transaction id: the transaction id that the candidate announce.

  • is current candidate: indicate whether the candidate can be elected in the current term.

GetVictories

Gets the victories of the latest term.

rpc GetVictories (google.protobuf.Empty) returns (PubkeyList) {}
message PubkeyList {
repeated bytes value = 1;
}

returns:

  • value the array of public key who has been elected as block producers.

GetTermSnapshot

Gets the snapshot of the term provided as input.

rpc GetTermSnapshot (GetTermSnapshotInput) returns (TermSnapshot) {}
message GetTermSnapshotInput {
sint64 term_number = 1;
}
message TermSnapshot {
sint64 end_round_number = 1;
sint64 mined_blocks = 2;
map<string, sint64> election_result = 3;
}

GetTermSnapshotInput:

  • term number: term number.

returns:

  • end round number: the last term id be saved.

  • mined blocks: number of blocks produced in previous term.

  • election result: candidate => votes.

GetMinersCount

Count miners.

rpc GetMinersCount (google.protobuf.Empty) returns (aelf.SInt32Value) {}
message SInt32Value
{
sint32 value = 1;
}

returns:

  • value: the total number of block producers.

GetElectionResult

Gets an election result by term id.

rpc GetElectionResult (GetElectionResultInput) returns (ElectionResult) {}
message GetElectionResultInput {
sint64 term_number = 1;
}
message ElectionResult {
sint64 term_number = 1;
map<string, sint64> results = 2;
bool is_active = 3;
}

GetElectionResultInput:

  • term number: term id.

returns:

  • term number: term id.

  • results: candidate => votes.

  • is active: indicates that if the term number you input is the current term.

GetElectorVote

Gets the voter's information.

rpc GetElectorVote (google.protobuf.StringValue) returns (ElectorVote) {}
message StringValue {
string value = 1;
}
message ElectorVote {
repeated aelf.Hash active_voting_record_ids = 1;// Not withdrawn.
repeated aelf.Hash withdrawn_voting_record_ids = 2;
sint64 active_voted_votes_amount = 3;
sint64 all_voted_votes_amount = 4;
repeated ElectionVotingRecord active_voting_records = 5;
repeated ElectionVotingRecord withdrawn_votes_records = 6;
bytes pubkey = 7;
}

StringValue:

  • value: the public key (hexadecimal string) of voter.

returns:

  • active voting record ids: transaction ids, in which transactions you voted.

  • withdrawn voting record ids: transaction ids.

  • active voted votes amount: the number(excluding the withdrawn) of token you vote.

  • all voted votes amount: the number of token you have voted.

  • active voting records: no records in this api.

  • withdrawn votes records: no records in this api.

  • pubkey: voter public key (byte string).

GetElectorVoteWithRecords

Gets the information about a voter including the votes (excluding withdrawal information).

rpc GetElectorVoteWithRecords (google.protobuf.StringValue) returns (ElectorVote) {}
message StringValue {
string value = 1;
}
message ElectorVote {
repeated aelf.Hash active_voting_record_ids = 1;// Not withdrawn.
repeated aelf.Hash withdrawn_voting_record_ids = 2;
sint64 active_voted_votes_amount = 3;
sint64 all_voted_votes_amount = 4;
repeated ElectionVotingRecord active_voting_records = 5;
repeated ElectionVotingRecord withdrawn_votes_records = 6;
bytes pubkey = 7;
}
message ElectionVotingRecord {
aelf.Address voter = 1;
string candidate = 2;
sint64 amount = 3;
sint64 term_number = 4;
aelf.Hash vote_id = 5;
sint64 lock_time = 7;
google.protobuf.Timestamp unlock_timestamp = 10;
google.protobuf.Timestamp withdraw_timestamp = 11;
google.protobuf.Timestamp vote_timestamp = 12;
bool is_withdrawn = 13;
sint64 weight = 14;
bool is_change_target = 15;
}

StringValue:

  • value: the public key (hexadecimal string) of the voter.

returns:

  • active voting record ids: transaction ids, in which transactions you vote.

  • withdrawn voting record ids: transaction ids.

  • active voted votes amount: the number(excluding the withdrawn) of token you vote.

  • all voted votes amount: the number of token you have voted.

  • active voting records: records of the vote transaction with detail information.

  • withdrawn votes records: no records in this api.

  • pubkey: voter public key (byte string).

ElectionVotingRecord:

  • voter: voter address.

  • candidate: public key.

  • amount: vote amount.

  • term number: snapshot number.

  • vote id: transaction id.

  • lock time: time left to unlock token.

  • unlock timestamp: unlock date.

  • withdraw timestamp: withdraw date.

  • vote timestamp: vote date.

  • is withdrawn: indicates if the vote has been withdrawn.

  • weight: vote weight for sharing bonus.

  • is change target: whether vote others.

GetElectorVoteWithAllRecords

Gets the information about a voter including the votes and withdrawal information.

rpc GetElectorVoteWithAllRecords (google.protobuf.StringValue) returns (ElectorVote) {}
message StringValue {
string value = 1;
}
message ElectorVote {
repeated aelf.Hash active_voting_record_ids = 1;// Not withdrawn.
repeated aelf.Hash withdrawn_voting_record_ids = 2;
sint64 active_voted_votes_amount = 3;
sint64 all_voted_votes_amount = 4;
repeated ElectionVotingRecord active_voting_records = 5;
repeated ElectionVotingRecord withdrawn_votes_records = 6;
bytes pubkey = 7;
}
message ElectionVotingRecord {
aelf.Address voter = 1;
string candidate = 2;
sint64 amount = 3;
sint64 term_number = 4;
aelf.Hash vote_id = 5;
sint64 lock_time = 7;
google.protobuf.Timestamp unlock_timestamp = 10;
google.protobuf.Timestamp withdraw_timestamp = 11;
google.protobuf.Timestamp vote_timestamp = 12;
bool is_withdrawn = 13;
sint64 weight = 14;
bool is_change_target = 15;
}

StringValue:

  • value: the public key (hexadecimal string) of voter.

returns:

  • active voting record ids: transaction ids, in which transactions you vote.

  • withdrawn voting record ids: transaction ids.

  • active voted votes amount: the number(excluding the withdrawn) of token you vote.

  • all voted votes amount: the number of token you have voted.

  • active voting records: records of transactions that are active.

  • withdrawn votes records: records of transactions in which withdraw is true.

  • pubkey: voter public key (byte string).

ElectionVotingRecord:

  • voter: voter address.

  • candidate: public key.

  • amount: vote amount.

  • term number: snapshot number.

  • vote id: transaction id.

  • lock time: time left to unlock token.

  • unlock timestamp: unlock date.

  • withdraw timestamp: withdraw date.

  • vote timestamp: vote date.

  • is withdrawn: indicates if the vote has been withdrawn.

  • weight: vote weight for sharing bonus.

  • is change target: whether vote others.

GetCandidateVote

Gets statistical information about vote transactions of a candidate.

rpc GetCandidateVote (google.protobuf.StringValue) returns (CandidateVote) {}
message StringValue {
string value = 1;
}
message CandidateVote {
repeated aelf.Hash obtained_active_voting_record_ids = 1;
repeated aelf.Hash obtained_withdrawn_voting_record_ids = 2;
sint64 obtained_active_voted_votes_amount = 3;
sint64 all_obtained_voted_votes_amount = 4;
repeated ElectionVotingRecord obtained_active_voting_records = 5;
repeated ElectionVotingRecord obtained_withdrawn_votes_records = 6;
bytes pubkey = 7;
}

StringValue:

  • value: public key of the candidate.

returns:

  • obtained active voting record ids: vote transaction ids.

  • obtained withdrawn voting record ids: withdrawn transaction ids.

  • obtained active voted votes amount: the valid number of vote token in current.

  • all obtained voted votes amount: total number of vote token the candidate has got.

  • obtained active voting records: no records in this api.

  • obtained withdrawn votes records: no records in this api.

GetCandidateVoteWithRecords

Gets statistical information about vote transactions of a candidate with the detailed information of the transactions that are not withdrawn.

rpc GetCandidateVoteWithRecords (google.protobuf.StringValue) returns (CandidateVote) {}
message StringValue {
string value = 1;
}
message CandidateVote {
repeated aelf.Hash obtained_active_voting_record_ids = 1;
repeated aelf.Hash obtained_withdrawn_voting_record_ids = 2;
sint64 obtained_active_voted_votes_amount = 3;
sint64 all_obtained_voted_votes_amount = 4;
repeated ElectionVotingRecord obtained_active_voting_records = 5;
repeated ElectionVotingRecord obtained_withdrawn_votes_records = 6;
bytes pubkey = 7;
}
message ElectionVotingRecord {
aelf.Address voter = 1;
string candidate = 2;
sint64 amount = 3;
sint64 term_number = 4;
aelf.Hash vote_id = 5;
sint64 lock_time = 7;
google.protobuf.Timestamp unlock_timestamp = 10;
google.protobuf.Timestamp withdraw_timestamp = 11;
google.protobuf.Timestamp vote_timestamp = 12;
bool is_withdrawn = 13;
sint64 weight = 14;
bool is_change_target = 15;
}

StringValue:

  • value: public key of the candidate.

returns:

  • obtained active voting record ids: vote transaction ids.

  • obtained withdrawn voting record ids: withdraw transaction ids.

  • obtained active voted votes amount: the valid number of vote token in current.

  • all obtained voted votes amount: total number of vote token the candidate has got.

  • obtained active voting records: the records of the transaction without withdrawing.

  • obtained withdrawn votes records: no records in this api.

ElectionVotingRecord:

  • voter voter address.

  • candidate public key.

  • amount vote amount.

  • term number snapshot number.

  • vote id transaction id.

  • lock time time left to unlock token.

  • unlock timestamp unlock date.

  • withdraw timestamp withdraw date.

  • vote timestamp vote date.

  • is withdrawn indicates whether the vote has been withdrawn.

  • weight vote weight for sharing bonus.

  • is change target whether vote others.

GetCandidateVoteWithAllRecords

Gets statistical information about vote transactions of a candidate with the detailed information of all the transactions.

rpc GetCandidateVoteWithAllRecords (google.protobuf.StringValue) returns (CandidateVote) {}
message StringValue {
string value = 1;
}
message CandidateVote {
repeated aelf.Hash obtained_active_voting_record_ids = 1;
repeated aelf.Hash obtained_withdrawn_voting_record_ids = 2;
sint64 obtained_active_voted_votes_amount = 3;
sint64 all_obtained_voted_votes_amount = 4;
repeated ElectionVotingRecord obtained_active_voting_records = 5;
repeated ElectionVotingRecord obtained_withdrawn_votes_records = 6;
bytes pubkey = 7;
}
message ElectionVotingRecord {
aelf.Address voter = 1;
string candidate = 2;
sint64 amount = 3;
sint64 term_number = 4;
aelf.Hash vote_id = 5;
sint64 lock_time = 7;
google.protobuf.Timestamp unlock_timestamp = 10;
google.protobuf.Timestamp withdraw_timestamp = 11;
google.protobuf.Timestamp vote_timestamp = 12;
bool is_withdrawn = 13;
sint64 weight = 14;
bool is_change_target = 15;
}

StringValue:

  • value: public key of the candidate.

returns:

  • obtained active voting record ids: vote transaction ids.

  • obtained withdrawn voting record ids: withdrawn transaction ids.

  • obtained active voted votes amount: the valid number of vote token in current.

  • all obtained voted votes amount: total number of vote token the candidate has got.

  • obtained active voting records: the records of the transaction without withdrawing.

  • obtained withdrawn votes records: the records of the transaction withdrawing the vote token.

ElectionVotingRecord:

  • voter: voter address.

  • candidate: public key.

  • amount: vote amount.

  • term number: snapshot number.

  • vote id: transaction id.

  • lock time: time left to unlock token.

  • unlock timestamp: unlock date.

  • withdraw timestamp: withdraw date.

  • vote timestamp: vote date.

  • is withdrawn: indicates whether the vote has been withdrawn.

  • weight: vote weight for sharing bonus.

  • is change target: whether vote others.

GetVotersCount

Gets the total number of voters.

rpc GetVotersCount (google.protobuf.Empty) returns (aelf.SInt64Value) {}
message SInt64Value
{
sint64 value = 1;
}

returns:

  • value: number of voters.

GetVotesAmount

Gets the total number of vote token (not counting those that have been withdrawn).

rpc GetVotesAmount (google.protobuf.Empty) returns (aelf.SInt64Value) {}
message SInt64Value
{
sint64 value = 1;
}

returns:

  • value: number of vote token.

GetCurrentMiningReward

Gets the current block reward (produced block Number times reward unit).

rpc GetCurrentMiningReward (google.protobuf.Empty) returns (aelf.SInt64Value) {}
message SInt64Value
{
sint64 value = 1;
}

returns:

  • value: number of ELF that rewards miner for producing blocks.

GetPageableCandidateInformation

Gets candidates' information according to the page's index and records length.

rpc GetPageableCandidateInformation (PageInformation) returns (GetPageableCandidateInformationOutput) {}
message PageInformation {
sint32 start = 1;
sint32 length = 2;
}
message GetPageableCandidateInformationOutput {
repeated CandidateDetail value = 1;
}
message CandidateDetail {
CandidateInformation candidate_information = 1;
sint64 obtained_votes_amount = 2;
}
message CandidateInformation {
string pubkey = 1;
repeated sint64 terms = 2;
sint64 produced_blocks = 3;
sint64 missed_time_slots = 4;
sint64 continual_appointment_count = 5;
aelf.Hash announcement_transaction_id = 6;
bool is_current_candidate = 7;
}

PageInformation:

  • start: start index.

  • length: number of records.

returns:

  • CandidateDetail: candidates' detailed information.

CandidateDetail:

  • candidate information: candidate information.

  • obtained votes amount: obtained votes amount.

CandidateInformation:

  • pubkey: public key (hexadecimal string).

  • terms: indicate which terms have the candidate participated.

  • produced blocks: the number of blocks the candidate has produced.

  • missed time slots: the time the candidate failed to produce blocks.

  • continual appointment count: the time the candidate continue to participate in the election.

  • announcement transaction id: the transaction id that the candidate announce.

  • is current candidate: indicate whether the candidate can be elected in the current term.

GetMinerElectionVotingItemId

Gets the voting activity id.

rpc GetMinerElectionVotingItemId (google.protobuf.Empty) returns (aelf.Hash) {}
message Hash
{
bytes value = 1;
}

returns:

  • value: voting item id.

GetDataCenterRankingList

Gets the data center ranking list.

rpc GetDataCenterRankingList (google.protobuf.Empty) returns (DataCenterRankingList) {}
message DataCenterRankingList {
map<string, sint64> data_centers = 1;
sint64 minimum_votes = 2;
}

returns:

  • data centers: the top n * 5 candidates with vote amount.

  • minimum votes: not be used.