Blockchain Logging Framework

Documentation

Please visit the javadoc documentation for more information.

This framework provides advanced logging capabilities for Ethereum applications on top of Web3J / Ethereum's JSON RPC. It consists of four components:

• BcQL: a query language for data on blockchains
• Validator: a component to check bcql documents for specification erros
• Extractor: a component to extract, transform and format data based on bcql
• Generator: a component to create efficient logging functionality that can be embedded into smart contracts

Example bcql documents include

• AugurContractRegistry.bcql
• CryptoKitties.bcql
• GeneratorShirtExample.bcql
• GeneratorGitExample.bcql
• NetworkStatistics.bcql
• Scripts contributed by Hendrik Bockrath
  • Bockrath_Forsage.bcql
  • Bockrath_Raiden.bcql
• Scripts contributed by Martin Rebesky
  • Rebesky_Augur.bcql
  • Rebesky_ChickenHunt.bcql
  • Rebesky_Idex1.bcql
  • Rebesky_Idex2.bcql
  • Rebesky_Idex3.bcql

Code demonstrating the use of the component scan be found here

• Validator
• Extractor
• Generator (the generated code has been tested with Solidity 0.5.10)

Publications

Details of the framework are described in more detail in the following publication:

C. Klinkmüller, A. Ponomarev, A.B. Tran, I. Weber, W. van der Aalst (2019): "Mining Blockchain Processes: Extracting Process Mining Data from Blockchain Applications". In: 17th International Conference on Business Process Management (Blockchain Forum).

C. Klinkmüller, I. Weber, A. Ponomarev, A.B. Tran, W. van der Aalst (2020): Efficient Logging for Blockchain Applications. arXiv:2001.10281.

Short video demonstration

https://user-images.githubusercontent.com/17274966/123259876-41be5200-d4f5-11eb-9e57-d1bfb387e1c3.mov

Build

1. Ensure Java 11 or higher is installed locally and the env var JAVA_HOME is properly set. AdoptOpenJDK provides binaries and installation guides for various operating systems.

2. Install Apache Maven. Distribution archive and installation guidelines are available at maven.apache.org.

3. To check whether Java and Maven have been set up correctly, run

   mvn --version

4. To build the project, run

   cd Blockchain-Logging-Framework
   mvn clean verify

   • To not build the executable jar blf-cmd.jar, add the option

     "-Dblf.skip.assemble=true"

   • To skip testing, add the option

     "-DskipTests"

Now you're ready to develop!

Test

To run unit tests, run

mvn test

Enable Git Hooks

 git config --local core.hooksPath .githooks/
 chmod u+x .githooks/pre-commit

License

This software is released under the MIT Licence Agreement. Details can be found LICENSE.md. Moreover the third party components distributed with the software and their licenses are listed in NOTICE.md.