docs: add waffle example + ci

.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

@@ -0,0 +1,2 @@
+build/
+build-ovm/

examples/waffle/.prettierrc.json

@@ -0,0 +1 @@
+../../.prettierrc.json

examples/waffle/LICENSE

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,3 @@
+# 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)

examples/waffle/contracts/ERC20.sol

@@ -0,0 +1,93 @@
+// 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

@@ -0,0 +1,65 @@
+// 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

@@ -0,0 +1,44 @@
+{
+  "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"
+  }
+}

examples/waffle/test/erc20.spec.js

@@ -0,0 +1,109 @@
+/* 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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,5 @@
+{
+  "compilerVersion": "./node_modules/@eth-optimism/solc",
+  "sourceDirectory": "./contracts",
+  "outputDirectory": "./build-ovm"
+}

examples/waffle/waffle.json

@@ -0,0 +1,5 @@
+{
+  "compilerVersion": "./../../node_modules/solc",
+  "sourceDirectory": "./contracts",
+  "outputDirectory": "./build"
+}