Skip to content

Commit 22c85c5

Browse files
maltemoesermaltemoeser
committed
docs: update readme
[ci skip]
1 parent 9f0b657 commit 22c85c5

File tree

1 file changed

+30
-103
lines changed

1 file changed

+30
-103
lines changed

‎README.rst‎

Lines changed: 30 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,147 +1,74 @@
11
BlockSci
22
~~~~~~~~~~~~~~~~~~
33

4-
**We're currently preparing a new release, which should be ready in a few weeks. If you've used the development branch `v0.6`, the current master branch is not backwards-compatible and requires a reparse. The documentation has not been fully updated yet.**
4+
The Bitcoin blockchain — currently 280 GB and growing — contains a massive amount of data that can give us insights into the Bitcoin ecosystem, including how users, businesses, and miners operate. BlockSci enables fast and expressive analysis of Bitcoin’s and many other blockchains. The accompanying paper explains its design and applications: https://arxiv.org/pdf/1709.02489.pdf (an updated version of the paper has been accepted at Usenix Security and will be available soon).
55

6-
The Bitcoin blockchain — currently 170 GB and growing — contains a massive amount of data that can give us insights into the Bitcoin ecosystem, including how users, businesses, and miners operate. BlockSci enables fast and expressive analysis of Bitcoin’s and many other blockchains. The accompanying working paper explains its design and applications: https://arxiv.org/pdf/1709.02489.pdf
6+
Current tools for blockchain analysis depend on general-purpose databases that provide "ACID" guarantees. But that’s unnecessary for blockchain analysis where the data structures are append-only. We take advantage of this observation in the design of our custom in-memory blockchain database as well as an analysis library. BlockSci’s core infrastructure is written in C++ and optimized for speed. (For example, traversing every transaction input and output on the Bitcoin blockchain takes only **1 second** on our r5.4xlarge EC2 machine.) To make analysis more convenient, we provide Python bindings and a Jupyter notebook interface.
7+
8+
*This repository contains research code that may contain bugs and errors and may break in unexpected ways. We are an academic team and aren’t able to provide the level of QA and support that you might expect from a commercial project.*
79

8-
Current tools for blockchain analysis depend on general-purpose databases that provide "ACID" guarantees. But that’s unnecessary for blockchain analysis where the data structures are append-only. We take advantage of this observation in the design of our custom in-memory blockchain database as well as an analysis library. BlockSci’s core infrastructure is written in C++ and optimized for speed. (For example, traversing every transaction input and output on the Bitcoin blockchain takes only **1 second** on our r4.2xlarge EC2 machine.) To make analysis more convenient, we provide Python bindings and a Jupyter notebook interface.
910

1011
Documentation
1112
=====================
12-
- Documentation_ is available for the Python interface.
13-
14-
.. _Documentation: https://citp.github.io/BlockSci/
15-
16-
- A demonstration Notebook_ is available in the Notebooks folder.
17-
18-
.. _Notebook: https://citp.github.io/BlockSci/demo.html
19-
20-
- Our FAQ_ contains many useful examples and tips.
21-
22-
.. _FAQ: https://github.com/citp/BlockSci/wiki
23-
24-
For installation instructions, see below.
25-
26-
Latest release (BlockSci v0.5.0)
27-
================================
28-
29-
Version 0.5.0 focuses mainly on improvements and cleanups in the Python interface. The largest new feature is the introduction of vectorized operations which return NumPy arrays, enabling much more rapid usage of BlockSci's Python interface. You can read more details about the release in the `release notes`_. We are releasing a new AMI_ running 0.5.0 (explained under "Quick setup" below).
30-
31-
.. _release notes: https://citp.github.io/BlockSci/changelog.html#version-0-5-0
32-
.. _AMI: https://console.aws.amazon.com/ec2/home?region=us-east-1#launchAmi=ami-0d0091e593d44cce1
33-
34-
35-
Quick setup using Amazon EC2
36-
==============================
37-
38-
Note: The AMI is temporarily unavailable. We are currently working on a new version on the v0.6 development branch and will make a new AMI available soon.
39-
40-
AMI Last updated on May 8, 2018.
41-
42-
If you want to start using BlockSci immediately, we have made available an EC2 image: ami-0d0091e593d44cce1_. We recommend using an instance with 60 GB of memory or more for optimal performance (r5.2xlarge). As of August 2019 the default disk size of 500GB may not suffice anymore, we therefore recommend choosing a larger disk size (e.g., 600 GB) when you first create the instance. On boot, a Jupyter Notebook running BlockSci will launch immediately. To access the notebook, you must set up port forwarding to your computer. Inserting the name of your private key file and the domain of your ec2 instance into the following command will make the Notebook available on your machine.
4313

