Skip to content

Commit

Permalink
Merge pull request #48 from kaiachain/feat/update-rpc-docs
Browse files Browse the repository at this point in the history 
Feat/update rpc docs
  • Loading branch information
@Sotatek-TanHoang
Sotatek-TanHoang authored Oct 10, 2024
2 parents 3544ec7 + 75d4da5 commit 9552ab7
Show file tree
Hide file tree
Showing 12 changed files with 352 additions and 134 deletions.
22 changes: 22 additions & 0 deletions web3rpc/rpc-specs/components/schemas/common/Common.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2041,3 +2041,25 @@ components:
"transactionsRoot": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
"voteData": "0x"
}
StateOverrideSet:
type: object
description: The state override set is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call.
properties:
balance:
type: integer
format: int64
description: (optional) Fake balance to set for the account before executing the call.
nonce:
type: integer
format: int64
description: (optional) Fake nonce to set for the account before executing the call.
code:
type: string
format: DATA
description: (optional) Fake EVM bytecode to inject into the account before executing the call.
state:
type: object
description: (optional) Fake key-value mapping to override all slots in the account storage before executing the call.
stateDiff:
type: object
description: (optional) Fake key-value mapping to override individual slots in the account storage before executing the call.
27 changes: 2 additions & 25 deletions web3rpc/rpc-specs/paths/eth/transaction/call.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ paths:
description: The state override set is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call.
required: false
schema:
$ref: "#/components/schemas/StateOverrideSet"
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/StateOverrideSet"

requestBody:
content:
Expand Down Expand Up @@ -96,32 +96,9 @@ components:
BlockNumberOrTag:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/BlockNumberOrTag"
StateOverrideSet:
$ref: "#/components/schemas/StateOverrideSet"
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/StateOverrideSet"
example: [{"from": "0xca7a99380131e6c76cfa622396347107aeedca2d", "to": "0xbE3892d33620bE5aca8c75D39e7401871194d290", "input": "0x2e64cec1"}, "latest", {"0xbE3892d33620bE5aca8c75D39e7401871194d290": {"code":"0x6080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632e64cec114604e5780636057361d146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a9565b005b60008054905090565b80600081905550505600a165627a7a723058207783dba41884f73679e167576362b7277f88458815141651f48ca38c25b498f80029"}}]

StateOverrideSet:
type: object
description: The state override set is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call.
properties:
balance:
type: integer
format: int64
description: (optional) Fake balance to set for the account before executing the call.
nonce:
type: integer
format: int64
description: (optional) Fake nonce to set for the account before executing the call.
code:
type: string
format: DATA
description: (optional) Fake EVM bytecode to inject into the account before executing the call.
state:
type: object
description: (optional) Fake key-value mapping to override all slots in the account storage before executing the call.
stateDiff:
type: object
description: (optional) Fake key-value mapping to override individual slots in the account storage before executing the call.

KlayCallResp:
type: object
properties:
Expand Down
30 changes: 24 additions & 6 deletions web3rpc/rpc-specs/paths/eth/transaction/estimateGas.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ paths:
required: true
schema:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/EthCallObject"
- name: BlockNumberOrHashOrTag
in: query
required: false
schema:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/BlockNumberOrHashOrTag"


requestBody:
content:
Expand Down Expand Up @@ -74,15 +80,28 @@ components:
properties:
method:
type: string
default: 'eth_estimateGas'
default: "eth_estimateGas"
params:
type: array
items:
properties:
EthCallObject:
description: The transaction call object. See the next table for the object's properties.
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/EthCallObject"
example: [{"from": "0x3f71029af4e252b25b9ab999f77182f0cd3bc085", "to": "0x87ac99835e67168d4f9a40580f8f5c33550ba88b", "gas": "0x100000", "gasPrice": "0x5d21dba00", "value": "0x0", "input": "0x8ada066e"}]
CallObject:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/KaiaCallObject"
BlockNumberOrHashOrTag:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/BlockNumberOrHashOrTag"
StateOverrideSet:
$ref: "../../../components/schemas/common/Common.yaml#/components/schemas/StateOverrideSet"
example:
[
{
"from": "0x3f71029af4e252b25b9ab999f77182f0cd3bc085",
"to": "0x87ac99835e67168d4f9a40580f8f5c33550ba88b",
"gas": "0x100000",
"gasPrice": "0x5d21dba00",
"value": "0x0",
"input": "0x8ada066e",
},
]

