libXMTP

https://github.com/xmtp/libxmtp
Admin
libXMTP is a shared library implementing the XMTP messaging protocol using Messaging Layer Security...
Tokens:52,357
Snippets:407
Trust Score:9
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup and Install Release Tools

Source: https://github.com/xmtp/libxmtp/blob/main/dev/release-tools/README.md

Instructions for installing the release tools dependencies using Yarn.

```bash
cd dev/release-tools
yarn install
```

--------------------------------

### Environment Setup Commands

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

Commands for setting up the development environment, including installing dependencies and starting/stopping Docker services for the XMTP node.

```bash
dev/up                    # Install dependencies and start Docker services (XMTP node)
dev/docker/down           # Stop Docker services
just backend up           # Build validation service + start Docker
just backend down         # Stop Docker services
```

--------------------------------

### Sign and Verify Messages with Installation Key (TypeScript)

Source: https://context7.com/xmtp/libxmtp/llms.txt

Demonstrates how to sign a message using the client's installation key for authentication and then verify the signature. It also shows how to verify a signature using a specific installation public key.

```typescript
const message = 'Authenticate this action'
const signature = client.signWithInstallationKey(message)

try {
  client.verifySignedWithInstallationKey(message, signature)
  console.log('Signature valid')
} catch (error) {
  console.log('Signature invalid')
}

import { verifySignedWithPublicKey } from '@xmtp/node-bindings'
verifySignedWithPublicKey(message, signature, client.installationIdBytes())
```

--------------------------------

### Backend Commands: Up and Down

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

Manages the backend services using the 'just' build tool. The 'up' command builds a validation service image and starts the backend, while 'down' stops it. These commands rely on Nix for building and a local docker setup.

```just
backend command="up":
  @just _backend-{{command}}

[private]
_backend-up:
  nix build .#validation-service-image
  dev/docker/up

[private]
_backend-down:
  dev/docker/down
```

--------------------------------

### Run Local Backend and Tests

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/ios/CLAUDE.md

Commands to start the local XMTP backend infrastructure and execute the Swift test suite.

```bash
just backend up
just ios test
```

--------------------------------

### Subscribe to Welcome Message Topics

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-subscribe-topics-migration-design.md

Demonstrates how to build a subscription stream for welcome messages by mapping installation topics and filtering by the latest cursor from the store.

```rust
let topics: Vec<_> = installations
    .iter()
    .map(|ins| TopicKind::WelcomeMessagesV1.create(ins))
    .collect();
let mut builder = SubscribeTopics::builder();
for topic in &topics {
    let cursor = self.cursor_store.latest(topic)?;
    tracing::debug!("subscribing to welcome messages for topic {} @cursor={}", topic, cursor);
    builder.filter((topic.clone(), Some(cursor)));
}
let s = builder
    .build()?
    .stream(&self.client)
    .await?;
let (s, _status) = stream::status_aware(s);
Ok(stream::try_extractor(s))
```

--------------------------------

### Installation Key Signatures

Source: https://context7.com/xmtp/libxmtp/llms.txt

Sign and verify messages using the client's installation key for authentication.

```APIDOC
## Installation Key Signatures

### Description
Sign and verify messages using the client's installation key for authentication.

### Method
N/A (Client-side operations)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```typescript
// Sign a message with installation key
const message = 'Authenticate this action'
const signature = client.signWithInstallationKey(message)

// Verify signature
try {
  client.verifySignedWithInstallationKey(message, signature)
  console.log('Signature valid')
} catch (error) {
  console.log('Signature invalid')
}

// Verify with specific installation public key
import { verifySignedWithPublicKey } from '@xmtp/node-bindings'
verifySignedWithPublicKey(message, signature, client.installationIdBytes())
```

### Response
N/A
```

--------------------------------

### Run XMTP Example Notification Server

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/android/library/src/main/java/org/xmtp/android/library/push/README.md

Commands to set the FCM credentials environment variable and execute the notification server with required network and database parameters.

```bash
YOURFCMJSON=$(cat /path/to/FCMCredentials.json)
dev/run \
--xmtp-listener-tls \
--xmtp-listener \
--api \
-x "grpc.production.xmtp.network:443" \
-d "postgres://postgres:xmtp@localhost:25432/postgres?sslmode=disable" \
--fcm-enabled \
--fcm-credentials-json=$YOURFCMJSON \
--fcm-project-id="YOURFCMPROJECTID"
```

