|
| 1 | +# Tutorial |
| 2 | + |
| 3 | +Hello! |
| 4 | +This tutorial is an introduction to the process of developing applications on Optimistic Ethereum. |
| 5 | +Specifically, we'll take you through the process of building, testing, deploying, and interacting with a Solidity smart contract on top of the platform. |
| 6 | + |
| 7 | +Planned future iterations of this tutorial will include: |
| 8 | +- Communicating between Optimistic Ethereum and Ethereum. |
| 9 | +- Using more advanced Optimism tooling. |
| 10 | + |
| 11 | +## Prerequisite Software |
| 12 | +We make use of some external software throughout this tutorial. |
| 13 | +Please make sure you've installed the following before continuing: |
| 14 | + |
| 15 | +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) |
| 16 | +- [Node.js](https://nodejs.org/en/download/) |
| 17 | + |
| 18 | +## Setting Up |
| 19 | +We've structured this tutorial as a follow-along exercise where we'll be writing code in tandem. |
| 20 | +Please clone and enter [this repository](https://github.com/ethereum-optimism/optimism-tutorial): |
| 21 | + |
| 22 | +```sh |
| 23 | +git clone https://github.com/ethereum-optimism/optimism-tutorial |
| 24 | +cd optimism-tutorial |
| 25 | +``` |
| 26 | + |
| 27 | +We're using an Ethereum development framework called [Hardhat](https://hardhat.org) to make our lives a lot easier. |
| 28 | +If you haven't used Hardhat before, we hope you'll be pleasantly surprised! |
| 29 | +Hardhat is well designed and full of useful features. |
| 30 | +Go ahead and set up Hardhat by running: |
| 31 | + |
| 32 | +```sh |
| 33 | +yarn install |
| 34 | +``` |
| 35 | + |
| 36 | +We'll writing all of our smart contracts in Solidity and writing the rest of our code in TypeScript. |
| 37 | + |
| 38 | +## The Task |
| 39 | +We're going to be deploying an ERC20 contract (written in Solidity) to Optimistic Ethereum. |
| 40 | +We've already gone ahead and written that contract for you, which you should be able to locate in [`optimism-tutorial/contracts/ERC20.sol`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/contracts/ERC20.sol). |
| 41 | +This contract is just a relatively standard (though completely unsafe) ERC20 implementation. |
| 42 | + |
| 43 | +(**Note**: Seriously! This implementation is unsafe! Don't use it in production!) |
| 44 | + |
| 45 | +We'd recommend running the following command to compile this ERC20 contract. This will also make sure that Hardhat is installed correctly: |
| 46 | + |
| 47 | +```sh |
| 48 | +yarn compile |
| 49 | +``` |
| 50 | + |
| 51 | +## The Tests |
| 52 | +We've also written some very basic tests for you, which you can locate in [`optimism-tutorial/test/ERC20.spec.ts`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/test/ERC20.spec.ts). |
| 53 | +Though tests are pretty straight forward, we'd recommend taking a quick read through the test file. |
| 54 | +We're using [Ethers](https://docs.ethers.io/v5/) for the majority of our testing and [Waffle](https://ethereum-waffle.readthedocs.io/en/latest/) for some of its utilities. |
| 55 | +Hardhat provides convenient plugins for both; we've already added these plugins to [`optimism-tutorial/hardhat.config.ts`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/hardhat.config.ts). |
| 56 | + |
| 57 | +Once you've taken a look at the tests, feel free to verify that everything is working correctly by running the following command: |
| 58 | + |
| 59 | +```sh |
| 60 | +yarn test |
| 61 | +``` |
| 62 | + |
| 63 | +If everything is going as planned, you should see a bunch of green checkmarks. |
| 64 | + |
| 65 | +## Making it Optimistic |
| 66 | +Now that we've gotten that out of the way, it's time to get our ERC20 ready for Optimistic Ethereum. |
| 67 | +Contracts deployed to Optimistic Ethereum are required to replace certain EVM opcodes with custom behavior. |
| 68 | +Since the Solidity compiler doesn't handle this custom behavior, developers have to make sure to use the Optimism fork of the Solidity compiler instead. |
| 69 | +We'll need to add a special plugin to hardhat that enables this custom Optimism Solidity compiler. |
| 70 | + |
| 71 | +First, add the Optimism plugins package to your project: |
| 72 | + |
| 73 | +```sh |
| 74 | +yarn add @eth-optimism/plugins |
| 75 | +``` |
| 76 | + |
| 77 | +Next, add the following line to [`optimism-tutorial/hardhat.config.ts`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/hardhat.config.ts): |
| 78 | + |
| 79 | +```ts |
| 80 | +// hardhat.config.ts |
| 81 | + |
| 82 | +import '@eth-optimism/plugins/hardhat/compiler' |
| 83 | +``` |
| 84 | + |
| 85 | +Finally, compile it! |
| 86 | + |
| 87 | +```sh |
| 88 | +yarn compile |
| 89 | +``` |
| 90 | + |
| 91 | +Congrats, you're ready to deploy an application to Optimistic Ethereum! |
| 92 | +It really is that easy. |
| 93 | + |
| 94 | +You can verify that everything went well by checking the `artifacts` folder that should be generated whenever you run `yarn compile`. |
| 95 | +Alongside the normal compiler output located at `artifacts/contracts/ERC20.sol/ERC20.json`, you should also see `artifacts/contracts/ERC20.sol/ERC20.ovm.json`. |
| 96 | +Here, `.ovm.json` signifies that this file has been compiled for the OVM, the **O**ptimistic **V**irtual **M**achine, as opposed to the Ethereum Virtual Machine. |
| 97 | + |
| 98 | +### Testing (Again) |
| 99 | +We provided you with an ERC20 test file earlier in this tutorial. |
| 100 | +Now it's time to test this ERC20 again. |
| 101 | +This time, however, we'll be testing our new OVM-compatible smart contract on top of Optimistic Ethereum. |
| 102 | +Luckily, this is almost as easy as compiling the contract! |
| 103 | + |
| 104 | +First, make a copy of [`optimism-tutorial/test/ERC20.spec.ts`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/test/ERC20.spec.ts). |
| 105 | +You can name the copy whatever you'd like, perhaps `optimistic-ERC20.spec.ts`. |
| 106 | +We'll modify this copy in just a minute. |
| 107 | + |
| 108 | +Now we're going to add another Hardhat plugin to [`optimism-tutorial/hardhat.config.ts`](https://github.com/ethereum-optimism/optimism-tutorial/blob/master/hardhat.config.ts): |
| 109 | + |
| 110 | +```ts |
| 111 | +// hardhat.config.ts |
| 112 | + |
| 113 | +import '@eth-optimism/plugins/hardhat/compiler' // You already had this one. |
| 114 | +import '@eth-optimism/plugins/hardhat/ethers' // Now just add this one! |
| 115 | +``` |
| 116 | +
|
| 117 | +This plugin adds a new modified version of `ethers` to Hardhat that makes it possible to test the Layer 2 version of your contracts. |
| 118 | +
|
| 119 | +Finally, we're going to modify `optimistic-ERC20.spec.ts` (or whatever you named your copy of the original test file). |
| 120 | +Don't worry though, we only have to change a single line of code to make everything work! |
| 121 | +Find the line of code that looks like this: |
| 122 | +
|
| 123 | +```ts |
| 124 | +// optimistic-ERC20.spec.ts |
| 125 | + |
| 126 | +import { ethers } from 'hardhat' |
| 127 | +``` |
| 128 | + |
| 129 | +Now, replace that line of code with this: |
| 130 | + |
| 131 | +```ts |
| 132 | +// optimistic-ERC20.spec.ts |
| 133 | + |
| 134 | +import { l2ethers as ethers } from 'hardhat' |
| 135 | +``` |
| 136 | + |
| 137 | +You're all set! |
| 138 | +Confirm that everything worked as expected by running: |
| 139 | + |
| 140 | +```sh |
| 141 | +yarn test |
| 142 | +``` |
| 143 | + |
| 144 | +You should see even more green checkmarks this time around. |
0 commit comments