Event Watching

Watch and decrypt SRC20 Transfer and Approval events

Watch SRC20 Transfer and Approval events with automatic decryption of encrypted amounts.

Overview

SRC20 tokens emit Transfer and Approval events with encrypted amounts. The event watching system provides tools to:

• Poll for SRC20 events matching your viewing key

• Automatically decrypt encrypted amounts using AES-256-GCM

• Invoke callbacks with fully decoded event data

• Handle both sync (threading) and async (asyncio) execution models

Quick Start

Watch Your Own Events

import os
from seismic_web3 import create_wallet_client, PrivateKey
from seismic_web3.src20 import watch_src20_events

private_key = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])
w3 = create_wallet_client("https://gcp-1.seismictest.net/rpc", private_key=private_key)

watcher = watch_src20_events(
    w3,
    encryption=w3.seismic.encryption,
    private_key=private_key,
    on_transfer=lambda log: print(f"Transfer: {log.decrypted_amount}"),
)

# Later...
watcher.stop()

Watch with Explicit Key

import os
from web3 import Web3
from seismic_web3 import Bytes32
from seismic_web3.src20 import watch_src20_events_with_key

w3 = Web3(Web3.HTTPProvider("https://gcp-1.seismictest.net/rpc"))
viewing_key = Bytes32(bytes.fromhex(os.environ["VIEWING_KEY"].removeprefix("0x")))

watcher = watch_src20_events_with_key(
    w3,
    viewing_key=viewing_key,
    on_transfer=lambda log: print(f"Transfer: {log.decrypted_amount}"),
)

Factory Functions

High-level functions that create and start watchers:

Function	Description
watch_src20_events	Watch with automatic key fetching (sync)
watch_src20_events_with_key	Watch with explicit viewing key (sync)

Both have async variants (async_watch_src20_events, async_watch_src20_events_with_key).

Watcher Classes

Low-level classes for advanced use cases:

Class	Description
SRC20EventWatcher	Thread-based watcher (sync)
AsyncSRC20EventWatcher	Task-based watcher (async)

Event Types

Decoded event data structures:

Type	Description
DecryptedTransferLog	Transfer event with decrypted amount
DecryptedApprovalLog	Approval event with decrypted amount

How It Works

1. Key hash filtering - Events are filtered by keccak256(viewing_key) in the event topics

2. Polling - The watcher polls eth_getLogs at a configurable interval

3. Decryption - Encrypted amounts are decrypted using AES-256-GCM with the viewing key

4. Callbacks - User callbacks are invoked with fully decoded event data

Sync vs Async

Sync (Threading)

• Runs in a background daemon thread

• Uses Web3 (synchronous)

• Callbacks are regular functions

• Good for scripts and simple applications

watcher = watch_src20_events(w3, ...)
watcher.stop()

Async (asyncio)

• Runs as an asyncio.Task

• Uses AsyncWeb3 (asynchronous)

• Callbacks can be async or sync functions

• Good for async applications and WebSocket connections

watcher = await async_watch_src20_events(w3, ...)
await watcher.stop()

Common Patterns

Context Manager

with watch_src20_events(...) as watcher:
    time.sleep(60)
# Automatically stopped

Error Handling

def on_error(exc: Exception):
    print(f"Error: {exc}")

watcher = watch_src20_events(
    w3,
    ...,
    on_error=on_error,
)

Filter by Token

watcher = watch_src20_events(
    w3,
    ...,
    token_address="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
)

Historical Events

watcher = watch_src20_events(
    w3,
    ...,
    from_block=1000000,  # Start from specific block
)

See Also

• Directory - Manage viewing keys

• Types - Event data structures

• SRC20 Overview - Full SRC20 documentation