In this tutorial you will learn how to port an existing browser Ethereum application to run on Nervos' EVM compatible Layer 2.
MetaMask is the primary method of interacting with dApps on Nervos. The over user experience will be very similar to existing Ethereum. The one big difference is that the MetaMask confirmation dialog will ask them to sign a hex string instead of displaying transaction. This is normal behavior when using MetaMask on Nervos since MetaMask is currently not capable of deciphering a Godwoken transaction.
The eventual goal of Polyjuice is 100% compatibility with existing EVM smart contracts. However, this goal is still being worked on, and there will always be a few differences in the setup of the development environment and the tooling and frameworks that are used.
Note: Before starting the tasks, it is recommended that you review the Task Submission section so you know what materials you will need to provide to judges to review your task submission.
In this task, you will need to port over an existing Ethereum dApp to Nervos' Layer 2. Our examples will use the Simple Storage smart contract, but your submission must be significantly different. Using the Simple Storage smart contract is allowed, but only the end result of your dApp is significant different than the example. If it your application is too similar to the example, it will be rejected by the judges. Our general suggestion is that you take an existing Ethereum dApp that you are already familiar with, then make the changes required to port it to Nervos.
In this guide we assume you have application that is using Web3.js. Instructions for Ethers.js can be found in "Additional Tutorials and Code Resources".
Important: The example in this task uses the Simple Storage smart contract, but you cannot clone this code for your task. In order to get credit for this task you must use a different project.
Your MetaMask wallet should be installed and configured with the same Ethereum accounts from the previous tasks. Your MetaMask Ethereum account should still be funded on Layer 2 from the previous tasks.
Your MetaMask wallet will need to be configured to communicate with the Godwoken Layer 2 network. To do this, you will need to configure a new custom RPC. From the network selection dropdown, select "Custom RPC".
From there you will be presented with a form to specify the network settings.
Enter the following details.
Network Name: Godwoken Testnet
RPC URL: https://godwoken-testnet-web3-rpc.ckbapp.dev
Chain ID: 71393
Currency Symbol: <Leave Empty>
Block Explorer URL: <Leave Empty>After MetaMask is configured you may see a zero balance even after you have deposited funds into this Ethereum address on Layer 2. Don't be alarmed by this. Later on we will show you how to setup your application to call web3.eth.getBalance with your Ethereum address to query for your balance.
A simple Ethereum demo application has been built to use the Simple Storage to read and write number values. We will walk through this Ethereum application, and demonstrate the changes needed to make this run on Nervos' Layer 2.
We recommend that you clone the source code and follow along with our explanations so you become familiar with the process invovled in porting an application.
Note: Remember, the application you submit must be different from our example. This guide will walk you through the process, but you must port over a different application to submit your task.
First, we need to clone the repo. This contains the Ethereum version of the application before it has been updated to support Godwoken.
Create ~/projects directory if it doesn't exist.
Linux/MacOS:
mkdir -p ~/projectsWindows (PowerShell):
New-Item -ItemType Directory -Force -Path ~/projectsEnter the ~/projects directory and clone the repository.
cd ~/projects
git clone https://github.com/Kuzirashi/blockchain-workshop.git -b ethereum-simple blockchain-workshop-ethereum-simple
cd blockchain-workshop-ethereum-simpleNext, install the dependencies, build the smart contracts, and start Ganache to run a local Ethereum development chain.
cd ~/projects/blockchain-workshop-ethereum-simple
yarn
yarn build
yarn start:ganacheGanache should now be running and creating blocks.
Switch back to your web browser. Open MetaMask and switch your network to Localhost 8545. It should switch and connect without giving an error now that Ganache is running.
In a second terminal, start the UI server.
cd ~/projects/blockchain-workshop-ethereum-simple
yarn uiThe server should now be started, and you can open a browser tab to http://localhost:3000 to view the dApp UI!
Now we will begin porting this Ethereum application to use Nervos' Layer 2. The first step is to install the required dependencies for working with Godwoken and Polyjuice. Use the following command in the main project directory to install these dependencies in your application.
cd ~/projects/blockchain-workshop-ethereum-simple
yarn add @polyjuice-provider/web3@0.0.1-rc11 nervos-godwoken-integration@0.0.8@polyjuice-provider/web3is a custom Polyjuice web3 provider. It is required for interaction with Nervos' Layer 2 smart contracts.nervos-godwoken-integrationis a tool that can generate Polyjuice address based on your Ethereum address. You might be required to use Polyjuice address if you store values mapped to addresses in your contracts.
The next step is to configure the Polyjuice Web3 Provider for the application. This replaces the normal web3 provider that may be currently in use for Ethereum with one for the Godwoken Testnet.
The example below is just for demonstration of how your configuration file could look. You will not find it in any of the example project source files.
export const CONFIG = {
WEB3_PROVIDER_URL: 'http://localhost:8545'
};is changed to:
export const CONFIG = {
WEB3_PROVIDER_URL: 'https://godwoken-testnet-web3-rpc.ckbapp.dev'
};Note: Your configuration might be using
localhost:8545, or some other settings for some other service like Infura.
Above config will be needed by our project, so we are creating a new config file called config.ts to our source code. This is example path for the config you can use: ~/projects/blockchain-workshop-ethereum-simple/src/config.ts.
We will use this config in a moment, but first we need to import a few dependencies. We will update the main UI in the file ~/projects/blockchain-workshop-ethereum-simple/src/ui/app.tsx.
Next, we add the following lines in the main dependency importation section of the file.
import { PolyjuiceHttpProvider } from '@polyjuice-provider/web3';
import { CONFIG } from '../config';This imports the Polyjuice Web3 Provider, which we will use in a moment, and the config file that we just created.
Next we prepare a few constants, create the Polyjuice Provider, and use the Polyjuice Provider with a Web3 instance.
const providerConfig = {
web3Url: CONFIG.WEB3_PROVIDER_URL
};
const provider = new PolyjuiceHttpProvider(providerConfig.web3Url, providerConfig);
const web3 = new Web3(provider);The above code is a Web3 instance using a Polyjuice Web3 Provider. We will just call it "Polyjuice Web3" for short. We need to take this code and replace the existing Ethereum Web3 instance. In app.tsx, locate the existing Web3 instance, which should match the line below.
const web3 = new Web3((window as any).ethereum);Delete this line, and replace it with the Polyjuice Web3 code from above. Now our application is setup to communicate with Polyjuice using Web3!
Godwoken requires the gas limit to be set when sending transactions. This may not always be the case in the future, but it is a requirement for the current version on the Testnet.
To accomodate for this, we can make a simple change to default the gas limit to 6000000 for the user when they make transactions. In our project, this is all handled in the file SimpleStorageWrapper.ts. Open the file ~/projects/blockchain-workshop-ethereum-simple/src/lib/contracts/SimpleStorageWrapper.ts in your editor.
First, we define a simple object that contains the gas property used by MetaMask.
const DEFAULT_SEND_OPTIONS = {
gas: 6000000
};This can be added in the top region of the file, and we will be using this constant in several other places.
We will be adding it into the object passed to send() as the default values. For example, this code:
this.contract.methods.set(value).send({
from: fromAddress
});is changed to:
this.contract.methods.set(value).send({
...DEFAULT_SEND_OPTIONS,
from: fromAddress
});Every Ethereum address can be translated into a Polyjuice address on Nervos' Layer 2. This can be done using the AddressTranslator class. We will show the basic code here, but we will not cover the necessary changes for React to display it.
import { AddressTranslator } from 'nervos-godwoken-integration';We can then use the following code to find the Polyjuice address.
const addressTranslator = new AddressTranslator();
const polyjuiceAddress = addressTranslator.ethAddressToGodwokenShortAddress(ethereumAddress);We covered the main code changes required to port an Ethereum application to Nervos, but several small other changes were also necessary to display the new information in React. We didn't cover this since it is out of scope of this guide.
To view the final ported application you can checkout the godwoken-simple branch of the project using the commands below.
Note: If you still have the Ethereum version of the project running, make sure to shut it down before launching the Godwoken version.
git clone https://github.com/Kuzirashi/blockchain-workshop.git -b godwoken-simple blockchain-workshop-godwoken-simple
cd blockchain-workshop-godwoken-simple
yarn
yarn build
yarn uiThis will start the UI server, and you can now open http://localhost:3000 in a browser. Once your browser is open, change your MetaMask network to Godwoken Testnet, which we setup earlier in this guide.
You can now try out the application running on the Godwoken Testnet!
- If you get a CORS error in your web browser's console, try searching your code for a Godwoken RPC URL that is not using
https. Change any instances ofhttp://godwoken-testnet-web3-rpc.ckbapp.devtohttps://godwoken-testnet-web3-rpc.ckbapp.dev.
To complete the tasks, add the following materials to a document on your Github and submit for review by the judges (include the link in your Gitcoin submission):
- Screenshots or video of your application running on Godwoken.
- Link to the GitHub repository with your application which has been ported to Godwoken. This must be a different application than the one covered in this guide.
- If you deployed any smart contracts as part of this tutorial, please provide the transaction hash of the deployment transaction, the deployed contract address, and the ABI of the deployed smart contract. (Provide all in text format.)
Instructions how to migrate your dApp if you're using web3.js can be found here.
Instructions how to migrate your dApp if you're using ethers.js can be found here.
There are a number of small differences that can potentially impact your application and cause problems if you're not aware of them. A list of these differences can be found here.
If you need to use ecrecover you will have to modify your smart-contracts to do an internal system call using assembly. You can find documentation for that syscall here, there is an example code.
If you need more examples of working Nervos' Layer 2 applications you can take a look at the following repositories: