Refactor/readme

README.md

@@ -19,6 +19,28 @@
 
 > HQ20/contracts is a Solidity project with contracts, libraries and examples to help you build fully-featured distributed applications for the real world.
 
+**Disclaimer:** The contracts are expected to be used as smart contract patterns for you to draw inspiration from, and for them to be easy to understand they have been kept deliberately simple. If you decide to reuse the contracts, or to copy and paste code in them, make sure that you look for and close the vulnerabilities. If you plan to go to the mainnet, please get a third party audit done.
+
+## In a Nutshell
+
+At the time of this writing (`May 2020`), this are the contents of this repository:
+
+```
+contracts ──┬─── access        - Access Control Contracts, some of them built on top of `AccessControl.sol`
+            ├─── classifieds   - Example of a decentralized classifieds market for ERC721
+            ├─── dao           - Example of building a decentralized venture capital fund
+            ├─── energy        - Example of building a decentralized market for energy distribution
+            ├─── exchange      - The Uniswap decentralized market contracts, with solidity tests
+            ├─── introspection - Example of using ERC165 to verify contract types before casting
+            ├─── issuance      - Example of an ICO, can be used as well for share issuances
+            ├─── lists         - Reusable implementations of different types of linked lists
+            ├─── math          - Reusable implementation of a lightweight fixed point math library
+            ├─── state         - Reusable implementation of a fully-featured state machine
+            ├─── token         - Token implementations, including a reusable dividend-bearing ERC20
+            ├─── utils         - Reusable library to cast between `uint` and `int`.
+            └─── voting        - Example implementations of token-based and address-based votings
+```
+
 ## Installation
 
 Use the package manager [yarn](https://yarnpkg.com) to install dependencies.
@@ -49,42 +71,12 @@ Inside the contracts folder the files are organized by topic and by type.
 
 At the root of `contracts` are directories for each one of the topics, containing the simplest implementations that are in a mature state.
 
-For contracts that are used as example implementations there is a `contracts/examples` directory with the appropriate topic folders inside.
-
 For contracts that are under development there is a `contracts/drafts` directory with the appropriate topic folders inside.
 
 For contracts that are used for testing of libraries or internal methods there is a `contracts/test` directory with the appropriate topic folders inside.
 
 The `test` directory replicates the structure of the `contracts` directory.
 
-At the time of this writing (`Feb 2020`), this is the directory structure:
-
-```
-contracts ──┬─── access
-            │
-            ├─── classifieds
-            │
-            ├─── drafts ───────┬─── classifieds
-            │                  ├─── issuance
-            |                  ├─── lists ──────────── mocks
-            |                  ├─── strings
-            |                  ├─── token
-            |                  └─── voting
-            │
-            ├─── examples ─────┬─── access
-            │                  ├─── dao
-            │                  ├─── energy
-            │                  └─── introspection
-            │
-            ├─── exchange
-            ├─── issuance
-            ├─── lists 
-            ├─── state
-            ├─── test
-            ├─── token
-            └─── utils
-```
-
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 

contracts/access/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project that implements different access control structures on top of OpenZeppelin's AccessControl.sol.
 
+For a longer explanation of some of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-use-accesscontrol-sol-9ea3a57f4b15?source=friends_link&sk=c274faededcbb71c6a211f33de4cf5c9).
+
 
 # Community
 

contracts/classifieds/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project which implements a classifieds board.
 
+For a longer explanation of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-implement-an-erc721-market-f805959ddcf?source=friends_link&sk=5a9c2bb92a2bb92403a32e389e933613).
+
 ## Description
 
 A classifieds board can be used to open and close trades between ERC20 and ERC721 tokens.

contracts/examples/dao/DAO.sol → contracts/dao/DAO.sol

@@ -4,7 +4,7 @@ import "@openzeppelin/contracts/math/SafeMath.sol";
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import "@openzeppelin/contracts/utils/EnumerableSet.sol";
 import "./VentureEth.sol";
