docs: add waffle example + ci (#665)

* git reset to reorder dirs

* fix: typos

* chore(waffle-example): make tests pass
Co-authored-by: Georgios Konstantopoulos <me@gakonst.com>

.github/workflows/integration.yml

@@ -63,3 +63,14 @@ jobs:
         run: |
           yarn deploy:ovm
           yarn test:ovm
+
+      - name: Test & deploy waffle-example on waffle (regression)
+        working-directory: ./examples/waffle
+        run: |
+          yarn compile
+          yarn test
+      - name: Test & deploy waffle-example on Optimism
+        working-directory: ./examples/waffle
+        run: |
+          yarn compile:ovm
+          yarn test:ovm

examples/waffle/.gitignore

+build/
+build-ovm/

examples/waffle/.prettierrc.json

+../../.prettierrc.json
\ No newline at end of file

examples/waffle/LICENSE

+MIT License
+
+Copyright (c) 2021 OptimismPBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/waffle/README.md

+# Getting Started with the Optimistic Ethereum: Simple ERC20 Token Waffle Tutorial
+
+### For the full README, please see the [guided repository, `Waffle-ERC20-Example`](https://github.com/ethereum-optimism/Waffle-ERC20-Example)
\ No newline at end of file

examples/waffle/contracts/ERC20.sol

+// SPDX-License-Identifier: MIT LICENSE
+/*
+Implements ERC20 token standard: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
+.*/
+
+pragma solidity ^0.7.6;
+
+import "./IERC20.sol";
+
+contract ERC20 is IERC20 {
+    uint256 private constant MAX_UINT256 = 2**256 - 1;
+    mapping(address => uint256) public balances;
+    mapping(address => mapping(address => uint256)) public allowed;
+    /*
+    NOTE:
+    The following variables are OPTIONAL vanities. One does not have to include them.
+    They allow one to customise the token contract & in no way influences the core functionality.
+    Some wallets/interfaces might not even bother to look at this information.
+    */
+    string public name; //fancy name: eg OVM Coin
+    uint8 public decimals; //How many decimals to show.
+    string public symbol; //An identifier: eg OVM
+    uint256 public override totalSupply;
+
+    constructor(
+        uint256 _initialAmount,
+        string memory _tokenName,
+        uint8 _decimalUnits,
+        string memory _tokenSymbol
+    ) {
+        balances[msg.sender] = _initialAmount; // Give the creator all initial tokens
+        totalSupply = _initialAmount; // Update total supply
+        name = _tokenName; // Set the name for display purposes
+        decimals = _decimalUnits; // Amount of decimals for display purposes
+        symbol = _tokenSymbol; // Set the symbol for display purposes
+    }
+
+    function transfer(address _to, uint256 _value)
+        external
+        override
+        returns (bool success)
+    {
+        require(balances[msg.sender] >= _value);
+        balances[msg.sender] -= _value;
+        balances[_to] += _value;
+        emit Transfer(msg.sender, _to, _value);
+        return true;
+    }
+
+    function transferFrom(
+        address _from,
+        address _to,
+        uint256 _value
+    ) external override returns (bool success) {
+        uint256 allowance_ = allowed[_from][msg.sender];
+        require(balances[_from] >= _value && allowance_ >= _value);
+        balances[_to] += _value;
+        balances[_from] -= _value;
+        if (allowance_ < MAX_UINT256) {
+            allowed[_from][msg.sender] -= _value;
+        }
+        emit Transfer(_from, _to, _value);
+        return true;
+    }
+
+    function balanceOf(address _owner)
+        external
+        view
+        override
+        returns (uint256 balance)
+    {
+        return balances[_owner];
+    }
+
+    function approve(address _spender, uint256 _value)
+        external
+        override
+        returns (bool success)
+    {
+        allowed[msg.sender][_spender] = _value;
+        emit Approval(msg.sender, _spender, _value);
+        return true;
+    }
+
+    function allowance(address _owner, address _spender)
+        external
+        view
+        override
+        returns (uint256 remaining)
+    {
+        return allowed[_owner][_spender];
+    }
+}

examples/waffle/contracts/IERC20.sol

+// SPDX-License-Identifier: MIT LICENSE
+// Abstract contract for the full ERC 20 Token standard
+// https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
+pragma solidity ^0.7.6;
+
+interface IERC20 {
+    /* This is a slight change to the ERC20 base standard.
+    function totalSupply() constant returns (uint256 supply);
+    is replaced with:
+    uint256 public totalSupply;
+    This automatically creates a getter function for the totalSupply.
+    This is moved to the base contract since public getter functions are not
+    currently recognised as an implementation of the matching abstract
+    function by the compiler.
+    */
+    /// total amount of tokens
+    function totalSupply() external view returns (uint256);
+
+    /// @param _owner The address from which the balance will be retrieved
+    /// @return balance
+    function balanceOf(address _owner) external view returns (uint256 balance);
+
+    /// @notice send `_value` token to `_to` from `msg.sender`
+    /// @param _to The address of the recipient
+    /// @param _value The amount of token to be transferred
+    /// @return success Whether the transfer was successful or not
+    function transfer(address _to, uint256 _value)
+        external
+        returns (bool success);
+
+    /// @notice send `_value` token to `_to` from `_from` on the condition it is approved by `_from`
+    /// @param _from The address of the sender
+    /// @param _to The address of the recipient
+    /// @param _value The amount of token to be transferred
+    /// @return success Whether the transfer was successful or not
+    function transferFrom(
+        address _from,
+        address _to,
+        uint256 _value
+    ) external returns (bool success);
+
+    /// @notice `msg.sender` approves `_spender` to spend `_value` tokens
+    /// @param _spender The address of the account able to transfer the tokens
+    /// @param _value The amount of tokens to be approved for transfer
+    /// @return success Whether the approval was successful or not
+    function approve(address _spender, uint256 _value)
+        external
+        returns (bool success);
+
+    /// @param _owner The address of the account owning tokens
+    /// @param _spender The address of the account able to transfer the tokens
+    /// @return remaining Amount of remaining tokens allowed to spent
+    function allowance(address _owner, address _spender)
+        external
+        view
+        returns (uint256 remaining);
+
+    // solhint-disable-next-line no-simple-event-func-name
+    event Transfer(address indexed _from, address indexed _to, uint256 _value);
+    event Approval(
+        address indexed _owner,
+        address indexed _spender,
+        uint256 _value
+    );
+}

examples/waffle/package.json

+{
+  "name": "@eth-optimism/ERC20-Example",
+  "version": "0.0.1-alpha.1",
+  "description": "Basic example of how to test a basic token contract with Waffle in the OVM",
+  "scripts": {
+    "clean": "rimraf build",
+    "compile": "waffle",
+    "compile:ovm": "waffle waffle-ovm.json",
+    "test": "mocha 'test/*.spec.js' --timeout 10000",
+    "test:ovm": "TARGET=OVM mocha 'test/*.spec.js' --timeout 50000"
+  },
+  "keywords": [
+    "optimism",
+    "rollup",
+    "optimistic",
+    "ethereum",
+    "virtual",
+    "machine",
+    "OVM",
+    "ERC20",
+    "waffle"
+  ],
+  "homepage": "https://github.com/ethereum-optimism/ERC20-Example#readme",
+  "license": "MIT",
+  "author": "Optimism PBC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethereum-optimism/ERC20-Example.git"
+  },
+  "devDependencies": {
+    "chai": "^4.3.4",
+    "dotenv": "^8.2.0",
+    "ethereum-waffle": "^3.0.0",
+    "mocha": "^7.0.1",
+    "rimraf": "^2.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@eth-optimism/solc": "0.7.6-alpha.1",
+    "solc": "0.7.6"
+  }
+}
\ No newline at end of file

