Updates README, adds INSTALL and FAQ and created an example for utxo …

…set analysis

FAQ.md

@@ -0,0 +1,52 @@
+# Frequently Asked Questions (and Answers!)
+
+### I just downloaded the code from GitHub, how can I make it work?
+
+First, you must install all the dependencies, both system and Python ones. Refer to the dependencies section of the
+README to check them (specially for system dependencies). Python dependencies can be installed by running `pip install -r requirements.txt`
+
+### I installed all the dependencies, but the code still doesn't work!
+
+Once all dependencies are installed you should create a configuration file using `sample_conf.py` as an example. The purpose
+of the configuration file is to define the paths of the directories that will be used for IO by the library, for example
+where the public and private keys will be stored once a new pair are created, where the `chainstate` directory is located
+when performing an `utxo set` analysis using `STATUS`, where the data files of the analysis or the charts will be stored,
+etc. `sample_conf.py` contains come hints of what the folders should be for each case, but it will change depending on your OS.
+
+### Is there any OS required to use the library?
+
+Not really, it has been tested both in `OSX` and `Linux` (specially `arch`, `debian` and `ubuntu`). However, `leveldb` does
+not work properly with `Windows` systems (at lest it doesn't at the time of writing this, Hi people from the future!), so if
+you are planning to use `STATUS`, better avoid `Windows`. (If someone can make it work on it, PR are more than welcome!)
+
+
+### I'm trying to use some code I found in the examples / Issues and it's not working. Why you do this to me?!
+
+Have you checked that you are in the proper `git` branch? Sometimes the functionality or even the calls can change between
+different branches. Some parts of the code could have been moved or renamed. Run `git branch` and `git checkout branch_name`
+if you are not in the one you are supposed to be!
+
+### I want to use your library to create some fancy app for "insert the purpose here", can you do it for me?
+
+Nope! I'm more than happy to help you with any kind of trouble you face when using the library, as well as to fix any
+bug you may find. However, don't ask me to develop your application for you!
+
+### Do I need a PhD to use the library?
+
+Not really, the library is quite exhaustively commented to ease the process of using it, however, some knowledge of `Python`,
+`Bitcoin` and `git` is required.
+
+### I really like your library, is there anything I can do to thank you?
+
+You can star the GitHub code.
+
+### But I really really like it!
+
+Well, I like beer, fell free to buy me one:
+
+BTC_ADDR_HERE
+
+### Was this FAQ really necessary?
+
+Seems so :(
+

INSTALL.md

@@ -0,0 +1,23 @@
+### Installation
+
+Download / clone the repository and add it as a Python repository by:
+
+- Placing it under the Python's lib folder (by default under `/usr/lib/python2.7/` for Linux systems and 
+`/Library/Python/2.6/site-packages/` for OS X).
+
+or
+
+- Including the library folder path in the Python's path by running 
+`PYTHONPATH=$PYTHONPATH:path_to_the_code/bitcoin_tools`.
+
+or
+
+- Using the library as a `PyCharm project`.
+
+Copy / rename `sample_conf.py` to `conf.py` and configure it using your own data (some hints are included in 
+the file).
+
+Create a directory that matches `bitcoin_tools_dir` on you `conf.py` (Notice that this is a user data directory, where
+the data generated by the library will be read / written, not the path to the code itself).
+
+Install all the dependencies (see next section).

README.md

@@ -20,30 +20,6 @@ bitcoin_tools allows you to:
 Additionally, bitcoin_tools contains ``STATUS`` an
 **ST**atistical **A**nalysis **T**ool for **U**txo **S**et under `analysis/status`
 
-### Installation
-
-Download / clone the repository and add it as a Python repository by:
-
-- Placing it under the Python's lib folder (by default under `/usr/lib/python2.7/` for Linux systems and 
-`/Library/Python/2.6/site-packages/` for OS X).
-
-or
-
-- Including the library folder path in the Python's path by running 
-`PYTHONPATH=$PYTHONPATH:path_to_the_code/bitcoin_tools`.
-
-or
-
-- Using the library as a `PyCharm project`.
-
-Copy / rename `sample_conf.py` to `conf.py` and configure it using your own data (some hints are included in 
-the file).
-
-Create a directory that matches `bitcoin_tools_dir` on you `conf.py` (Notice that this is a user data directory, where
-the data generated by the library will be read / written, not the path to the code itself).
-
-Install all the dependencies (see next section).
-
 ### Dependencies
 
 The library has the abovementioned dependencies (which can be satisfied by using `pip install -r requirements.txt`):
@@ -71,6 +47,18 @@ and `libleveldb-dev` must be installed:
 
 `sudo apt-get install python-tk libleveldb-dev`
 
+### Installation
+
+Refer to INSTALL.md
+
+### Some trouble getting started with the repo?
+
+Refer to INSTALL.md and FAQ.md
+
+### Still not working?
+
+Fell free to open an issue.
+
 ### Examples
 
 Down below you can find some examples of how to use some of the library functions. More examples can be found in 
@@ -145,13 +133,16 @@ tx.display()
 from bitcoin_tools.analysis.status.data_dump import utxo_dump
 from bitcoin_tools.analysis.status.utils import parse_ldb
 
-f_utxos = "utxos.txt"
+# Set the version of the Bitcoin Core you are using (which defines the chainstate format)
+# and the IO files.
+version = 0.15
+f_utxos = "decoded_utxos.txt"
 f_parsed_utxos = "parsed_utxos.txt"
 
 # Parse all the data in the chainstate.
-parse_ldb(f_utxos)
+parse_ldb(f_utxos, version=version)
 # Parses transactions and utxos from the dumped data.
-utxo_dump(f_utxos, f_parsed_utxos)
+utxo_dump(f_utxos, f_parsed_utxos, version=version)
 
 # Data is stored in f_utxos and f_parsed_utxos files respectively
 ```

examples/utxo_set_analysis.py

@@ -0,0 +1,3 @@
+# For an example of an analysis of the UTXO set using STATUS you can directly refer to:
+# bitcoin_tools/analysis/status/run_analysis. If you run the code as it is, it will perform a full analysis, which
+# may take quite long, comment the parts of the analysis that you don't desire to run.