kaiachain/kaia v3.0.0

Kaia v3.0.0 Release Notice

on GitHub

IMPORTANT: Kaia v3.0.0 contains a hardfork upgrade that results in changes that are not backward compatible. All Kairos testnet nodes must be upgraded to v3.0.0 or later before the target block number. The Mainnet hardfork block number will be specified in a later release.

Kaia v3.0.0 introduces the Permissionless hardfork. Validators join, pause, resume, and leave the network through the AddressBookV2 contract under the validator lifecycle of KIP-286. Validator performance is scored by VRank as per KIP-227. Peer admission and the CN-EN network topology follow KIP-311, and the proxy node (PN) role is retired. This version also hardens consensus and P2P message handling and improves transaction-pool and tracing performance.

Here's the hardfork schedule for the Kairos testnet

• Block number: 233366400 (estimated time: 18 Nov 2026, 23:06 UTC+9)
• Hardfork contents: Permissionless hardfork

Notes to node operators

Notes to Core Cell Operators (CCO): Consensus Node (CN) and Proxy Node (PN)

• Validator operations are available as kcn valops subcommands. Use --datadir for tar-based installations.
  • generate-keys: creates the missing ECDSA and BLS onboarding keys in <datadir>/klay offline. Existing key files are reused and never overwritten.
  • sign-create-node: creates the node ID ownership signature that AddressBookV2.createNode requires, offline with the node key.
  • ready-candidate: moves the node to the CandReady state.
  • unready-candidate: moves the node out of the CandReady state.
  • ready-validator: moves the node to the ValReady state.
  • unready-validator: moves the node out of the ValReady state.
  • pause: pauses the node.
  • resume: resumes a paused node.
  • exit: removes the node from the validator set.
  • offboard: offboards the node from AddressBookV2.
  • suspend-validator, unsuspend-validator: suspend and unsuspend a validator. Only the suspender role can run them.
• The lifecycle subcommands (ready-candidate to offboard) send a transaction to AddressBookV2. Each transaction is checked with eth_call before it is sent.
• The packaged kcnd.conf sets MAXCONNECTIONS=103 (previously 100) so that a full mesh of 100 CNs and the reserved CN-EN slots fit. A package upgrade keeps a kcnd.conf that you have edited, so set MAXCONNECTIONS=103 in it, or remove the line to use the CN default of 103.
• --maxconnections now limits the number of peers for inbound connections as well. A multichannel peer counts once, regardless of how many sockets it uses. Before, a multichannel node accepted only about half of --maxconnections as inbound peers.
• A CN reserves 3 connection slots for ENs and an EN reserves 2 slots for CNs by default. The reservation is also the limit for these links: a CN accepts at most 3 discovered ENs, and an EN accepts at most 2 discovered CNs. Static and trusted peers are not limited. Use --reserved-cross-type-slots to change the reservation. The node does not start if --maxconnections is not larger than the reservation. This check does not apply to --maxconnections 0, which allows only static and trusted peers.
• The proxy node (PN) role is retired. The kpn and kspn binaries and packages are removed, and --nodetype pn and --nodetype spn now fail at startup with Unknown node type. ENs connect to CNs directly. A v3.0.0 node still accepts connections from PNs that run an older version and treats them as ENs.

Notes to Endpoint Node (EN) operators

• ENs connect to CNs directly, without a PN in between.

Notes to all node operators

