Skip to content

Commit 4004c84

Browse files
willcl-arkwillcl-ark
committed
add jupyter notebook exercies 01
1 parent 275f9b1 commit 4004c84

File tree

4 files changed

+218
-0
lines changed

4 files changed

+218
-0
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
index.html
2+
.ipynb_checkpoints
3+
*Copy*.ipynb

‎01_overview-and-development.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -769,6 +769,73 @@ Many ideas are assigned a BIP and then never implemented or used on the wider ne
769769

770770
Source: https://github.com/XAMPPRocky/tokei[tokei^]
771771

772+
== Exercises
773+
774+
Subsequent sections will contain various exercises related to their subject areas which will require controlling Bitcoin Core nodes, compiling Bitcoin Core and making changes to the code.
775+
776+
To prepare for this we will begin with the following exercises which will ensure that our environment is ready:
777+
778+
. Build Bitcoin Core from source
779+
** Clone Bitcoin Core repository from GitHub
780+
** Check out the latest release tag (e.g. `v24.0.1`)
781+
** Install any dependencies required for your system
782+
** Follow the build instructions to compile the program
783+
** Run `make check` to run the unit tests
784+
** Follow the documentation to install dependencies required to run the functional tests
785+
*** Run the functional tests
786+
. Run a `bitcoind` node in regtest mode and control it using the `cli` tool
787+
** `./src/bitcoind -regtest` will start bitcoind in regtest mode. You can then control it using `./src/bitcoin-cli -regtest -getinfo`
788+
. Run and control a Bitcoin Core node using the `TestShell` python class from the test framework in a Jupyter notebook
789+
** See <<test_shell_nodes, Running nodes via Test Framework>> for more information on how to do this
790+
791+
[#test_shell_nodes]
792+
.Running nodes via Test Framework
793+
****
794+
Using Bitcoin Core's Test Framework means that nodes can be started, controlled and stopped using a python control class.
795+
Additionally, they are run in a temporary directory which is automatically removed by the system later, if not done
796+
manually.
797+
798+
In addition to this, the `TestShell` class has an extremely similar interface to `bitcoin-cli`, where `bitcoin-cli` commands are mapped to `TestShell` methods, and arguments can be supplied positionally or as named values.
799+
800+
When combined with a jupyter notebook, the result is easy-to-setup ephemeral nodes where iteration on complex commands is more pleasant, and complex sequences of commands can be reproduced without having to write bash scripts or use shell history.
801+
802+
To begin it is recommended to create a python virtual environment which can be done as follows when in the onboarding to bitcoin core top level directory:
803+
804+
[source, bash]
805+
----
806+
python3 -m venv "obc-venv"
807+
source obc-venv/bin/activate
808+
----
809+
810+
TIP: if using fish shell you can use: `source obc-venv/bin/activate.fish` instead
811+
812+
Once your venv is set up and activated you can install the requirements for jupyter notebook using:
813+
814+
[source, bash]
815+
----
816+
pip install -r requirements.txt
817+
----
818+
819+
Next start the notebook with:
820+
821+
[source, bash]
822+
----
823+
jupyter notebook
824+
----
825+
826+
This will open a list of all the files in this directory.
827+
Opening the file named `exercises.ipynb` will start the empty notebook containing instructions on how to use `TestShell` from the test Framework.
828+
829+
When you are finished you can deactivate the venv using
830+
831+
[source, bash]
832+
----
833+
deactivate
834+
----
835+
836+
TIP: Don't forget to re-activate your venv each time you want to start the Jupyter notebook after deactivating the venv!
837+
****
838+
772839
////
773840
== Group work
774841

‎exercises.ipynb‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {
6+
"pycharm": {
7+
"name": "#%% md\n"
8+
}
9+
},
10+
"source": [
11+
"## Extending python path\n",
12+
"\n",
13+
"First we must add the path to Bitcoin Core's test_framework directory to the python system path\n",
14+
"\n",
15+
"The test_framework is found within the Bitcoin Core source directory's `/test/functional` directory, e.g. as shown below\n",
16+
"`/home/will/src/bitcoin/test/functional`"
17+
]
18+
},
19+
{
20+
"cell_type": "code",
21+
"execution_count": 1,
22+
"metadata": {},
23+
"outputs": [],
24+
"source": [
25+
"# Add the functional test framework to our PATH\n",
26+
"import sys\n",
27+
"sys.path.insert(0, \"/home/will/src/bitcoin/test/functional\")"
28+
]
29+
},
30+
{
31+
"cell_type": "markdown",
32+
"metadata": {
33+
"pycharm": {
34+
"name": "#%% md\n"
35+
}
36+
},
37+
"source": [
38+
"## Importing the TestShell class\n",
39+
"\n",
40+
"Next we can import the `TestShell` class which will let us control a regtest Bitcoin Core node using python commands\n",
41+
"equivalent to the `bitcoin-cli` ones."
42+
]
43+
},
44+
{
45+
"cell_type": "code",
46+
"execution_count": 2,
47+
"metadata": {
48+
"pycharm": {
49+
"name": "#%%\n"
50+
}
51+
},
52+
"outputs": [],
53+
"source": [
54+
"# Import libraries\n",
55+
"from test_framework.test_shell import TestShell"
56+
]
57+
},
58+
{
59+
"cell_type": "markdown",
60+
"metadata": {
61+
"pycharm": {
62+
"name": "#%% md\n"
63+
}
64+
},
65+
"source": [
66+
"## Node setup\n",
67+
"\n",
68+
"Finally, we must set up one or more nodes using the `setup()` method."
69+
]
70+
},
71+
{
72+
"cell_type": "code",
73+
"execution_count": 3,
74+
"metadata": {
75+
"pycharm": {
76+
"name": "#%%\n"
77+
}
78+
},
79+
"outputs": [
80+
{
81+
"name": "stdout",
82+
"output_type": "stream",
83+
"text": [
84+
"2022-12-13T22:18:13.318000Z TestFramework (INFO): Initializing test directory /tmp/bitcoin_func_test_wbfjhnzg\n"
85+
]
86+
}
87+
],
88+
"source": [
89+
"# Setup our regtest environment\n",
90+
"test = TestShell().setup(\n",
91+
" num_nodes=2,\n",
92+
" setup_clean_chain=True,\n",
93+
")"
94+
]
95+
},
96+
{
97+
"cell_type": "markdown",
98+
"metadata": {},
99+
"source": [
100+
"## Node control\n",
101+
"\n",
102+
"Nodes are presented as a list stored in the `nodes` attribute of the `TestShell` object.\n",
103+
"Simply index the list to control the required node, e.g.:"
104+
]
105+
},
106+
{
107+
"cell_type": "code",
108+
"execution_count": null,
109+
"metadata": {
110+
"pycharm": {
111+
"name": "#%%\n"
112+
}
113+
},
114+
"outputs": [],
115+
"source": [
116+
"node1 = test.nodes[0]\n",
117+
"node2 = test.nodes[1]\n"
118+
]
119+
},
120+
{
121+
"cell_type": "markdown",
122+
"metadata": {},
123+
"source": []
124+
}
125+
],
126+
"metadata": {
127+
"kernelspec": {
128+
"display_name": "Python 3 (ipykernel)",
129+
"language": "python",
130+
"name": "python3"
131+
},
132+
"language_info": {
133+
"codemirror_mode": {
134+
"name": "ipython",
135+
"version": 3
136+
},
137+
"file_extension": ".py",
138+
"mimetype": "text/x-python",
139+
"name": "python",
140+
"nbconvert_exporter": "python",
141+
"pygments_lexer": "ipython3",
142+
"version": "3.9.7"
143+
}
144+
},
145+
"nbformat": 4,
146+
"nbformat_minor": 1
147+
}

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
notebook

0 commit comments

Comments
 (0)