eth/event_filter.hpp

Namespaces

Name
eth

Classes

	Name
struct	eth::EventFilter Specifies which logs to accept: by emitting address(es) and/or topic(s).
struct	eth::MatchedEvent A matched event: the original log decorated with block context.
class	eth::EventWatcher Registers filters and dispatches matching logs to callbacks.

Types

	Name
using uint32_t	WatchId Registration handle returned by EventWatcher::watch(). Passed back to EventWatcher::unwatch() to remove a subscription.
using std::function< void(const MatchedEvent &)>	EventCallback Callback invoked for every log that matches a registered filter.

Types Documentation

using WatchId

using eth::WatchId = uint32_t;

Registration handle returned by EventWatcher::watch(). Passed back to EventWatcher::unwatch() to remove a subscription.

using EventCallback

using eth::EventCallback = std::function<void(const MatchedEvent&)>;

Callback invoked for every log that matches a registered filter.

Source code

// Copyright 2026 Genius Ventures, Inc.
// SPDX-License-Identifier: MIT

#ifndef EVMRELAY_INCLUDE_ETH_EVENT_FILTER_HPP
#define EVMRELAY_INCLUDE_ETH_EVENT_FILTER_HPP

#include <eth/objects.hpp>
#include <functional>
#include <optional>
#include <string>
#include <vector>

namespace eth {

struct EventFilter
{
    std::vector<codec::Address> addresses;

    std::vector<std::optional<codec::Hash256>> topics;

    std::optional<uint64_t> from_block;
    std::optional<uint64_t> to_block;

    [[nodiscard]] bool matches(const codec::LogEntry& log, uint64_t block = 0) const noexcept;
};

struct MatchedEvent
{
    codec::LogEntry log;          
    uint64_t        block_number; 
    codec::Hash256  block_hash;   
    codec::Hash256  tx_hash;      
    uint32_t        log_index;    
};

using WatchId = uint32_t;

using EventCallback = std::function<void(const MatchedEvent&)>;

class EventWatcher
{
public:
    EventWatcher() = default;
    ~EventWatcher() = default;

    // Non-copyable
    EventWatcher(const EventWatcher&) = delete;
    EventWatcher& operator=(const EventWatcher&) = delete;

    // Moveable
    EventWatcher(EventWatcher&&) = default;
    EventWatcher& operator=(EventWatcher&&) = default;

    WatchId watch(EventFilter filter, EventCallback callback) noexcept;

    void unwatch(WatchId id) noexcept;

    size_t process_block_logs(
        const std::vector<codec::LogEntry>& logs,
        uint64_t                            block_number,
        const codec::Hash256&               block_hash) noexcept;

    size_t process_receipt(
        const codec::Receipt& receipt,
        const codec::Hash256& tx_hash,
        uint64_t              block_number,
        const codec::Hash256& block_hash,
        uint32_t              first_log_index = 0) noexcept;

    [[nodiscard]] size_t subscription_count() const noexcept
    {
        return subscriptions_.size();
    }

private:
    struct Subscription
    {
        WatchId       id;
        EventFilter   filter;
        EventCallback callback;
    };

    std::vector<Subscription> subscriptions_;
    WatchId                   next_id_ = 1;
};

} // namespace eth

#endif // EVMRELAY_INCLUDE_ETH_EVENT_FILTER_HPP

---

Updated on 2026-06-05 at 17:22:19 -0700