Toward Ethereum Equivalence #3 — Supporting Ethereum APIs
Starting with the Klaytn v1.8.0 release, the `eth` namespace (`eth_`) APIs will be supported in the same format as Ethereum APIs (in addition to the existing klay namespace APIs). In this article, we explain the purpose of supporting Ethereum APIs, as well as some points to take note of while using this new feature.
For more details on these changes, please refer to Klaytn Docs — eth.
Purpose
Klaytn v1.8.0 supports Ethereum APIs in order to ensure compatibility with the Ethereum interface, as part of the Klaytn 2.0 initiative the Klaytn team set out earlier — supporting Ethereum equivalence,so that Ethereum dApp developers can seamlessly build on Klaytn by allowing for the same tooling, workflows, and interaction, they are accustomed to within the Ethereum environment.
The eth namespace APIs (`eth_`) provided on Klaytn nodes prior to Klaytn v1.8.0 functioned in the same way as their klay namespace API (`klay_`) counterparts. They were invoked in the same way and responded in the same way as their `klay` equivalents. These earlier versions of the `eth` APIs were intended to enable the use of Ethereum development tools on Klaytn; however, due to divergent data structures between Klaytn and Ethereum there were still interoperability problems with much of the Ethereum tooling and interfacing of third party software.
To solve this problem, the `eth` namespace APIs included in the latest Klaytn v1.8.0 release, have been calibrated to support the same request and response formats as those of the native Ethereum APIs. With the update of the eth namespace APIs and Klaytn v1.8.0 release, Ethereum development tools are now usable on Klaytn with immediate effect, and Ethereum dApps can now be migrated to Klaytn with minimal modification.
Below we have outlined some potential considerations for different types of API users.
Users of eth namespace APIs
If you are using `eth` namespace APIs with Geth client and Ethereum development tools (ethers.js, web3.js, hardhat, truffle, …), there are some considerations to be aware of regarding some changes in the features. In this document we are giving you a brief outline of the things to consider. You can find the details in Klaytn Docs — eth — Caution.
When you are using `eth` namespace APIs, some of the fields that are not used in Klaytn will return adjusted values.
The fields `mixHash`, `difficulty`, `nonce`, `gasLimit`, `sha3Uncles` and `uncles` are not used in Klaytn because Klaytn is not a PoW based chain, nor does it have uncle blocks produced in its consensus mechanism. Instead these fields will return fixed default values. Therefore, depending on the purpose, you may have to make some accommodations while using these fields because using them in your dApps may not be valid for some specific scenarios.
However, all other block fields not mentioned above will return values as expected. For more details on the return values of block fields, please refer to Klaytn Docs — eth — Block.
There are some other usage behaviors to consider for each data type commonly used in dApps:
When creating transactions
When you are generating and retrieving Ethereum-formatted transactions, you can use the `eth` namespace APIs the same way as you would in Ethereum. This is only true if you are dealing with transactions which are Ethereum-formatted (read more about Klaytn’s Ethereum format support at Klaytn Legacy Transaction format). In this case, you can use the `eth` namespace APIs to utilize the various Ethereum development tools on Klaytn and migrate Ethereum dApps to Klaytn with minimal changes.
However, please be aware that if you build and submit any non-Legacy Klaytn-formatted transactions (i.e., those transactions which are not specifically Ethereum-formatted) then there may be unexpected behaviors and incomplete data returned through the `eth` namespace API as explained in the next section below.
The full list of Klaytn transaction formats and comprehensive documentation of the Klaytn Transaction model can be found here.
When retrieving externally created transactions
Klaytn uses a robust transaction model which includes (but is not limited to) Ethereum-formatted transactions. Users should be aware that when using the `eth` namespace APIs, not all Klaytn transaction type data can be represented. When retrieving any Klaytn transaction data via the `eth` namespace APIs, that data will be returned in the Legacy Tx format. This means fields related to Klaytn-specific features (Fee Delegation, Account Key Update, Klaytn Transaction Types etc.) will not be included in `eth` namespace API responses.
Additionally, some fields may not be used when building certain Klaytn transactions (like `to`, `input` or `value`) and may return adjusted/default values for those missing fields in `eth` API responses depending on the transaction type. For more details, please refer to Klaytn Docs — eth — Transaction.
For the above reasons, when using a dApp to retrieve externally created transactions, it is recommended to use the namespace `klay` API to maintain consistent behaviors.
In cases where the developer is certain that all involved transactions are Ethereum-formatted, they could choose to use the `eth` API for data retrieval; however, be aware that on a decentralized network you may not have control over the format users would use to submit transactions to your contracts and you may need to handle non-Ethereum-formatted transaction cases.
Users of klay namespace APIs
Support for Ethereum APIs applies only to `eth` namespace APIs. If you are using `klay` namespace APIs via the Klaytn Client, or the Klaytn development tools (caver-js, caver-java, etc.), you can continue using all the features provided by Klaytn using the `klay` namespace APIs as normal.
The Klaytn team are excited to introduce these new features in the latest release of Klaytn v1.8.0 and can’t wait for the Klaytn community to use them. For more technical details regarding the contents of this article, please refer to Klaytn Docs — eth. Stay tuned to our social media for more updates and future Klaytn progress:
Article Series
