xmtp / libxmtp

libXMTP shared library encapsulating the core functionality of the XMTP messaging protocol, such as cryptography, networking, and language bindings. Documentation · Contributing Requirements • Rustup • Docker • Foundry • just (optional for testing) Development Adding Dependencies • adding dependencies will require re-generating the crate, which can be done with: to verify correctness you can optionally run Start Docker Desktop. • To install other dependencies and start background services: Specifically, this command creates and runs an XMTP node in Docker Desktop. • This project uses as a command runner. Run to list all available recipes, including submodules for Android, iOS, Node.js, and WASM: • To run tests: Many team members also install and use for better test isolation and log output behavior. • run tests and open coverage in a browser: • To run WebAssembly tests headless: 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. • To run WebAssembly tests interactively for a package, for example, : • To run browser SDK tests: Tips & Tricks Log Output Flags for Tests • Output test logs in a async-aware context-specific tree format with the environment variable • Filter tests logs by Crate • Output test logs as in a structured JSON format for inspection with third-party viewer • Two ways to replace InboxIds/InstallationIds/EthAddresses with a human-readable string name in logs _NOTE_: Only works when using flag. So to get the replacement, 1.) Before the test runs, add an declaration to the top 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. 2.) Build the 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: or Command line build using docker 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. To temporarily disable/enable direnv without uninstalling anything: See docs/nix-setup.md for the full setup guide, including binary cache configuration, available dev shells, and direnv usage. Structure libxmtp/ ├ apps/ │ ├ : Example Android app (in progress) │ ├ : Example XMTP console client. Use the CLI to try out sending double ratchet messages on the XMTP network. │ └ : MLS validation service ├ bindings/ │ ├ : FFI bindings for Android and iOS │ ├ : Node.js bindings │ └ : WebAssembly bindings ├ crates/ │ ├ : API client for XMTP's gRPC API │ ├ : Cryptographic operations │ ├ : Version 3 of XMTP which implements Messaging Layer Security │ └ : Generated code for handling XMTP protocol buffers ├ sdks/ │ └ : Android SDK (Kotlin) Run the benchmarks **possible benchmarks include:** • : benchmarks surrounding maximum members adding/removed from group • : benchmarks surrounding cryptographic functions **Example Commands** • **Run a specific category of benchmark** • **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 and is integrated into ci and reported to codecov. To run the tests locally you can run the script to run the same workspace tests and generate both an lcov and html report. If you have installed the 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.