examples/waffle/test/erc20.spec.js

+/* External imports */
+require('dotenv/config')
+const { use, expect } = require('chai')
+const { ethers } = require('ethers')
+const { solidity } = require('ethereum-waffle')
+
+/* Internal imports */
+const { getArtifact } = require('./getArtifact')
+
+use(solidity)
+
+describe('ERC20 smart contract', () => {
+  let ERC20,
+    provider,
+    wallet,
+    walletTo,
+    walletEmpty,
+    walletAddress,
+    walletToAddress,
+    walletEmptyAddress
+
+  const privateKey = ethers.Wallet.createRandom().privateKey
+  const privateKeyEmpty = ethers.Wallet.createRandom().privateKey
+  const useL2 = process.env.TARGET === 'OVM'
+
+  if (useL2 == true) {
+    provider = new ethers.providers.JsonRpcProvider('http://127.0.0.1:8545')
+    provider.pollingInterval = 100
+    provider.getGasPrice = async () => ethers.BigNumber.from(0)
+  } else {
+    provider = new ethers.providers.JsonRpcProvider('http://127.0.0.1:9545')
+  }
+
+  walletTo = new ethers.Wallet(privateKey, provider)
+  walletEmpty = new ethers.Wallet(privateKeyEmpty, provider)
+
+  // parameters to use for our test coin
+  const COIN_NAME = 'OVM Test Coin'
+  const TICKER = 'OVM'
+  const NUM_DECIMALS = 1
+
+  describe('when using a deployed contract instance', () => {
+    before(async () => {
+      wallet = await provider.getSigner(0)
+      walletAddress = await wallet.getAddress()
+      walletToAddress = await walletTo.getAddress()
+      walletEmptyAddress = await walletEmpty.getAddress()
+
+      const Artifact__ERC20 = getArtifact(useL2)
+      const Factory__ERC20 = new ethers.ContractFactory(
+        Artifact__ERC20.abi,
+        Artifact__ERC20.bytecode,
+        wallet
+      )
+
+      // TODO: Remove this hardcoded gas limit
+      ERC20 = await Factory__ERC20.connect(wallet).deploy(
+        1000,
+        COIN_NAME,
+        NUM_DECIMALS,
+        TICKER,
+        { gasLimit: 8_000_000 }
+      )
+      await ERC20.deployTransaction.wait()
+    })
+
+    it('should assigns initial balance', async () => {
+      expect(await ERC20.balanceOf(walletAddress)).to.equal(1000)
+    })
+
+    it('should correctly set vanity information', async () => {
+      const name = await ERC20.name()
+      expect(name).to.equal(COIN_NAME)
+
+      const decimals = await ERC20.decimals()
+      expect(decimals).to.equal(NUM_DECIMALS)
+
+      const symbol = await ERC20.symbol()
+      expect(symbol).to.equal(TICKER)
+    })
+
+    it('should transfer amount to destination account', async () => {
+      const tx = await ERC20.connect(wallet).transfer(walletToAddress, 7)
+      await tx.wait()
+      const walletToBalance = await ERC20.balanceOf(walletToAddress)
+      expect(walletToBalance.toString()).to.equal('7')
+    })
+
+    it('should emit Transfer event', async () => {
+      const tx = ERC20.connect(wallet).transfer(walletToAddress, 7)
+      await expect(tx)
+        .to.emit(ERC20, 'Transfer')
+        .withArgs(walletAddress, walletToAddress, 7)
+    })
+
+    it('should not transfer above the amount', async () => {
+      const walletToBalanceBefore = await ERC20.balanceOf(walletToAddress)
+      await expect(ERC20.transfer(walletToAddress, 1007)).to.be.reverted
+      const walletToBalanceAfter = await ERC20.balanceOf(walletToAddress)
+      expect(walletToBalanceBefore).to.eq(walletToBalanceAfter)
+    })
+
+    it('should not transfer from empty account', async () => {
+      const ERC20FromOtherWallet = ERC20.connect(walletEmpty)
+      await expect(ERC20FromOtherWallet.transfer(walletEmptyAddress, 1)).to.be
+        .reverted
+    })
+  })
+})