EthEstimateGasResp:
type: object
Expand All @@ -92,4 +111,3 @@ components:
format: hex
description: The amount of gas used.
example: "0x5208"

6 changes: 6 additions & 0 deletions web3rpc/rpc-specs/paths/governance/getChainConfig.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ paths:
**NOTE:** In versions earlier than Kaia v1.10.0, this API returned the initial chain configuration. However, due to its confusing name, it is updated since Kaia v1.10.0. To query the initial chain configuration, use getChainConfigAt(0) instead.
NOTE: If the requested block has Kore hardfork enabled, the value of `governance.reward.useGiniCoeff` will be `false` because all council members have an equal chance of being elected as a block proposer and thus Gini coefficient is not relevant.
NOTE: If the requested block has Randao hardfork enabled, the value of `governance.reward.proposerUpdateInterval` will be `1` because proposers are no longer selected at batch.
NOTE: If the requested block has Kaia hardfork enabled, the value of `governance.reward.stakingUpdateInterval` will be `1` because staking information is every block, effectively deprecating the interval.
**JSONRPC:** `governance_getChainConfig`
tags:
Expand Down
6 changes: 6 additions & 0 deletions web3rpc/rpc-specs/paths/governance/getParams.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ paths:
**NOTE:** The block number can be larger than the latest block number, in which case the API returns the tentative value based on the current chain state. The future governance parameters are subject to change via additional governance votes or GovParam contract state changes.
NOTE: If the requested block has Kore hardfork enabled, the value of `reward.useginicoeff` will be `false` because all council members have an equal chance of being elected as a block proposer and thus Gini coefficient is not relevant.
NOTE: If the requested block has Randao hardfork enabled, the value of `reward.proposerupdateinterval` will be `1` because proposers are no longer selected at batch.
NOTE: If the requested block has Kaia hardfork enabled, the value of `reward.stakingupdateinterval` will be `1` because staking information is every block, effectively deprecating the interval.
**JSONRPC:** `governance_getParams`
tags:
Expand Down
113 changes: 21 additions & 92 deletions web3rpc/rpc-specs/paths/governance/vote.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,26 @@ paths:
The vote method submits a new vote. If the node has the right to vote based on governance mode, the vote can be placed. If not, an error message will be returned and the vote will be ignored.
**JSONRPC:** `governance_vote`
The vote method submits a new vote. If the node has the right to vote based on governance mode, the vote can be placed. If not, an error message will be returned and the vote will be ignored.
You can vote for the parameters listed in kaia_getParams, except immutable items. Immutable items are first decided at the genesis configuration and remain unchanged.
In addition to the parameters described in kaia_getParams, you can vote for validator council changes using the values below.
<table>
<tr>
<th>Key<</th>
<th>Value</th>
</tr>
<tr>
<td><code>governance.addvalidator</code></td>
<td>ADDRESS. An address or comma-separated list of addresses of a new validator candidate. e.g., <code>0xe733cb4d279da696f30d470f8c04decb54fcb0d2</code>, <code>0xf39fd6e51aad88f6f4ce6a88827279cFfB92266</code></td>
</tr>
<tr>
<td><code>governance.removevalidator</code></td>
<td>ADDRESS. An address or comma-separated list of addresses of a current validator to be removed. e.g., <code>0xe733cb4d279da696f30d470f8c04decb54fcb0d2</code></td>
</tr>
</table>
tags:
- governance
Expand Down Expand Up @@ -100,97 +120,6 @@ components:
schemas:
Value:
type: string
description: |
Various types of value for each key.
<table>
<thead>
<tr>
<th>Key</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>"governance.governancemode"</td>
<td>STRING. One of the three governance modes. "none", "single", "ballot"</td>
</tr>
<tr>
<td>"governance.governingnode"</td>
<td>ADDRESS. Designated governing node's address. It only works if the governance mode is "single" e.g.,"0xe733cb4d279da696f30d470f8c04decb54fcb0d2"</td>
</tr>
<tr>
<td>"governance.unitprice"</td>
<td>NUMBER. Price of unit gas. e.g., 25000000000</td>
</tr>
<tr>
<td>"governance.addvalidator"</td>
<td>ADDRESS. Address of a new validator candidate. e.g., 0xe733cb4d279da696f30d470f8c04decb54fcb0d2</td>
</tr>
<tr>
<td>"governance.removevalidator"</td>
<td>ADDRESS. Address of a current validator which need to be removed. e.g., 0xe733cb4d279da696f30d470f8c04decb54fcb0d2</td>
</tr>
<tr>
<td>"governance.deriveshaimpl"</td>
<td>NUMBER. Policy to generate the transaction hash and receipt hash in a block header. See here for available options. e.g., 2 (DeriveShaConcat)</td>
</tr>
<tr>
<td>"governance.govparamcontract"</td>
<td>ADDRESS. Address of the GovParam contract. e.g., 0xe733cb4d279da696f30d470f8c04decb54fcb0d2</td>
</tr>
<tr>
<td>"istanbul.epoch"</td>
<td>NUMBER. A period in which votes are gathered in blocks. When an epoch end, all votes which haven't been passed will be cleared. e.g., 86400</td>
</tr>
<tr>
<td>"istanbul.committeesize"</td>
<td>NUMBER. The number of validators in a committee.(sub in chain configuration) e.g., 7</td>
</tr>
<tr>
<td>"reward.mintingamount"</td>
<td>STRING. Amount of Peb minted when a block is generated. Double quotation marks are needed for a value. e.g., "9600000000000000000"</td>
</tr>
<tr>
<td>"reward.ratio"</td>
<td>STRING. Distribution rate for a CN/KGF/KIR separated by "/". The sum of all values has to be 100. e.g., "50/40/10" meaning CN 50%, KGF 40%, KIR 10%</td>
</tr>
<tr>
<td>"reward.kip82ratio"</td>
<td>STRING. Distribution ratio of the block proposer to stakers separated by "/". The sum of all values has to be "100". See KIP-82 for further details. e.g., "20/80" means that the proposer takes 20% while stakers take 80%.</td>
</tr>
<tr>
<td>"reward.useginicoeff"</td>
<td>BOOL. Use the Gini coefficient or not. true, false</td>
</tr>
<tr>
<td>"reward.deferredtxfee"</td>
<td>BOOL. The way of giving transaction fee to a proposer. If true, it means the tx fee will be summed up with block reward and distributed to the proposer, KIR and KGF. If not, all tx fee will be given to the proposer. true, false</td>
</tr>
<tr>
<td>"reward.minimumstake"</td>
<td>STRING. Amount of Kaia required to be a CN (Consensus Node). Double quotation marks are needed for a value. e.g., "5000000"</td>
</tr>
<tr>
<td>"kip71.lowerboundbasefee"</td>
<td>NUMBER. The lowest possible base fee. See KIP-71 for further details. e.g., 25000000000</td>
</tr>
<tr>
<td>"kip71.upperboundbasefee"</td>
<td>NUMBER. The highest possible base fee. e.g., 750000000000</td>
</tr>
<tr>
<td>"kip71.gastarget"</td>
<td>NUMBER. The block gas that base fee wants to achieve. The base fee increases when parent block contains more than gas target, and decreases when parent block contains less than gas target. e.g., 30000000</td>
</tr>
<tr>
<td>"kip71.basefeedenominator"</td>
<td>NUMBER. Controls how fast base fee changes. e.g., 20</td>
</tr>
<tr>
<td>"kip71.maxblockgasusedforbasefee"</td>
<td>NUMBER. The maximum block gas perceived in base fee calculation. e.g., 60000000</td>
</tr>
</tbody>
</table>
description: Various types of value for each key.


12 changes: 11 additions & 1 deletion web3rpc/rpc-specs/paths/kaia/configuration/getChainConfig.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,18 @@ paths:
operationId: ..getChainConfig
summary: "[Configuration] kaia_getChainConfig"
description: |
Returns the configuration of the chain.
Returns the chain configuration at the given block number.
See kaia_getParams for the list of parameters.
NOTE: The block number can be larger than the latest block number, in which case the API returns the tentative value based on the current chain state. The future kaia parameters are subject to change via additional governance votes or GovParam contract state changes.
NOTE: If the requested block has Kore hardfork enabled, the value of `governance.reward.useGiniCoeff` will be `false` because all council members have an equal chance of being elected as a block proposer and thus Gini coefficient is not relevant.
NOTE: If the requested block has Randao hardfork enabled, the value of `governance.reward.proposerUpdateInterval` will be `1` because proposers are no longer selected at batch.
NOTE: If the requested block has Kaia hardfork enabled, the value of `governance.reward.stakingUpdateInterval` will be `1` because staking information is every block, effectively deprecating the interval.
**JSONRPC:** `kaia_getChainConfig`
tags:
- kaia
Expand Down
Loading

0 comments on commit 9552ab7

Please sign in to comment.