Running the example program, and next steps

The easiest way to get acquainted with the execution event system is to try out the example program and read the code, although you may want to read the quick overview explaining the basic concepts first.

If you're following this guide in order you should have already built one of the example programs. If you have not built one yet, choose the appropriate guide for you language or choice (either C or Rust), and then return to this page and follow these steps:

Run the SDK example program you just built
- Before running, make sure the execution daemon is running and that execution events are enabled (link coming soon); in particular, make sure you have passed the command line argument --exec-event-ring
- For C, run eventwatch with no arguments
- For Rust, run the command cargo run -- -d
Read the source code for the example program you just ran; if you haven't read the overview yet, you may want to read that first
Once you understand the basic ideas in the example, the rest of the SDK documentation should be easy to follow
Before using the SDK, make sure you understand the consensus events and what they mean
Try out a more sophisticated program and look at the source code for it
- For Rust, try the "Block Explorer" TUI example in the upstream monad-bft repository. You can run it with cargo run -p monad-exec-events --example explorer and then browse the source code in explorer.rs
- For C, look at the code for the eventcap program in the upstream monad repository; this program is the "tcpdump" of the execution event system, and shows several different uses of the API. You may also want to read the next section about compiling the eventcap program

Optional: build the `eventcap` program

eventcap is a useful utility for working with the event system. Like the Rust eventwatch example, eventcap can decode execution event payloads into human-readable form. It does several other tasks which are useful in the developer workflow, e.g., recording captures of events and creating snapshot event ring files for test cases.

warning

eventcap requires gcc 15.2 or higher, and will not build with gcc 15.0. The only Ubuntu release that ships with gcc 15.2 in its package repositories is Ubuntu 25.10, which was still a beta release at the time this guide was written.

If you do not have gcc 15.2 and do not want to build it yourself, you can instead use clang-19 but using libc++ instead of libstdc++. The default on Linux is for clang to use the gcc C++ standard library (libstdc++). If you specify -stdlib=libc++ it will use the LLVM standard library instead, which is supported.

If using libc++, you must also specify the -fexperimental-library compiler flag, to enable C++20 time zone support in <chrono>; eventcap uses this for printing the event timestamp in local time.

To build eventcap, clone the execution repository and check out the branch release/exec-events-sdk-v1.x, then build the CMake project rooted at cmd/eventcap.

Using clang-19 with libc++ and the above options:

$ git clone -b release/exec-events-sdk-v1.x https://github.com/category-labs/monad.git \
  ~/src/monad-eventcap
$ CC=clang-19 CFLAGS="-march=x86-64-v4" \
  CXX=clang++-19 CXXFLAGS="-stdlib=libc++ -fexperimental-library -march=x86-64-v4" cmake \
  -S ~/src/monad-eventcap/cmd/eventcap -B ~/build/monad-eventcap-release -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo
$ cmake --build ~/build/monad-eventcap-release

You should now be able to run:

$ ~/build/monad-eventcap-release/eventcap --help

note

The -march=x86-64-v4 is needed to enable certain atomic operations at the CPU instruction level, to avoid needing to link with libatomic.a; without this, a performance warning is emitted, which becomes a compilation error due to -Werror

To simplify running cmake with all these settings, you might want to create a CMake toolchain file instead of using environment variables. To do this, create a file called clang19-libcxx.cmake with these contents:

set(CMAKE_C_COMPILER clang-19)
set(CMAKE_CXX_COMPILER clang++-19)
set(CMAKE_ASM_FLAGS_INIT -march=x86-64-v4)
set(CMAKE_C_FLAGS_INIT -march=x86-64-v4)
set(CMAKE_CXX_FLAGS_INIT "-march=x86-64-v4 -stdlib=libc++ -fexperimental-library")

Now can you run this slightly cleaner command:

$ cmake --toolchain <path-to-toolchain-file> -S ~/src/monad-eventcap/cmd/eventcap \
  -B ~/build/monad-eventcap-release -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo

Optional: build the eventcap program​

Optional: build the `eventcap` program