44-
.. code-block:: bash
14+
We provide instructions in our online documentation_:
4515

46-
ssh -i .ssh/your_private_key.pem -N -L 8888:localhost:8888 ubuntu@your_url.amazonaws.com
16+
- `Installation instructions`_
4717

48-
This sets up an SSH tunnel between port 8888 on your remote EC2 instance and port 8888 on your localhost. You can use whichever port you like on your local machine. Next, you can navigate to http://localhost:8888/ in your browser and log in with the password 'blocksci'. A demo notebook will be available for you to run and you can begin exploring the blockchain. Don't forget to shut down the EC2 instance when you are finished since EC2 charges hourly.
18+
- `Using BlockSci`_
4919

50-
AWS instances suffer from a `known performance issue`_ when starting up from an existing AMI. When the machine starts up it doesn't actually load all of the data on the disk so that startup can be instant. Instead it only loads the data when it is accessed for the first time. Thus BlockSci will temporarily operate slowly when the image has first been launched. Within about 20 minutes after launch, the most crucial data files will be loaded to disk from the network, and most queries should run at full speed, including all examples in the demo Notebook. After about 3.5 hours, all data will be loaded to disk and all queries will reach full speed.
20+
- `Guide for the fluent interface`_
5121

52-
There is no need for user intervention to resolve this issue since the machine will do so automatically on launch.
22+
- `Module reference for the Python interface`_
5323

54-
The AMI contains a fully updated version of the Bitcoin blockchain as of the creation date of the AMI (May 8, 2018). Additionally it will automatically start a Bitcoin full node and update the blockchain once every hour to the latest version of the chain.
55-
When you start the AMI for the first time, it will take a few hours for the full node to synchronize with the Bitcoin network and for new blocks (after May 2018) to become available in BlockSci.
24+
- `Troubleshooting`_
5625

57-
.. _known performance issue: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-initialize.html
58-
59-
Using the analysis library
60-
============================
61-
62-
After the parser has been run, the analysis library is ready for use. This can again be used through two different interfaces
63-
64-
C++
65-
------
66-
67-
In order to use the C++ library, you must compile your code against the BlockSci dynamic library and add its headers to your include path. The Blockchain can then be constructed given the path to the output of the parser.
68-
69-
.. code-block:: c++
70-
71-
#include <blocksci/blocksci.hpp>
72-
73-
int main(int argc, const char * argv[]) {
74-
blocksci::Blockchain chain{"file_path_to_output-directory"};
75-
}
26+
.. _documentation: https://citp.github.io/BlockSci/
7627

77-
Python
78-
-------
28+
.. _Installation instructions: https://citp.github.io/BlockSci/setup.html
7929

80-
Note that BlockSci only supports Python 3.
30+
.. _Guide for the fluent interface: https://citp.github.io/BlockSci/fluent-interface.html
8131

82-
To use the BlockSci in Python, you only need to import the BlockSci library. By default the library is installed into BlockSci/Notebooks. To use the library first open the Python interpreter in that folder:
32+
.. _Using BlockSci: https://citp.github.io/BlockSci/using-blocksci.html
8333

84-
.. code-block:: bash
34+
.. _Module reference for the Python interface: https://citp.github.io/BlockSci/reference/reference.html
8535

86-
cd BlockSci/Notebooks
87-
python3
88-
89-
With the Python interpreter open, the following code will load a Blockchain object created from the data output by the parser:
36+
.. _Troubleshooting: https://citp.github.io/BlockSci/troubleshooting.html
9037

91-
.. code-block:: python
9238

93-
import blocksci
94-
chain = blocksci.Blockchain("file_path_to_parser_output-directory")
39+
Our FAQ_ contains additional useful examples and tips.
9540

96-
If you would like to use BlockSci through a web interface, we recommend the use of `Jupyter Notebook`_. Once Jupyter is installed, simply navigate into BlockSci/Notebooks and run:
41+
.. _FAQ: https://github.com/citp/BlockSci/wiki
9742

98-
.. code-block:: bash
9943

100-
jupyter notebook
101-
102-
which will open a window in your browser to the Jupyter server.
44+
Latest release (BlockSci v0.7.0)
45+
================================
10346

