Add README docs (NOTICE) for LinkTokenChild contract

- style changes to LinkTokenChild contract
- additional useful documentationn

Author: krebernisak

README.md

@@ -20,8 +20,16 @@ Security audit for [0.4 version of the contracts](./contracts/v0.4/) is availabl
 
 The project contains [0.4 contracts](./contracts/v0.4/) that were used for LINK Ethereum Mainnet deployment in 2017. For deployments moving forward, we use the updated [0.6 contracts](./contracts/v0.6/) which use a more recent version of solc and the OpenZeppelin token standards. These updates include a minor ABI change around approval/allowance naming.
 
+To mitigate supply chain attack type of risk, we currently avoid using NPM modules to pull Solidity vendor code, but instead use git submodules. Make sure you pull submodules explicitly:
+
+```bash
+git submodule update --init --recursive
+```
+
+After submodules are updated, we can run:
+
 ```bash
-yarn install
+yarn
 ```
 
 Setup contracts:
@@ -30,7 +38,13 @@ Setup contracts:
 yarn setup
 ```
 
-This will compile all versions of the contracts.
+**NOTICE:** This will compile all versions of the contracts, but as Hardhat doesn't have robust support for multiple Solidity versions the resulting artifacts will include only final (latest) compiler output. To make sure you compile the specific version please use the specific command:
+
+Setup v0.6 contracts using Solidity 0.6 compiler:
+
+```bash
+build:contracts:0.6
+```
 
 ## Testing
 

contracts/v0.7/bridge/README.md

@@ -1,3 +1,25 @@
 # LINK Token Bridge v0.7
 
-- `./token/LinkTokenChild.sol`: A mintable & burnable child LinkToken contract to be used on child networks.
+- `./token/LinkTokenChild.sol`: A generalized mintable & burnable child LinkToken contract to be used on child networks.
+
+NOTICE: Current implementation of LinkTokenChild contract requires some additional consideration:
+
+- Supporting more than one gateway (multiple bridges minting the same token) leaves room for accounting issues.
+  If we have more than one gateway supported, an additional check needs to exist that limits withdrawals per
+  gateway to an amount locked on L1, for the specific gateway. Otherwise one can accidentally "burn" tokens
+  by withdrawing more than locked in L1 (tx will fail on L1). When there is a 1:1 relationship between the
+  gateway and token, the token itself is an accounting mechanism. For a potential N:1 relationship, a more
+  sophisticated type of accounting needs to exist.
+- Every bridge is unique in the amount of risk it bears, so tokens bridged by different bridges are not 1:1
+  the same token, and shouldn't be forced as such.
+- Bridges often require an unique interface to be supported by the child network tokens
+  (e.g. `mint` vs. `deposit`, `burn` vs. `withdraw/unwrap`, etc.).
+- Bridges often assume that the child contract they are bridging to is the ERC20 token itself, not a gateway
+  (intermediate contract) that could help us map from the specific bridge interface to our standard
+  LinkTokenChild interface.
+- Chainlink often needs to launch on a new network before the native bridge interface is defined.
+- To support early (before the bridge is defined) Chainlink network launch, we could make an upgradeable
+  LinkTokenChild contract which would enable us to slightly update the contract interface after the bridge
+  gets defined, and once online transfer the ownership (bridge gateway role) to the new bridge.
+
+TODO: Potentially create an upgradeable `LinkTokenChild.sol` and limit gateway support to only one (owner)!

contracts/v0.7/bridge/token/LinkTokenChild.sol

@@ -11,17 +11,8 @@ import { ERC20Burnable } from "../../../../vendor/OpenZeppelin/openzeppelin-cont
 import { SimpleWriteAccessController } from "../../../../vendor/smartcontractkit/chainlink/evm-contracts/src/v0.6/SimpleWriteAccessController.sol";
 import { LinkToken } from "../../../v0.6/LinkToken.sol";
 
-/// @dev Access controlled mintable & burnable LinkToken, for use on sidechains and L2 networks.
+/// @dev A generalized mintable & burnable child LinkToken contract to be used on child networks.
 contract LinkTokenChild is ITypeAndVersion, IERC20Child, SimpleWriteAccessController, ERC20Burnable, LinkToken {
-  /**
-   * @dev Overrides parent contract so no tokens are minted on deployment.
-   * @inheritdoc LinkToken
-   */
-  function _onCreate()
-    internal
-    override
-  {}
-
   /**
    * @notice versions:
    *
@@ -86,6 +77,15 @@ contract LinkTokenChild is ITypeAndVersion, IERC20Child, SimpleWriteAccessContro
     super.burnFrom(account, amount);
   }
 
+  /**
+   * @dev Overrides parent contract so no tokens are minted on deployment.
+   * @inheritdoc LinkToken
+   */
+  function _onCreate()
+    internal
+    override
+  {}
+
   /// @inheritdoc LinkToken
   function _transfer(
     address sender,
@@ -111,4 +111,4 @@ contract LinkTokenChild is ITypeAndVersion, IERC20Child, SimpleWriteAccessContro
   {
     super._approve(owner, spender, amount);
   }
-}
+}