--------------------------------

### Install Nix for Development

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/android/README.md

Command to install Determinate Nix, a prerequisite for the XMTP Android SDK development environment. This ensures reproducible builds.

```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```

--------------------------------

### XMTP CLI Usage Examples (Bash)

Source: https://context7.com/xmtp/libxmtp/llms.txt

Demonstrates common commands for the XMTP command-line interface (CLI), useful for testing and development workflows. Includes registering identities, managing groups, sending messages, and syncing history.

```bash
# Register a new identity
./xli.sh --db user1.db3 register

# Get account info
./xli.sh --db user1.db3 info

# Create a new group
./xli.sh --db user1.db3 create-group

# Add members to group
./xli.sh --db user1.db3 add-group-members $GROUP_ID \
  --account-addresses 0x1234...,0x5678...

# Send a message
./xli.sh --db user1.db3 send $GROUP_ID "Hello, world!"

# List messages in a group
./xli.sh --db user2.db3 list-group-messages $GROUP_ID

# Request history sync from other devices
./xli.sh --db user1.db3 request-history-sync

# Process history sync
./xli.sh --db user1.db3 reply-to-history-sync-request
./xli.sh --db user1.db3 process-history-sync-reply

# Use local development server
./xli.sh --local --db user1.db3 register

# Enable structured JSON logging
./xli.sh --json --db user1.db3 list-groups
```

--------------------------------

### Node.js Binding Automation

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-design.md

Recipes for Node.js bindings, handling dependency installation, N-API builds, and testing with Vitest.

```just
install:
  nix develop .#{{devshell}} --command bash -c 'yarn'
test: install
  nix develop .#{{devshell}} --command bash -c 'rm -rf dist && yarn napi build --platform --esm --features test-utils && mkdir -p dist && mv index.js dist && mv index.d.ts dist && mv *.node dist && yarn vitest run'
```

--------------------------------

### Install XMTP Android SDK

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/android/README.md

Instructions for adding the XMTP Android SDK to your project using Gradle. Replace X.X.X with the desired version.

```gradle
implementation 'org.xmtp:android:X.X.X'
```

--------------------------------

### Execute Development Tasks via Just

Source: https://github.com/xmtp/libxmtp/blob/main/bindings/node/CLAUDE.md

Common command-line tasks for managing the Node.js bindings, including installation, building, and testing.

```bash
just node install
just node check
just node lint
just node format
just node test
just node build
```

--------------------------------

### Install Determinate Nix

Source: https://github.com/xmtp/libxmtp/blob/main/docs/nix-setup.md

Installs Determinate Nix, a distribution of Nix optimized for developer and CI workflows with caching. It can be installed interactively via a script or manually using curl.

```bash
./dev/nix-up
```

```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --determinate
```

--------------------------------

### Register Wallet Account with CLI

Source: https://github.com/xmtp/libxmtp/blob/main/apps/cli/README.md

Registers a new wallet account (user) and creates an XMTP identity, storing it in a local database. It also grants the installation key bundle permission to message on behalf of the sender address. This is a prerequisite for using other CLI commands.

```bash
./xli.sh --db user1.db3 register
```

--------------------------------

### XMTP Client Usage on Android (Kotlin)

Source: https://context7.com/xmtp/libxmtp/llms.txt

Provides a comprehensive example of setting up and using the XMTP client on Android with Kotlin. It covers client configuration, creating group and direct message conversations, sending messages, and streaming incoming messages.

```kotlin
import org.xmtp.android.library.Client
import org.xmtp.android.library.ClientOptions
import org.xmtp.android.library.XMTPEnvironment
import org.xmtp.android.library.libxmtp.PublicIdentity
import org.xmtp.android.library.libxmtp.IdentityKind

const options = ClientOptions(
    api = ClientOptions.Api(
        env = XMTPEnvironment.DEV,
        appVersion = "MyApp/1.0"
    ),
    appContext = applicationContext,
    dbEncryptionKey = encryptionKey, // 32-byte key
    dbDirectory = filesDir.absolutePath
)

const client = Client.create(
    account = signingKey, // implements SigningKey interface
    options = options
)

const group = client.conversations.newGroupWithIdentities(
    identities = listOf(
        PublicIdentity(IdentityKind.ETHEREUM, "0x1234...")
    ),
    groupName = "My Group",
    groupDescription = "A test group"
)

group.send("Hello from Android!")

client.conversations.streamAllMessages().collect { message ->
    println("Received: ${message.body}")
}

val dm = client.conversations.findOrCreateDmWithIdentity(
    PublicIdentity(IdentityKind.ETHEREUM, peerAddress)
)
```