-import "../../voting/Democratic.sol";
+import "../voting/Democratic.sol";
 
 
 /**

contracts/examples/dao/VentureEth.sol → contracts/dao/VentureEth.sol

@@ -1,9 +1,9 @@
 pragma solidity ^0.6.0;
 
 import "@openzeppelin/contracts/math/SafeMath.sol";
-import "../../issuance/IssuanceEth.sol";
-import "../../token/ERC20DividendableEth.sol";
-import "../../token/ERC20Mintable.sol";
+import "../issuance/IssuanceEth.sol";
+import "../token/ERC20DividendableEth.sol";
+import "../token/ERC20Mintable.sol";
 
 
 /**

contracts/examples/energy/EnergyMarket.sol → contracts/energy/EnergyMarket.sol

@@ -1,8 +1,7 @@
 pragma solidity ^0.6.0;
 
 import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-// import "@hq20/contracts/contracts/access/Whitelist.sol";
-import "../../access/Administered.sol";
+import "../access/Administered.sol";
 
 
 /**

contracts/examples/energy/README.md → contracts/energy/README.md

@@ -1,6 +1,9 @@
 # EnergyMarket
 
-This is an Ethereum project that implements an Energy Market
+This is an Ethereum project that implements an Energy Market.
+
+For a longer explanation of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-build-an-energy-market-on-a-blockchain-c43b0cfc2d12?source=friends_link&sk=75fd59c0488c354782985321aa2919cb).
+
 
 ## Usage
 

contracts/lists/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project that implements singly and doubly linked lists (https://en.wikipedia.org/wiki/Linked_list).
 
+For a longer explanation of some of the contracts here, [please read this article](https://medium.com/coinmonks/a-linked-list-implementation-for-ethereum-a2915bf8122f?source=friends_link&sk=be8889a651eed8193b1c4421a50484dd).
+
 # Terminology
 Object: Objects are linked to each other and together they are a Linked List
 Head: The first object in the list. No other object points to the head.

contracts/test/examples/introspection/erc165/ERC20WhitelistedMock.sol → contracts/test/introspection/erc165/ERC20WhitelistedMock.sol

@@ -1,6 +1,6 @@
 pragma solidity ^0.6.0;
 import "@openzeppelin/contracts/access/Ownable.sol";
-import "./../../../../examples/introspection/erc165/ERC20Whitelisted.sol";
+import "./../../../introspection/erc165/ERC20Whitelisted.sol";
 
 
 contract ERC20WhitelistedMock is ERC20Whitelisted, Ownable {

test/examples/dao/DAO.test.ts → test/dao/DAO.test.ts

@@ -3,7 +3,7 @@ import * as chai from 'chai';
 // tslint:disable-next-line:no-var-requires
 const { balance, BN, constants, ether, expectEvent, expectRevert } = require('@openzeppelin/test-helpers');
 
-import { DAOInstance, VentureEthInstance, OneTokenOneVoteInstance } from '../../../types/truffle-contracts';
+import { DAOInstance, VentureEthInstance, OneTokenOneVoteInstance } from '../../types/truffle-contracts';
 
 const DAO = artifacts.require(
     'DAO',

test/examples/dao/VentureEth.test.ts → test/dao/VentureEth.test.ts

@@ -3,7 +3,7 @@ import { should } from 'chai';
 // tslint:disable-next-line:no-var-requires
 const { balance, BN, constants, ether, expectEvent, expectRevert, send } = require('@openzeppelin/test-helpers');
 
-import { VentureEthInstance } from '../../../types/truffle-contracts';
+import { VentureEthInstance } from '../../types/truffle-contracts';
 
 const VentureEth = artifacts.require(
     'VentureEth.sol',

test/examples/energy/EnergyMarket.test.ts → test/energy/EnergyMarket.test.ts

@@ -1,7 +1,7 @@
 // tslint:disable:no-var-requires
 import * as chai from 'chai';
 const { BN, expectEvent, expectRevert } = require('@openzeppelin/test-helpers');
-import { EnergyMarketInstance } from '../../../types/truffle-contracts';
+import { EnergyMarketInstance } from '../../types/truffle-contracts';
 
 const EnergyMarket = artifacts.require('EnergyMarket') as Truffle.Contract<EnergyMarketInstance>;
 

test/examples/introspection/erc165/ERC20Whitelisted.ts → test/introspection/erc165/ERC20Whitelisted.ts

@@ -1,7 +1,7 @@
 import { should } from 'chai';
-import { WhitelistERC165Instance } from '../../../../types/truffle-contracts';
-import { ERC20WhitelistedInstance } from '../../../../types/truffle-contracts';
-import { ERC20WhitelistedMockInstance } from '../../../../types/truffle-contracts';
+import { WhitelistERC165Instance } from '../../../types/truffle-contracts';
+import { ERC20WhitelistedInstance } from '../../../types/truffle-contracts';
+import { ERC20WhitelistedMockInstance } from '../../../types/truffle-contracts';
 
 const Whitelist = artifacts.require(
     './examples/introspection/erc165/WhitelistERC165.sol',
@@ -15,7 +15,7 @@ const ERC20WhitelistedMock = artifacts.require(
 should();
 
 // tslint:disable-next-line no-var-requires
-const { itShouldThrow } = require('./../../../utils');
+const { itShouldThrow } = require('./../../utils');
 
 /** @test {ERC20Whitelisted} contract */
 contract('ERC20Whitelisted', (accounts) => {

test/examples/introspection/erc165/WhitelistERC165.test.ts → test/introspection/erc165/WhitelistERC165.test.ts

@@ -1,13 +1,13 @@
 import { should } from 'chai';
-import { WhitelistERC165Instance } from '../../../../types/truffle-contracts';
+import { WhitelistERC165Instance } from '../../../types/truffle-contracts';
 
 const WhitelistERC165 = artifacts.require(
     './examples/introspection/erc165/WhitelistERC165.sol',
 ) as Truffle.Contract<WhitelistERC165Instance>;
 should();
 
 // tslint:disable-next-line no-var-requires
-const { itShouldThrow } = require('./../../../utils');
+const { itShouldThrow } = require('./../../utils');
 
 /** @test {Whitelist} contract */
 contract('Whitelist', (accounts) => {

test/examples/introspection/erc165/WhitelistInterfaceId.test.ts → test/introspection/erc165/WhitelistInterfaceId.test.ts

@@ -1,5 +1,5 @@
 import { should } from 'chai';
-import { WhitelistInterfaceIdInstance } from '../../../../types/truffle-contracts';
+import { WhitelistInterfaceIdInstance } from '../../../types/truffle-contracts';
 
 const WhitelistInterfaceId = artifacts.require(
     './examples/introspection/erc165/WhitelistInterfaceId.sol',
@@ -8,7 +8,7 @@ const WhitelistInterfaceId = artifacts.require(
 should();
 
 // tslint:disable-next-line no-var-requires
-const { itShouldThrow } = require('./../../../utils');
+const { itShouldThrow } = require('./../../utils');
 
 /** @test {WhitelistInterfaceId} contract */
 contract('WhitelistInterfaceId', (accounts) => {