libXMTP

封装 XMTP 消息协议核心功能的共享库， 例如加密、网络以及语言绑定。
文档 · 贡献指南

要求

• Rustup
• Docker
• Foundry
• just（测试时可选）

开发

添加依赖项

• 添加依赖项需要重新生成 workspace-hack crate， 可以通过以下方式完成：

nix develop --command cargo hakari generate

要验证正确性，您可以选择性地运行

nix develop --command cargo hakari verify

启动 Docker Desktop。

• 要安装其他依赖项并启动后台服务：

  ./dev/up

具体而言，此命令会在 Docker Desktop 中创建并运行一个 XMTP 节点。

• 本项目使用 just 作为命令运行器。 运行 just 以列出所有可用的配方，包括 Android、 iOS、Node.js 和 WASM 的子模块：

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

• 运行测试：

  RUST_LOG=off cargo test

许多团队成员也会安装并使用 cargo nextest 以获得更好的测试 隔离和日志输出行为。

• 运行测试并在浏览器中打开覆盖率：

./dev/test/coverage

• 要无头运行 WebAssembly 测试：

  just wasm test

注意：如果测试因 "bind() failed: Cannot assign requested address" 而失败， Chrome 无法绑定到 IPv6，并将回退到 IPv4。尽管这 应该是一个警告，但 Chromedriver 目前将此消息记录为 SEVERE，这会 中断 wasm-bindgen-test。您可以选择禁用 Chromedriver 日志 输出以防止此问题。

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

• 要交互式地运行某个包的 WebAssembly 测试，例如，xmtp_mls：

  ./dev/test/wasm-interactive xmtp_mls

• 运行浏览器 SDK 测试：

  ./dev/test/browser-sdk

技巧与窍门

测试的日志输出标志

• 使用环境变量 CONTEXTUAL 以异步感知的上下文特定树格式输出测试日志

CONTEXTUAL=1 cargo test

• 按 Crate 筛选测试日志

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

• 以结构化 JSON 格式输出测试日志，以便使用 第三方查看器进行检查

STRUCTURED=1 cargo test

• 在日志中将 InboxIds/InstallationIds/EthAddresses 替换为 人类可读的字符串名称的两种方式

注意：仅在使用 CONTEXTUAL=1 标志时有效。因此，要获取替换结果， CONTEXTUAL=1 cargo test

1.)

在测试运行之前，在顶部添加一个 TestLogReplace 声明 replace.add 接受两个参数：日志中要替换的字符串以及 用于替换它的字符串。请注意，在丢弃 "TestLogReplace" 对象后， 将不再进行替换。

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

2.) 构建 TesterBuilder with_name

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

这将测试输出日志中所有 alix 的 InboxIds、InstallationIds 和 Identifiers 分别替换为 "alix"、"alix_installation" 和 "alix_identifier"。

快速入门（Dev Containers）

本项目支持容器化开发。从 Visual Studio Code Dev Containers 扩展中指定 Dockerfile 作为目标：

Reopen in Container

或

使用 docker 进行命令行构建

docker build . -t libxmtp:1

快速入门 (nix)

本项目支持 Determinate Nix 以 实现可复现的开发环境。Nix 为 Rust、 Android、iOS、WebAssembly 和 Node.js 构建提供固定版本的工具链。

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

要临时禁用/启用 direnv 而不卸载任何内容：

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

参见 docs/nix-setup.md 获取完整的设置指南，包括 二进制缓存配置、可用的开发 shell 以及 direnv 的使用。

结构

libxmtp/

├ apps/

│ ├ android: 示例 Android 应用（进行中） │ ├ [xdbg: 用于发送/负载测试 XMTP 客户端与网络的综合性 CLI

│ └ mls_validation_service: MLS 验证 服务

├ bindings/

│ ├ mobile: Android 和 iOS 的 FFI 绑定

│ ├ node: Node.js 绑定

│ └ wasm: WebAssembly 绑定

├ crates/

│ ├ xmtp_api_grpc: XMTP gRPC API 的 API 客户端

│ ├ xmtp_cryptography: 加密操作

│ ├ xmtp_mls: 实现 Messaging Layer Security 的 XMTP 版本 3

│ └ xmtp_proto: 用于处理 XMTP 协议缓冲区的生成代码

├ sdks/

│ ├ android: Android SDK (Kotlin)

│ ├ ios: iOS SDK (Swift)

│ └ js: 浏览器和 Node SDK (TypeScript)

运行基准测试

可能的基准测试包括：

• group_limit: 围绕从群组中添加/移除最大成员数的基准测试
• crypto: 围绕加密函数的基准测试

示例命令

• 运行特定类别的基准测试 cargo bench --features bench -p xmtp_mls --bench group_limit
• 针对 dev grpc 运行 DEV_GRPC=1 cargo bench --features bench -p xmtp_mls --bench group_limit
• 仅运行所有基准测试 ./dev/bench
• 运行一个特定的基准测试 ./dev/bench add_1_member_to_group
• 从一个基准测试生成火焰图 ./dev/flamegraph add_1_member_to_group

代码覆盖率

代码覆盖率使用 cargo llvm-cov 生成，并集成到 ci 中， 报告至 codecov。

要在本地运行测试，你可以运行 dev/llvm-cov 脚本来执行相同的 工作区测试，并生成 lcov 和 html 报告。

如果你在 vscode（或其 衍生版本）中安装了 Coverage Gutters 扩展，你可以在 IDE 中获取覆盖率信息。

贡献

请参阅我们的 贡献指南 以了解有关如何 为该项目做出贡献的更多信息。