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 with 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
All Tokens Are ERC20 Tokens
Ethereum processes ERC20 tokens differently from native ETH tokens, which is the reason wETH was invented. However, Godwoken conceals this difference.
All tokens on Godwoken are represented as Layer 2 sUDT types, regardless of whether they are native CKB or any sUDT types. Polyjuice proceeds from this Layer 2 sUDT contract and ensures that all tokens on Godwoken are ERC20 compliant, regardless of whether supported by native CKB or sUDT. That is to say, it is unnecessary to distinguish between native tokens and ERC20 tokens. All the different tokens must be handled with the same ERC20 interface.
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|
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 25600B.
- the size limit for contract's storage is 25600B.
transfer valuecan not exceed uint128:MAX.
bn256_pairingis not yet supported because of the high cycle cost (WIP)
- addition pre-compiled contracts
Godwoken Web3 API Compatibility
Godwoken Web3 API is a Web3 RPC compatible layer developed on top of Godwoken.
For more information about the usage, see Ethereum RPC docs.
transaction.to MUST be a Contract Address
to member of a Godwoken transaction must be a contract address. Direct transfer of the value (pCKB) from EOA to EOA is not supported.
to parameter of the following RPC methods must be a contract address, not an EOA address:
Signing Transaction Only Support EIP155
Currently, we only support the EIP155 signing scheme that incorporated
CHAIN_ID for simple replay attack protection.
If you use an outdated Ethereum toolchain to send transactions, such as
truffle-hdwallet-provider, you will experience failures.
Godwoken does not support the concept of zero address (0x0000000000000000000000000000000000000000). This means that Polyjuice cannot support the zero address as well.
Transactions with the zero address in the
to field are not supported.
To use the zero address as a black hole to burn ethers, you can use the transfer function of the CKB_ERC20_Proxy contract to send ethers to the zero address.
For more information on the compatibility changes of Godwoken Web3 API, see compatibility-breaking-changes.
A Layer 2 Account is Mandatory
It is mandatory to create an account on a Godwoken chain for using Godwoken and Polyjuice.
There are two ways to create a layer 2 account:
- Deposit to Godwoken at layer 1;
- Call the Godwoken built-in meta_contract and create an account at layer 2.