gleeth - v1.7.0

gleeth/event_watcher

Real-time contract event streaming.

Combines the block watcher with ABI event decoding to deliver typed contract events as they happen. Internally spawns a block watcher, queries logs for each new block, decodes them, and forwards matches to the caller.

Examples

let assert Ok(abi) = json.parse_abi(erc20_abi_json)
let assert Ok(ew) = event_watcher.start(provider, usdc_address, abi)

// Receive decoded events as they arrive
case event_watcher.receive(ew, 30_000) {
  Ok(event) -> // event.name, event.params, event.log
  Error(Nil) -> // timeout
}

event_watcher.stop(ew)

Types

ContractEvent

</>

A decoded contract event with the original log attached.

pub type ContractEvent {
  ContractEvent(
    name: String,
    params: List(#(String, types.AbiValue)),
    log: types.Log,
  )
}

Constructors 

  • ContractEvent(
  name: String,
  params: List(#(String, types.AbiValue)),
  log: types.Log,
)

    Arguments

    name

    The event name from the ABI (e.g. “Transfer”).

    params

    Decoded parameters as name-value pairs.

    log

    The raw log this event was decoded from.

EventWatcher

opaque </>

An opaque handle to a running event watcher.

pub opaque type EventWatcher

EventWatcherConfig

</>

Configuration for the event watcher.

pub type EventWatcherConfig {
  EventWatcherConfig(poll_interval_ms: Int, event_name: String)
}

Constructors 

  • EventWatcherConfig(poll_interval_ms: Int, event_name: String)

    Arguments

    poll_interval_ms

    How often to poll for new blocks in milliseconds. Default: 2000.

    event_name

    Optional event name filter. Empty string means all events.

Values

default_config

</> 
pub fn default_config() -> EventWatcherConfig

Default config: poll every 2s, no event name filter.

receive

</> 
pub fn receive(
  ew: EventWatcher,
  timeout_ms: Int,
) -> Result(ContractEvent, Nil)

Receive the next decoded event, blocking up to timeout_ms milliseconds.

Examples

case event_watcher.receive(ew, 10_000) {
  Ok(event) -> // event.name, event.params
  Error(Nil) -> // timeout
}

start

</> 
pub fn start(
  provider: provider.Provider,
  address: String,
  abi: List(json.AbiEntry),
) -> Result(EventWatcher, String)

Start watching for all contract events with default config.

Examples

let assert Ok(ew) = event_watcher.start(provider, "0xA0b8...", abi)

start_for_event

</> 
pub fn start_for_event(
  provider: provider.Provider,
  address: String,
  abi: List(json.AbiEntry),
  event_name: String,
) -> Result(EventWatcher, String)

Start watching for a specific event by name.

Examples

let assert Ok(ew) = event_watcher.start_for_event(
  provider, "0xA0b8...", abi, "Transfer",
)

start_with_config

</> 
pub fn start_with_config(
  provider: provider.Provider,
  address: String,
  abi: List(json.AbiEntry),
  config: EventWatcherConfig,
) -> Result(EventWatcher, String)

Start watching with custom configuration.

stop

</> 
pub fn stop(ew: EventWatcher) -> Nil

Stop the event watcher and its underlying block watcher.

✨ Search Document