Vote Contract

The Vote contract is an abstract layer for voting. Developers implement concrete voting activities by calling this contract.

Voting for Block Producers:

To build a voting activity, the developer should register first.

rpc Register (VotingRegisterInput) returns (google.protobuf.Empty) {}
message VotingRegisterInput {
google.protobuf.Timestamp start_timestamp = 1;
google.protobuf.Timestamp end_timestamp = 2;
string accepted_currency = 3;
bool is_lock_token = 4;
sint64 total_snapshot_number = 5;
repeated string options = 6;
}

VotingRegisterInput:

  • start timestamp: activity start time.

  • end timestamp: activity end time.

  • accepted currency: the token symbol which will be accepted.

  • is lock token: indicates whether the token will be locked after voting.

  • total snapshot number: number of terms.

  • options: default candidate.

Vote

After building successfully a voting activity, others are able to vote.

rpc Vote (VoteInput) returns (google.protobuf.Empty) {}
message VoteInput {
aelf.Hash voting_item_id = 1;
aelf.Address voter = 2;
sint64 amount = 3;
string option = 4;
aelf.Hash vote_id = 5;
bool is_change_target = 6;
}
message Voted {
option (aelf.is_event) = true;
aelf.Hash voting_item_id = 1;
aelf.Address voter = 2;
sint64 snapshot_number = 3;
sint64 amount = 4;
google.protobuf.Timestamp vote_timestamp = 5;
string option = 6;
aelf.Hash vote_id = 7;
}

VoteInput:

  • voting item id: indicates which voting activity the user participate in.

  • voter: voter's address.

  • amount: vote amount.

  • option: candidate's public key.

  • vote id: transaction id.

  • is change target: indicates whether the option is changed.

After a successfully vote, a Voted event log can be found in the transaction result.

Voted:

  • voting item id: voting activity id.

  • voter: voter's address.

  • snapshot number: the current round.

  • amount: vote amount.

  • vote timestamp: vote time.

  • option: the candidate's public key.

  • vote id: transaction id.

Withdraw

A voter can withdraw the token after the lock time.

rpc Withdraw (WithdrawInput) returns (google.protobuf.Empty) {}
message WithdrawInput {
aelf.Hash vote_id = 1;
}
message Withdrawn {
aelf.Hash vote_id = 1;
}

WithdrawInput:

  • vote id: transaction id.

After a successful vote, a Withdrawn event log can be found in the transaction result.

Withdrawn:

  • vote id: transaction id.

TakeSnapshot

Distributes profits and saves the state every round.

rpc TakeSnapshot (TakeSnapshotInput) returns (google.protobuf.Empty) {}
message TakeSnapshotInput {
aelf.Hash voting_item_id = 1;
sint64 snapshot_number = 2;
}

TakeSnapshotInput:

  • voting item id: voting activity id.

  • snapshot number: the round number.

AddOption

Adds an option (a choice) to a voting activity.

rpc AddOption (AddOptionInput) returns (google.protobuf.Empty) {}
message AddOptionInput {
aelf.Hash voting_item_id = 1;
string option = 2;
}

AddOptionInput:

  • voting item id: voting activity id.

  • option: the new option.

AddOptions

Adds multiple options (choices) to a voting activity.

rpc AddOptions (AddOptionsInput) returns (google.protobuf.Empty) {}
message AddOptionsInput {
aelf.Hash voting_item_id = 1;
repeated string options = 2;
}

AddOptionsInput:

  • voting item id: voting activity id.

  • option: the list of new options.

RemoveOption

Removes an option from a voting activity.

rpc RemoveOption (RemoveOptionInput) returns (google.protobuf.Empty) {}
message RemoveOptionInput {
aelf.Hash voting_item_id = 1;
string option = 2;
}

RemoveOptionInput:

  • voting item id: voting activity id.

  • option: the option to remove.

RemoveOptions

Removes multiple options from a voting activity.

rpc RemoveOptions (RemoveOptionsInput) returns (google.protobuf.Empty) {}
message RemoveOptionsInput {
aelf.Hash voting_item_id = 1;
repeated string options = 2;
}

RemoveOptionsInput:

  • voting item id: voting activity id.

  • option: the options to remove.

view methods

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

GetVotingItem

Gets the information related to a voting activity.

rpc GetVotingItem (GetVotingItemInput) returns (VotingItem) {}
message GetVotingItemInput {
aelf.Hash voting_item_id = 1;
}
message VotingItem {
aelf.Hash voting_item_id = 1;
string accepted_currency = 2;
bool is_lock_token = 3;
sint64 current_snapshot_number = 4;
sint64 total_snapshot_number = 5;
repeated string options = 6;
google.protobuf.Timestamp register_timestamp = 7;
google.protobuf.Timestamp start_timestamp = 8;
google.protobuf.Timestamp end_timestamp = 9;
google.protobuf.Timestamp current_snapshot_start_timestamp = 10;
aelf.Address sponsor = 11;
}

GetVotingItemInput:

  • voting item id: voting activity id.

returns:

  • voting item id: voting activity id.

  • accepted currency: vote token.

  • is lock token: indicates if the token will be locked after voting.

  • current snapshot number: current round.

  • total snapshot number: total number of round.

  • register timestamp: register time.

  • start timestamp: start time.

  • end timestamp: end time.

  • current snapshot start timestamp: current round start time.

  • sponsor: activity creator.

