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: vote 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.