basic project description

README.md

@@ -1,35 +1,55 @@
-# Repository Template for Python 3.11 Projects with Cython Modules
+# POLLU-BLOCK Blockchain Demonstrator
 
-## Tools for Project and Package Management
+## Anwendungsszenario
 
-[![pdm-managed](https://img.shields.io/endpoint?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fpdm-project%2F.github%2Fbadge.json)](https://pdm-project.org)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+Dieses Repo enthält eine Applikation, die im Rahmen des Forschungsprojekts "POLLU-BLOCK" entwickelt wurde. Ziel der Applikation ist, eine Blockchain als Integritätsprüfanker zu verwenden. Aufgenommene Sensordaten aus einem Produktionsprozess werden in einer lokalen Datenbank abgespeichert. Die enthaltenen Attribute werden in einem gemeinsamen String zusammengeführt, mit SHA-256 gehasht und dieser Hashwert in der Blockchain als Datenkomponente im Block hinterlegt.
 
-Python projects are managed with **PDM** ([link to GitHub Source](https://github.com/pdm-project/pdm)), a PEP-compliant project and dependency management tool.
-The applicable settings are contained within the PyProject-TOML file. In order to use a repo which was created with this template is to tell PDM which Python interpreter to use and then to install the whole project into the created virtual environment. If the interpreter is not available you will need to install it via PDM.
+Das System ist so gestaltet, dass ein Block immer die Daten genaue eines Datenbankeintrags enthält.
+
+### Nutzerführung
+
+Die Anwendung ist ein Kommandozeilen-Programm mit geführter Nutzerinterkation. Schritte werden der Reihe nach beschrieben. Möchte der Nutzer fortfahren, so ist an geeigneter Stelle stets eine kurze Bestätigung erforderlich. So kann die Anwendung in individuellem Tempo genutzt werden.
+
+### Szenario-Auswahl
+
+Die Anwendung erlaubt die Auswahl zweier möglicher Anwendungsszenarien:
+
+#### *Datenvalidierung*
+
+In diesem Szenario werden Daten zufällig aus der Sensordatenbank ausgelesen und deren Hashwert bestimmt. Anschließend wird geschaut, ob der zu diesem Eintrag hinterlegte Block tatsächlich denselben Hashwert für die Daten besitzt. Ist dies der Fall, so gilt der Datensatz als integer. In einem realen Anwendungsfall könnte hier also sichergestellt werden, dass die Daten nicht manipuliert wurden.
+
+#### *Datengenerierung*
+
+Bei der Datengenerierung wird auf Basis der Vergangenheit zufällig ein vermeintlich neuer Eintrag für die Sensordatenbank generiert und dort abgespeichert. Anschließend wird gezeigt, wie die Daten gebündelt und der Blockchain übergeben werden. Danach wird tatsächlich ein Block "geschürft" oder "gemined", was je nach Rechnerausstattung und eingestellter Schwierigkeit eine gewisse Zeit dauern kann.
+
+Ist der Mining-Prozess abgeschlossen wird analog zur *Datenvalidierung* geprüft, ob der Mining-Vorgang erfolgreich war und die Hashwerte in beiden Fällen übereinstimmen.
+
+
+## Blockchain
+
+Das Projekt enthält eine funktionsfähige Blockchain, die nach dem Konsensus-Algorithmus Proof-of-Work (PoW) funktioniert. Es wird solange ein Baustein des Blocks, die Nonce, geändert, bis der resultierende Hashwert des gesamten Blocks einer bestimmten Schwierigkeit entspricht. Im vorliegenden Fall wird das durch die Anzahl der Null-Bits am Anfang des Hashwertes definiert. Ein guter Richtwert für Demonstrationszwecke mit Live-Mining ist ein Wert von 24 Bits, also 3 Bytes. Die Schwierigkeit kann über eine Konstante im Paket festgelegt werden. Diese ist in der Datei ``constants.py`` zu finden.
+
+Im Hintergrund wird für jeden Hash-Lauf einmalig SHA-256 genutzt. Dieser Hash-Algorithmus wird beispielsweise auch von der Kryptowährung Bitcoin verwendet. Die Blöcke sind miteinander verbunden, indem jeder Block den Haswert seines Vorgängers enthält.
+
+Die Implementierung der Blockchain erfolgte mithilfe von [Cython](https://cython.org/) und arbeitet mit [OpenSSL](https://www.openssl.org/) für Hashing-Operationen. Python wird als Wrapper um diese Blockchain-Implementierung genutzt. Der Rest der Applikation ist ebenfalls in Python implementiert.
+
+Die Blockchain wird zu Beginn geladen und validiert. Die Validierung beinhaltet die Prüfung der Hashwerte eines jeden Blocks sowie der korrekten Verkettung aller Blöcke über ihren Vorgänger-Hashwert.
+
+## Start der Anwendung
+
+Die Anwendung wird über ein Terminal mit dem Python-Interpreter der mitgelieferten Umgebung gestartet. Hierfür steht ein Startup-Skript zur Verfügung, welches im selben Ordner wie der Interpreter abgelegt ist. Es ist darauf zu achten, dass das Skript auch mit dem Interpreter dieses Ordners ausgeführt wird und nicht mit einer Systeminstallation.
+
+Der Start erfolgt über den Aufruf:
 
 ```console
-pdm use 3.11.11 # example of a given version
-pdm install
+path\to\env> .\python.exe .\pollublock.py 
 ```
 
-This installs all mandatory development dependencies such as:
-- Ruff (formatting and linting)
-- pytest (unittest framework)
-- coverage.py (measuring test coverage)
-- pytest-cov (integration of coverage into pytest)
-- pytest-xdist (allows to execute the tests on multiple CPU cores)
-- bump-my-version (CLI tool to manage version bumping)
-- Nox (Python runner, e.g. to run test suite on multiple Python versions)
-- pdoc (to auto-generate documentation from docstrings)
-- Jupyterlab and widgets (to perform fast prototyping and enable exploratory data analysis)
+## Datenbanken
 
-## Cython
+Die Applikation nutzt im Hintergrund zwei Datenbanken:
 
-This template repository assumes the need of [Cython](https://cython.org/) modules. Usually this is the case if the default Python performance is not sufficient or the code shall be obfuscated because of possible theft by a customer to whom it is shipped. Cython is convenient way to build C-Extensions for Python without the hustle of directly using Python's clumsy C-API. It is even possible to directly compile Python modules which have no Cython-specific code in them. Sometimes this alone yields performance gains. To achieve better results Cython's type annotation must be used and the interaction with the Python interpreter should be avoided, so that as much work as possible is done in the compiled C code.
+- ``blockchain.db``: Hier werden die Daten der Blockchain persistiert. Aus dieser Datenbank heraus wird die Blockchain initialisiert. Bei einer realen Blockchain-Anwendung wären diese Informationen verteilt im Netzwerk und könnten damit nicht einfach überschrieben werden.
+- ``pollublock_data.db``: Hier wurden die Sensordaten gespeichert, die als Datenauszug durch die Projektpartner bereitgestellt wurden. Zusätzlich werden neue Datensätze angelegt, die im Anwendungsszenario *Datengenerierung* entstehen.
 
-Cython also supports C++ language compilation, even though it is not as well supported as C.
-
-### Compilation
-
-This repo still uses PDM to manage the project. Since PDM does not support building C extensions it is configured to call [setuptools](https://setuptools.pypa.io/en/latest/index.html). The invoked build script is defined in the file `setup.py` in the project's root directory. All Cython modules have to be defined in this file. Cython provides a convenience function `cythonize` to construct a list of `setuptools.Extension` instances which are handed over to the build process. Depending on the project the script needs adaptation to meet specific requirements.
+> *Die Datenbanken liegen im Paketverzeichnis und dürfen **nicht verändert** werden. Anderenfalls kann es zu Fehlern in der Programmausführung kommen.*