Note: The Blockchain Logging Framework is an extension of ELF that provides logging capabilities for DApps on any blockchain platform and that currently supports Ethereum and HyperLedger Fabric.

Note: The open collection of resources for process mining on blockchain data contains event logs extracted with ELF from DApps deployed on public Ethereum.

This framework provides advanced logging capabilities for Ethereum applications on top of Web3J / Ethereum's JSON RP. It is essentially a lightweight ETL engine for extracting and sharing network and application specific data stored on Ethereum with off-chain components. In its current version the framework supports a broad range of use cases, e.g., extraction of data for business-level analysis of DApps, monitoring of relationships and states of individual smart contracts, or event-based streaming of data to other off-chain components.

The main features of the framework include:

• A query language that abstracts from technical details and hence minimizes configuration effort
• Syntactic and semantic validation of user-defined queries
• Extraction of standard attributes (e.g., block hash, gas price, gas used, etc.) from all confirmed blocks and of application specific data including log entry parameters, input parameters for transactions, or smart contract states
• Definition of arbitrary data filters and basic transformation operations
• A variety of target data formats: CSV, textual log, and XES files
• Two export modes: batch, i.e., extracting all data at once, vs. streaming, i.e., extracting data block by block, potentially endlessly
• Generation of cost efficient Solidity code for logging from user defined queries. The generated code compresses log entry attributes before emitting a log entry and it can be manually integrated into custom smart contract code.

The architecture of the framework consists of four components:

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

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

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)

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.

R. Hobeck, C. Klinkmüller, D. Bandara, I. Weber, W. van der Aalst (2021): "Process Mining on Blockchain Data: a Case Study of Augur". In: 19th International Conference on Business Process Management.

P. Beck, H. Bockrath, T. Knoche, M. Digtiar, T. Petrich, D. Romanchenko, R. Hobeck, L. Pufahl, C. Klinkmüller, I. Weber (2021): "BLF: A Blockchain Logging Framework for MiningBlockchain Data". In: 19th International Conference on Business Process Management (Demo & Resource Track).

D. Bandara, H. Bockrath, R. Hobeck, C. Klinkmüller, L. Pufahl, M. Rebesky, W. van der Aalst, I. Weber (2021): "Event Logs of Ethereum-Based Applications -- A Collection of Resources for Process Mining on Blockchain Data". In: 19th International Conference on Business Process Management (Demo & Resource Track).

1. Ensure Java 13 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 setup the lib folder as a local repository, run

   cd lib
   mvn deploy:deploy-file "-Durl=file:///<project-path>/lib" "-Dfile=Spex.jar" "-DgroupId=org.deckfour" "-DartifactId=spex" "-Dversion=1.0" "-Dpackaging=jar"
   mvn deploy:deploy-file "-Durl=file:///<project-path>/lib" "-Dfile=OpenXES-20181205.jar" "-DgroupId=org.deckfour" "-DartifactId=open-xes" "-Dversion=1.0" "-Dpackaging=jar"

5. To build the project, run

   cd ethereum-logging-framework
   mvn verify

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

     "-Delf.skip.assemble=false"

   • To skip testing, add the option

     "-DskipTests"

Now you're ready to develop!

To run unit tests, run

mvn test

The compiled jar elf-cmd.jar can be executed from the command line in different modes:

1. Validator: java -jar elf-cmd.jar validate <PATH_TO_SCRIPT> (-errors|-full)? executes the validator on the specified script. There are two options for validation: whereas -errors only reports specification errors, the default option is -full and also includes warnings and infos.
2. Extractor: java -jar elf-cmd.jar extractor <PATH_TO_SCRIPT> executes the extractor and retrieves the data as specified in the script.
3. Generator: java -jar elf-cmd.jar generate <PATH_TO_SCRIPT> executes the generation of efficient logging code for the script.

This software is released under the CSIRO Open Source Software 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.