examples/waffle/test/getArtifact.js

+const getArtifact = (useL2) => {
+  const buildFolder = useL2 ? 'build-ovm' : 'build'
+  const ERC20Artifact = require(`../${buildFolder}/ERC20.json`)
+  return ERC20Artifact
+}
+
+module.exports = { getArtifact }

examples/waffle/waffle-ovm.json

+{
+  "compilerVersion": "./node_modules/@eth-optimism/solc",
+  "sourceDirectory": "./contracts",
+  "outputDirectory": "./build-ovm"
+}
\ No newline at end of file

examples/waffle/waffle.json

+{
+  "compilerVersion": "./../../node_modules/solc",
+  "sourceDirectory": "./contracts",
+  "outputDirectory": "./build"
+}

yarn.lock

@@ -230,6 +230,21 @@
   resolved "https://registry.yarnpkg.com/@ensdomains/resolver/-/resolver-0.2.4.tgz#c10fe28bf5efbf49bff4666d909aed0265efbc89"
   integrity sha512-bvaTH34PMCbv6anRa9I/0zjLJgY4EuznbEMgbV77JBCQ9KNC46rzi0avuxpOfu+xDjPEtSFGqVEOr5GlUSGudA==
 
+"@eth-optimism/solc@0.7.6-alpha.1":
+  version "0.7.6-alpha.1"
+  resolved "https://registry.yarnpkg.com/@eth-optimism/solc/-/solc-0.7.6-alpha.1.tgz#f503073161fdc0029dbc1dae6fae28eeb046b559"
+  integrity sha512-tVYeBtjwNRUDmaTdJNlKI0lTM0yV1hez0jPFOtACoepBwBEZOuuFLBgQLBOWPaR95UU2ke1YjqB7rrpkE3oRDg==
+  dependencies:
+    command-exists "^1.2.8"
+    commander "3.0.2"
+    follow-redirects "^1.12.1"
+    fs-extra "^0.30.0"
+    js-sha3 "0.8.0"
+    memorystream "^0.3.1"
+    require-from-string "^2.0.0"
+    semver "^5.5.0"
+    tmp "0.0.33"
+
 "@eth-optimism/solc@^0.6.12-alpha.1":
   version "0.6.12-alpha.1"
   resolved "https://registry.yarnpkg.com/@eth-optimism/solc/-/solc-0.6.12-alpha.1.tgz#041876f83b34c6afe2f19dfe9626568df6ed8590"