--------------------------------

### JSON Output Example for List Groups

Source: https://github.com/xmtp/libxmtp/blob/main/apps/cli/README.md

An example of the structured JSON output generated by the CLI client when the `--json` flag is enabled, specifically for the `list-groups` command. It shows various log events and the final command output.

```json
{"level":30,"time":1708561011597,"msg":"Starting CLI Client...."}
{"level":30,"time":1708561011597,"msg":"List Groups"}
{"level":30,"time":1708561011597,"msg":"Using persistent storage: user1.db3 "}
{"level":30,"time":1708561011597,"msg":"Setting up DB connection pool"}
{"level":30,"time":1708561011599,"msg":"Running DB migrations"}
{"level":30,"time":1708561011600,"msg":"Migrations successful"}
{"level":30,"time":1708561011600,"msg":"Using dev network"}
{"level":30,"time":1708561011999,"msg":"Initializing identity"}
{"level":30,"time":1708561012155,"msg":"group members","command_output":true,"success":true,"members":["0x2501622cbc306e06a09260c6f1dc4e166c4d814b","0xe11ac9f2b3f3c8b54690ef8c4c8e15c41c251bc1","0x8e6df612589feabc9524d371a018120175cb3b4d"],"group_id":"b360839b3d2e15bb86c2dca227095c14"}
```

--------------------------------

### Stream Real-time Messages and Conversations

Source: https://context7.com/xmtp/libxmtp/llms.txt

Provides examples for setting up real-time streams for incoming messages, new conversations, and specific conversation activity using callback functions.

```typescript
import { ConsentState, ConversationType } from '@xmtp/node-bindings'

const messageStream = await client.conversations().streamAllMessages(
  (message) => {
    console.log('New message received:', message.content)
  },
  () => { console.log('Stream closed') },
  ConversationType.Group,
  [ConsentState.Allowed, ConsentState.Unknown]
)

await messageStream.waitForReady()

const conversationStream = await client.conversations().stream(
  (err, conversation) => { if (conversation) console.log('New conversation:', conversation.id()) },
  () => console.log('Conversation stream closed'),
  ConversationType.Group
)

const convStream = conversation.stream(
  (err, message) => { if (message) console.log('Message:', message.id) },
  () => console.log('Closed')
)

await messageStream.endAndWait()
conversationStream.end()
```

--------------------------------

### XMTP WASM Browser Usage (TypeScript)

Source: https://context7.com/xmtp/libxmtp/llms.txt

Illustrates how to integrate and use the libXMTP library in a browser environment via WebAssembly. Examples include initializing the WASM module, creating test clients, managing conversations, and handling custom authentication.

```typescript
import init, { createTestClient, Conversation } from '@xmtp/wasm-bindings'

await init()

const client = await createTestClient()
console.log('Inbox ID:', client.inboxId)

const group = await client.conversations().createGroupByInboxIds([
  otherClient.inboxId,
])

const stream = await client.conversations().streamLocal()
const reader = stream.getReader()

while (true) {
  const { value, done } = await reader.read()
  if (done) break
  console.log('New conversation:', value.id())
}

const groups: Conversation[] = []
await client.conversations().stream({
  on_conversation: async (conversation: Conversation) => {
    groups.push(conversation)
    console.log('Received conversation:', conversation.id())
  }
})

import { AuthHandle, createAuthTestClient } from '@xmtp/wasm-bindings'

const handle = new AuthHandle()
await createAuthTestClient(
  {
    on_auth_required: async () => {
      return {
        value: 'Bearer your-auth-token',
        expiresAtSeconds: BigInt(Date.now() + 3600000),
      }
    },
  },
  handle
)
```

--------------------------------

### Configure Test Log Output - Bash

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

These examples show how to customize the log output for tests. The CONTEXTUAL=1 flag enables a tree-like log format, RUST_LOG filters logs by crate, and STRUCTURED=1 outputs logs in JSON format for easier parsing.

