Skip to main content
Version: 1.3-rc1

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.

  • Ecosystem

    • 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.

Known Caveats

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.

EVM Revision

The maximum EVM revision supported is EVMC_BERLIN.


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 pCKB.

Account Abstraction

Polyjuice only provides contract accounts. Godwoken's user accounts are leveraged as EOAs.

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.

Transaction Structure

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 OpcodeSolidity UsageBehavior in PolyjuiceBehavior in EVM
COINBASEblock.coinbaseaddress of the block_produceraddress of the current block miner
GASLIMITblock.gaslimit12,500,000current block’s gas limit
DIFFICULTYblock.difficulty2,500,000,000,000,000current block’s difficulty


  • Transaction context

    • chain_id is defined in Godwoken RollupConfig#chain_id.
    • the block difficulty is always 2500000000000000.
    • 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.
  • The transfer value can not exceed uint128:MAX.

  • Pre-compiled contract

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. MUST be a Contract Address

The to member of a Godwoken transaction must be a contract address. Direct transfer of the value (pCKB) from EOA to EOA is not supported.


The to parameter of the following RPC methods must be a contract address, not an EOA address:

  • eth_call
  • eth_estimateGas
  • eth_sendRawTransaction

Recommend Workaround

Use the transfer function of the CKB_ERC20_Proxy contract combined with sudtId = 1 (CKB a.k.a. pCKB) to transfer assets from EOA To EOA.

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.

Recommend Workaround

Make sure to use the latest Ethereum toolchain, such as ether.js / web3.js / truffle / @truffle/hdwallet-provider, etc.

Zero Address

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 from/to field are not supported.

Recommend Workaround

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.