12 files changed, 559 insertions, 0 deletions
diff --git a/contracts/examples/README.md b/contracts/examples/README.md
new file mode 100644
index 000000000..1c603bfcf
--- /dev/null
+++ b/contracts/examples/README.md
@@ -0,0 +1,56 @@
+## Contract examples
+
+Smart contract examples of the 0x protocol.
+
+## Usage
+
+Contracts can be found in the [contracts](./contracts) directory.
+This package contains example implementations of contracts that interact with the protocol but are _not_ intended for use in production. Examples include [filter](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#filter-contracts) contracts, a [Wallet](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#wallet) contract, and a [Validator](https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#validator) contract, among others.
+
+## Contributing
+
+We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.
+
+For proposals regarding the 0x protocol's smart contract architecture, message format, or additional functionality, go to the [0x Improvement Proposals (ZEIPs)](https://github.com/0xProject/ZEIPs) repository and follow the contribution guidelines provided therein.
+
+Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.
+
+### Install Dependencies
+
+If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:
+
+```bash
+yarn config set workspaces-experimental true
+```
+
+Then install dependencies
+
+```bash
+yarn install
+```
+
+### Build
+
+To build this package and all other monorepo packages that it depends on, run the following from the monorepo root directory:
+
+```bash
+PKG=@0x/contracts-examples yarn build
+```
+
+Or continuously rebuild on change:
+
+```bash
+PKG=@0x/contracts-examples yarn watch
+```
+
+### Clean
+
+```bash
+yarn clean
+```
+
+### Lint
+
+```bash
+yarn lint
+```
diff --git a/contracts/examples/compiler.json b/contracts/examples/compiler.json
new file mode 100644
index 000000000..375fa0c55
--- /dev/null
+++ b/contracts/examples/compiler.json
@@ -0,0 +1,22 @@
+{
+    "artifactsDir": "./generated-artifacts",
+    "contractsDir": "./contracts",
+    "compilerSettings": {
+        "optimizer": {
+            "enabled": true,
+            "runs": 1000000
+        },
+        "outputSelection": {
+            "*": {
+                "*": [
+                    "abi",
+                    "evm.bytecode.object",
+                    "evm.bytecode.sourceMap",
+                    "evm.deployedBytecode.object",
+                    "evm.deployedBytecode.sourceMap"
+                ]
+            }
+        }
+    },
+    "contracts": ["ExchangeWrapper", "Validator", "Wallet", "Whitelist"]
+}
diff --git a/contracts/examples/contracts/ExchangeWrapper/ExchangeWrapper.sol b/contracts/examples/contracts/ExchangeWrapper/ExchangeWrapper.sol
new file mode 100644
index 000000000..d98136922
--- /dev/null
+++ b/contracts/examples/contracts/ExchangeWrapper/ExchangeWrapper.sol
@@ -0,0 +1,100 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity 0.4.24;
+pragma experimental ABIEncoderV2;
+
+import "@0x/contracts-interfaces/contracts/protocol/Exchange/IExchange.sol";
+import "@0x/contracts-libs/contracts/libs/LibOrder.sol";
+
+
+contract ExchangeWrapper {
+
+    // Exchange contract.
+    // solhint-disable-next-line var-name-mixedcase
+    IExchange internal EXCHANGE;
+
+    constructor (address _exchange)
+        public
+    {
+        EXCHANGE = IExchange(_exchange);
+    }
+
+    /// @dev Cancels all orders created by sender with a salt less than or equal to the targetOrderEpoch
+    ///      and senderAddress equal to this contract.
+    /// @param targetOrderEpoch Orders created with a salt less or equal to this value will be cancelled.
+    /// @param salt Arbitrary value to gaurantee uniqueness of 0x transaction hash.
+    /// @param makerSignature Proof that maker wishes to call this function with given params.
+    function cancelOrdersUpTo(
+        uint256 targetOrderEpoch,
+        uint256 salt,
+        bytes makerSignature
+    )
+        external
+    {
+        address makerAddress = msg.sender;
+
+        // Encode arguments into byte array.
+        bytes memory data = abi.encodeWithSelector(
+            EXCHANGE.cancelOrdersUpTo.selector,
+            targetOrderEpoch
+        );
+
+        // Call `cancelOrdersUpTo` via `executeTransaction`.
+        EXCHANGE.executeTransaction(
+            salt,
+            makerAddress,
+            data,
+            makerSignature
+        );
+    }
+
+    /// @dev Fills an order using `msg.sender` as the taker.
+    /// @param order Order struct containing order specifications.
+    /// @param takerAssetFillAmount Desired amount of takerAsset to sell.
+    /// @param salt Arbitrary value to gaurantee uniqueness of 0x transaction hash.
+    /// @param orderSignature Proof that order has been created by maker.
+    /// @param takerSignature Proof that taker wishes to call this function with given params.
+    function fillOrder(
+        LibOrder.Order memory order,
+        uint256 takerAssetFillAmount,
+        uint256 salt,
+        bytes memory orderSignature,
+        bytes memory takerSignature
+    )
+        public
+    {
+        address takerAddress = msg.sender;
+
+        // Encode arguments into byte array.
+        bytes memory data = abi.encodeWithSelector(
+            EXCHANGE.fillOrder.selector,
+            order,
+            takerAssetFillAmount,
+            orderSignature
+        );
+
+        // Call `fillOrder` via `executeTransaction`.
+        EXCHANGE.executeTransaction(
+            salt,
+            takerAddress,
+            data,
+            takerSignature
+        );
+    }
+}
diff --git a/contracts/examples/contracts/Validator/Validator.sol b/contracts/examples/contracts/Validator/Validator.sol
new file mode 100644
index 000000000..e488a9ca7
--- /dev/null
+++ b/contracts/examples/contracts/Validator/Validator.sol
@@ -0,0 +1,56 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity 0.4.24;
+
+import "@0x/contracts-interfaces/contracts/protocol/Exchange/IValidator.sol";
+
+
+contract Validator is 
+    IValidator
+{
+
+    // The single valid signer for this wallet.
+    // solhint-disable-next-line var-name-mixedcase
+    address internal VALID_SIGNER;
+
+    /// @dev constructs a new `Validator` with a single valid signer.
+    /// @param validSigner The sole, valid signer.
+    constructor (address validSigner) public {
+        VALID_SIGNER = validSigner;
+    }
+
+    /// @dev Verifies that a signature is valid. `signer` must match `VALID_SIGNER`.
+    /// @param hash Message hash that is signed.
+    /// @param signerAddress Address that should have signed the given hash.
+    /// @param signature Proof of signing.
+    /// @return Validity of signature.
+    // solhint-disable no-unused-vars
+    function isValidSignature(
+        bytes32 hash,
+        address signerAddress,
+        bytes signature
+    )
+        external
+        view
+        returns (bool isValid)
+    {
+        return (signerAddress == VALID_SIGNER);
+    }
+    // solhint-enable no-unused-vars
+}
diff --git a/contracts/examples/contracts/Wallet/Wallet.sol b/contracts/examples/contracts/Wallet/Wallet.sol
new file mode 100644
index 000000000..8edc74eb3
--- /dev/null
+++ b/contracts/examples/contracts/Wallet/Wallet.sol
@@ -0,0 +1,65 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity 0.4.24;
+
+import "@0x/contracts-interfaces/contracts/protocol/Exchange/IWallet.sol";
+import "@0x/contracts-utils/contracts/utils/LibBytes/LibBytes.sol";
+
+
+contract Wallet is 
+    IWallet
+{
+    using LibBytes for bytes;
+
+    // The owner of this wallet.
+    // solhint-disable-next-line var-name-mixedcase
+    address internal WALLET_OWNER;
+
+    /// @dev constructs a new `Wallet` with a single owner.
+    /// @param walletOwner The owner of this wallet.
+    constructor (address walletOwner) public {
+        WALLET_OWNER = walletOwner;
+    }
+
+    /// @dev Validates an EIP712 signature.
+    ///      The signer must match the owner of this wallet.
+    /// @param hash Message hash that is signed.
+    /// @param eip712Signature Proof of signing.
+    /// @return Validity of signature.
+    function isValidSignature(
+        bytes32 hash,
+        bytes eip712Signature
+    )
+        external
+        view
+        returns (bool isValid)
+    {
+        require(
+            eip712Signature.length == 65,
+            "LENGTH_65_REQUIRED"
+        );
+
+        uint8 v = uint8(eip712Signature[0]);
+        bytes32 r = eip712Signature.readBytes32(1);
+        bytes32 s = eip712Signature.readBytes32(33);
+        address recoveredAddress = ecrecover(hash, v, r, s);
+        isValid = WALLET_OWNER == recoveredAddress;
+        return isValid;
+    }
+}
diff --git a/contracts/examples/contracts/Whitelist/Whitelist.sol b/contracts/examples/contracts/Whitelist/Whitelist.sol
new file mode 100644
index 000000000..2a3d33738
--- /dev/null
+++ b/contracts/examples/contracts/Whitelist/Whitelist.sol
@@ -0,0 +1,136 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity 0.4.24;
+pragma experimental ABIEncoderV2;
+
+import "@0x/contracts-interfaces/contracts/protocol/Exchange/IExchange.sol";
+import "@0x/contracts-libs/contracts/libs/LibOrder.sol";
+import "@0x/contracts-utils/contracts/utils/Ownable/Ownable.sol";
+
+
+contract Whitelist is
+    Ownable
+{
+
+    // Mapping of address => whitelist status.
+    mapping (address => bool) public isWhitelisted;
+
+    // Exchange contract.
+    // solhint-disable var-name-mixedcase
+    IExchange internal EXCHANGE;
+    bytes internal TX_ORIGIN_SIGNATURE;
+    // solhint-enable var-name-mixedcase
+
+    byte constant internal VALIDATOR_SIGNATURE_BYTE = "\x05";
+
+    constructor (address _exchange)
+        public
+    {
+        EXCHANGE = IExchange(_exchange);
+        TX_ORIGIN_SIGNATURE = abi.encodePacked(address(this), VALIDATOR_SIGNATURE_BYTE);
+    }
+
+    /// @dev Adds or removes an address from the whitelist.
+    /// @param target Address to add or remove from whitelist.
+    /// @param isApproved Whitelist status to assign to address.
+    function updateWhitelistStatus(
+        address target,
+        bool isApproved
+    )
+        external
+        onlyOwner
+    {
+        isWhitelisted[target] = isApproved;
+    }
+
+    /// @dev Verifies signer is same as signer of current Ethereum transaction.
+    ///      NOTE: This function can currently be used to validate signatures coming from outside of this contract.
+    ///      Extra safety checks can be added for a production contract.
+    /// @param signerAddress Address that should have signed the given hash.
+    /// @param signature Proof of signing.
+    /// @return Validity of order signature.
+    // solhint-disable no-unused-vars
+    function isValidSignature(
+        bytes32 hash,
+        address signerAddress,
+        bytes signature
+    )
+        external
+        view
+        returns (bool isValid)
+    {
+        // solhint-disable-next-line avoid-tx-origin
+        return signerAddress == tx.origin;
+    }
+    // solhint-enable no-unused-vars
+
+    /// @dev Fills an order using `msg.sender` as the taker.
+    ///      The transaction will revert if both the maker and taker are not whitelisted.
+    ///      Orders should specify this contract as the `senderAddress` in order to gaurantee
+    ///      that both maker and taker have been whitelisted.
+    /// @param order Order struct containing order specifications.
+    /// @param takerAssetFillAmount Desired amount of takerAsset to sell.
+    /// @param salt Arbitrary value to gaurantee uniqueness of 0x transaction hash.
+    /// @param orderSignature Proof that order has been created by maker.
+    function fillOrderIfWhitelisted(
+        LibOrder.Order memory order,
+        uint256 takerAssetFillAmount,
+        uint256 salt,
+        bytes memory orderSignature
+    )
+        public
+    {
+        address takerAddress = msg.sender;
+
+        // This contract must be the entry point for the transaction.
+        require(
+            // solhint-disable-next-line avoid-tx-origin
+            takerAddress == tx.origin,
+            "INVALID_SENDER"
+        );
+
+        // Check if maker is on the whitelist.
+        require(
+            isWhitelisted[order.makerAddress],
+            "MAKER_NOT_WHITELISTED"
+        );
+
+        // Check if taker is on the whitelist.
+        require(
+            isWhitelisted[takerAddress],
+            "TAKER_NOT_WHITELISTED"
+        );
+
+        // Encode arguments into byte array.
+        bytes memory data = abi.encodeWithSelector(
+            EXCHANGE.fillOrder.selector,
+            order,
+            takerAssetFillAmount,
+            orderSignature
+        );
+
+        // Call `fillOrder` via `executeTransaction`.
+        EXCHANGE.executeTransaction(
+            salt,
+            takerAddress,
+            data,
+            TX_ORIGIN_SIGNATURE
+        );
+    }
+}
diff --git a/contracts/examples/package.json b/contracts/examples/package.json
new file mode 100644
index 000000000..541a67f2c
--- /dev/null
+++ b/contracts/examples/package.json
@@ -0,0 +1,83 @@
+{
+    "private": true,
+    "name": "@0x/contracts-examples",
+    "version": "1.0.0",
+    "engines": {
+        "node": ">=6.12"
+    },
+    "description": "Smart contract examples of 0x protocol",
+    "main": "lib/src/index.js",
+    "directories": {
+        "test": "test"
+    },
+    "scripts": {
+        "build": "yarn pre_build && tsc -b",
+        "build:ci": "yarn build",
+        "pre_build": "run-s compile generate_contract_wrappers",
+        "compile": "sol-compiler --contracts-dir contracts",
+        "clean": "shx rm -rf lib generated-artifacts generated-wrappers",
+        "generate_contract_wrappers": "abi-gen --abis  ${npm_package_config_abis} --template ../../node_modules/@0x/abi-gen-templates/contract.handlebars --partials '../../node_modules/@0x/abi-gen-templates/partials/**/*.handlebars' --output generated-wrappers --backend ethers",
+        "lint": "tslint --format stylish --project . --exclude ./generated-wrappers/**/* --exclude ./generated-artifacts/**/* --exclude **/lib/**/* && yarn lint-contracts",
+        "lint-contracts": "solhint -c ../.solhint.json contracts/**/**/**/**/*.sol"
+    },
+    "config": {
+        "abis": "generated-artifacts/@(ExchangeWrapper|Validator|Wallet|Whitelist).json"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/0xProject/0x-monorepo.git"
+    },
+    "license": "Apache-2.0",
+    "bugs": {
+        "url": "https://github.com/0xProject/0x-monorepo/issues"
+    },
+    "homepage": "https://github.com/0xProject/0x-monorepo/contracts/examples/README.md",
+    "devDependencies": {
+        "@0x/contracts-test-utils": "^1.0.0",
+        "@0x/abi-gen": "^1.0.17",
+        "@0x/dev-utils": "^1.0.19",
+        "@0x/sol-compiler": "^1.1.14",
+        "@0x/sol-cov": "^2.1.14",
+        "@0x/subproviders": "^2.1.6",
+        "@0x/tslint-config": "^1.0.10",
+        "@types/bn.js": "^4.11.0",
+        "@types/lodash": "4.14.104",
+        "@types/node": "*",
+        "@types/yargs": "^10.0.0",
+        "chai": "^4.0.1",
+        "chai-as-promised": "^7.1.0",
+        "chai-bignumber": "^2.0.1",
+        "dirty-chai": "^2.0.1",
+        "make-promises-safe": "^1.1.0",
+        "ethereumjs-abi": "0.6.5",
+        "mocha": "^4.1.0",
+        "npm-run-all": "^4.1.2",
+        "shx": "^0.2.2",
+        "solc": "^0.4.24",
+        "solhint": "^1.4.1",
+        "tslint": "5.11.0",
+        "typescript": "3.0.1",
+        "yargs": "^10.0.3"
+    },
+    "dependencies": {
+        "@0x/base-contract": "^3.0.8",
+        "@0x/order-utils": "^3.0.4",
+        "@0x/contracts-multisig": "^1.0.0",
+        "@0x/contracts-utils": "^1.0.0",
+        "@0x/contracts-tokens": "^1.0.0",
+        "@0x/contracts-libs": "^1.0.0",
+        "@0x/contracts-interfaces": "^1.0.0",
+        "@0x/types": "^1.3.0",
+        "@0x/typescript-typings": "^3.0.4",
+        "@0x/utils": "^2.0.6",
+        "@0x/web3-wrapper": "^3.1.6",
+        "@types/js-combinatorics": "^0.5.29",
+        "bn.js": "^4.11.8",
+        "ethereum-types": "^1.1.2",
+        "ethereumjs-util": "^5.1.1",
+        "lodash": "^4.17.5"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}
diff --git a/contracts/examples/src/artifacts/index.ts b/contracts/examples/src/artifacts/index.ts
new file mode 100644
index 000000000..c921fbf89
--- /dev/null
+++ b/contracts/examples/src/artifacts/index.ts
@@ -0,0 +1,13 @@
+import { ContractArtifact } from 'ethereum-types';
+
+import * as ExchangeWrapper from '../../generated-artifacts/ExchangeWrapper.json';
+import * as Validator from '../../generated-artifacts/Validator.json';
+import * as Wallet from '../../generated-artifacts/Wallet.json';
+import * as Whitelist from '../../generated-artifacts/Whitelist.json';
+
+export const artifacts = {
+    ExchangeWrapper: ExchangeWrapper as ContractArtifact,
+    Validator: Validator as ContractArtifact,
+    Wallet: Wallet as ContractArtifact,
+    Whitelist: Whitelist as ContractArtifact,
+};
diff --git a/contracts/examples/src/index.ts b/contracts/examples/src/index.ts
new file mode 100644
index 000000000..d55f08ea2
--- /dev/null
+++ b/contracts/examples/src/index.ts
@@ -0,0 +1,2 @@
+export * from './artifacts';
+export * from './wrappers';
diff --git a/contracts/examples/src/wrappers/index.ts b/contracts/examples/src/wrappers/index.ts
new file mode 100644
index 000000000..dc67277d7
--- /dev/null
+++ b/contracts/examples/src/wrappers/index.ts
@@ -0,0 +1,4 @@
+export * from '../../generated-wrappers/exchange_wrapper';
+export * from '../../generated-wrappers/validator';
+export * from '../../generated-wrappers/wallet';
+export * from '../../generated-wrappers/whitelist';
diff --git a/contracts/examples/tsconfig.json b/contracts/examples/tsconfig.json
new file mode 100644
index 000000000..63245da1e
--- /dev/null
+++ b/contracts/examples/tsconfig.json
@@ -0,0 +1,16 @@
+{
+    "extends": "../../tsconfig",
+    "compilerOptions": {
+        "outDir": "lib",
+        "rootDir": ".",
+        "resolveJsonModule": true
+    },
+    "include": ["./src/**/*", "./test/**/*", "./generated-wrappers/**/*"],
+    "files": [
+        "./generated-artifacts/ExchangeWrapper.json",
+        "./generated-artifacts/Validator.json",
+        "./generated-artifacts/Wallet.json",
+        "./generated-artifacts/Whitelist.json"
+    ],
+    "exclude": ["./deploy/solc/solc_bin"]
+}
diff --git a/contracts/examples/tslint.json b/contracts/examples/tslint.json
new file mode 100644
index 000000000..1bb3ac2a2
--- /dev/null
+++ b/contracts/examples/tslint.json
@@ -0,0 +1,6 @@
+{
+    "extends": ["@0x/tslint-config"],
+    "rules": {
+        "custom-no-magic-numbers": false
+    }
+}