```bash
CONTEXTUAL=1 cargo test
RUST_LOG=xmtp_mls=debug,xmtp_api=off,xmtp_id=info cargo test
STRUCTURED=1 cargo test
```

--------------------------------

### Install direnv and Configure Shell Hooks

Source: https://github.com/xmtp/libxmtp/blob/main/docs/nix-setup.md

Installs direnv, a tool that automatically loads environment variables for directories. This snippet includes installation via Homebrew for macOS and configuration for zsh and bash shells.

```bash
# macOS
brew install direnv
```

```bash
# ~/.zshrc
eval "$(direnv hook zsh)"
```

```bash
# ~/.bashrc
eval "$(direnv hook bash)"
```

--------------------------------

### Parameterized Rust Test Example

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

An example of a parameterized Rust test using the `rstest` crate with `#[case]` attributes for different input and expected output pairs.

```rust
#[rstest]
#[case("input1", "expected1")]
#[case("input2", "expected2")]
fn test_function(#[case] input: &str, #[case] expected: &str) {
    assert_eq!(function_to_test(input), expected);
}
```

--------------------------------

### Build Native Bindings and SDK

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/android/README.md

Commands to build the native bindings (shared objects and Kotlin bindings) and the full XMTP Android SDK using Nix.

```bash
./dev/bindings
```

```bash
./dev/build
```

--------------------------------

### Initialize Nix Development Environment

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

Commands to initialize the development environment using Determinate Nix and manage direnv auto-activation.

```bash
./dev/nix-up
nix develop
```

```bash
./dev/direnv-down
./dev/direnv-up
```

--------------------------------

### Root Justfile: Build, Check, Lint, and Format

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

The root Justfile provides recipes for compiling, checking, linting, and formatting the project. It supports workspace-level and crate-level operations, utilizing Nix and Cargo for environment and build processes. It also includes git commit instructions.

```just
# Verify root justfile compiles
just --list --list-submodules

# Test check recipe
just check crate xmtp_common

# Test lint-toml recipe
just lint-toml

# Test lint-nix recipe
just lint-nix

# Test lint-markdown recipe
just lint-markdown

# Test lint-shell recipe
just lint-shell

# Test format recipe (workspace only)
just _format-workspace

# Commit
git add justfile
git commit -m "feat: consolidate root justfile with check/lint/format/test recipes

Add configurable NIX_DEVSHELL and CARGO_TEST_CMD env var overrides.
Add check (workspace + crate), lint (rust + config + markdown), format (treefmt + module delegates), and test (all/v3/d14n/crate) recipes."
```

--------------------------------

### FFI Error Propagation

Source: https://github.com/xmtp/libxmtp/blob/main/docs/error-architecture.md

Example of how error codes are formatted and exposed through UniFFI bindings for mobile consumers.

```rust
impl std::fmt::Display for FfiError {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		match self {
			FfiError::Error(e) => write!(f, "[{}] {}", e.error_code(), e),
		}
	}
}
```

--------------------------------

### Identity and Inbox Management

Source: https://context7.com/xmtp/libxmtp/llms.txt

Operations for managing wallet associations, retrieving inbox states, and handling installation keys.

```APIDOC
## GET /inbox/state

### Description
Retrieves the current state of the user's inbox, including associated installations and identifiers.

### Method
GET

### Parameters
#### Query Parameters
- **refresh** (boolean) - Optional - Whether to refresh the state from the network.

### Response
#### Success Response (200)
- **inboxId** (string) - The unique ID of the inbox.
- **installations** (array) - List of active installations.
- **identifiers** (array) - List of linked wallet addresses.
```

--------------------------------

### Initialize Nix Development Environment

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/ios/CLAUDE.md

Commands to enter the Nix development shell for iOS development or execute build tasks directly using the justfile.

```bash
nix develop .#ios
just ios build
```

--------------------------------

### Create and Register XMTP Client with Wallet Signature (TypeScript)

Source: https://context7.com/xmtp/libxmtp/llms.txt

This snippet demonstrates how to create an XMTP client by connecting to the network, generating an inbox ID, and registering an identity using a wallet signature. It utilizes viem for wallet operations and @xmtp/node-bindings for XMTP functionalities. The process involves creating a wallet, building the XMTP backend, generating or retrieving an inbox ID, and then registering the identity if it's not already on the network.

