ethereum-optimism · karlfloersch · Jun 4, 2020 · May 2, 2020 · May 3, 2020 · May 3, 2020
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -0,0 +1,8 @@
+root: ./packages/docs/
+
+structure:  
+    readme: README.md  
+    summary: SUMMARY.md
+
+redirects:  
+    previous/page: new-folder/page.md
diff --git a/packages/docs/.gitbook/assets/rollup-contracts-overview.png b/packages/docs/.gitbook/assets/rollup-contracts-overview.png
diff --git a/packages/docs/.gitbook/assets/untitled-diagram-4.png b/packages/docs/.gitbook/assets/untitled-diagram-4.png
diff --git a/packages/docs/README.md b/packages/docs/README.md
@@ -0,0 +1,10 @@
+# Introduction
+
+Hello and welcome to the documentation for Optimism's OVM and Optimistic rollup.
+
+Our `@eth-optimism` module is the set of core modules that the OVM and our L2 implementations use.
+
+![The OVM Optipus](https://i.imgur.com/kWJ9eZ8.png)
+
+You can find all of our source code here in [our monorepo](https://github.com/ethereum-optimism/optimism-monorepo).
+
diff --git a/packages/docs/SUMMARY.md b/packages/docs/SUMMARY.md
@@ -0,0 +1,25 @@
+# Table of contents
+
+* [Introduction](README.md)
+* [Synthetix Demo FAQ](synthetix-l2.md)
+
+## Protocol Specifications
+
+* [Optimistic Ethereum](protocol-specifications/optimistic-ethereum.md)
+* [Optimistic Rollup](protocol-specifications/optimistic-rollup/README.md)
+  * [Block Production](protocol-specifications/optimistic-rollup/block-production.md)
+* [Optimistic VM \(OVM\)](protocol-specifications/ovm/README.md)
+  * [OVM Core Components](protocol-specifications/ovm/ovm-components.md)
+  * [Execution Manager Overview](protocol-specifications/ovm/execution-manager.md)
+  * [Transpilation Overview](protocol-specifications/ovm/transpiler.md)
+  * [JUMP Transpilation](protocol-specifications/ovm/jump-transpilation.md)
+  * [CODECOPY Transpilation](protocol-specifications/ovm/codecopy.md)
+
+## Developer Documentation
+
+* [Getting Started](developer-documentation/getting-started/README.md)
+  * [ERC20 Token Tutorial](developer-documentation/getting-started/do-yo-thang.md)
+* [Integrating the OVM](developer-documentation/erc20-tutorial/README.md)
+  * [Limitations](developer-documentation/erc20-tutorial/limitations.md)
+  * [Troubleshooting](developer-documentation/erc20-tutorial/troubleshooting.md)
+
diff --git a/packages/docs/developer-documentation/erc20-tutorial.md b/packages/docs/developer-documentation/erc20-tutorial.md
@@ -0,0 +1,2 @@
+# ERC20 Tutorial
+
diff --git a/packages/docs/developer-documentation/erc20-tutorial/README.md b/packages/docs/developer-documentation/erc20-tutorial/README.md
@@ -0,0 +1,130 @@
+# Integrating the OVM
+
+If you're interested in testing your contracts running on the OVM, then you're in the right place! Please note that the OVM is in alpha and, as such, you'll probably find some bugs. If you do, please drop us a line or open a github issue!
+
+There are two steps you need to take to get your contracts running on the ovm: using `@eth-optimism/solc-transpiler` in place of `solc` so your contracts can be transpiled into OVM-compatible versions, and using `@eth-optimism/rollup-full-node` as your web3 provider.
+
+For reference, example integrations for both Truffle and Waffle can be found [in our monorepo](https://github.com/ethereum-optimism/optimism-monorepo/tree/master/packages/examples) .
+
+### Integrating the OVM Transpiler
+
+#### Installing
+
+Both `truffle` and `ethereum-waffle` allow you to specify a custom replacement for `solc-js`. First, you'll need to install `@eth-optimism/solc-transpiler`:
+
+```bash
+yarn add @eth-optimism/solc-transpiler && yarn install
+```
+
+or
+
+```bash
+npm install --save @eth-optimism/solc-transpiler
+```
+
+`@eth-optimism/solc-transpiler` Accepts the same compiler options as as `solc`, with one additional option, `executionManagerAddress`. The Execution Manager is a smart contract implementing the OVM's containerization functionality. If you are using an unmodified `rollup-full-node`, the default execution manager address is `0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA`. More info on the execution manager can be found here. \(link\)
+
+#### Using With Waffle
+
+To use the transpiler with `ethereum-waffle`, set the `solc.version` configuration to `""@eth-optimism/solc-transpiler"` and `compilerOptions.executionManagerAddress` to `"0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA"`.
+
+example waffle-config.json:
+
+```javascript
+{
+  "solcVersion": "@eth-optimism/solc-transpiler",
+  "compilerOptions": {
+    "executionManagerAddress": "0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA"
+  }
+}
+```
+
+#### Using With Truffle
+
+To use the transpiler with Truffle, set truffle's `compilers.solc.version` configuration to `@eth-optimism/solc-transpiler`, and configure the `EXECUTION_MANAGER_ADDRESS` environment variable.
+
+Currently, Truffle does not provide a clean way to use custom chain IDs, so we have created the `@eth-optimism/ovm-truffle-provider-wrapper` package to seamlessly wrap your provider of choice to handle this. Note: you will also need to include `@eth-optimism/rollup-full-node` as a dependency if you would like to run a full node locally \(or use `ProviderWrapper.wrapProviderAndStartLocalNode(...)`\).
+
+example truffle-config.json:
+
+```javascript
+const HDWalletProvider = require('truffle-hdwallet-provider');
+const ProviderWrapper = require("@eth-optimism/ovm-truffle-provider-wrapper");
+const mnemonic = 'candy maple cake sugar pudding cream honey rich smooth crumble sweet treat';
+
+// Set this to the desired Execution Manager Address -- required for the transpiler
+process.env.EXECUTION_MANAGER_ADDRESS = process.env.EXECUTION_MANAGER_ADDRESS || "0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA"
+
+module.exports = {
+/**
+ * Note: this runs the OVM full node for the duration of the tests at `http://127.0.0.1:8545`
+ *
+ * To run tests:
+ * $ truffle test ./truffle-tests/test-erc20.js --config truffle-config-ovm.js
+ */
+networks: {
+  test: {
+    network_id: 108,
+    provider: function() {
+      return ProviderWrapper.wrapProviderAndStartLocalNode(new HDWalletProvider(mnemonic, "http://127.0.0.1:8545/", 0, 10));
+    },
+    gasPrice: 0,
+    gas: 9000000,
+  },
+  live_example: {
+    provider: function () {
+      return ProviderWrapper.wrapProvider(new HDWalletProvider(mnemonic, "http://127.0.0.1:8545/", 0, 10));
+    },
+    gasPrice: 0,
+    gas: 9000000,
+  },
+},
+
+// Set default mocha options here, use special reporters etc.
+mocha: {
+  timeout: 100000
+},
+
+compilers: {
+  solc: {
+    // Add path to the solc-transpiler
+    version: "@eth-optimism/solc-transpiler",
+  }
+}
+```
+
+}
+
+As you can see in the above comments, you must spin up the rollup full node before running truffle tests. To do this, with `@eth-optimism/rollup-full-node` installed, you can run:
+
+\`\`\` sourceCode bash node rollup-full-node/build/src/exec/fullnode.js
+
+```text
+Currently, `rollup-full-node` breaks Truffle's `gasLimit` and
+`blockGasLimit`. To avoid this, you can set both to `undefined` where
+they are used.
+
+## Integrating the OVM Full Node
+
+To use your transpiled contracts, you need to use
+`@eth-optimism/rollup-full-node` as your web3 provider. To do this, make
+sure it's installed:
+
+```bash
+yarn add @eth-optimism/rollup-full-node && yarn install
+```
+
+or
+
+```bash
+npm install --save @eth-optimism/rollup-full-node
+```
+
+To get your provider and some wallets:
+
+```typescript
+const RollupFullNode = require("@eth-optimism/rollup-full-node")
+const provider = RollupFullNode.getMockProvider()
+const wallets = RollupFullNode.getWallets(provider)
+```
+
diff --git a/packages/docs/developer-documentation/erc20-tutorial/limitations.md b/packages/docs/developer-documentation/erc20-tutorial/limitations.md
@@ -0,0 +1,16 @@
+# Limitations
+
+Some features of the Ethereum are not yet implemented, or just don't make sense to have, in the OVM. This page documents some of those differences.
+
+## No Native ETH
+
+On L1, sending/recieving ETH is a special opcode different from ERC20s. This often leads to developers having to implement their contract functionality twice. For the OVM, we decided to eliminate this complexity and enforce that ETH only exist as an ERC20 \(WETH\). We think this will make developers' lives easier--but if you feel strongly otherwise, reach out and let us know!
+
+## Block Number
+
+Many L2 constructions, including our rollup implementation, support instant, real-time transactions. One way this manifests is that `block.number` is not easily interpretable or specified in the OVM. Instead, contracts can use `block.timestamp` \(though right now, this is not implemented so it stays at 0.\)
+
+## Parent/Child chain communication
+
+Communication between L1 and L2, also known as deposits and withdrawals, are not yet implemented in the OVM. Stay tuned for more on this!
+
diff --git a/packages/docs/developer-documentation/erc20-tutorial/troubleshooting.md b/packages/docs/developer-documentation/erc20-tutorial/troubleshooting.md
@@ -0,0 +1,22 @@
+# Troubleshooting
+
+The OVM is an alpha. In trying it out, you're helping us scale Ethereum and pave the way for a new generation of Layer 2 systems. It also means you'll probably run into some bugs! If you do, please reach out to us and create an issue on our [monorepo](https://github.com/ethereum-optimism/optimism-monorepo).
+
+While you do so, here is a collection of tips and notes that may help you figure out what's going on.
+
+### Limitations
+
+Some features of the Ethereum are not yet implemented, or just don't make sense to have, in the OVM. Check out our limitations section \(link\) to get more information to check if this is why you're running into issues.
+
+### Logging
+
+We use the npm package`debug` for logging. To get a better sense of what might be breaking, you can run .. code-block:: none
+
+> env DEBUG="debug:_,error:_" \[test command\]
+
+in your terminal.
+
+### Getting Wallets
+
+`rollup-full-node` provides an RPC-based provider, and does not always allow you to getWallets\(\). Instead, use the getWallets\(\) function exported by `rollup-full-node` instead.
+
diff --git a/packages/docs/developer-documentation/getting-started/README.md b/packages/docs/developer-documentation/getting-started/README.md
@@ -0,0 +1,6 @@
+# Getting Started
+
+If you're looking to integrate with the OVM, welcome! You've come to the right place. Please note that the OVM is still in Alpha, and integrating now will inevitably uncover bugs. If you do, feel free to reach out to our [discord](https://discord.gg/cveQWV) or create a Github issue. We love talking to early adopters--don't be a stranger!
+
+To get you up to speed, you can follow along with our ERC20 conversion tutorial which takes a simple ERC20 EVM contract, and shows you how to transpile and run tests through the OVM. After that you will find some general notes on the current status of the OVM and helpful debugging tips.
+
diff --git a/packages/docs/developer-documentation/getting-started/cash.md b/packages/docs/developer-documentation/getting-started/cash.md
@@ -0,0 +1,2 @@
+# Some other child page
+
diff --git a/packages/docs/developer-documentation/getting-started/do-yo-thang.md b/packages/docs/developer-documentation/getting-started/do-yo-thang.md
@@ -0,0 +1,108 @@
+# ERC20 Token Tutorial
+
+## Getting Started with the OVM: Simple ERC20 Token Tutorial
+
+Hi there! Welcome to our OVM ERC20 tutorial.
+
+If you're interested in writing your first L2-compatible smart contract, you've come to the right place! This tutorial will cover how to move an existing contract and its tests into the wonderful world of L2.
+
+### Set up
+
+To start out, clone this example repo as a starting point.
+
+```bash
+git clone https://github.com/ethereum-optimism/ERC20-Example.git
+```
+
+Now, enter the repository
+
+```bash
+cd ERC20-Example
+```
+
+Install all dependencies
+
+```bash
+yarn install
+```
+
+This project represents a fresh, non-OVM ERC20 contract example. Feel free to stop here and have a quick look at the contract and tests.
+
+In this tutorial, we'll cover the steps required to bring it into the world of L2. First, let's make sure all of our tests are running in our normal Ethereum environment:
+
+```bash
+yarn test
+```
+
+You should see all of the tests passing. We're now ready to convert the project to build and test in an OVM environment!
+
+### Configuring the Transpiler
+
+First, we need to configure `ethereum-waffle` \(which is an alternative to truffle\) to use our new transpiler-enabled Solidity compiler. To do this, edit the `waffle-config.json` and replace it with:
+
+```javascript
+{
+  "sourcesPath": "./contracts",
+  "targetPath": "./build",
+  "npmPath": "./node_modules",
+  "solcVersion": "./node_modules/@eth-optimism/solc-transpiler",
+  "compilerOptions": {
+    "outputSelection": {
+      "*": {
+      "*": ["*"]
+    }
+  },
+    "executionManagerAddress": "0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA"
+  }
+}
+```
+
+### Using the Full Node
+
+To use the OVM to run our tests, open the test file at `test/erc20.spec.js`. We can import the OVM-ified versions of getWallets, createMockProvider, and deployContract near the top of the test file:
+
+```typescript
+const { createMockProvider, getWallets, deployContract } = require('@eth-optimism/rollup-full-node')
+```
+
+Now remove the duplicated imports from ethereum-waffle, replacing the import on Line 2 with:
+
+```typescript
+const {solidity} = require('ethereum-waffle');
+```
+
+Our imports at the top of the file should now look like:
+
+```typescript
+const {use, expect} = require('chai');
+const {solidity} = require('ethereum-waffle');
+const {createMockProvider, getWallets, deployContract } = require('@eth-optimism/rollup-full-node')
+const ERC20 = require('../build/ERC20.json');
+```
+
+We're almost there! After we've run our tests on the OVM, we need to stop our OVM server. We're going to add a single line of code after our before\(\) hook in order to close our OVM Server after our tests run:
+
+```typescript
+before(async () => {
+  provider = await createMockProvider()
+  const wallets = getWallets(provider)
+  wallet = wallets[0]
+  walletTo = wallets[1]
+})
+
+//ADD TO SUPPORT OVM
+after(() => {provider.closeOVM()})
+```
+
+### Running the New Tests
+
+Great, we're ready to go! Now you can try to re-run your tests on top of the OVM with
+
+```bash
+yarn test
+```
+
+### Wasn't that easy?
+
+The OVM provides a fresh new take on layer 2 development: it's identical to layer 1 development. No hoops, no tricks--the Ethereum you know and love, ready to scale up with L2. For more info on our progress and what's going on behind the scenes, you can follow us on [twitter](https://twitter.com/optimismPBC) and [check out our docs](https://docs.optimism.io)!
+
diff --git a/packages/docs/protocol-specifications/optimistic-ethereum.md b/packages/docs/protocol-specifications/optimistic-ethereum.md
@@ -0,0 +1,10 @@
+# Optimistic Ethereum
+
+![Optimistic Ethereum Protocol Stack](../.gitbook/assets/untitled-diagram-4%20%281%29.png)
+
+The Optimistic Ethereum protocol consists of three key components:
+
+1. Ethereum mainnet: the root of security for Optimistic Ethereum.
+2. Optimistic Rollup: the core scalability solution powering Optimistic Ethereum.
+3. The Optimistic VM \(OVM\): EVM-compliant execution environment enabling Optimistic Ethereum to function just like L1 Ethereum.
+
diff --git a/packages/docs/protocol-specifications/optimistic-rollup/README.md b/packages/docs/protocol-specifications/optimistic-rollup/README.md
@@ -0,0 +1,4 @@
+# Optimistic Rollup
+
+Optimistic Rollup is the core scaling solution which enables the off-chain OVM to acieve cheap, instant transactions that still inherit L1 security. This section is a WIP. If you're interested in how ORU works, you can read more at a high level [here](https://medium.com/plasma-group/ethereum-smart-contracts-in-l2-optimistic-rollup-2c1cef2ec537).
+
diff --git a/packages/docs/protocol-specifications/optimistic-rollup/block-production.md b/packages/docs/protocol-specifications/optimistic-rollup/block-production.md
@@ -0,0 +1,20 @@
+# Block Production
+
+![Overview of Optimistic Rollup block production contracts on L1 Ethereum.](../../.gitbook/assets/rollup-contracts-overview%20%281%29.png)
+
+## Canonical Transaction Chain
+
+This is a monotonically increasing list of transactions which is maintained in an Ethereum smart contract. It can never change & is only reverted if L1 Ethereum blocks are reverted. It is the final word on what transactions are applied to the rollup chain, and in what order. Transactions from this chain come from one of two "queues": the OVM Transaction queue, and the L1-&gt;L2 Transaction Queue.
+
+### OVM Transaction Queue
+
+This is where the sequencer is allowed to post transactions which they recieved off chain to be applied to the rollup chain. Transactions can only be moved from the OVM Transaction Queue to the Canonical Transaction Chain if the transactions in the L1-&gt;L2 transaction queue are not older than some number of L1 blocks.
+
+### L1-&gt;L2 Transaction queue
+
+This is where users who are being censored, as well as L1 contracts like deposit contracts, enqueue transactions to be added to the rollup chain. After some number of L1 blocks, the L1-&gt;L2 transactions _must be included_ next in the canonical transaction chain. This enforces censorship resistance.
+
+## State Commitment Chain
+
+The state commitment chain is a rollup list of OVM “outputs” \(namely, state roots and outgoing messages\) which must correspond to the canonical chain’s inputs. When a transaction is appended to the canonical transaction chain, there is only 1 valid state which should result. These outputs are committed by the sequencer, and rolled back in the case of fraud--without touching the canonical transactions.
+
diff --git a/packages/docs/protocol-specifications/ovm/README.md b/packages/docs/protocol-specifications/ovm/README.md
@@ -0,0 +1,18 @@
+# Optimistic VM \(OVM\)
+
+## What is the OVM?
+
+The Optimistic Virtual Machine \(OVM\) is a scalable form of the EVM. It lives at the core of [Optimistic Rollup](https://medium.com/plasma-group/ethereum-smart-contracts-in-l2-optimistic-rollup-2c1cef2ec537) \(ORU\) fullnodes and is able to execute Ethereum smart contracts at scale. It makes use of **optimistic execution**, allowing the blockchain to only evaluate smart contracts when there is fraud. This enables OVM computation to scale in the number of disputes as opposed to the number of transactions.
+
+### For Developers...
+
+The OVM is an EVM-based VM which supports optimistically executing EVM smart contracts on a layer 1 blockchain like Ethereum. It is structured in such a way that it is possible to verify individual steps of its computation on Ethereum mainnet. This allows the mainnet to enforce validity of state roots with fraud proofs in the layer 2 Optimistic Rollup chain.
+
+Each computational step is called a transition. These transitions can be evaluated off-chain as well as on-chain in an OVM [sandbox](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) to ensure their validity. Through techniques similar to a technique called [stateless clients](https://ethresear.ch/t/the-stateless-client-concept/172) originally developed for Eth2, each transition's validity may be evaluated efficiently & in isolation.
+
+### Why not just use the EVM?
+
+Unfortunately the EVM is not structured in a way that allows you to spawn sandboxed subprocesses. Without sandboxing, we are unable to verify the validity of ORU transitions, and therefore are unable to build an ORU compatible with the EVM.
+
+Thankfully, the EVM is turing complete & therefore flexible enough for us to embed this sandbox functionality directly inside of it. By embedding the OVM inside of the EVM, we're able to take advantage of all of the great work on the EVM while adding this critical feature that we need for ORU.
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# Optimistic Rollup

		Optimistic Rollup is the core scaling solution which enables the off-chain OVM to acieve cheap, instant transactions that still inherit L1 security. This section is a WIP. If you're interested in how ORU works, you can read more at a high level [here](https://medium.com/plasma-group/ethereum-smart-contracts-in-l2-optimistic-rollup-2c1cef2ec537).