Crate zoe_wire_protocol 

Zoe Wire Protocol

The wire protocol crate provides the core messaging infrastructure for the Zoe distributed messaging system. It defines message formats, cryptographic primitives, transport security, and RPC service interfaces.

Key Features

• Versioned Message Protocol: Forward-compatible message types with multiple encryption schemes
• Hybrid Cryptography: Support for both Ed25519 (legacy) and ML-DSA (post-quantum) signatures
• Multiple Content Types: Raw, ChaCha20-Poly1305, self-encrypted, and ephemeral ECDH encryption
• Transport Security: TLS certificate generation with embedded identity keys
• RPC Services: MessageService and BlobService for relay communication
• Streaming Protocol: Real-time message subscriptions and filtering
• Challenge-Response Authentication: Dynamic session management with configurable timeouts

Quick Start

use zoe_wire_protocol::{
    MessageFull, Message, MessageV0, MessageV0Header, Content, Kind,
    KeyPair, VerifyingKey, SigningKey
};
use rand::rngs::OsRng;

// Create a keypair (supports Ed25519, ML-DSA-44, ML-DSA-65, ML-DSA-87)
let keypair = KeyPair::generate(&mut OsRng);
let verifying_key = keypair.public_key();

// Create message content (multiple encryption options available)
let content = Content::raw(b"Hello, Zoeyr!".to_vec());

// Create message header
let header = MessageV0Header {
    sender: verifying_key.clone(),
    when: std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_secs(),
    kind: Kind::Regular,
    tags: vec![], // Optional: Tag::Event, Tag::User, Tag::Channel, Tag::Protected
};

// Create versioned message
let message = Message::new_v0_raw(
    content.as_raw().unwrap().clone(),
    verifying_key,
    header.when,
    header.kind,
    header.tags
);

// Create full message with signature
let message_full = MessageFull::new(message, &keypair)?;

// Access message properties
println!("Message ID: {}", message_full.id());

Message Structure

Messages follow a versioned, forward-compatible structure:

MessageFull
├── id: Hash                    // Blake3 hash (computed from signature)
├── signature: Signature        // Digital signature (Ed25519 or ML-DSA)
└── message: Message            // Versioned message content
    └── V0(MessageV0)
        ├── header: MessageV0Header
        │   ├── sender: VerifyingKey
        │   ├── when: u64
        │   ├── kind: Kind
        │   └── tags: Vec<Tag>
        └── content: Content    // Payload with encryption options

Content Encryption

The protocol supports multiple encryption schemes:

• Content::Raw - Unencrypted content
• Content::ChaCha20Poly1305 - Context-based encryption with shared keys
• Content::Ed25519SelfEncrypted - Self-encryption using Ed25519 keys
• Content::MlDsaSelfEncrypted - Self-encryption using ML-DSA keys (post-quantum)
• Content::EphemeralEcdh - Public key encryption with perfect forward secrecy

RPC Services

The crate defines two main services for relay communication:

• MessageService - Message publishing, retrieval, and real-time subscriptions
• BlobService - Binary blob storage and retrieval

Transport Security

TLS certificates can embed identity keys for authentication:

use zoe_wire_protocol::{generate_ed25519_cert_for_tls, extract_ed25519_public_key_from_cert};

// Generate Ed25519 certificate
let ed25519_key = ed25519_dalek::SigningKey::generate(&mut OsRng);
let certs = generate_ed25519_cert_for_tls(&ed25519_key, "example.com")?;
let extracted_key = extract_ed25519_public_key_from_cert(&certs[0])?;

Serialization

All data structures use postcard for efficient binary serialization:

use zoe_wire_protocol::MessageFull;

// Serialize for transmission
let bytes = postcard::to_stdvec(&message_full)?;

// Deserialize received data
let received: MessageFull = postcard::from_bytes(&bytes)?;

Re-exports

pub use invitation::generate_ephemeral_group_invite_id;

pub use invitation::GroupInvitationData;

pub use invitation::GroupMetadata;

pub use invitation::HandshakePurpose;

pub use invitation::HandshakeResponse;

pub use invitation::ProfileSetEvent;

pub use invitation::UserProfile;

pub use invitation::VerificationHandshakeRequest;

pub use crypto::generate_ml_dsa_from_mnemonic;

pub use crypto::recover_ml_dsa_from_mnemonic;

pub use crypto::MlDsaSelfEncryptedContent;

pub use bip39;

pub use blob::*;

pub use challenge::*;

pub use connection_info::*;

pub use crypto::*;

pub use inbox::*;

pub use message::*;

pub use relay::*;

pub use services::*;

pub use streaming::*;

pub use version::*;

pub use primitives::*;

pub use keys::*;

Modules

blob

challenge

connection

Connection Management and Protocol Negotiation

connection_info

Connection information for authenticated connections

crypto

Message-level cryptography for the Zoe protocol

inbox

Inbox system for asynchronous message protocols

invitation

Group invitation message types for PQXDH-based secure invitations

keys

Hybrid cryptographic key system supporting multiple signature algorithms.

message

primitives

relay

services

streaming

version

Protocol Version Negotiation

Structs

Ed25519SigningKey

ed25519 signing key which can be used to produce signatures.

Ed25519VerifyingKey

An ed25519 public key.

Functions

hash

Convinience function to creates from simple byte slices

Type Aliases

Hash