```typescript
import {
  BackendBuilder,
  createClientWithBackend,
  generateInboxId,
  getInboxIdByIdentity,
  IdentifierKind,
  SyncWorkerMode,
  LogLevel,
  XmtpEnv,
} from '@xmtp/node-bindings'
import { createWalletClient, http, toBytes } from 'viem'
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
import { sepolia } from 'viem/chains'

// Create a wallet
const key = generatePrivateKey()
const account = privateKeyToAccount(key)
const wallet = createWalletClient({
  account,
  chain: sepolia,
  transport: http(),
})

// Connect to XMTP backend
const backend = await new BackendBuilder(XmtpEnv.Dev)
  .setAppVersion('MyApp/1.0')
  .build()

// Generate or retrieve inbox ID
const identifier = {
  identifier: account.address,
  identifierKind: IdentifierKind.Ethereum,
}
const inboxId = await getInboxIdByIdentity(backend, identifier)
  || generateInboxId(identifier)

// Create client with database path
const client = await createClientWithBackend(
  backend,
  { dbPath: './xmtp.db3' },
  inboxId,
  identifier,
  SyncWorkerMode.Disabled,
  { level: LogLevel.Error },
  undefined
)

// Register identity if not already registered
if (!client.isRegistered()) {
  const signatureRequest = await client.createInboxSignatureRequest()
  const signature = await wallet.signMessage({
    message: await signatureRequest.signatureText(),
  })
  await signatureRequest.addEcdsaSignature(toBytes(signature))
  await client.registerIdentity(signatureRequest)
}

console.log('Client registered:', client.inboxId())
console.log('Installation ID:', client.installationId())
```

--------------------------------

### Log Output Control in Rust Tests

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

Examples of controlling log output during Rust tests using environment variables for different logging formats and filtering.

```bash
# CONTEXTUAL=1 cargo test - Async-aware structured logging (supports TestLogReplace for readable IDs)
# STRUCTURED=1 cargo test - JSON structured logs
# RUST_LOG=xmtp_mls=debug,xmtp_api=off cargo test - Filter by crate
```

--------------------------------

### Run Interactive WebAssembly Tests - Bash

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

This command allows for interactive testing of specific WebAssembly packages, such as 'xmtp_mls'. It provides a way to debug and test individual components in a more controlled environment.

```bash
./dev/test/wasm-interactive xmtp_mls
```

--------------------------------

### Development Commands

Source: https://github.com/xmtp/libxmtp/blob/main/dev/release-tools/README.md

Standard commands for testing and formatting the release tools codebase.

```bash
yarn test
yarn test:watch
yarn format
yarn format:check
```

--------------------------------

### Update Workspace Testing Workflow

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

Updates the test-workspace.yml to use 'just test' with a CARGO_TEST_CMD override. This workflow includes backend setup, test execution, and coverage reporting via Codecov.

```yaml
name: Test Workspace
on:
  workflow_call:
env:
  NIX_DEVSHELL: rust
  CARGO_TEST_CMD: "cargo llvm-cov nextest --no-fail-fast --no-report"
jobs:
  test:
    name: Test (Rust Workspace)
    runs-on: warp-ubuntu-latest-x64-16x
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - uses: ./.github/actions/setup-nix
        with:
          github-token: ${{ github.token }}
          cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
          sccache: "true"
      - uses: taiki-e/install-action@just
      - name: Start backend
        run: just backend up
      - name: Dump docker logs on failure
        if: failure()
        uses: jwalton/gh-docker-logs@v2
      - name: Run tests (v3 + d14n with coverage)
        run: just test
      - name: Generate coverage report
        run: nix develop .#rust --command cargo llvm-cov report --output-path lcov.info --lcov
      - name: Upload coverage
        uses: codecov/codecov-action@v5
        with:
          files: lcov.info
          token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Format Code and Run Lint Checks

Source: https://github.com/xmtp/libxmtp/blob/main/sdks/android/README.md

Gradle commands to format the codebase according to defined style guides and run lint checks to identify potential issues in the Android library.

```gradle
./gradlew spotlessApply
```

```gradle
./gradlew :library:lintDebug
```

--------------------------------

### Execute Performance Benchmarks

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

Commands to run benchmarks for the xmtp_mls crate, including specific categories, dev gRPC integration, and flamegraph generation.

```bash
cargo bench --features bench -p xmtp_mls --bench group_limit
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
```

--------------------------------

### Update Node CI Workflow with Just

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

This snippet updates the `.github/workflows/test-node.yml` file to use 'just' recipes for setting up the backend and running Node.js tests. It replaces previous setup steps with a more streamlined approach.

```yaml
name: Test Node
on:
  workflow_call:
