Populus¶

Populus is a tool for the Ethereum blockchain and smart contract management. The project uses Populus internally. Populus is a Python based suite for

• Running arbitrary Ethereum chains (mainnet, testnet, private testnet)
• Running test suites against Solidity smart contracts

Preface¶

Instructions are written in OSX and Linux in mind.

Experience needed

• Basic command line usage
• Basic Github usage
• Basic GNU make usage

Setting up - OSX¶

Packages needed

• Populus native dependencies

Get Solidity compiler. For OSX:

# Install solcjs using npm (JavaScript port of solc)
sudo npm install -g solc

# Symlink solcjs as solc, so that Populus finds it as default solc command
sudo ln -s `which solcjs` /usr/local/bin/solc

Clone this repository from Github.

Python 3.x required. See installing Python.

python3.5 --version
Python 3.5.2

Create virtualenv for Python package management in the project root folder (same as where setup.py is):

python3.5 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Setting up - Ubuntu Linux 14.04¶

Install dependencies:

sudo add-apt-repository ppa:fkrull/deadsnakes
sudo apt-get update
sudo apt-get install -y python3.5 python3.5-dev
sudo apt install -y git build-essential python3-setuptools libssl-dev

Install Go Ethereum:

sudo apt-get install software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install -y ethereum solc

Then:

git clone git@github.com:nordledger/eireg.git
cd eireg
python3.5 -m venv --without-pip venv
source venv/bin/activate
curl https://bootstrap.pypa.io/get-pip.py | python
pip install -r requirements.txt
pip install -e .

Working on a local private testnet¶

See a local private chain starts:

make run-local-test-chain

Abort with CTRL-C when it starts to generate DAG.

Copy in a custom keyfile for the coinbase account, so that we have the same deterministic coinbase account id for all runs:

cp keyfiles/UTC--2016-11-08T16-15-25.205056382Z--27d1755735abaf6cefb2299d18458b1091bb2c7b  chains/local_test/keystore/

Start a local private chain again and mine some ETH for a while (1 minute):

make run-local-test-chain

Abort with CTRL-C.

First we deploy a version of the contract on local chain managed by Populus.

make deploy-local

You will get deployment details:

Transaction Mined
=================
Tx Hash      : 0x3557ed87c7eb517c0e9c69dd15ba7d5c4064ce8d9b40caee40f3522fe6357a73
Address      : 0xb52fc9040759e04b793cbb094dc64ee051377c4c
Gas Provided : 362249
Gas Used     : 262249

Write down the deployed contract Address field. It varies across deployments.

This will take ~60 seconds. The default coinbase account is 0x27d1755735abaf6cefb2299d18458b1091bb2c7b. It is configured in populus.ini.

Tieke / CSV import¶

Get Tieke electronic invoicing registry data dump as CSV.

Use import-tieke-csv tool to import existing records to a given smart contract address:

import-tieke-csv sample.csv local_test 0xb52fc9040759e04b793cbb094dc64ee051377c4c

Interacting with web browser¶

A simple interactive HTML demo is provided to interact with the contract.

Start geth deamon running a local chain. This is the same chain where we deployed the smart contract earlier:

make run-local-test-chain

It will start to mine transactions on your local computer.

In another terminal start a local development web server:

make run-web-server

Point your browser to:

http://localhost:8000

The demo directly interacts with Ethereum node over JSON-RPC protocol using web3.js library.

Fill in Contract address based on prior populus deploy command and Connect to contract.

Running automated test suite¶

To run test suite:

Types of Contributions¶

Get Started!¶

Ready to contribute? Here’s how to set up eireg for local development.

1. Fork the eireg repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/eireg.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv eireg
   $ cd eireg/
   $ python setup.py develop
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 eireg tests
   $ python setup.py test or py.test
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/miohtama/eireg/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ py.test tests.test_eireg