Crate dig_events_protocol 

dig-events-protocol — the canonical blockchain→app event contract

The ONE ecosystem definition of the wallet/chain event taxonomy that the DIG node/wallet engine EMITS and apps (dig-app) SUBSCRIBE to. This crate owns only the CONTRACT — the wire types and the two shape traits — so a second implementation matches the first byte-for-byte. The machinery that produces, persists, and streams events (the event bus, the catch-up delta store, live subscriptions) STAYS in the engine (dig-wallet-backend); moving it here would couple every consumer to the runtime.

The contract

• WalletEvent — the event enum the engine emits (tagged type snake_case on the wire), with WalletEvent::kind and WalletEvent::matches for subscription filtering.
• EventKind — the kind discriminant; an EnumSet<EventKind> is the subscription FILTER (serialized as a snake_case list).
• Cursor + EmittedEvent — the monotonic delivery cursor and the envelope that flows over the live stream and is returned by catch-up.
• SyncLifecycle / SyncStatus — the tri-state sync snapshot.
• WalletId / Amount / AssetId — the payload newtypes.
• EventEmitter + CatchUp + filter_events — the emit/backfill shape traits and the shared filtering rule.

The drift-freeze

The wire format is frozen by golden-JSON conformance KATs (tests/conformance.rs): every WalletEvent variant and the EventKind list round-trip against a byte-stable fixture. A change that alters the wire shape breaks a KAT — that is the guardrail against silent drift.

Macros

enum_set

Creates an EnumSet literal, which can be used in const contexts.

Structs

Amount

An on-chain value amount, in the smallest indivisible unit (mojos).

AssetId

A CAT asset identifier — the asset’s TAIL hash, hex-encoded.

Cursor

A monotonic, per-instance sequence number stamped on delivered events.

EmittedEvent

A delivered event paired with its monotonic Cursor.

EnumSet

An efficient set type for enums.

SyncStatus

A snapshot of sync state for a wallet.

WalletId

The stable identifier of a wallet within an engine instance.

Enums

EventKind

The kind discriminant of a WalletEvent, used as the subscription FILTER.

SyncLifecycle

Where the sync loop is relative to the chain tip (a tri-state, pushed via a SyncProgress event).

WalletEvent

The event the engine emits and apps consume.

Traits

CatchUp

The backfill half of the subscription contract: a subscriber that fell behind calls this ONCE to fetch the events it missed, then resumes the live stream.

EventEmitter

A sink that accepts emitted events and stamps each with a monotonic Cursor.

Functions

filter_events

Retain only the EmittedEvents whose event kind passes filter, preserving cursor order.