env:
  NIX_DEVSHELL: js
jobs:
  test:
    name: Test (Node)
    runs-on: warp-ubuntu-latest-x64-16x
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - uses: ./.github/actions/setup-nix
        with:
          github-token: ${{ github.token }}
      - uses: taiki-e/install-action@just
      - name: Start backend
        run: just backend up
      - name: Run Node tests
        run: just node test
```

```bash
git add .github/workflows/test-node.yml
git commit -m "ci: switch test-node to use just node test

Replace setup-rust + setup-node + yarn with just recipe.
Use just backend up for Docker services."
```

--------------------------------

### Build Docker Image - Dockerfile

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

This command builds a Docker image for the libxmtp project, tagging it as 'libxmtp:1'. This is useful for creating a consistent development or deployment environment.

```dockerfile
docker build . -t libxmtp:1
```

--------------------------------

### Run XMTP Debug CLI in Docker

Source: https://github.com/xmtp/libxmtp/blob/main/apps/xmtp_debug/README.md

Executes the XMTP Debug tool (xdbg) as a one-off command within a Docker container. This is useful for running specific commands without installing the tool locally.

```bash
docker run --rm xdbg:local xdbg -d -b dev generate --entity identity --amount 5
```

--------------------------------

### Root Justfile Configuration for Linting

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-design.md

Configures linting commands including Rust, configuration files (toml, nix, shell), and Markdown. It leverages Nix for consistent environments and uses various tools like clippy, fmt, taplo, nixfmt, markdownlint, and treefmt.

```just
# --- LINT ---
lint: lint-rust lint-config lint-markdown

lint-rust:
  nix develop .#{{devshell}} --command \
    cargo clippy --locked --workspace \
    --all-features --all-targets --no-deps --exclude bindings_wasm -- -Dwarnings
  nix develop .#{{devshell}} --command cargo fmt --check
  nix develop .#{{devshell}} --command cargo hakari generate --diff
  nix develop .#{{devshell}} --command cargo hakari manage-deps --dry-run

lint-config: lint-toml lint-nix lint-shell

lint-toml:
  nix develop .#{{devshell}} --command taplo format --check --diff
  nix develop .#{{devshell}} --command taplo check

lint-nix:
  nix develop .#{{devshell}} --command nixfmt --check nix/ flake.nix

lint-shell:
  nix fmt -- --fail-on-change

lint-markdown:
  nix develop .#{{devshell}} --command markdownlint "**/*.md" --disable MD001 MD013
```

--------------------------------

### Get Wallet Info with CLI

Source: https://github.com/xmtp/libxmtp/blob/main/apps/cli/README.md

Retrieves information about a registered wallet account, specifically the wallet address. This address is often needed when adding members to a group or for other operations requiring a recipient's identifier.

```bash
./xli.sh --db user2.db3 info
```

--------------------------------

### Manage Identity and Inbox Associations

Source: https://context7.com/xmtp/libxmtp/llms.txt

Provides methods for managing inbox state, verifying message capability, and handling wallet associations. It covers adding or revoking identifiers and managing installation security through signature requests.

```typescript
import { IdentifierKind } from '@xmtp/node-bindings'

const inboxState = await client.inboxState(true)
console.log('Inbox ID:', inboxState.inboxId)

const canMessage = await client.canMessage([{ identifier: address, identifierKind: IdentifierKind.Ethereum }])

const signatureRequest = await client.addIdentifierSignatureRequest({ identifier: newWalletAddress, identifierKind: IdentifierKind.Ethereum })
const signature = await newWallet.signMessage({ message: await signatureRequest.signatureText() })
await signatureRequest.addEcdsaSignature(toBytes(signature))
await client.applySignatureRequest(signatureRequest)

const revokeRequest = await client.revokeIdentifierSignatureRequest({ identifier: walletToRemove, identifierKind: IdentifierKind.Ethereum })
const revokeSignature = await wallet.signMessage({ message: await revokeRequest.signatureText() })
await revokeRequest.addEcdsaSignature(toBytes(revokeSignature))
await client.applySignatureRequest(revokeRequest)
```

--------------------------------

### Standard Rust Test with unwrap_try

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

An example of a standard asynchronous Rust test using the `#[xmtp_common::test(unwrap_try = true)]` attribute, which enables the use of the `?` operator within the test function for better error handling.

