Integration Guide for Ethereum Developers
This documentation can be used as an integration guide for wallets and exchanges or as a reference for developing dApps on Godwoken. It explains the rationale for developing decentralized applications using Godwoken, the known caveats of version 1 and corresponding workarounds, as well as providing hands-on training on integrating Ethereum dApps with CKB through Godwoken.
Prior knowledge of Ethereum is required for using this guide.
If you want to obtain direct experience and prepare yourself for deploying applications, you can check out the Layer 2 EVM Training section for a hands-on trial of developing your own EVM dapps on the Nervos platform.
Why Develop on Godwoken?
Security - Nervos Network is a Proof-of-Work (PoW) layer 1 chain, and Godwoken is an optimistic rollup layer 2 chain built on Nervos Network. The security model is quite different from other EVM-compatible PoS/DPoS/PoA chains or sidechains.
Low-cost - A typical Godwoken transaction currently costs less than $0.01.
- With Force Bridge, assets from 3 chains (Nervos, Ethereum and BSC) are already available on Godwoken. The support for more chains (Cardano, BTC) is on the way.
Interoperability 2.0 - This may be the trump card of Godwoken. With the design abstractions of Nervos Network and Godwoken, it is possible to use any on-chain tool to port smart contracts to manipulate assets on the corresponding chain.
Godwoken V1 is still under development and targets 100% EVM compatibility. Having the best compatibility is the objective of designing and building Godwoken:
- The EVM being used in Godwoken must be 100% compatible with the latest forked version of Ethereum.
- Godwoken must be 100% compatible with Ethereum over the Web3 interfaces by using Godwoken Web3.
Several discrepancies inevitably exist due to the wide architectural and design differences between Godwoken and Ethereum.
Comparison with EVM
Godwoken targets 100% EVM compatibility and is designed to work with every smart contract that the latest Ethereum hard fork version supports. But, the current version is not yet fully compatible with EVM.
The maximum EVM revision supported is
Godwoken v1 introduced a new concept, pCKB which is a defined layer-2 sUDT token type when deploying a Godwoken chain.
pCKB serves a similar purpose for the Godwoken chain as ETH does for the Ethereum chain, in the sense that it is used for collecting transaction fees. In Ethereum, the gas for each smart contract is derived by calculation. And the transaction fee is then calculated by multiplying the gas by the specified gas price. In Godwoken, pCKB is the unit for calculating transaction fees. In other words, the gas price in Ethereum is calculated as ETH/gas (in wei, i.e., 10-18 ETH), and the gas price in Godwoken is calculated as pCKB/gas. When Godwoken executes a transaction, it will deduct the transaction fee by using layer-2 sUDT type, which is represented by pCKB.
Godwoken chain uses CKB as pCKB by default, while different Godwoken chains may use different token types as pCKB.
Note: With certain transactions being sent to the smart contract, the
value of the transaction is
Polyjuice only provides contract accounts. Godwoken's user accounts are leveraged as EOAs.
sUDT-ERC20 proxy contract
When you use a sUDT token type, it will be represented in Godwoken as a layer-2 sUDT type. Polyjuice ensures that all the layer-2 sUDT tokens on Godwoken are in compliance with the ERC20 standard by the sUDT-ERC20 Proxy Contract. This contract provides a way for EVM code to interact with ERC20 standard interface to operate sUDT tokens on Godwoken as if they were ERC20 tokens.
In other words, all bridged sUDT tokens have the same ERC20 interface thanks to the 1-to-1 sUDT-ERC20 proxy contract:
Bridged sUDT Token List
- mainnet_v1: https://github.com/godwokenrises/godwoken-info/blob/main/mainnet_v1/bridged-token-list.json
- testnet_v1: https://github.com/godwokenrises/godwoken-info/blob/main/testnet_v1_1/bridged-token-list.json
A Polyjuice transaction is essentially a Godwoken transaction. When Ethereum transactions are sent, they are converted to the Godwoken RawL2Transaction type when being sent and are automatically processed by Godwoken Web3.
Behavioral Differences of Some Opcodes
|EVM Opcode||Solidity Usage||Behavior in Polyjuice||Behavior in EVM|
|COINBASE||block.coinbase||address of the block_producer||address of the current block miner|
|GASLIMIT||block.gaslimit||12,500,000||current block’s gas limit|
|DIFFICULTY||block.difficulty||2,500,000,000,000,000||current block’s difficulty|
Restriction of Memory Usage
Polyjuice runs EVM on CKB-VM. EVM has no limit on memory usage, yet EVM has a limit of 1024 on stack depth. But, CKB-VM can currently use a maximum of 4MB of memory, of which 3MB is for heap space and 1MB is for stack space. For more information, refer here.
chain_idis defined in Godwoken RollupConfig#chain_id.
- the block difficulty is always
- the gas limit is 12500000 per block, but it is not a transaction-level limit. Any transaction can reach the gas limit.
- the size limit for contract's return data is
- the size limit for contract's storage is
transaction.toMUST be a Contract Address.
transfer valuecan not exceed
uint128:MAX, because the type of sUDT.amount is
Godwoken Web3 Compatibility
Godwoken Web3 is a Web3 RPC compatible layer developed on top of Godwoken.
1. Gas Limit
Godwoken applies the Cycle Limit to limit transaction execution resources in CKB-VM. By setting the
50000000 to maximise the compatibility with Ethereum toolchain, but the real gas limit that users can utilize relies on this Cycle Limit.