Crate arminius_lib_events 

Event lifecycle management for Matrix room events.

This crate provides a type-safe implementation of the complete Matrix room event lifecycle, from initial draft to verified persistence. The implementation follows the ADR “ESIG-RDAC” and uses the type system to enforce correct state transitions.

Architecture

Events progress through four distinct states, each represented by a different type:

• RoomEvent<Draft>: Raw user intent (content + type only)
• RoomEvent<Contextualized>: Contextualized in the DAG with auth/prev events
• RoomEvent<Signed>: Signed with event ID and signatures
• RoomEvent<Verified>: Verified signatures and authorization

State transitions are enforced at compile-time, preventing common errors like attempting to verify an event which has not been signed yet or storing an unverified event.

Lifecycle Flow

The typical lifecycle flows are:

Local Event Creation (Client → Database):

1. Client Request → Draft (via new())
2. Draft → Contextualized (via contextualize())
3. Contextualized → Verified (via sign() - Signatures are trivially valid, auth rules are checked)
4. Verified → Database

Federation Event Reception (Federation → Database):

1. Federation Input → Signed
2. Signed → Verified (via verify() - explicitly verified)
3. Verified → Database

Event Distribution (Database → Clients/Federation):

1. Database → Verified
2. Verified → PDU (via to_pdu() for federation)
3. Verified → Client Event (via to_client_event() for client API)

Room Version Support

This crate supports multiple Matrix room versions (V1, V3-V11, V12+) with version-specific handling of:

• Event ID format (included in PDU vs. computed from reference hash)
• Event reference format (hashed vs. plain)
• Authorization rules
• Field requirements (e.g., room_id in m.room.create events)

Room version rules are configurable via [ruma::room_version_rules::RoomVersionRules].

Verifying an event from federation

use std::collections::HashMap;

use arminius_lib_events::{RoomEvent, Signed, Verified, VerifiedFields as _};
use arminius_lib_events::errors::ValidationError;
use ruma::{events::StateEventType, signatures::PublicKeyMap};

// Verify signatures and authorization against room state
let verified = signed.verify(
    &previous_state,
    &auth_events,
    &current_state,
    &required_verify_keys,
)?;

// Check if the event was soft-failed
if verified.soft_failed() {
    // Event passed auth against its own auth_events and previous_state
    // but failed against current room state. Persist it, but don't add
    // to leaf events or relay to clients.
}

Error Handling

The crate provides specific error types for different failure modes:

• errors::SigningError: Canonicalization, signing, or event ID generation failures
• errors::ValidationError: Signature verification, authorization, or key fetch failures
• errors::EventConversionError: PDU/client event serialization failures

Modules

conversions 🔒

Helper functions for converting events between different formats.

errors

Error types for event validation, signing, and conversion operations.

event_id 🔒

Event ID derivation from federation PDUs.

fields 🔒

Utility traits for RoomEvents, which allows accessing fields that would otherwise be deep inside the structs

pdu 🔒

PDU (Persistent Data Unit) representations for different room version formats.

redaction 🔒

Event redaction functionality.

states 🔒

Event lifecycle state type definitions.

traits 🔒

Public traits defining shared behavior.

transitions 🔒

Core RoomEvent<S> type and state transition logic.

types 🔒

Foundational type definitions and aliases used throughout the crate.

Structs

ClientContext

Client context used when converting to client events.

Contextualized

State representing an event contextualized in the room DAG.

Draft

State representing a draft event containing only user intent.

EventFormatOptions

Event format options derived from room version rules.

EventHash

Content hashes for a Matrix event.

HashedEventRef

An event reference with content hash (room versions 1-2).

PduCommon

Common PDU fields independent of room version format.

RoomEvent

A Matrix room event in a specific lifecycle state.

Signed

State representing a signed event with event ID and signatures.

V1Pdu

PDU representation for room version formats V1/V2.

V3Pdu

PDU representation for room version formats V3-V5.

V12Pdu

PDU representation for room version format V12.

VerificationMetadata

Metadata recorded when attempting to verify the signature of an event.

Verified

State representing a fully verified event ready for persistence or distribution.

Enums

EventRefs

Event references in a room-version-specific format.

KnownRoomVersionId

An alternative to [ruma::RoomVersionId], including only types supported by arminius-lib-rooms

PartsVerified

Describes how much of a ruma event was actually verified during a signature verification

Pdu

Supported PDU representations for room versions.

Constants

SUPPORTED_ROOM_VERSIONS

The room versions which are completely supported in arminius-lib-events

Traits

ContextualizedFields

A trait which accesses fields of a contextualized event

DraftFields

A trait which accesses fields of a draft event

Redactable

Trait for events that can be redacted in-place.

SignedFields

A trait which accesses fields of a signed event

VerifiedFields

A trait which accesses fields of a verified event

Functions

event_id_from_pdu

Resolves the event ID for a federation PDU.

Type Aliases

ClientEvent

Client event representation.