```rust
#[xmtp_common::test(unwrap_try = true)]
async fn test_simple() {
    // Single test case - can use ? operator freely
}
```

--------------------------------

### Root Justfile Configuration for Formatting

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-design.md

Sets up the 'format' command to format the entire workspace and calls specific formatting commands for Android, iOS, Node, and WASM modules. It uses Nix for consistent formatting environments and tools like `nix fmt`.

```just
# --- FORMAT ---
format: _format-workspace
  just android format
  just ios format
  just node format
  just wasm format

[private]
_format-workspace:
  nix fmt
```

--------------------------------

### Build and Run CI Verification Script in Linux Container

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

This script builds a temporary Docker image with Nix and necessary tools, then runs various check, lint, and format commands within the container. It mounts the local repository for verification and reports PASS/FAIL status for each command. Dependencies include Docker and Nix.

```bash
#!/usr/bin/env bash
set -euo pipefail

REPO_DIR="$(pwd)"

GREEN='\033[0;32m'
RED='\033[0;31m'
NC='\033[0m'

echo "=== CI-Parity Verification in Linux Container ==="
echo ""

IMAGE_NAME="ci-verify-libxmtp:tmp"

echo "Building temporary verification image..."
docker build -t "$IMAGE_NAME" -f - /dev/null <<'DOCKERFILE'
FROM nixos/nix:latest
RUN mkdir -p /etc/nix && \
    echo "experimental-features = nix-command flakes" >> /etc/nix/nix.conf && \
    echo "accept-flake-config = true" >> /etc/nix/nix.conf
RUN nix-env -iA nixpkgs.just
WORKDIR /workspace
DOCKERFILE

echo "Image built successfully."
echo ""

run_in_container() {
  local description="$1"
  local env_vars="$2"
  local command="$3"

  printf "  %-50s " "$description"

  local env_args=""
  if [ -n "$env_vars" ]; then
    for var in $env_vars; do
      env_args="$env_args -e $var"
    done
  fi

  output=$(docker run --rm \
    -v "${REPO_DIR}:/workspace:ro" \
    -w /workspace \
    $env_args \
    "$IMAGE_NAME" \
    bash -c "$command" 2>&1) && rc=0 || rc=$?

  if [ $rc -eq 0 ]; then
    echo -e "${GREEN}PASS${NC}"
  else
    echo -e "${RED}FAIL${NC}"
    echo "    Last 5 lines of output:"
    echo "$output" | tail -5 | sed 's/^/    /'
  fi
}

echo "--- Smoke test ---"
echo ""
run_in_container "just --list" "" "just --list --list-submodules"

echo ""
echo "--- Check commands ---"
echo ""
run_in_container "just check (workspace)"          "NIX_DEVSHELL=rust"    "just check"
run_in_container "just check crate xmtp_common"    "NIX_DEVSHELL=rust"    "just check crate xmtp_common"
run_in_container "just wasm check"                 "NIX_DEVSHELL=wasm"    "just wasm check"
run_in_container "just android check"              "NIX_DEVSHELL=android" "just android check"

echo ""
echo "--- Lint commands ---"
echo ""
run_in_container "just lint-rust"                  "NIX_DEVSHELL=rust"    "just lint-rust"
run_in_container "just lint-config"                "NIX_DEVSHELL=rust"    "just lint-config"
run_in_container "just lint-markdown"              "NIX_DEVSHELL=rust"    "just lint-markdown"
run_in_container "just wasm lint"                  "NIX_DEVSHELL=wasm"    "just wasm lint"
run_in_container "just node lint"                  "NIX_DEVSHELL=js"      "just node lint"
run_in_container "just android lint"               "NIX_DEVSHELL=android" "just android lint"

echo ""
echo "--- Format commands (dry-run / check mode) ---"
echo ""
run_in_container "just lint-shell (format check)"  "NIX_DEVSHELL=rust"    "just lint-shell"
run_in_container "just node lint (prettier check)" "NIX_DEVSHELL=js"      "just node lint"
run_in_container "just wasm lint (prettier check)" "NIX_DEVSHELL=wasm"    "just wasm lint"

echo ""
echo "=== Cleanup ==="
docker rmi "$IMAGE_NAME" 2>/dev/null && echo "Removed temporary image." || true
echo ""
echo "=== Verification complete ==="

```

