xmtpd

⚠️ Experimental: This software is in early development. Expect frequent changes and unresolved issues.

xmtpd (XMTP daemon) is an experimental version of XMTP node software. It is not the node software that currently forms the XMTP network.

After xmtpd meets specific functional requirements, the plan is for it to become the node software that powers the XMTP network.

Some of these requirements include reaching functional parity with the current node software and reliably performing data replication without data loss.

To keep up with and provide feedback about xmtpd development, see the Issues tab in this repo.

Tip

Looking for info on how to get started as a registered node operator? See the xmtpd-infrastructure repository, which provides infrastructure-as-code examples and tooling to help node operators deploy and manage xmtpd nodes.

Prerequisites

• Go 1.25 -- On macOS install with brew install go@1.25
• Docker
• Foundry

Quickstart

Install and build dependencies

To install dependencies and build background services needed by the node, run:

dev/up

This starts the following background services in Docker:

• A Postgres database that is used to store data needed to run the node

• A Prometheus instance that enables you to view metrics and data about the node, such as resource usage and errors

To stop the background services running in Docker, run:

dev/down

Start the node

To start the xmtpd node, run:

dev/run

Test the node

To run tests against the xmtpd node, run:

dev/test

These tests provide a full suite of unit and integration tests for the xmtpd repo to help ensure and maintain correctness of the code over time and to avoid regressions as the code evolves. You can explore the tests by taking a look at any files with the suffix _test.go.

Monitor the node

To enable metrics you need to start the node with --metrics.enable.

By default, we expose Prometheus metrics on port 8008.

curl http://localhost:8008

About the XMTP testnet

The XMTP testnet environment lives in XMTP Sepolia Chain.

The XMTP testnet nodes operated by Ephemera include:

DNS name	Location	Public key
https://grpc.testnet.xmtp.network	US-EAST-2	0x03e5442c5d1fe2f02b6b9a1a386383a7766860b40a6079a0223994ffa2ce10512c
https://grpc2.testnet.xmtp.network	EU-NORTH-1	0x02fc261d43a0153539a4c64c29763cb0e7e377c0eac2910c3d4bedb2235ac70371

Configuration

All XMTP binaries (servers and CLI tools) use a unified configuration system for contract addresses and chain settings.

Contract Configuration

Contract configuration can be loaded in three ways (in priority order):

1. Named Environment - Use a predefined environment configuration:

   # Command line
   xmtpd --contracts.environment=testnet
   xmtpd-cli --environment=testnet
   
   # Environment variable
   export XMTPD_CONTRACTS_ENVIRONMENT=testnet

   Available environments: testnet, mainnet

2. Configuration File - Specify a local file path or URL:

   # Local file
   xmtpd --contracts.config-file-path=/path/to/config.json
   xmtpd-cli --config-file=/path/to/config.json
   
   # HTTP(S) URL
   xmtpd --contracts.config-file-path=https://example.com/config.json
   
   # config:// scheme (shorthand for named environments)
   xmtpd-cli --config-file=config://testnet
   
   # Environment variable
   export XMTPD_CONTRACTS_CONFIG_FILE_PATH=/path/to/config.json

3. Raw JSON - Pass configuration directly as JSON (servers only):

   xmtpd --contracts.config-json='{"nodeRegistry": "0x..."}'
   export XMTPD_CONTRACTS_CONFIG_JSON='{"nodeRegistry": "0x..."}'

Note: Only one configuration source should be specified. Multiple sources will result in an error.

Environment Variables

All CLI tools now support standardized XMTPD_ prefixed environment variables for consistency with the server:

Configuration	CLI Flag	Environment Variable	Legacy Env Var (deprecated)
Log Level	--log-level	XMTPD_LOG_LEVEL	LOG_LEVEL
Log Encoding	--log-encoding	XMTPD_LOG_ENCODING	LOG_ENCODING
Private Key	--private-key	XMTPD_SIGNER_PRIVATE_KEY	PRIVATE_KEY
Settlement RPC	--settlement-rpc-url	XMTPD_SETTLEMENT_CHAIN_RPC_URL	SETTLEMENT_RPC_URL
App Chain RPC	--app-rpc-url	XMTPD_APP_CHAIN_RPC_URL	APP_RPC_URL

Backward Compatibility: Legacy environment variables are still supported but will print deprecation warnings. Please migrate to the new standardized names.

Deploy a local environment for developing with xmtpd

See Deploy a local environment for developing with xmtpd.

Support a new XMTP testnet node operator

See Support a new XMTP testnet node operator.

Migrate to XMTP node registry V2

See Node Registry Migration.

xmtpd OpenMetrics catalog

See xmptd OpenMetrics catalog.

Contributing

Please follow the style guide.

Modifying the protobuf schema

Submit and land a PR to https://github.com/xmtp/proto. Then run:

dev/gen/all

Or wait for the nightly automation to finish.

Modify the database schema

Create a new migration by running:

dev/gen/migration {migration-name}

Fill in the migrations in the generated files. If you are unfamiliar with migrations, you may follow this guide. The database is PostgreSQL and the driver is PGX.

Modify database queries

We use sqlc to generate the code for our DB queries. Modify the queries.sql file, and then run:

dev/gen/all

If needed, you may use dev/psql to test more complex SQL syntax. To determine the level of support in sqlc, there is a sqlc playground for experimenting with how the query syntax translates into Go code.