Libxmtp

<!-- LOGO --> <h1> <p align="center"> <img src="https://raw.githubusercontent.com/xmtp/brand/1bf5822708c9ce7e06964b85121093d69b3a4ff2/assets/postmark-outlined-color.svg" alt="Logo" width="128"> <br>libXMTP </h1> <p align="center"> shared library encapsulating the core functionality of the XMTP messaging protocol, such as cryptography, networking, and language bindings. <br /> <a href="https://docs.xmtp.org/">Documentation</a> · <a href="CONTRIBUTING.md">Contributing</a> </p> </p>

Requirements

• Rustup
• Docker
• Foundry
• just (optional for testing)

Development

Adding Dependencies

• adding dependencies will require re-generating the workspace-hack crate, which can be done with:

nix develop --command cargo hakari generate

to verify correctness you can optionally run

nix develop --command cargo hakari verify

Start Docker Desktop.

• To install other dependencies and start background services:

  ./dev/up
  

  Specifically, this command creates and runs an XMTP node in Docker Desktop.

• This project uses just as a command runner. Run just to list all available recipes, including submodules for Android, iOS, Node.js, and WASM:

  just          # List all recipes
  just format   # Format code
  just lint     # Run all linting
  

• To run tests:

  RUST_LOG=off cargo test
  

  Many team members also install and use cargo nextest for better test isolation and log output behavior.

• run tests and open coverage in a browser:

./dev/test/coverage

• To run WebAssembly tests headless:

  just wasm test
  

Note: If the tests fail with "bind() failed: Cannot assign requested address," Chrome is unable to bind to IPv6 and will fall back to IPv4. Although this should be a warning, Chromedriver currently logs this message as SEVERE, which halts the wasm-bindgen-test. You can optionally disable the Chromedriver logs output to prevent this.

CHROMEDRIVER_ARGS="--log-level=OFF" just wasm test

• To run WebAssembly tests interactively for a package, for example, xmtp_mls:

  ./dev/test/wasm-interactive xmtp_mls
  

• To run browser SDK tests:

  ./dev/test/browser-sdk
  

Tips & Tricks

Log Output Flags for Tests

• Output test logs in a async-aware context-specific tree format with the environment variable CONTEXTUAL

CONTEXTUAL=1 cargo test

• Filter tests logs by Crate

RUST_LOG=xmtp_mls=debug,xmtp_api=off,xmtp_id=info cargo test

• Output test logs as in a structured JSON format for inspection with third-party viewer

STRUCTURED=1 cargo test

• Two ways to replace InboxIds/InstallationIds/EthAddresses with a human-readable string name in logs

NOTE: Only works when using CONTEXTUAL=1 flag. So to get the replacement, CONTEXTUAL=1 cargo test

1.)

Before the test runs, add an TestLogReplace declaration to the top replace.add accepts two arguments: the string to replace in logs and the string to replace it with. Note that on dropping the "TestLogReplace" object, the replacements will no longer be made.

let mut replace = TestLogReplace::default();
replace.add(alix.installation_id(), "alix_installation_id");

2.) Build the TesterBuilder with_name

let tester = Tester::builder().with_name("alix").build().await;

This replaces all instances of alix's InboxIds, InstallationIds and Identifiers with "alix", "alix_installation", "alix_identifier" respectively, in test output logs.

Quick Start (Dev Containers)

This project supports containerized development. From Visual Studio Code Dev Containers extension specify the Dockerfile as the target:

Reopen in Container

or

Command line build using docker

docker build . -t libxmtp:1

Quick Start (nix)

This project supports Determinate Nix for reproducible development environments. Nix provides pinned toolchains for Rust, Android, iOS, WebAssembly, and Node.js builds.

./dev/nix-up    # One-time setup: install Determinate Nix + direnv + binary caches
nix develop     # Enter the default dev shell

To temporarily disable/enable direnv without uninstalling anything:

./dev/direnv-down  # Disable direnv auto-activation
./dev/direnv-up    # Re-enable direnv

See docs/nix-setup.md for the full setup guide, including binary cache configuration, available dev shells, and direnv usage.

Structure

libxmtp/

├ apps/

│ ├ android: Example Android app (in progress)

│ ├ cli: Example XMTP console client. Use the CLI to try out sending double ratchet messages on the XMTP dev network.

│ └ mls_validation_service: MLS validation service

├ bindings/

│ ├ mobile: FFI bindings for Android and iOS

│ ├ node: Node.js bindings

│ └ wasm: WebAssembly bindings

├ crates/

│ ├ xmtp_api_grpc: API client for XMTP's gRPC API

│ ├ xmtp_cryptography: Cryptographic operations

│ ├ xmtp_mls: Version 3 of XMTP which implements Messaging Layer Security

│ └ xmtp_proto: Generated code for handling XMTP protocol buffers

├ sdks/

│ └ android: Android SDK (Kotlin)

Run the benchmarks

possible benchmarks include:

• group_limit: benchmarks surrounding maximum members adding/removed from group
• crypto: benchmarks surrounding cryptographic functions

Example Commands

• Run a specific category of benchmark cargo bench --features bench -p xmtp_mls --bench group_limit
• Run against dev grpc DEV_GRPC=1 cargo bench --features bench -p xmtp_mls --bench group_limit
• Just run all benchmarks ./dev/bench
• Run one specific benchmark ./dev/bench add_1_member_to_group
• Generate flamegraph from one benchmark ./dev/flamegraph add_1_member_to_group

Code Coverage

Code coverage is generated using cargo llvm-cov and is integrated into ci and reported to codecov.

To run the tests locally you can run the dev/llvm-cov script to run the same workspace tests and generate both an lcov and html report.

If you have installed the Coverage Gutters extension in vscode (or a derivative) you can get coverage information in your IDE.

Contributing

See our contribution guide to learn more about contributing to this project.