104-
.. _Jupyter Notebook: https://jupyter.readthedocs.io/en/latest/install.html
47+
Version 0.7.0 is based on the development branch 0.6, but requires a full reparse.
10548

49+
Version 0.7.0 comes with a new `fluent Python interface`_ for fast and expressive blockchain queries. It contains a number of `important bug fixes`_ as well as many smaller improvements. We recommend upgrading to the latest version of BlockSci and no longer use v0.5.
10650

107-
Setting up BlockSci Locally
108-
======================================
51+
.. _important bug fixes: https://citp.github.io/BlockSci/changelog.html
52+
.. _fluent Python interface: https://citp.github.io/BlockSci/fluent-interface.html
10953

110-
Compilation_ instructions as well as setup_ instructions are available in the documentation.
54+
Amazon EC2 AMI
55+
==============================
11156

112-
.. _Compilation: https://citp.github.io/BlockSci/compiling.html
113-
.. _setup: https://citp.github.io/BlockSci/setup.html
57+
We currently do not provide an AMI for BlockSci.
11458

11559

11660
Getting help
11761
============
11862

119-
Please make sure to check the list of `Frequently Asked Questions`_ first.
120-
If you've encountered a bug or have a question about using BlockSci not answered in the FAQ, the best way to get help is to open a GitHub issue. We are an academic team and aren't able to provide the standard of support that you might expect for a commercial project, but we'll do our best.
63+
Please make sure to check the list of `Frequently Asked Questions`_ as well as the issue tracker first.
64+
If you've encountered a bug or have a question about using BlockSci not already answered, the best way to get help is to open a GitHub issue. We are an academic team and aren't able to provide the standard of support that you might expect for a commercial project.
12165

12266
.. _Frequently Asked Questions: https://github.com/citp/BlockSci/wiki
12367

12468

125-
Contributing
126-
============
127-
128-
We highly welcome contributions to BlockSci. Below we've listed a few ways you can help improve BlockSci:
129-
130-
- *Maintenance:* We greatly appreciate help in maintaining BlockSci, including raising issues with reproducible examples, reviewing pull requests, helping answer questions about using BlockSci, or fixing smaller bugs.
131-
- *Documentation:* We welcome contributions that improve our documentation_ and FAQ_ or add helpful comments to the code.
132-
- *Testing:* We welcome contributions that extend or improve our existing Python test suite. We also welcome improvements of the `testchain-generator`_ that we use to generate a synthetic blockchain to run tests against.
133-
- *Code contributions:* If you're interested in making larger code contributions (e.g., adding new features, extensive rewrites of existing code), please contact us first.
134-
135-
We're currently working on a new version on the `v0.6 branch`_. Most contributions should use this development branch as a starting point. (The development branch can be unstable at times. The master branch contains the last stable version for which an AMI was released. All other branches are feature branches that shouldn't be used.)
136-
137-
.. _testchain-generator: https://github.com/citp/testchain-generator
138-
.. _v0.6 branch: https://github.com/citp/BlockSci/tree/v0.6
139-
.. _documentation: https://citp.github.io/BlockSci/
140-
.. _FAQ: https://github.com/citp/BlockSci/wiki
141-
14269
Team & contact info
14370
===================
14471

145-
BlockSci was created by Harry Kalodner, Steven Goldfeder, Alishah Chator, Malte Möser, and Arvind Narayanan at Princeton University. It is supported by NSF grants CNS-1421689 and CNS-1651938 and an NSF Graduate Research Fellowship under grant number DGE-1148900. We've released a paper_ describing BlockSci's design and a few applications that illustrate its capabilities. You can contact the team at blocksci@lists.cs.princeton.edu.
72+
BlockSci was created by Harry Kalodner, Malte Möser, Kevin Lee, Steven Goldfeder, Martin Plattner, Alishah Chator, and Arvind Narayanan at Princeton University. It is supported by NSF grants CNS-1421689 and CNS-1651938, an NSF Graduate Research Fellowship under grant number DGE-1148900 and a grant from the Ripple University Blockchain Research Initiative. We've released a paper_ describing BlockSci's design and a few applications that illustrate its capabilities (an updated version of the paper has been accepted at Usenix Security and will be available soon). You can contact the team at blocksci@lists.cs.princeton.edu.
14673

14774
.. _paper: https://arxiv.org/abs/1709.02489

0 commit comments

Comments
 (0)