XMTP API D14n

Decentralized API implementation for XMTP

Overview

The xmtp_api_d14n crate provides the decentralized (d14n) API implementation for XMTP, supporting both v3 (centralized MLS) and v4 (decentralized) protocol endpoints. This implementation follows the XIP-49 Decentralized Backend specification.

Source Location

crates/xmtp_api_d14n/

Architecture

The crate is organized into three main components:

File Hierarchy

endpoints/

• gRPC endpoints for v3 and decentralization protobuf interface
• Divided into v3/ (centralized) and d14n/ (decentralized) modules

queries/

• Query implementations according to the XMTP Protocol Interface

protocol/

• XMTP d14n implementation according to the d14n XIP

config/

• Backend configuration for decentralized network

Decentralized (D14n) Endpoints

The d14n endpoints implement the v4 decentralized protocol:

PublishClientEnvelopes

Publishes client envelopes to the decentralized network.

pub struct PublishClientEnvelopes {
    envelopes: Vec<ClientEnvelope>,
}

Endpoint: /xmtp.xmtpv4.payer_api.PayerApi/PublishClientEnvelopes

Builder Example:

let endpoint = PublishClientEnvelopes::builder()
    .envelope(client_envelope_1)
    .envelope(client_envelope_2)
    .build()?;

QueryEnvelopes

Queries envelopes from the network with filtering options.

pub struct QueryEnvelopes {
    envelopes: EnvelopesQuery,
    limit: u32,
}

Endpoint: /xmtp.xmtpv4.message_api.ReplicationApi/QueryEnvelopes

Builder Example:

let endpoint = QueryEnvelopes::builder()
    .envelopes(EnvelopesQuery {
        topics: vec![topic_bytes],
        originator_node_ids: vec![],
        last_seen: Some(cursor),
    })
    .limit(100)
    .build()?;

QueryEnvelope (Single)

Queries a single envelope topic.

pub struct QueryEnvelope {
    topics: Vec<Topic>,
    last_seen: GlobalCursor,
    limit: u32,
}

Builder Example:

let endpoint = QueryEnvelope::builder()
    .topic(topic)
    .last_seen(cursor)
    .limit(50)
    .build()?;

SubscribeEnvelopes

Subscribes to envelope updates in real-time.

pub struct SubscribeEnvelopes {
    topics: Vec<Topic>,
    last_seen: Option<GlobalCursor>,
    originators: Vec<OriginatorId>,
}

Endpoint: /xmtp.xmtpv4.message_api.ReplicationApi/SubscribeEnvelopes

Builder Example:

let mut endpoint = SubscribeEnvelopes::builder()
    .topic(topic_1)
    .topic(topic_2)
    .last_seen(Some(cursor))
    .build()?;

let stream = endpoint.subscribe(&client).await?;

GetInboxIds

Retrieves inbox IDs for given addresses.

Endpoint: Defined in endpoints/d14n/get_inbox_ids.rs

GetNewestEnvelopes

Fetches the newest envelopes from the network.

Endpoint: Defined in endpoints/d14n/get_newest_envelopes.rs

HealthCheck

Checks the health status of the decentralized network nodes.

Endpoint: Defined in endpoints/d14n/health_check.rs

GetNodes

Retrieves information about available network nodes.

Endpoint: Defined in endpoints/d14n/get_nodes.rs

FetchD14nCutover

Fetches the cutover information for transitioning to the decentralized network.

Endpoint: Defined in endpoints/d14n/fetch_d14n_cutover.rs

V3 Endpoints

The v3 endpoints provide compatibility with the centralized MLS Group Chat implementation:

Identity Endpoints (v3/identity/)

GetIdentityUpdatesV2

• Retrieves identity updates for inboxes
• Source: endpoints/v3/identity/get_identity_updates_v2.rs

GetInboxIds

• Maps addresses to inbox IDs
• Source: endpoints/v3/identity/get_inbox_ids.rs

PublishIdentityUpdate

• Publishes identity updates to the network
• Source: endpoints/v3/identity/publish_identity_update.rs

VerifySmartContractWalletSignatures

• Verifies signatures from smart contract wallets
• Source: endpoints/v3/identity/verify_smart_contract_wallet_signatures.rs

MLS Endpoints (v3/mls/)

FetchKeyPackages

• Fetches key packages for installations
• Source: endpoints/v3/mls/fetch_key_packages.rs

GetNewestGroupMessage

• Retrieves the newest message for a group
• Source: endpoints/v3/mls/get_newest_group_message.rs

Additional v3 MLS endpoints are available in the endpoints/v3/mls/ directory.

Endpoint Trait

All endpoints implement the Endpoint trait from xmtp_proto:

pub trait Endpoint {
    type Output;
    fn grpc_endpoint(&self) -> Cow<'static, str>;
    fn body(&self) -> Result<Bytes, BodyError>;
}

Usage with API Client

Unary Request:

use xmtp_proto::api;

let endpoint = QueryEnvelopes::builder()
    .envelopes(query)
    .build()?;

let response = api::ignore(endpoint)
    .query(&client)
    .await?;

Streaming Request:

let mut endpoint = SubscribeEnvelopes::builder()
    .topics(vec![topic])
    .build()?;

let mut stream = endpoint.subscribe(&client).await?;

while let Some(envelope) = stream.next().await {
    // Process envelope
}

Protocol Interface

The d14n protocol implements the client-to-node protocol as specified in XIP-49 Section 3.3.

Key Components:

• Client envelope authentication
• Topic-based message routing
• Global cursor-based pagination
• Originator node filtering
• Real-time envelope subscriptions

Configuration

The config module provides backend configuration for connecting to the decentralized network:

use xmtp_api_d14n::config::BackendConfig;

Configuration includes:

• Node discovery
• Network topology
• Connection parameters

Type Definitions

Common types used throughout the d14n API:

Topics:

use xmtp_proto::types::Topic;

Cursors:

use xmtp_proto::types::GlobalCursor;

Envelopes:

use xmtp_proto::xmtpv4::envelopes::ClientEnvelope;

Originators:

use xmtp_proto::types::OriginatorId;

Builder Pattern

All endpoints use the derive_builder crate for ergonomic construction:

let endpoint = EndpointName::builder()
    .field1(value1)
    .field2(value2)
    .build()?;

Builders provide:

• Type-safe construction
• Optional field handling
• Validation before building
• Fluent API interface

Testing

The crate includes test utilities and clients:

XmtpdClient - Test client for d14n endpoints GatewayClient - Test client for gateway endpoints

use xmtp_api_grpc::test::{XmtpdClient, GatewayClient};

let client = XmtpdClient::create().build()?;
let gateway = GatewayClient::create().build()?;

Migration from V3 to D14n

The FetchD14nCutover endpoint helps coordinate the migration from v3 (centralized) to v4 (decentralized) infrastructure:

1. Query cutover status
2. Determine migration timeline
3. Switch to decentralized endpoints
4. Maintain backward compatibility during transition

Related XIPs

• XIP-49: Decentralized Backend
• XIP-46: Multi-Wallet Identity

Related Crates

• xmtp_api - Core trait definitions
• xmtp_api_grpc - gRPC client implementation
• xmtp_proto - Protocol buffer definitions