diff --git a/.gitignore b/.gitignore
index dcf3ab2..f0ce0ce 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@ build
 dist
 *.egg-info
 .eggs
+*.swp
 
 venv
 *.pyc
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
new file mode 100644
index 0000000..20819d2
--- /dev/null
+++ b/CHANGELOG.rst
@@ -0,0 +1,4 @@
+0.2.6
+-----
+
+initial release to pypi
diff --git a/MANIFEST.in b/MANIFEST.in
index 3e9b9dd..16b25e9 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -5,3 +5,8 @@ graft docs
 
 recursive-exclude docs/build *
 global-exclude *.py[co]
+
+include *.md
+include *.yml
+recursive-include requirements *.txt
+
diff --git a/README.rst b/README.rst
index 9082fad..b2bd832 100644
--- a/README.rst
+++ b/README.rst
@@ -18,7 +18,107 @@ claimchain-core
    :target: https://zenodo.org/badge/latestdoi/92275408
    :alt: Zenodo Citation
 
-|
+Installing
+==========
+
+You can install ``claimchain`` via pip::
+
+    pip install claimchain
+
+To run tests, checkout the git repository and run tox::
+
+
+    git clone https://github.com/claimchain/claimchain-core
+    cd claimchain-core
+    tox
+
+
+Usage
+=====
+
+High-level interface for ClaimChain consists of two classes, ``State`` for building claimchains, and ``View`` for parsing and interpreting claimchains.
+
+Building chains
+---------------
+
+The core abstraction for the a ClaimChain user is a `state`. The `state` contains information about the user, and claims they make about other users or objects. Currently, this package only supports private claims, which means the owner of a chain needs to explicitly make every claim readable by intended readers. Once the `state` is constructed it can be committed to the chain.
+
+Here is how user `Alice` would prepare her `state`::
+
+    from claimchain import State
+
+    state = State()
+
+    # Alice adds information about herself
+    state.identity_info = "Hi, I'm Alice"
+
+    # Alice adds private claims
+    state['bob'] = 'Bob is a good lad'
+
+Making claims accessible requires knowing the DH public key of each authorized reader. The way to obtain the DH keys of other users is described later. Assuming Alice has Carol's DH public key, ``carol_dh_pk``, she can allow Carol to access her claim about Bob::
+
+    state.grant_access(carol_dh_pk, ['bob'])
+
+Note that the second argument must be an iterable of claim labels, not a single label.
+
+To commit the state, first, a chain needs to be built, and second, the cryptographic keys have to be generated::
+
+    from hippiehug import Chain
+    from claimchain import LocalParams, State
+
+    state = State()
+
+    # Generate cryptographic keys
+    params = LocalParams.generate()
+
+    store = {}
+    chain = Chain(store)
+
+    with params.as_default():
+        head = state.commit(chain)
+
+The chain can then be published or transmitted to other users by publishing the ``store`` and communicating the chain's ``head``. Other users will be able to interpret the chain using the ``View`` interface, described below.
+
+
+Interpreting chains
+-------------------
+
+Having access to the store (dictionary) containing other user's chain, and a head of this user's chain, one can use the ``View`` interface.
+
+Here is how Carol can interpret Alice's claimchain, assuming Alice's store is ``alice_store``, the head of her chain is ``alice_head``, and ``params`` is Carol's ``LocalParams`` object::
+
+    from hippiehug import Chain
+    from claimchain import View
+
+    alice_chain = Chain(alice_store, root_hash=alice_head)
+
+    with params.as_default():
+        alice_view = View(alice_chain)
+
+        # Try to get claim with label 'bob'
+        claim = alice_view['bob']
+
+        assert claim == b'Bob is a good lad'
+
+Finally, this is how Carol can retrieve Alice's DH public key::
+
+    alice_dh_pk = alice_view.params.dh.pk
+
+This DH public key can be later used to grant Alice rights to read claims on Carol's chain.
+
+
+This package
+============
+
+=======================   =======================================================
+claimchain/state.py       High-level ClaimChain interface
+claimchain/core.py        Core operations of encoding claims and capabilities
+claimchain/crypto         Cryptographic utilities, and algorithm implementations
+=======================   =======================================================
+
+
+Simulations
+===========
 
 A core and experimental implementation of ClaimChain, a cryptographic data
 structure. See the `web page <https://claimchain.github.io>`_ to learn about
diff --git a/claimchain/utils/encodings.py b/claimchain/utils/encodings.py
index 3a1b8a9..12e9760 100644
--- a/claimchain/utils/encodings.py
+++ b/claimchain/utils/encodings.py
@@ -28,7 +28,7 @@ def ascii2bytes(s):
     >>> ascii2bytes('3yZe7d')
     b'test'
     """
-    return b58decode(s)
+    return b58decode(ensure_bytes(s))
 
 
 def pet2ascii(p):
@@ -47,4 +47,10 @@ def ascii2pet(s):
     >>> ascii2pet('3Xw3vNAdCmDLs')
     EcPt(00)
     """
-    return decode(b58decode(s))
+    return decode(b58decode(ensure_bytes(s)))
+
+
+def ensure_bytes(s):
+    if not isinstance(s, bytes):
+        s = s.encode("ascii")
+    return s
diff --git a/setup.py b/setup.py
index 69ded26..a6e89ee 100644
--- a/setup.py
+++ b/setup.py
@@ -12,7 +12,7 @@
 
 setup(
     name='claimchain',
-    version='0.2.5',
+    version='0.2.6',
     packages=["claimchain", "claimchain.crypto", "claimchain.utils"],
     license='MIT',
     description='Implementation of ClaimChain, a cryptographic data structure',
@@ -34,7 +34,7 @@
         'base58',
         'statistics',
         'defaultcontext',
-        'hippiehug >= 0.1.1',
+        'hippiehug >= 0.1.3',
         'profiled'
     ],
 
diff --git a/tox.ini b/tox.ini
index c87622d..3a0d0b8 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,8 +1,7 @@
 [tox]
 envlist = py27, py35
-skipsdist = True
 
 [testenv]
-deps =
-  -rrequirements/dev.txt
+deps = pytest
+    pdbpp
 commands = pytest -vs tests