@@ -5586,7 +5601,7 @@ ethereum-waffle@3.0.0:
     "@ethereum-waffle/provider" "^3.0.0"
     ethers "^5.0.1"
 
-ethereum-waffle@^3.3.0:
+ethereum-waffle@^3.0.0, ethereum-waffle@^3.3.0:
   version "3.3.0"
   resolved "https://registry.yarnpkg.com/ethereum-waffle/-/ethereum-waffle-3.3.0.tgz#166a0cc1d3b2925f117b20ef0951b3fe72e38e79"
   integrity sha512-4xm3RWAPCu5LlaVxYEg0tG3L7g5ovBw1GY/UebrzZ+OTx22vcPjI+bvelFlGBpkdnO5yOIFXjH2eK59tNAe9IA==
@@ -9257,7 +9272,7 @@ mocha@^6.1.4:
     yargs-parser "13.1.2"
     yargs-unparser "1.6.0"
 
-mocha@^7.1.1, mocha@^7.1.2:
+mocha@^7.0.1, mocha@^7.1.1, mocha@^7.1.2:
   version "7.2.0"
   resolved "https://registry.yarnpkg.com/mocha/-/mocha-7.2.0.tgz#01cc227b00d875ab1eed03a75106689cfed5a604"
   integrity sha512-O9CIypScywTVpNaRrCAgoUnJgozpIofjKUYmJhiCIJMiuYnLI6otcb1/kpW9/n/tJODHGZ7i8aLQoDVsMtOKQQ==
@@ -11801,6 +11816,21 @@ solc@0.7.3:
     semver "^5.5.0"
     tmp "0.0.33"
 
+solc@0.7.6:
+  version "0.7.6"
+  resolved "https://registry.yarnpkg.com/solc/-/solc-0.7.6.tgz#21fc5dc11b85fcc518c181578b454f3271c27252"
+  integrity sha512-WsR/W7CXwh2VnmZapB4JrsDeLlshoKBz5Pz/zYNulB6LBsOEHI2Zj/GeKLMFcvv57OHiXHvxq5ZOQB+EdqxlxQ==
+  dependencies:
+    command-exists "^1.2.8"
+    commander "3.0.2"
+    follow-redirects "^1.12.1"
+    fs-extra "^0.30.0"
+    js-sha3 "0.8.0"
+    memorystream "^0.3.1"
+    require-from-string "^2.0.0"
+    semver "^5.5.0"
+    tmp "0.0.33"
+
 solc@^0.4.20:
   version "0.4.26"
   resolved "https://registry.yarnpkg.com/solc/-/solc-0.4.26.tgz#5390a62a99f40806b86258c737c1cf653cc35cb5"