--------------------------------

### CLI Usage

Source: https://context7.com/xmtp/libxmtp/llms.txt

Use the command-line interface for testing and development workflows.

```APIDOC
## CLI Usage

### Description
Use the command-line interface for testing and development workflows.

### Method
N/A (CLI commands)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
# Register a new identity
./xli.sh --db user1.db3 register

# Get account info
./xli.sh --db user1.db3 info

# Create a new group
./xli.sh --db user1.db3 create-group

# Add members to group
./xli.sh --db user1.db3 add-group-members $GROUP_ID \
  --account-addresses 0x1234...,0x5678...

# Send a message
./xli.sh --db user1.db3 send $GROUP_ID "Hello, world!"

# List messages in a group
./xli.sh --db user2.db3 list-group-messages $GROUP_ID

# Request history sync from other devices
./xli.sh --db user1.db3 request-history-sync

# Process history sync
./xli.sh --db user1.db3 reply-to-history-sync-request
./xli.sh --db user1.db3 process-history-sync-reply

# Use local development server
./xli.sh --local --db user1.db3 register

# Enable structured JSON logging
./xli.sh --json --db user1.db3 list-groups
```

### Response
N/A
```

--------------------------------

### Android SDK Development

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

Commands for entering the Android development shell and building Android bindings using Nix and Cargo.

```bash
nix develop .#android             # Enter Android development shell
./sdks/android/dev/bindings       # Build Android bindings via Nix
just android build                # Build Android native bindings
```

--------------------------------

### Replace Log Identifiers - Rust

Source: https://github.com/xmtp/libxmtp/blob/main/README.md

This Rust code demonstrates two methods for replacing specific identifiers (like installation IDs or Ethereum addresses) with human-readable names in test logs. This is particularly useful when using the CONTEXTUAL=1 flag for improved log readability.

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

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

--------------------------------

### Root Justfile Configuration for Testing

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-design.md

Defines the 'test' command and its variants 'test v3' and 'test d14n' for the root workspace. It utilizes Nix for consistent testing environments and specifies the use of 'nextest v3' and 'd14n' for testing.

```just
# --- TEST ---

```

--------------------------------

### Benchmark Execution

Source: https://github.com/xmtp/libxmtp/blob/main/CLAUDE.md

Commands for running benchmarks, either all at once or specific benchmarks and categories.

```bash
dev/bench                                    # Run all benchmarks
dev/bench add_1_member_to_group              # Run a specific benchmark
cargo bench --features bench -p xmtp_mls --bench group_limit  # Run benchmark category
```

--------------------------------

### iOS SDK Build and Test Automation

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-design.md

Automation for iOS development tasks using Swift build tools and SwiftLint within a Nix environment.

```just
check:
  nix develop .#{{devshell}} --command bash -c './dev/bindings && swift build'
test:
  nix develop .#{{devshell}} --command bash -c './dev/bindings && swift test --parallel'
```

--------------------------------

### Update Android CI Workflow with Just

Source: https://github.com/xmtp/libxmtp/blob/main/docs/plans/2026-02-23-justfile-consolidation-plan.md

This update to `.github/workflows/test-android.yml` introduces 'just' recipes for Android testing. It modifies both the 'unit-tests' and 'integration-tests' jobs to use 'just backend up' for service setup and 'just android test' or 'just android test-integration' for running tests, including specific configurations for the emulator.

```yaml
- uses: taiki-e/install-action@just
      - name: Start backend
        env:
          NIX_DEVSHELL: android
        run: just backend up
      - name: Run unit tests
        env:
          NIX_DEVSHELL: android
        run: just android test
```

```yaml
- uses: taiki-e/install-action@just
      - name: Start backend
        env:
          NIX_DEVSHELL: android
        run: just backend up
      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm
      - name: Run integration tests
        timeout-minutes: 20
        env:
          NIX_DEVSHELL: android
          NIX_ANDROID_EMULATOR_FLAGS: "-no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -memory 4096 -partition-size 8192"
        run: just android test-integration
```

```bash
git add .github/workflows/test-android.yml
git commit -m "ci: switch test-android to use just android test

Replace direct nix develop + gradlew with just recipes.
Preserve KVM setup for emulator integration tests."
```
Tokens:
Raw