GetVotingResult

Gets a voting result according to the provided voting activity id and round number.

rpc GetVotingResult (GetVotingResultInput) returns (VotingResult) {}
message GetVotingResultInput {
aelf.Hash voting_item_id = 1;
sint64 snapshot_number = 2;
}
message VotingResult {
aelf.Hash voting_item_id = 1;
map<string, sint64> results = 2; // option -> amount
sint64 snapshot_number = 3;
sint64 voters_count = 4;
google.protobuf.Timestamp snapshot_start_timestamp = 5;
google.protobuf.Timestamp snapshot_end_timestamp = 6;
sint64 votes_amount = 7;
}

GetVotingResultInput:

  • voting item id: voting activity id.

  • snapshot number: round number.

returns:

  • voting item id: voting activity id.

  • results: candidate => vote amount.

  • snapshot number: round number.

  • voters count: how many voters.

  • snapshot start timestamp: start time.

  • snapshot end timestamp: end time.

  • votes amount total votes(excluding withdraws).

GetLatestVotingResult

Gets the latest result of the provided voting activity.

rpc GetLatestVotingResult (aelf.Hash) returns (VotingResult) {}
message Hash
{
bytes value = 1;
}
message VotingResult {
aelf.Hash voting_item_id = 1;
map<string, sint64> results = 2; // option -> amount
sint64 snapshot_number = 3;
sint64 voters_count = 4;
google.protobuf.Timestamp snapshot_start_timestamp = 5;
google.protobuf.Timestamp snapshot_end_timestamp = 6;
sint64 votes_amount = 7;
}

Hash:

  • value: voting activity id.

returns:

  • voting item id: voting activity id.

  • results: candidate => vote amount.

  • snapshot number: round number.

  • voters count: how many voters.

  • snapshot start timestamp: start time.

  • snapshot end timestamp: end time.

  • votes amount: total votes(excluding withdraws).

GetVotingRecord

Get the voting record for the given record ID.

rpc GetVotingRecord (aelf.Hash) returns (VotingRecord) {}
message Hash
{
bytes value = 1;
}
message VotingRecord {
aelf.Hash voting_item_id = 1;
aelf.Address voter = 2;
sint64 snapshot_number = 3;
sint64 amount = 4;
google.protobuf.Timestamp withdraw_timestamp = 5;
google.protobuf.Timestamp vote_timestamp = 6;
bool is_withdrawn = 7;
string option = 8;
bool is_change_target = 9;
}

Hash:

  • value: transaction id.

returns:

  • voting item id: voting activity id.

  • voter: voter's address.

  • snapshot number: round number.

  • withdraw timestamp: withdraw time.

  • vote timestamp: vote time.

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

  • option: candidate id.

  • is change target: has withdrawn and vote to others.

GetVotingRecords

Get the voting records for the given record IDs.

rpc GetVotingRecords (GetVotingRecordsInput) returns (VotingRecords) {}
message GetVotingRecordsInput {
repeated aelf.Hash ids = 1;
}
message Hash
{
bytes value = 1;
}
message VotingRecords {
repeated VotingRecord records = 1;
}
message VotingRecord {
aelf.Hash voting_item_id = 1;
aelf.Address voter = 2;
sint64 snapshot_number = 3;
sint64 amount = 4;
google.protobuf.Timestamp withdraw_timestamp = 5;
google.protobuf.Timestamp vote_timestamp = 6;
bool is_withdrawn = 7;
string option = 8;
bool is_change_target = 9;
}

GetVotingRecordsInput:

  • ids: transaction ids.

Hash:

  • value: transaction id.

returns:

  • records: records.

VotingRecord:

  • voting item id: voting activity id.

  • voter: voter's address.

  • snapshot number: round number.

  • withdraw timestamp: withdraw time.

  • vote timestamp: vote time.

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

  • option: candidate id.

  • is change target: has withdrawn and vote to others.

GetVotedItems

Get the voter's withdrawn and valid transaction ids respectively.

rpc GetVotedItems (aelf.Address) returns (VotedItems) {}
message Address
{
bytes value = 1;
}
message VotedItems {
map<string, VotedIds> voted_item_vote_ids = 1;
}
message VotedIds {
repeated aelf.Hash active_votes = 1;
repeated aelf.Hash withdrawn_votes = 2;
}

Address:

  • value: voter's address.

returns:

  • voted item vote ids: voting activity id => vote information.

VotedIds:

  • active votes: valid transaction id.

  • withdrawn votes: withdrawn transaction id.

GetVotingIds

Get the voter's withdrawn and valid transaction ids respectively according to voting activity id.

rpc GetVotingIds (GetVotingIdsInput) returns (VotedIds) {}
message GetVotingIdsInput {
aelf.Address voter = 1;
aelf.Hash voting_item_id = 2;
}
message VotedIds {
repeated aelf.Hash active_votes = 1;
repeated aelf.Hash withdrawn_votes = 2;
}

GetVotingIdsInput:

  • voter: voter's address.

  • voting item id: voting activity id.

returns:

  • active votes: valid transaction id.

  • withdrawn votes: withdrawn transaction id.