• The default bootnode lists are replaced with new Mainnet and Kairos bootnodes, and all node types, including CNs, now use the same list. If you set BOOTNODES (--bootnodes) to the previous default bootnodes, update or remove the setting.
• The web3 RPC namespace is removed. It is also removed from RPC_API and WS_API in the packaged configuration files. An unknown module name in an existing configuration is ignored, and the node starts normally.
• The --vrank.log-frequency flag is removed. A node started with this flag fails.
• The miner/block/* mining timer metrics now report per-block values and percentile series (_0_5 to _0_9999). The _maxgauge series is removed; use _0_9999 instead. Review dashboards and alerts that use these metrics.
• The vrank/commit/*, vrank/preprepare/first, miner/resultch, and miner/tx/resend/gauge metrics are removed. Review dashboards and alerts that use these metrics.

API changes

Removed

• Removed the web3 RPC namespace. Use kaia_clientVersion and kaia_sha3 instead of web3_clientVersion and web3_sha3. (#849, #1111)
• Removed the proxy node: the kpn and kspn binaries, --nodetype pn/spn, --txpool.spamthrottler.disable, and the homi options --pn-num, --spn-num, and --pn-nodekey-dir. (#981)
• Removed the bootnode allowlist: the kbn --authorized-nodes flag and the bootnode_getAuthorizedNodes, bootnode_putAuthorizedNodes, and bootnode_deleteAuthorizedNodes RPC methods. (#867, #912, #1006)
• Removed the --vrank.log-frequency flag. (#899)

Changed

• Changed the bootnode RPC namespace of kbn. The methods refresh, nodes, getNode, putNode, and deleteNode replace name, resolve, lookup, readRandomNodes, createUpdateNodeOnDB, createUpdateNodeOnTable, getNodeFromDB, getTableEntries, getTableReplacements, deleteNodeFromDB, and deleteNodeFromTable. (#867)
• Renamed the eth_feeHistory result field blobBaseFeePerGas to baseFeePerBlobGas and added blobGasUsedRatio, as in Ethereum. (#886)
• Changed kaia_getStakingInfo and governance_getStakingInfo after the Permissionless hardfork. (#959, #1120, #1125)
  • Before the hardfork, they list every node registered in AddressBook, including nodes that do not receive the staking reward. After the hardfork, for block N they list only the nodes that receive the staking reward of block N: the ValActive nodes in AddressBookV2 after the validator transitions of block N, including suspended validators. Paused and ready nodes are not listed.
  • Staking amounts are effective stakes (KIP-290; staking amount minus unstaking amount).
  • The staking reward is distributed over the same nodes, and the proposer reward goes to the reward address registered in AddressBookV2.
• governance_getParams, kaia_getParams, kaia_getChainConfig, and governance_getContractParams return an error for a block number above the latest block. Block number parameters above the int64 range are rejected. (#958)
• The pending block tag now behaves as latest on all node types. Before, an EN answered pending with an empty block numbered one above the latest block, so calls such as eth_call with pending saw that block number. kaia_getTransactionCount and eth_getTransactionCount with pending still include the transactions in the transaction pool. (#925)
• Changed the default of homi --reward-minimum-stake from 2000000 to 5000000 to match the validator admission amount. The same homi command now creates a different genesis file. (#1055)
• governance_vote rejects governance.addvalidator, governance.removevalidator, and istanbul.committeesize after the Permissionless hardfork. (#869, #905)
• JSON-RPC batch requests are limited to 1,000 items and 25 MiB of response data by default. Use --rpc.batch-request-limit and --rpc.batch-response-max-size to change the limits, or set them to 0 to disable the check. (#883)
• Structured traces (the default logger of debug_trace*) are limited to 128 MiB of output, 1,000,000 log entries, and 2 concurrent traces (other requests wait for a free slot). The trace timeout is 5 seconds by default and can be set by the caller. The loggerTimeout option is deprecated and ignored. (#1078)
• kaia_getBlockWithConsensusInfoByNumberRange accepts at most 50 blocks, counting both ends of the range. A 51-block range was accepted before. (#1049)

Added

• Added governance_getPFS and governance_getCFS to return the VRank proposal-failure and candidate-failure scores. (#922, #1005)
• Added kaia_getNodesByState to return the AddressBookV2 validator nodes at a block, filtered by state. It returns an error before the Permissionless hardfork. (#905)
• Added the kcn valops subcommands for validator operations, with dry-run checks, slot-limit error details, --datadir, and --timeout. (#913, #940, #961, #993, #1124)
• Added --reserved-cross-type-slots to reserve connection slots for CN-EN links. (#939, #1014)
• Added --bn.ping-ratelimit and --bn.ping-burst for bootnode discovery ping rate limiting, and bound discovery endpoint proofs to the source IP. The rate limit is enabled by default. (#929, #1003, #1087)
• Replaced the JavaScript prestateTracer with a native tracer that supports the diffMode, disableCode, and disableStorage options. Added the onlyTopCall and withLog options to callTracer, and the stateOverrides and tracerConfig options to debug_traceCall. (#920, #1027)
• Added the receipt txError value 0x1f (ErrZeroThreshold). (#1080)
• Added homi --public-delegation to deploy genesis validators with public delegation. (#1038)

Permissionless hardfork features

• Implemented the validator lifecycle as per KIP-286 (#766, #884, #897, #905, #914, #930, #964, #986, #1007, #1015, #1022, #1033, #1050, #1056, #1090, #1100, #1106, #1119)
• Implemented VRank as per KIP-227 (#875, #879, #923, #943, #968, #987, #989, #992, #994, #995, #998, #1016, #1019, #1031, #1040, #1073, #1099, #1104)
• Recorded the parent round with its committed-seal certificate in VRank (#1054)
• Implemented permissionless networking as per KIP-311 (#867, #880, #912, #927, #931, #965, #988, #996, #1013, #1017, #1026, #1034, #1035, #1036, #1075, #1094)
• Updated the system contracts to kaia-system-contracts v3.0.0 (#972, #1037, #1089)
• Bound committed seals to the consensus round. The block hash does not change with the round (#985)
• Propagated prepared certificates across rounds to recover from split locks, and released the certificate when the locked block fails execution (#1084, #1098)
• Enforced canonical recovery IDs in the validateSender precompile (#889, #1118)
• Set the computation cost of the CLZ opcode to 165 (#916)
• Applied the half fee burn of the non-deferred reward mode. The block reward base is now decided before transaction execution. (#816, #1112)

Improvements

• Updated the packaged CN and BN configuration files for KIP-311: MAXCONNECTIONS 103 for CNs and no AUTHORIZED_NODES for BNs (#980)
• Improved transaction-pool scalability and the admission of transactions that fill nonce gaps (#919)
• Removed redundant sender recovery before transaction-pool admission (#1065)
• Throttled repeated inbound connections from one IP and backed off on temporary accept errors (#926, #1018)
• Cached BLS proof-of-possession results (#1030)
• Removed duplicate scans of governance vote history (#952)
• Moved governance parameter deprecation to a fork-aware rule (#869)
• Added maxGasPrice and versioned EIP-712 encoding to auction bids. They apply when the auction entry-point contract reports version 3.0. (#901)
• Made the startup error for --syncmode fast point to full sync or a chaindata snapshot (#1044)
• Stopped unqualified validators from producing blocks (#936)
• Added a check of the header reward address against staking information (#891)
• Hardened reward calculation (#951)
• Pre-deployed the EIP-2935 history storage contract in genesis when Prague is active at genesis (#843)
• Upgraded go-eth-kzg to v1.5.0 (#1004)

Fixes

Consensus and block validation

• Fixed a peer validation race at startup (#809)
• Kept peers connected during synchronization (#1093)
• Aligned proposal verification with block import rules (#967, #1028, #1072)
• Fixed the block size check at import (#1128)
• Hardened consensus header, message, and seal verification (#924)
• Hardened the handling of consensus views and rounds (#898, #984, #1032, #1066)
• Fixed the committed seal in COMMIT messages rebroadcast for an old block, and kept sealed blocks from sharing header data with the original block (#962, #1048)
• Bounded the resources used by consensus messages (#1029, #1053, #1063, #1074)
• Fixed historical proposer and council lookups (#966, #971)

P2P and synchronization

• Reduced the memory and GC load of per-peer known caches (#910)
• Fixed trusted and static peer handling (#1101)
• Fixed multichannel connection handling (#997, #1123)
• Hardened peer type validation for consensus message (#1008)
• Fixed peer discovery issues (#1002)
• Bounded the resources used by peer messages (#892, #1010, #1024, #1025, #1042, #1062, #1069, #1071)
• Bounded transaction propagation batches (#1064, #1108)
• Bounded inbound auction bids (#1041, #1046)
• Fixed block fetcher deadlocks (#1105)
• Fixed false gas-used mismatches caused by prefetch (#1020)
• Fixed staking information sync and invalid block body handling (#1047, #1051, #1060, #1082)

Blob transactions

• Verified each blob transaction sidecar only once (#1012)
• Fixed blob fee accounting in reward and supply reports (#815, #848)
• Fixed blob sidecar and blob transaction cost handling (#857, #963, #977, #1067)
• Added a chain configuration check for the blob schedule (#1021)

Transactions, auction, and gasless

• Fixed role-based account key updates (#976)
• Hardened fee-delegation ratio validation (#893, #1113)
• Hardened transaction signature handling (#978, #1009, #1096)
• Fixed the spam throttler (#894)
• Fixed transaction pool behavior when the pool is full (#938)
• Fixed auction bid and gasless bundle handling (#906, #937, #970)

Governance and rewards

• Fixed contract governance validation (#946, #947, #1109)
• Fixed governance index and serialization handling (#948, #957)

APIs, tracing, and operations

• Fixed call tracer issues (#969)
• Fixed JSON values relayed from an upstream archive EN (#1088)
• Fixed gRPC handling (#888)
• Hardened APM request handling (#1079)
• Removed pprof handlers from the Prometheus metrics port (#1023)
• Fixed mining timer metrics (#908)
• Fixed offline database migration error handling (#895)
• Fixed kbn --nodekeyhex (#867)
• Fixed state migration issues (#1068, #1110)

Miscellaneous

• Kairos Permissionless hardfork configuration (#1103)
• Fixed genesis and private network issues (#790, #881, #921)
• Consensus engine refactoring toward KaiaBFT (#724, #729, #733, #740, #782, #783, #784, #786, #795, #800, #801, #833, #834, #835, #844, #858, #859, #868, #944, #1039, #1091, #1092, #1107, #1115)
• Moved the system contracts to the kaia-system-contracts submodule and generated bindings from its artifacts (#900, #903, #904, #911, #953)
• Updated the CI workflows (#799, #805, #806, #836, #1122, #1129)
• Added and updated tests, including a multi-validator consensus scenario suite (#813, #907, #1000, #1043, #1076, #1077, #1083, #1085)
• Updated code and repository documentation (#949, #955, #956, #1011, #1052, #1070, #1095)
• Code maintenance (#788, #804, #807, #808, #814, #823, #854, #890, #928, #950, #974, #999, #1045, #1057, #1081, #1126)
• Updated comments, typos, CODEOWNERS, and the version constant (#896, #902, #917, #918, #973, #975, #1001, #1086)

Downloads

Please find the download links at https://docs.kaia.io/nodes/downloads/

Thank you @box4wangjing, @colinaumaty, @cuoguojida, @GeunhwaJeong, @stringsbuilder, @swapscanner-ryan, @tsinglua, @vividvisit, @wangjingshuiku, @zjuzhongwen, and @zoupingcenter, for your first contribution to Kaia.