added comments and readme

example/README.md

@@ -0,0 +1,48 @@
+# Chanterelle Example
+
+This folder contains a complete example project for an Ethereum appliation managed using chanterelle. The application is simple -- there is an ERC20 token contract (`Token.sol`) and a contract (`SimplePaidStorage.sol`) that maintains a simple `uint` variable and requires users to pay tokens to update the state.
+
+There is a deploy script (`Deploy.purs`) which demonstrates how to use chanterelle to deploy your contracts, and there is a comprehensive test suite (`Test.SimplePaidStorage.purs`) that lays out common testing patterns.
+
+## Quickstart
+
+### Build
+To build the project, including compiling the smart contracts and generating the purescript FFI modules:
+```
+> npm i
+> npm run chanterelle-build
+> npm run build
+```
+
+### Running a Node
+For simplicity, we assume you are running a local node at host `http://localhost:8545`. We recommend using our dockerized geth instance [cliquebait](https://github.com/f-o-a-m/cliquebait) as it is guaranteed to support the entire web3 api:
+
+```
+> docker run --rm -d -it -p 8545:8545 foamspace/cliquebait:latest
+```
+
+### Test
+To test the smart contracts, you will need a node running as above:
+
+```
+npm run test
+```
+
+### Deploy
+To deploy the contracts, you will need a node running as above:
+
+```
+> npm run deploy
+```
+
+## Project Layout
+This folder contains a simple example project which uses chanterelle. There are some important files and directories:
+
+- `chanterelle.json`: This is the configuration file for the project. It specifies things like:
+  - The directory which contains the solidity contracts
+  - The directory to write the build artifacts to (i.e. the ABI files)
+  - The configuration for the purescript code generator
+  - Compiler options for solc, e.g. evm version, remappings, etc.
+- `contracts`: This directory contains all of the solidity contracts for the project
+- `src/Deploy.purs`: This module defines a value `deployContracts :: DeployM _`, which we call a _deploy script_. This is the function that deploys all of the contracts and writes the deployment data to the build artifacts (e.g. contract address, transaction hash, etc.)
+- `test`: This directory contains all of the integration tests for the contracts, written in purescript. The test suite deploys a fresh set of contracts to test against using the deploy script.

example/package.json

@@ -8,6 +8,7 @@
     "build": "spago build",
     "chanterelle-build": "spago run -m ChanterelleMain --node-args=\"build\"",
     "test": "spago test",
+    "deploy": "spago run",
     "tidy": "purs-tidy format-in-place \"src/**/*.purs\" \"test/**/*.purs\""
   },
   "dependencies": {

example/src/Deploy.purs

@@ -15,26 +15,32 @@ import Network.Ethereum.Core.BigNumber (fromInt)
 import Network.Ethereum.Web3 (Address, UIntN, _from, defaultTransactionOptions, uIntNFromBigNumber)
 import Type.Proxy (Proxy(..))
 
+-- Deployment Results captures the values which were created/used at deployment. 
 type DeployResults =
   { token :: Address
   , tokenOwner :: Address
   , simplePaidStorage :: Address
   , simplePaidStorageOwner :: Address
   }
 
+-- This is our Deploy Script. We return a value of type `DeployResults` to facilitate with testing,
+-- or potentially write the deployment data to a file for future use.
 deployContracts :: DeployM DeployResults
 deployContracts = do
   (DeployConfig { primaryAccount }) <- ask
   let txOpts = defaultTransactionOptions # _from ?~ primaryAccount
   { deployAddress: tokenAddress } <- deployContract txOpts tokenCfg
   { deployAddress: simplePaidStorage } <- deployContract txOpts $ simplePaidStorageCfg { tokenAddress }
-  pure 
+  pure
     { token: tokenAddress
     , tokenOwner: primaryAccount
     , simplePaidStorage
     , simplePaidStorageOwner: primaryAccount
     }
 
+-- This is the minimal configuration needed to deploy the Token contract. Notice
+-- that since the contract requires arguments to deploy, we need to submit a parser
+-- to the unvalidatedArgs field.
 tokenCfg :: ContractConfig (initialSupply :: UIntN 256)
 tokenCfg =
   { filepath: "build/contracts/Token.json"
@@ -45,6 +51,9 @@ tokenCfg =
       pure { initialSupply: n }
   }
 
+-- This is the minimal configuration needed to deploy the SimplePaidStorage contract. 
+-- The contract needs the Token address for its constructor, which we will pass after
+-- deploying the Token contract.
 simplePaidStorageCfg
   :: { tokenAddress :: Address }
   -> ContractConfig (tokenAddress :: Address)