com.klaytn.caver.rpc.Governance Maven / Gradle / Ivy
/*
* Copyright 2021 The caver-java Authors
*
* Licensed under the Apache License, Version 2.0 (the “License”);
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an “AS IS” BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.klaytn.caver.rpc;
import com.klaytn.caver.methods.response.*;
import org.web3j.protocol.Web3jService;
import org.web3j.protocol.core.DefaultBlockParameter;
import org.web3j.protocol.core.DefaultBlockParameterName;
import org.web3j.protocol.core.DefaultBlockParameterNumber;
import org.web3j.protocol.core.Request;
import java.math.BigInteger;
import java.util.Arrays;
import java.util.Collections;
public class Governance {
/**
* JSON-RPC service instance.
*/
protected final Web3jService provider;
/**
* Creates a Governance instance
* @param provider JSON-RPC service instance.
*/
public Governance(Web3jService provider) {
this.provider = provider;
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* String value = "single";
* Bytes response = caver.rpc.governance.vote(IVote.VoteItem.GOVERNANCE_GOVERNANCE_MODE.getKey(), value);
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Request<?, Bytes>
*/
public Request vote(IVote.VoteItem key, String value) {
return vote(key.toString(), value);
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* String key = "governance.governancemode";
* String value = "single";
*
* Bytes response = caver.rpc.governance.vote(key, value);
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Request<?, Bytes>
*/
public Request vote(String key, String value) {
if(!IVote.VoteItem.isExist(key)) {
throw new IllegalArgumentException("The key " + key + "is invalid.");
}
return new Request<>(
"governance_vote",
Arrays.asList(key, value),
provider,
Bytes.class
);
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* BigInteger unitPriceValue = new BigInteger("25000000000");
*
* Bytes response = caver.rpc.governance.vote(IVote.VoteItem.GOVERNANCE_UNIT_PRICE.getKey(), unitPriceValue).send();
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Bytes
*/
public Request vote(IVote.VoteItem key, BigInteger value) {
return vote(key.toString(), value);
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* String key = "governance.unitprice";
* BigInteger unitPriceValue = new BigInteger("25000000000");
*
* Bytes response = caver.rpc.governance.vote(key, value);
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Request<?, Bytes>
*/
public Request vote(String key, BigInteger value) {
if(!IVote.VoteItem.isExist(key)) {
throw new IllegalArgumentException("The " + key + "is invalid.");
}
return new Request<>(
"governance_vote",
Arrays.asList(key, value),
provider,
Bytes.class
);
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* boolean value = true;
*
* Bytes response = caver.rpc.governance.vote(IVote.VoteItem.REWARD_USE_GINICOEFF.getKey(), value).send();
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Request<?, Bytes>
*/
public Request vote(IVote.VoteItem key, boolean value) {
return new Request<>(
"governance_vote",
Arrays.asList(key, value),
provider,
Bytes.class
);
}
/**
* Submits a new vote.
* If the node has the right to vote based on governance mode, the vote can be placed. If not, and error message will be returned and the vote will be ignored.
*
Example :
* {@code
* String key = "reward.useginicoeff";
* boolean value = true;
*
* Bytes response = caver.rpc.governance.vote(key, value);
* }
*
* @param key The name of the configuration setting to be changed. See the {@link IVote.VoteItem}.
* @param value The value for each key.
* @return Request<?, Bytes>
*/
public Request vote(String key, boolean value) {
if(!IVote.VoteItem.isExist(key)) {
throw new IllegalArgumentException("The key " + key + "is invalid.");
}
return new Request<>(
"governance_vote",
Arrays.asList(key, value),
provider,
Bytes.class
);
}
/**
* Provides the current tally of governance votes.
* It shows the aggregated approval rate in percentage. When it goes over 50%, the vote passed.
*
Example :
* {@code
* GovernanceTally response = caver.rpc.governance.showTally().send();
* GovernanceTally.TallyData item = item.getResult().get(0);
*
* float percent = item.getApprovalPercentage();
* BigInteger unitPrice = IVote.VoteItem.getUnitPrice(item);
* }
*
* @return Request<?, GovernanceTally>
*/
public Request showTally() {
return new Request<>(
"governance_showTally",
Collections.emptyList(),
provider,
GovernanceTally.class
);
}
/**
* Provides the sum of all voting power that CNs have. Each CN has 1.0 ~ 2.0 voting power.
* In "none", "single" governance mode, totalVotingPower don't provide any information.
*
Example :
* {@code
* GovernanceVotingPower response = caver.rpc.governance.getTotalVotingPower().send();
* }
*
* @return Request<?, GovernanceTally>
*/
public Request getTotalVotingPower() {
return new Request<>(
"governance_totalVotingPower",
Collections.emptyList(),
provider,
GovernanceVotingPower.class
);
}
/**
* Provides the voting power of the node. The voting power can be 1.0 ~ 2.0.
* In "none", "single" governance mode, totalVotingPower don't provide any information.
*
Example :
* {@code
* GovernanceVotingPower response = caver.rpc.governance.getMyVotingPower().send();
* }
*
* @return Request<?, GovernanceVotingPower>
*/
public Request getMyVotingPower() {
return new Request<>(
"governance_myVotingPower",
Collections.emptyList(),
provider,
GovernanceVotingPower.class
);
}
/**
* Provides my vote information in the epoch.
* Each vote is stored in a block when the user's node generates a new block. After current epoch ends, this information is cleared.
*
Example :
* {@code
* GovernanceMyVotes response = caver.rpc.governance.getMyVotes().send();
* List voteList = response.getResult();
* GovernanceMyVotes.MyVote myVote = (GovernanceMyVotes.MyVote)voteList.get(0);
*
* String mode = IVote.VoteItem.getGovernanceMode(voteList); // passed list.
* mode = IVote.VoteItem.getGovernanceMode(myVote)); // passed list item.
* }
*
* @return Request<?, GovernanceMyVotes>
*/
public Request getMyVotes() {
return new Request<>(
"governance_myVotes",
Collections.emptyList(),
provider,
GovernanceMyVotes.class
);
}
/**
* Provides the latest chain configuration
* Example :
* {@code
* GovernanceChainConfig response = caver.rpc.governance.getChainConfig().send();
* }
*
* @return Request<?, GovernanceChainConfig>
*/
public Request getChainConfig() {
return getChainConfig(DefaultBlockParameterName.LATEST);
}
/**
* Provides the chain configuration at the specified block number
* Example :
* {@code
* GovernanceChainConfig response = caver.rpc.governance.getChainConfig(BigInteger.ZERO).send();
* }
*
* @return Request<?, GovernanceChainConfig>
*/
public Request getChainConfig(BigInteger blockNumber) {
return getChainConfig(DefaultBlockParameter.valueOf(blockNumber));
}
/**
* Provides the chain configuration by block tag (latest, earliest, pending)
* Example :
* {@code
* GovernanceChainConfig response = caver.rpc.governance.getChainConfig("latest").send();
* }
*
* @return Request<?, GovernanceChainConfig>
*/
public Request getChainConfig(String blockTag) {
return getChainConfig(DefaultBlockParameterName.fromString(blockTag));
}
/**
* Provides the chain configuration by block tag (latest, earliest, pending)
* Example :
* {@code
* GovernanceChainConfig response = caver.rpc.governance.getChainConfig(DefaultBlockParameterName.LATEST).send();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
*
* @return Request<?, GovernanceChainConfig>
*/
public Request getChainConfig(DefaultBlockParameterName blockTag) {
return getChainConfig((DefaultBlockParameter)blockTag);
}
public Request getChainConfig(DefaultBlockParameter blockNumberOrTag) {
return new Request<>(
"governance_getChainConfig",
Arrays.asList(blockNumberOrTag),
provider,
GovernanceChainConfig.class
);
}
/**
* Provides the address of the node that a user is using.
* It is derived from the nodekey and used to sign consensus messages. And the value of "governingnode" has to be one of validator's node address.
*
Example :
* {@code
* Bytes20 response = caver.rpc.governance.getNodeAddress().send();
* }
*
* @return Request<?, Bytes20>
*/
public Request getNodeAddress() {
return new Request<>(
"governance_nodeAddress",
Collections.emptyList(),
provider,
Bytes20.class
);
}
/**
* Returns governance items at specific block.
* It is the result of previous voting of the block and used as configuration for chain at the given block number.
* It pass the latest block tag as a parameter.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getParams().send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
* @return Request<?, Bytes20>
*/
public Request getParams() {
return getParams(DefaultBlockParameterName.LATEST);
}
/**
* Returns governance items at specific block.
* It is the result of previous voting of the block and used as configuration for chain at the given block number.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getParams(BigInteger.ZERO).send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
* @param blockNumber The block number to query.
* @return Request<?, GovernanceItems>
*/
public Request getParams(BigInteger blockNumber) {
return getParams(DefaultBlockParameter.valueOf(blockNumber));
}
/**
* Returns governance items at specific block.
* It is the result of previous voting of the block and used as configuration for chain at the given block number.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getParams("latest").send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
*
* @param blockTag The block tag to query
* @return Request<?, GovernanceItems>
*/
public Request getParams(String blockTag) {
DefaultBlockParameterName blockTagName = DefaultBlockParameterName.fromString(blockTag);
return getParams(blockTagName);
}
/**
* Returns governance items at specific block.
* It is the result of previous voting of the block and used as configuration for chain at the given block number.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getParams(DefaultBlockParameterName.LATEST).send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
*
* @param blockTag The block tag to query
* @return Request<?, GovernanceItems>
*/
public Request getParams(DefaultBlockParameterName blockTag) {
return getParams((DefaultBlockParameter)blockTag);
}
Request getParams(DefaultBlockParameter blockParameter) {
return new Request<>(
"governance_getParams",
Arrays.asList(blockParameter.getValue()),
provider,
GovernanceItems.class
);
}
/**
* Returns governance items at specific block.
* It is the result of previous voting of the block and used as configuration for chain at the given block number.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getItemsAt(DefaultBlockParameterName.LATEST).send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* }
*
* @param blockTag The block tag to query
* @return Request<?, GovernanceItems>
*/
// public Request getItemsAt(DefaultBlockParameterName blockTag) {
// return getItemsAt((DefaultBlockParameter)blockTag);
// }
// Request getItemsAt(DefaultBlockParameter blockParameter) {
// return new Request<>(
// "governance_itemsAt",
// Arrays.asList(blockParameter.getValue()),
// provider,
// GovernanceItems.class
// );
// }
/**
* Returns the list of items that have received enough number of votes but not yet finalized.
* At the end of the current epoch, these changes will be finalized and the result will be in effect from the epoch after next epoch.
*
Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getPendingChanges().send();
* Map governanceItem = response.getResult();
*
* String mode = IVote.VoteItem.getGovernanceMode(governanceItem);
* mode = governanceItem.get("governance.governancemode");
* }
* @return Request<?, GovernanceItems>
*/
public Request getPendingChanges() {
return new Request<>(
"governance_pendingChanges",
Collections.emptyList(),
provider,
GovernanceItems.class
);
}
/**
* Returns the votes from all nodes in the epoch. These votes are gathered from the header of each block.
* Example :
* {@code
* GovernanceNodeVotes response = caver.rpc.governance.getVotes().send();
* List list = response.getResult();
* GovernanceNodeVotes.NodeVote item = (GovernanceNodeVotes.NodeVote)list.get(0);
*
* BigInteger unitPrice = IVote.VoteItem.getUnitPrice(list);
* boolean useGini = IVote.VoteItem.toBooleanValue(item.getKey(), item.getValue());
* }
*
* @return Request<?, GovernanceItems>
*/
public Request getVotes() {
return new Request<>(
"governance_votes",
Collections.emptyList(),
provider,
GovernanceNodeVotes.class
);
}
/**
* Returns an array of current idxCache in the memory cache.
* idxCache contains the block numbers where governance change happened. The cache can have up to 1000 block numbers in memory by default.
*
Example :
* {@code
* GovernanceIdxCache response = caver.rpc.governance.getIdxCache().send();
* }
* @return Request<?, GovernanceIdxCache>
*/
public Request getIdxCache() {
return new Request<>(
"governance_idxCache",
Collections.emptyList(),
provider,
GovernanceIdxCache.class
);
}
/**
* Returns an array that contains all block numbers on which a governance change ever happened.
* The result of idxCacheFromDb is the same or longer than that of idxCache.
*
Example :
* {@code
* GovernanceIdxCache response = caver.rpc.governance.getIdxCacheFromDb().send();
* }
*
* @return Request<?, GovernanceIdxCache>
*/
public Request getIdxCacheFromDb() {
return new Request<>(
"governance_idxCacheFromDb",
Collections.emptyList(),
provider,
GovernanceIdxCache.class
);
}
/**
* Returns the governance information stored in the given block. If no changes were stored in the given block, the function returns null.
* Example :
* {@code
* GovernanceItems response = caver.rpc.governance.getItemCacheFromDb(BigInteger.ZERO).send();
* }
*
* @param blockNumber A block number to query the governance change made in the block.
* @return Request<?, GovernanceItems>
*/
public Request getItemCacheFromDb(BigInteger blockNumber) {
return new Request<>(
"governance_itemCacheFromDb",
Arrays.asList(new DefaultBlockParameterNumber(blockNumber)),
provider,
GovernanceItems.class
);
}
/**
* The getStakingInfo returns staking information at a specific block.
* It passes the latest block tag as a parameter.
*
Example :
* {@code
* GovernanceStackingInfo response = caver.rpc.governance.getStakingInfo().send();
* }
*
* @return Request<?, GovernanceStackingInfo>
*/
public Request getStakingInfo() {
return getStakingInfo(DefaultBlockParameterName.LATEST);
}
/**
* Returns staking information at a specific block.
*
Example :
* {@code
* GovernanceStackingInfo response = caver.rpc.governance.getStakingInfo(BigInteger.ZERO).send();
* }
*
* @param blockNumber The block number.
* @return Request<?, GovernanceStackingInfo>
*/
public Request getStakingInfo(BigInteger blockNumber) {
return getStakingInfo(DefaultBlockParameter.valueOf(blockNumber));
}
/**
* Returns staking information at a specific block.
*
Example :
* {@code
* GovernanceStackingInfo response = caver.rpc.governance.getStakingInfo("latest").send();
* }
*
* @param blockTag The block tag.
* @return Request<?, GovernanceStackingInfo>
*/
public Request getStakingInfo(String blockTag) {
DefaultBlockParameterName blockTagName = DefaultBlockParameterName.fromString(blockTag);
return getStakingInfo(blockTagName);
}
/**
* Returns staking information at a specific block.
*
Example :
* {@code
* GovernanceStackingInfo response = caver.rpc.governance.getStakingInfo(DefaultBlockParameterName.LATEST).send();
* }
*
* @param blockTag The block tag.
* @return Request<?, GovernanceStackingInfo>
*/
public Request getStakingInfo(DefaultBlockParameterName blockTag) {
return getStakingInfo((DefaultBlockParameter)blockTag);
}
Request getStakingInfo(DefaultBlockParameter blockParam) {
return new Request<>(
"governance_getStakingInfo",
Arrays.asList(blockParam),
provider,
GovernanceStakingInfo.class
);
}
public Request getRewardsAccumulated(String fromBlock, String toBlock) {
DefaultBlockParameterName fromBlockTagName = DefaultBlockParameterName.fromString(fromBlock);
DefaultBlockParameterName toBlockTagName = DefaultBlockParameterName.fromString(toBlock);
return getRewardsAccumulated(fromBlockTagName, toBlockTagName);
}
public Request getRewardsAccumulated(BigInteger fromBlock, BigInteger toBlock) {
return getRewardsAccumulated(DefaultBlockParameter.valueOf(fromBlock), DefaultBlockParameter.valueOf(toBlock));
}
public Request getRewardsAccumulated(DefaultBlockParameterName fromBlock, DefaultBlockParameterName toBlock) {
return getRewardsAccumulated((DefaultBlockParameter)fromBlock, (DefaultBlockParameter)toBlock);
}
Request getRewardsAccumulated(DefaultBlockParameter fromBlock, DefaultBlockParameter toBlock) {
return new Request<>(
"governance_getRewardsAccumulated",
Arrays.asList(fromBlock, toBlock),
provider,
RewardsAccumulated.class
);
}
}