added README and entry point specifications

Former-commit-id: a538db47a820ea4c317ed23f2cdbc7e4e7bb737a [formerly 1499bab1308c0c25675b4b33100a29d898af57f0]
Former-commit-id: ee02769ea60fb9abcc316eb0bfa57437bc9a4614

eth.log

@@ -0,0 +1,24 @@
+Welcome to the Geth JavaScript console!
+
+instance: Geth/v1.8.0-unstable-34918903/darwin-amd64/go1.9.2
+coinbase: 0xee477909449e30d22ce01bc673b3f69367e12805
+at block: 0 (Wed, 31 Dec 1969 18:00:00 CST)
+ datadir: /Users/rauljordan/Library/Ethereum
+ modules: admin:1.0 debug:1.0 eth:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
+
+> caught interrupt, exiting
+Welcome to the Geth JavaScript console!
+
+instance: Geth/v1.8.0-unstable-34918903/darwin-amd64/go1.9.2
+coinbase: 0xee477909449e30d22ce01bc673b3f69367e12805
+at block: 0 (Wed, 31 Dec 1969 18:00:00 CST)
+ datadir: /Users/rauljordan/Library/Ethereum
+ modules: admin:1.0 debug:1.0 eth:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
+
+> caught interrupt, exiting
+Welcome to the Geth JavaScript console!
+
+instance: Geth/v1.8.0-unstable-34918903/darwin-amd64/go1.9.2
+ modules: admin:1.0 debug:1.0 eth:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
+
+> caught interrupt, exiting

sharding/README.md

@@ -2,4 +2,61 @@
 
 [![Join the chat at https://gitter.im/prysmaticlabs/geth-sharding](https://badges.gitter.im/prysmaticlabs/geth-sharding.svg)](https://gitter.im/prysmaticlabs/geth-sharding?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Sharding implementation for Geth
+This repository contains the sharding implementation for the go-ethereum client. The system consists of an entry point that serves as a bridge between a **Validator Manager Contract** and a Geth node running on the same network.
+
+To get started with running the project, follow the instructions to initialize your own private Ethereum blockchain and geth node:
+
+```
+$ git clone github.com/prysmaticlabs/geth-sharding
+$ make geth
+$ cd $GOPATH/src/github.com/prysmaticlabs/geth-sharding
+$ make geth
+$ ./build/bin/geth init ./sharding/genesis.json -datadir /path/to/your/datadir
+$ ./build/bin/geth --nodiscover console --datadir /path/to/your/datadir
+```
+
+Then, the geth console can start up and you can start a miner as follows:
+
+```
+> personal.newAccount()
+> miner.setEtherbase(eth.accounts[0])
+> miner.start()
+```
+
+Then, once you are satisfied with mining for a few seconds, stop the miner with
+
+```
+> miner.stop()
+```
+
+Once you have this private geth node running on your local network, the sharding client can be started as a standalone geth command as follows in a separate terminal window:
+
+```
+$ geth sharding /path/to/your/datadir/geth.ipc
+```
+
+The project consists of the following parts, with each of them requiring comprehensive tests:
+
+### Validator Manager Contract
+
+The VMC is built in Solidity and deployed to the geth node upon launch of the client if it does not exist in the network at a specified address. If the contract already exists, the client simply sets up an interface to programmatically call the internal contract functions and listens to transactions broadcasted to the geth node to begin the sharding system.
+
+### VMC Wrapper & Sharding Client
+
+As we will be interacting with a geth node, we will create a Golang interface that wraps over the VMC and a client that connects to the local geth node upon launch via JSON-RPC.
+
+It will be the client's responsibility to listen to any new broadcasted transactions to the node and interact package validators up to be sent to the VMC.
+
+### Sharding VM
+
+As sharding will require a different set of protocol primitives, we will have to specify new primitives for Blocks, Transactions, and even the low-level functioning of the EVM to accommodate this new structure.
+
+We can implement a new ShardingEVM by overriding some of the regular EVM interface's methods in how it executes transactions. Our sharding client will process transactions using this modified vm.
+
+An example of the current approach followed in the python implementation can be found [here](https://github.com/ethereum/py-evm/blob/sharding/evm/vm/forks/sharding/__init__.py)
+
+In this case, the VM of the sharding client is set to be the subclassed ByzantiumVM that has its methods overwritten and sharding transactions primitives specified.
+
+### Contributing
+
+We will be tracking progress on these major milestones as through WIP pull requests. If you have any thoughts on major parts of the system that will still need to be implemented, message the Prysmatic Labs team gitter channel.

sharding/genesis.json

@@ -0,0 +1,14 @@
+{
+    "config": {
+        "chainId": 1000,
+        "homesteadBlock": 0,
+        "eip155Block": 0,
+        "eip158Block": 0
+    },
+    "difficulty": "200",
+    "gasLimit": "2100000",
+    "alloc": {
+        "826f3F66dB0416ea82033aE917A611bfBF4D98b6": { "balance": "300000" },
+        "Dd0cbc3AE49DD62915877ebFa6050cad362B83Ad": { "balance": "400000" }
+    }
+}