v1.2.0

XMTPD v1.2.0 Release Summary

🚀 Highlights

🛡️ Stability & Reliability

• Improved gRPC robustness, honoring message and stream limits and tightening timeout handling.
• Expanded error diagnostics with better contextual logging for JWT failures and originator/node identifiers.
• More resilient retry behavior for transient failures, including SQL errors, blockchain transaction lookup retries, and identity validation retries.

⚡ Performance & Scalability

• Significant performance improvements for payer lookups and envelope queries, including optimizations to FindOrCreatePayer, topic/originator filtering, and gateway envelope selection.
• Added SQL benchmarking suite and hot-path benchmarks to monitor and improve performance-critical code paths.
• Increased throughput through batch operations for gateway envelope inserts, address log updates, and migrator tasks.

🔁 Migrator & Data Pipeline

• Major improvements to migrator reliability and observability:
  • Configurable migration lower bounds
  • Backpressure control
  • Additional metrics for tracking migration progress
• Migration correctness improvements:
  • Preserve original expiration timestamps
  • Skip expired welcome messages
  • Generate payer reports for migrator originators
• Added last-seen metrics and additional debugging signals for migration monitoring.

📡 API & Networking

• Added SubscribeTopicEnvelopes API to support topic-based streaming subscriptions.
• Improved gateway routing stability by hashing topic identifiers for consistent node selection.
• Added networking health-check commands to improve operational diagnostics.

📊 Observability

• Added new API metrics including xmtp_api_outgoing_envelopes_total and per-method envelope emission metrics.
• Additional metrics for migrator progress and node activity.
• Expanded OpenTelemetry instrumentation and logging context.

🧰 Tooling & Developer Experience

• Added database population command for generating local development databases.
• Introduced ghz-based Node API performance tests.
• Improved repository organization and documentation.

⬆️ Platform Upgrades

• Upgraded to Go 1.26.
• Updated Ethereum client dependencies and several core libraries.
• Various dependency updates and lint improvements.

Changelog

• d30b470 EmitAPIOutgoingEnvelopes per API method (#1765)
• 32bbca0 Bump go.opentelemetry.io/otel/sdk from 1.39.0 to 1.40.0 in /tools (#1752)
• 5584fab Select by originators (#1751)
• 9bb75f5 Include contextual information on JWT errors (#1756)
• 29ea037 Ghz Node API Perf Tests (#1745)
• fcc96a8 Organize repository (#1750)
• 9c77ec4 docs: fix broken links in networking and onboarding (#1747)
• bb68675 docs: fix fenced code block in ratelimiter README (#1746)
• 12605e3 Honor gRPC limits on streams (#1744)
• cb9382d Add hot path bench tests (#1736)
• f72e436 Add missing checkout step for deployer tooling (#1731)
• 5300411 Fix migrator fees calculation (#1730)
• d3710c6 Add xmtp_api_outgoing_envelopes_total metric (#1727)
• 9977a12 Deploy to testnet and testnet-staging in parallel (#1724)
• 18c570b Honor gRPC message size limits (#1720)
• 6352cb4 Add populate database command to generate dev db locally (#1711)
• 2da422a Add SubscribeTopicEnvelopes API (#1653)
• 1fe108f Simplify node registration compose file (#1651)
• f445c55 Remove dead code (#1716)
• 3e6df53 Log migrator lower limits (#1715)
• cee886a Fix dev/bench (#1712)
• b0dc589 Fix log (#1713)
• 7609754 Generate payer reports for migrator originator IDs (#1708)
• bebf51b Make lower bounds for migrator configurable (#1707)
• 13f4414 Enable additional golangci-lint linters with autofix (#1654)
• 99b77f9 Add SQL Bench Suite (#1649)
• 3d7266d Overhaul SelectGatewayEnvelopesByTopics (#1642)
• a2e5e76 Deploy migrator image in CI (#1705)
• 84fd8a4 Reorder foundry installation (#1699)
• 24152f0 Upgrade to go 1.26 (#1701)
• 27e7ded Bump the gomod-updates group with 3 updates (#1702)
• 57b8a71 Fix sync service (#1695)
• ae28471 Also expose last seen metric from the migrator (#1663)
• 267f235 Retry on tx not found (#1664)
• 094b30f Update Protos (#1693)
• b9bdffe Bump github.com/ethereum/go-ethereum from 1.16.8 to 1.17.0 (#1686)
• 5a59d3b Bump github.com/ethereum/go-ethereum from 1.16.8 to 1.17.0 in /tools (#1687)
• 32bd2c6 Bump filippo.io/edwards25519 from 1.1.0 to 1.1.1 in /tools (#1691)
• ad146bf Allow migrator originators and Fix out of order warning (#1662)
• 934b055 Introduce database worker to check and create partitions (#1608)
• e970e5b Also add originators 0/1 to last seen originator metric (#1656)
• 4719b6b Honor migrator flag and add useful debugging (#1640)
• 3d30f22 Separate build and run steps (#1650)
• f320358 Bump the gomod-updates group with 4 updates (#1633)
• 1d37e1d Remove duplicate log (#1639)
• 617072a Add CLAUDE.md and some skills (#1630)
• 42be0da Fix preflight CORS CLI healthcheck (#1638)
• 8e21ffc refactor: replace context.WithCancel with t.Context (#1632)
• 567ba33 Gateway timeout for PublishClientEnvelopes (#1626)
• e2dba7f Insert and revoke address logs in batches (#1605)
• e293567 Prevent syncing migrator from local node (#1615)
• 1ada3e7 Upgrade to new RateRegistry contract (#1617)
• 42d238c Test deterministic db migration output (#1619)
• dcc49ad Help identify unmarshall problems (#1623)
• 73d1e3f Set expiration from original V3 creation date (#1621)
• 676047c Do not migrate expired welcome messages (#1620)
• d01b50d Annotate error message with originator node ID (#1618)
• 27679bf Enhance select by originator / topic (#1598)
• 2619aed refactor: use WaitGroup.Go to simplify code (#1616)
• b74b831 Update Protos (#1614)
• 8349f60 Bump the gomod-updates group with 5 updates (#1611)
• e20524b Trigger for updating latest envelope runs per statement (#1596)
• 26b388d Don't retry real MLS validation errors (#1602)
• 5352fa2 Bump migrator local work_mem (#1583)
• 8c98974 Add health-check networking command (#1587)
• 7fcb99d Retry MLS validation errors (#1594)
• 5142ffd Add payer_id missing foreign keys (#1584)
• 837ae44 Unify contract configuration loading across CLI and servers -Fixes #1540 (#1577)
• ef048fd Gateway node selection strategy fix - hash topic identifier instead of full bytes for stable routing (#1567)
• dd84195 Bump github.com/lib/pq from 1.10.9 to 1.11.1 in the gomod-updates group (#1586)
• c1736a3 Use WriteQuery for publish worker (#1580)
• ebd223e Update Protos (#1579)
• 953c14f Bump the gomod-updates group with 6 updates (#1569)
• 319c2a2 Enhance FindOrCreatePayer performance (#1565)
• 0f56fb0 Increase performance of FindOrCreatePayer (#1564)
• 695b07e Subscribe worker includes additional originator IDs (#1558)
• 3cbfe43 Migrator backpressure control (#1554)
• 3a0d110 nitpick: maintain log format lowcase (#1553)
• 4bb8839 Insert gateway envelope in batches (#1537)
• 2f3f6b9 Retry identity update if validation fails due to a transient sql failure (#1544)
• 43c7d03 Bump the gomod-updates group with 3 updates (#1549)
• 4913cfe Increase wait periods for a few flaky tests (#1542)
• 821a252 Update Protos (#1...

v1.1.1

XMTPD v1.1.1 — Targeted Fix & Debuggability Improvements

🛠️ Fixes & Improvements

• Honor migrator flag: ensures the migrator enable/disable configuration is correctly respected at runtime.
• Improved debugging signals: adds clearer and more actionable debug output to simplify diagnosing migrator behavior and configuration issues.

This patch focuses on correctness and operational clarity with no breaking changes.

Changelog

• 11f831b Honor migrator flag and add useful debugging (#1640)

v1.1.0

XMTPD v1.1.0 — Stability Highlights

🛡️ Stability & Correctness

• Safer concurrency and locking: envelope partition creation now uses less restrictive locking, and advisory locks use try-lock semantics to avoid deadlocks.
• Cleaner shutdown behavior: DB connections and test servers now close cleanly; publisher timeouts are handled as warnings instead of fatal errors.
• Stronger error handling: expanded verifier and on-chain error messages, proper CodeCanceled propagation, and safer handling of retryable DB errors.

🔁 Migrator Reliability

• Hardened migrator pipeline: batching, retries, worker pools, and a dead-letter box for failed migrations.
• Clear accounting and safety: migrator tracks commits and group messages separately, pays its own fees, and prunes only successfully migrated data.
• Improved observability: new metrics for bytes migrated, targets, and writer activity make migration progress and issues visible.

📈 Operational Observability

• Higher-quality metrics: added blockchain latency buckets (50ms precision), gateway publish wait timing, and indexed-bytes tracking.
• Better logging context: logs now include nodeID, sequenceID, topic, and address labels for faster debugging.
• Noise reduction: metrics emission throttled to avoid bursts and log overflow under load.

Changelog

• 27869d2 Change envelope partition creation to allow less restrictive locking (#1530)
• ba354f7 Fix test server shutdown (#1532)
• 7978344 Close DB connections on shutdown (#1526)
• f015a8f Bump github.com/DataDog/datadog-agent/pkg/trace from 0.73.0 to 0.74.0 in the gomod-updates group (#1525)
• 367f8b7 Some logging level changes (#1521)
• 756a9a4 chore: fix typos in pkg/db/db.go (#1524)
• dee6211 Migrator: commit messages batches (#1520)
• ce8c60d Add bytes indexed metric (#1522)
• 57bfc8d Add topic log field to errors in IU handling (#1507)
• 7bc8dcd Label indexer log processing time with address (#1508)
• 05a1103 Expand verifier error messages (#1512)
• 820d0be Measure wait for gateway publish (#1510)
• 462736b timeout waiting for publisher should be a warning (#1511)
• 62031ea Remove gateway sorting (#1468)
• 3cc062e Fix Uint32Slice param array to accept empty strings (#1495)
• dd4c71d Subscribe worker queries envelopes per originator (#1489)
• 5c78571 Bump the gomod-updates group with 2 updates (#1488)
• 4dda604 Gateway Alternative Node Selection Strategies (#1483)
• f04b75f Fix Duplicate OTEL Registration on DB Init (#1481)
• 3af3b9d GetPayerByAddress fetches EIP-55 formatted addresses (#1476)
• d9a2522 V3 Compatibility - Return nothing on empty filters (#1465)
• c250d4b Migrator now pays fees (#1470)
• 7192de7 Add migrator target metric (#1469)
• 5dd1641 Introduce support for read only DB (#1452)
• dbbbee6 Instrument logger with nodeId/SeqId (#1461)
• 55e076c Count message count for unsettled usage (#1462)
• 217e2a1 Only emit metrics once every 10 min, not multiple times per mod 0 min (#1460)
• d704cef Migrator: batches, retries and workers. (#1453)
• 9c23a99 Migrator: dead letter box (#1450)
• e9f5a57 Prune migrated messages (#1443)
• e3147c4 Bump the gomod-updates group with 6 updates (#1451)
• e12f0b5 Migrator: track commits and group messages separately (#1437)
• 55454af Enhance onchain error translation (#1428)
• 01d63f3 Actually register migratorWriterBytesMigrated (#1448)
• c07e5be Add migrator metrics and update gateway metrics (#1441)
• a239cf1 Bump github.com/quic-go/quic-go from 0.54.1 to 0.57.0 in /tools (#1439)
• 25d4f86 Serialize deploys on main using concurrency to prevent race conditions (#1435)
• c9d1edf Introduce 50ms precision blockchain prometheus buckets (#1434)
• 8433145 Teach CLI to use the --environment prebaked setting (#1433)
• 726178d Add blockchain oracle (#1412)
• cc38d47 Extend retryable pg errors (#1423)
• 1f5737c Use try lock for advisory locks (#1424)
• fe0344a Avoid log overflow (#1427)
• 77f345d Update Protos (#1425)
• fe2cb02 Register missing metrics (#1418)
• 8e34140 Return CodeCanceled properly (#1417)
• 8632339 Metrics interceptor (#1415)
• 739da46 Don't ban innocent nodes! (#1416)
• cfc5a5e XMTPD Goreleaser for Darwin and Linux (#1413)
• 19338d0 New Testnet addresses (#1411)
• 3b54d3d Enhance payer report system logging (#1402)
• c19ad80 Fix TestMigrator (#1394)
• 87e31ec Add client metrics in node to node sync (#1404)
• a8c7e3a Fix SemVer constraint (#1403)

v1.0.0

XMTPD v1.0.0 Release Summary

🏁 Production Readiness

XMTPD v1.0.0 marks the transition to production readiness.
This release focuses on stability, performance, and reliability, finalizing the core components needed for mainnet deployment.
It includes extensive testing, performance optimization, and hardening of blockchain integration, database operations, and gateway behavior.

🚀 Highlights

Core Platform & Stability

• Production-ready architecture with full settlement, attestation, and reporting flows verified.
• Improved vector clock performance and selection logic.
• Enhanced concurrency handling in the submitter and attestation workers.
• Introduced typed blockchain errors and rejection handling for on-chain reverts.
• Added rate limiter for improved system control under load.
• Multiple fixes to ensure stable startup, HA behavior, and consistent report generation.

Blockchain & Settlement

• Finalized payer report flow with 5 incremental improvements:
  • Smarter generation and Knuth-based distribution intervals.
  • Honors chain as the single source of truth.
  • Prevents duplicate or empty reports.
  • Only triggers settlement after all reports are processed.
  • Logs usage and settlement progress for observability.
• Added batch publishing of payer envelopes.
• Improved blockchain metrics and on-chain validation reporting.
• Updated to v2025.11.26-1 contract release with new ABIs.

API & Gateway

• Added new GetNodes gateway endpoint.
• Support for Connect-Go protocol.
• CORS support for API requests.
• Partitioned gateway envelopes for scalability.
• Added partially covering indexes to speed up API queries and pruning.

Database & Performance

• Major pruner improvements:
  • Speed boosted with indexed queries.
  • Prevents deletion of unsettled envelopes.
• Added automatic SQL metrics generation for visibility.
• Retries added to SQL operations for robustness.
• Condensed migrator upgrades and removed legacy tables.

CLI Enhancements

• Introduced version command and updated to latest contract ABIs.
• Added AppChain management and parameter handling.
• Improved funds and withdrawal workflows.
• CLI now fully supports modern admin flows and reflects production configuration.

Observability & Testing

• Expanded metrics for SQL, blockchain, and system performance.
• Improved logging consistency and added diagnostic logging for startup and reports.
• Supports tracing of failed transactions and fetch reports per worker.

What's Changed

• Update Protos by @github-actions[bot] in #1151
• Add explicit path in protos change by @fbac in #1152
• Do a proper delete of gen protos and re-run with newest by @mkysel in #1153
• Update the Gateway image in staging by @mkysel in #1157
• Enhance vector clock performance by @fbac in #1158
• Bump the gomod-updates group with 2 updates by @dependabot[bot] in #1160
• No timeout on migration 16 by @fbac in #1163
• Partial implementation of CLI funds commands by @mkysel in #1165
• Remove grpc-gateway by @fbac in #1167
• Add GetNodes gateway endpoint by @fbac in #1169
• Do not start GRPC server unless specified by @mkysel in #1171
• refactor: use WaitGroup.Go to simplify code by @juejinyuxitu in #1172
• Finish withdrawal flow for CLI by @mkysel in #1170
• Bump foundry to 1.3.5 by @mkysel in #1179
• Fix script post move by @mkysel in #1181
• Start the rate fetcher by @mkysel in #1180
• Implement AppChain CLI management and split param setting from update by @mkysel in #1182
• Add reports test scaffolding by @mkysel in #1178
• Allow gateway to enable gRPC reflection by @fbac in #1185
• Speed up pruner by adding a partially covering index by @mkysel in #1186
• Fix Identity update StoreLog under HA by @mkysel in #1184
• Enable XDBG tests again by @mkysel in #1191
• Infer parameter types in CLI so raw is not required by @mkysel in #1192
• Update GetNodes endpoint by @fbac in #1199
• Sort nodeIDs before packing by @fbac in #1202
• Update Protos by @github-actions[bot] in #1203
• Add a mini test for nodeID packing by @mkysel in #1205
• Fix ErrMessageAtStartSequenceIDNotFound during report generation by @mkysel in #1206
• Bump github.com/docker/docker from 28.4.0+incompatible to 28.5.0+incompatible in the gomod-updates group by @dependabot[bot] in #1212
• Trace failed transactions by @fbac in #1211
• Log event only when stored by @fbac in #1217
• Fix integration test which races with payer reports by @mkysel in #1221
• Prevent concurrent attestation from generating multiple envelopes by @mkysel in #1218
• Fix semantic merge conflict by @mkysel in #1224
• Payer reports: do not report others as frequently by @mkysel in #1220
• Rework Submitter Concurrency by @mkysel in #1219
• Make activeNodeIDs order predictable and fix broken test by @mkysel in #1230
• Log minutes for better debuggability by @fbac in #1231
• Return typed errors from blockchain by @fbac in #1233
• Submission rejected based on on-chain revert errors by @fbac in #1234
• Attest and submit filters by @fbac in #1235
• Submitter state and transition tests by @fbac in #1236
• Log fetch reports per worker by @fbac in #1237
• Fix attestation worker critical path by @fbac in #1238
• Bump github.com/quic-go/quic-go from 0.54.0 to 0.54.1 in /tools by @dependabot[bot] in #1239
• Bump the gomod-updates group with 2 updates by @dependabot[bot] in #1241
• Acquire HA generator lock by @mkysel in #1247
• Handle PayerReportAlreadySubmitted by @fbac in #1246
• Update Protos by @github-actions[bot] in #1253
• Manually generate protos by @mkysel in #1258
• Standardize logging by @fbac in #1262
• refactor: omit unnecessary reassignment by @spuradage in #1266
• Update Protos by @github-actions[bot] in #1267
• Add a partially covering index to speed up API queries by @mkysel in #1268
• Reduce subscribe worker batch size by @mkysel in #1270
• Fix payer report logger chain by @fbac in #1269
• Add logging to diagnose startup issues by @mkysel in #1271
• Speed up Vector Clock selection by @mkysel in #1272
• Update Protos by @github-actions[bot] in #1273
• Fix SQL Upgrade 20 by @mkysel in #1274
• Pass limit to the SQL query by @mkysel in #1275
• Unify vector selector queries by @mkysel in #1276
• Bubble up payer report verifier results by @fbac in #1264
• Initial stab at 0.6.0 contracts by @mkysel in #1254
• Add rate limiter and example by @neekolas in #1255
• Bump github.com/consensys/gnark-crypto from 0.18.0 to 0.18.1 by @dependabot[bot] in #1285
• Bump github.com/consensys/gnark-crypto from 0.14.0 to 0.18.1 in /tools by @dependabot[bot] in #1284
• Remove BlockUntilDesiredCursorReached clutch from payer by @mkysel in #1281
• Limit blockchain payload size by @mkysel in #1282
• Bump github.com/redis/go-redis/v9 from 9.14.0 to 9.16.0 in the gomod-updates group by @dependabot[bot] in #1278
• refactor: replace interface{} with any for clarity and modernization by @fengyuchuanshen in #1295
• Partitioned Gateway Envelopes by @mkysel in #1279
• Condense migrator upgrades and remove dead tables by @mkysel in #1296
• Optimize filter by topic queries by @mkysel in #1297
• Support connect-go protocol by @fbac in #1277
• Allow and handle CORS by @fbac in #1299
• ...

v0.5.1

XMTPD v0.5.1 Release Summary

🚀 Highlights

Core Upgrades

• Upgraded to Go 1.25.
• Enforced stricter Go standards across the codebase.
• Updated dependencies including Docker, Mapstructure, go-jose, gRPC, and more.

Migrator & Database

• Idempotent migrations: prevent duplicate registrations of nodes with existing pubkeys.
• Migrator writer established as source of truth.
• Added migration client.
• Database is created if not already present; migration requires DB to exist.
• Improved bulk move from previous → current states.

CLI Enhancements

• Made the new Cobra CLI canonical.
• Expanded CLI tooling with:
  • Parameter manager commands (admin & missing elements).
  • Group message bootstrapper.
  • Pause/unpause appchain contracts.
  • Hidden mint underlying token command.
  • On-chain parameter management with full CLI coverage.
  • HTTP config path support.
• Normalized error handling and silenced extra CLI usage output.
• Introduced payload generator.
• Added goreleaser workflow for building CLI and Homebrew publishing.

Smart Contracts

• Added missing contracts and upgraded to v0.5.5 contracts.
• Introduced pause/unpause workflows for appchain contracts.
• Updated Foundry to align with the contracts repo.

Observability & Testing

• Enabled TestCanGenerateAndAttestReport.
• Added ability to skip specific race tests.
• Normalized expiry calculation to UTC 24h days.
• Validation results now bubble up consistently.

Infrastructure & Misc

• Adopted good improvements from node-go pruner.
• Added on-chain errors dictionary.
• Support for using anvil with deployed gateways.

What's Changed

• build: update checkout action to v5 by @rejected-l in #1039
• Take the good improvements from node-go pruner by @mkysel in #1041
• Upgrade to go 1.25 by @fbac in #1044
• Bump github.com/docker/docker from 27.5.0+incompatible to 28.0.0+incompatible in /tools by @dependabot[bot] in #1051
• Idempotent migration: do not migrate nodes with pubkey already registered by @mkysel in #1043
• Migrator writer is the source of truth by @fbac in #1042
• Bump github.com/go-viper/mapstructure/v2 from 2.3.0 to 2.4.0 by @dependabot[bot] in #1058
• Enable TestCanGenerateAndAttestReport by @fbac in #1060
• Create db if not exists by @fbac in #1059
• Fix update protos by @fbac in #1056
• Bump github.com/go-jose/go-jose/v4 from 4.0.4 to 4.0.5 in /tools by @dependabot[bot] in #1061
• Update Protos by @github-actions[bot] in #1062
• Bump the gomod-updates group with 2 updates by @dependabot[bot] in #1069
• Migration client by @fbac in #1057
• First stage of parameter CLI admin by @mkysel in #1070
• Group message bootstrapper CLI by @mkysel in #1071
• Pause/unpause appchain contracts by @mkysel in #1072
• Add missing contracts and upgrade to v0.5.5 by @mkysel in #1073
• Require database exists if migration is enabled by @fbac in #1074
• Add onchain errors dictionary by @fbac in #1052
• Minor updates to PAUSED workflow by @mkysel in #1086
• Pass contract options correctly by @fbac in #1087
• Update foundry to version used in contracts repository by @fbac in #1088
• More pause CLI commands by @mkysel in #1090
• Bump github.com/go-viper/mapstructure/v2 from 2.2.1 to 2.4.0 in /tools by @dependabot[bot] in #1089
• Rework rate manager to use param manager and add tests by @mkysel in #1091
• Param management for all missing elements. No CLI commands yet by @mkysel in #1092
• Bulk move from previous to current by @mkysel in #1099
• All missing CLI commands by @mkysel in #1094
• Bump the gomod-updates group with 4 updates by @dependabot[bot] in #1101
• Make new cobra CLI canon by @mkysel in #1100
• Update Protos by @github-actions[bot] in #1106
• Ability to skip specific tests on race by @fbac in #1095
• Normalize expiry calculation to UTC with fixed 24h days by @mkysel in #1108
• Use anvil with deployed gateways by @mkysel in #1109
• Force Go standards by @fbac in #1105
• Bubble up validation results by @fbac in #1113
• Bump the gomod-updates group with 4 updates by @dependabot[bot] in #1125
• Add hidden mint underlying token CLI command by @mkysel in #1129
• Silence CLI usage print and unify error handling by @mkysel in #1130
• Add payload generator by @fbac in #1111
• Allow using HTTP config paths in the CLI by @mkysel in #1131
• Create goreleaser process for building CLI and brew pushing by @mkysel in #1133

New Contributors

• @rejected-l made their first contribution in #1039

Full Changelog: v0.5.0...v0.5.1

v0.5.0

XMTPD v0.5.0 Release Summary

🚀 Highlights

CLI Overhaul

• New xmtpd-cli built on spf13/cobra for a more structured and extensible command-line experience.

Blockchain & Indexer Improvements

• Validation now checks chains against chainID.
• Dynamic discovery of backfill block page size.
• Configurable prune batch size.
• Indexer updates progress even when no logs are found.
• Improved gateway stability with multiple bug fixes and panic prevention.
• Blockchain publisher can bootstrap messages and guarantee data integrity after subscription failures.
• App messages are now routed to the blockchain.

Metrics & Observability

• New metrics on subscription events.
• Additional logging for:
  • Shutdown events
  • Replication metrics
  • Out-of-order errors
• Added pprof HTTP server for profiling.
• Introduced GetVersion metadata endpoint.

Stability & Reliability

• Defensive checks for valid message expiration.
• Prevention of writes to closed channels.
• Fixes for:
  • Flaky registry tests
  • Off-by-one backfill block sizing
• Better error silencing and handling during shutdown.

Infrastructure & CI

• Support for deploying multiple images in a single run.
• Condensed CI actions.
• Skip test report uploads for fork PRs.
• Added migrator service for DB migrations.
• Keepalive config for chain client.
• Shellcheck compliance and typo fixes.

Protocol & Contract Updates

• Upgraded to v0.5.1 contracts.
• Reintroduced HTTP JSON-RPC client.
• Multiple Protobuf updates, including removal of targetOriginator.

Refactors

• Cleaner map handling via maps.Copy.
• Separated DB worker from sync loop.
• Validation-free isCommit determination.

What's Changed

• Add new xmtpd-cli based on spf13/cobra by @fbac in #880
• Add more debug info to duplicate inserts by @mkysel in #882
• Skip DD test report upload for fork PRs by @mkysel in #884
• chore: fix typos by @coderwander in #883
• Make shellcheck happy by @mkysel in #890
• Update metrics on subscription by @mkysel in #889
• Validate provided chains with chainID by @fbac in #887
• Update Protos by @github-actions[bot] in #886
• Update Protos by @github-actions[bot] in #895
• Bump github.com/go-chi/chi/v5 from 5.2.0 to 5.2.2 in /tools by @dependabot[bot] in #899
• Bump the gomod-updates group with 3 updates by @dependabot[bot] in #902
• Fix backfill block size off-by-1 by @mkysel in #903
• Always run API with /healthz endpoint by @mkysel in #904
• Close timing gap in socket discovery by @mkysel in #905
• Skip attestation test until a fix is found by @mkysel in #914
• Silence error during shutdown by @mkysel in #912
• Revert gen protos to xmtp/protos:main branch by @fbac in #915
• Update protos and remove targetOriginator by @mkysel in #916
• Add defensive checks for valid expiration by @mkysel in #911
• Check for closed channel by @fbac in #920
• Bump github.com/go-viper/mapstructure/v2 from 2.2.1 to 2.3.0 by @dependabot[bot] in #922
• Indexer updates backfill progress on no logs by @fbac in #919
• chore: fix some minor issues in the comments by @mountdisk in #926
• Print the data we need for out-of-order errors by @mkysel in #931
• Log replication.metrics shutdown by @fbac in #896
• Check closed channels by @fbac in #921
• Update Protos by @github-actions[bot] in #935
• Separate DB worker from sync by @mkysel in #932
• Prevent write-to-closed-channel panics by @mkysel in #933
• chore: fix some comments by @rustfix in #943
• Update Protos by @github-actions[bot] in #939
• Bump the gomod-updates group with 3 updates by @dependabot[bot] in #925
• Fix flaky registry tests by @mkysel in #938
• Update Protos by @github-actions[bot] in #945
• Condense CI actions by @mkysel in #946
• Add keepalive config to chain client by @fbac in #944
• GetVersion metadata endpoint by @fbac in #957
• Add pprof http server by @fbac in #923
• Discover backfill block page size dynamically by @fbac in #949
• Bump golang.org/x/crypto from 0.39.0 to 0.40.0 in the gomod-updates group by @dependabot[bot] in #965
• Make prune batch size configurable by @mkysel in #964
• Fix shellcheck error by @fbac in #967
• Backfill page on sub error by @fbac in #947
• Deploy multiple images in one go by @mkysel in #972
• Bump golang.org/x/oauth2 from 0.25.0 to 0.27.0 in /tools by @dependabot[bot] in #977
• Bump github.com/testcontainers/testcontainers-go from 0.37.0 to 0.38.0 in the gomod-updates group by @dependabot[bot] in #978
• Guarantee data integrity after sub fails completely by @fbac in #971
• refactor: use maps.Copy for cleaner map handling by @pingshuijie in #984
• Fix missing return by @fbac in #989
• Bump google.golang.org/grpc from 1.73.0 to 1.74.2 in the gomod-updates group by @dependabot[bot] in #990
• Validation free isCommit determination by @mkysel in #987
• Upgrade to v0.5.1 contracts by @fbac in #988
• Route app messages to the blockchain by @mkysel in #992
• Bump github.com/docker/docker from 28.3.0+incompatible to 28.3.3+incompatible by @dependabot[bot] in #1000
• Multiple gateway fixes by @mkysel in #1003
• Fix XDBG tests (partially) by @mkysel in #1004
• Teach blockchain publisher to bootstrap messages by @fbac in #998
• Add migrator service by @fbac in #897
• Prevent dependsOn for non-commits: by @mkysel in #1008
• Fix originator in indexer storer by @mkysel in #1009
• Bump the gomod-updates group with 4 updates by @dependabot[bot] in #1007
• Add a log when shutting down gateway by @mkysel in #1010
• Update Protos by @github-actions[bot] in #1021
• Bump the gomod-updates group with 2 updates by @dependabot[bot] in #1030
• Reintroduce HTTP JSON-RPC client by @fbac in #1001

New Contributors

• @coderwander made their first contribution in #883
• @mountdisk made their first contribution in #926
• @rustfix made their first contribution in #943
• @pingshuijie made their first contribution in #984

Full Changelog: v0.4.0...v0.5.0

v0.4.0

⚠️ Important Notes

• Contract Changes: Upgrading to v0.4.0 requires pointing your nodes to new smart contracts. Refer to the xmtpd-infrastructure repo for updated contract addresses.
• Pruning Support: This release introduces database pruning. You can now configure data retention limits and automatically discard older messages.

🧩 Major Features

Multi-Chain Indexing

Indexing support has been expanded to multiple chains, including smart chain selection, deployment-aware block tracking, and support for parameterized chain registries.

Parameter Registry Integration

The RateRegistry and NodeRegistry contracts now integrate with a central Parameter Registry, simplifying on-chain configuration and unifying admin flows.

Pruning and Data Retention

Initial support for node-side data pruning. Operators can configure how much data to retain and initiate pruning cycles via the new CLI tooling.

Improved Indexer + Blockchain Metrics

Even deeper visibility into system behavior with new metrics for the indexer, blockchain backfill, congestion, and storage layer performance.

gRPC Improvements

• gRPC API responses are now sanitized, hiding internal error messages.
• New API: GetNewestEnvelope
• New API: GetReaderNode for payers

CLI & Dev Enhancements

• Added get rates and prune commands to the CLI
• Docker Compose and DevContainer improvements for easier local development
• Stress test tooling now includes TPS tracking and concurrency limits

---

📊 Metrics Additions

• Payer gRPC client metrics
• Indexer stress test metrics (TPS, envelope rate)
• MLS method invocation statistics
• OpenMetrics negotiation format now supported

Stay tuned for the updated Grafana dashboards that incorporate these.

All PR's

• Reentrant add node to network by @fbac in #707
• Add from-0.3.0 upgrade tests by @mkysel in #710
• No more image baking (lets leave that to the bakeoff shows) by @mkysel in #711
• Bump github.com/prometheus/client_golang from 1.21.0 to 1.22.0 in the gomod-updates group by @dependabot in #714
• chore: fix some struct names in comment by @fivecut in #716
• Bump golang.org/x/net from 0.36.0 to 0.38.0 by @dependabot in #718
• chore: fix comment by @closeobserve in #713
• Bump golang.org/x/net from 0.36.0 to 0.38.0 in /tools by @dependabot in #717
• Bump the gomod-updates group with 2 updates by @dependabot in #724
• Generate metrics catalog by @mkysel in #719
• Sanitize gRPC API error responses to prevent exposure of internal error details in the logging interceptor by @mkysel in #728
• Add pkg merkle by @fbac in #712
• Fix docker down by @mkysel in #729
• fix err logging_test.go by @sky-coderay in #731
• Expose MLS method invocation statistics by @mkysel in #730
• docs(readme): add license and twitter badge by @Ocheretovich in #732
• CalculateBalanceNodesCount to handle int by @fbac in #733
• Add Prometheus metrics to Payer gRPC client operations and consolidate MLS validation service initialization by @mkysel in #735
• ci: bump actions/checkout to v4 by @dizer-ti in #737
• Add DevContainer setup by @neekolas in #723
• Even more indexer/blockchain metrics by @mkysel in #736
• Add poor's man identity updates stress test by @fbac in #738
• Handle concurrency limiter in stress test and dump analytics by @mkysel in #739
• Add TPS to stress test by @mkysel in #740
• Do not block forever on read-your-own-commits by @mkysel in #743
• Fix issue with identity update storer by @neekolas in #744
• Do not require 0x prefix for stress tests by @mkysel in #742
• Add GetNewestEnvelope API Endpoint by @neekolas in #741
• Add more test coverage for pkg/merkle by @fbac in #734
• Bump the gomod-updates group with 2 updates by @dependabot in #746
• Teach CLI the get rates command by @mkysel in #748
• Add dummy chain watcher by @fbac in #747
• Add expiry field to gateway envelopes by @mkysel in #752
• Clarify error to help with support by @mkysel in #757
• Manual protos build by @mkysel in #758
• Update docker-compose-register.yml to use latest xmtpd-cli version (sha-a96bf04) by @finnfisher-de in #766
• Add scaffolding for XMTPD DB prune / data retention by @mkysel in #772
• Add GetReaderNode payer API endpoint by @fbac in #771
• Remove nightly PAT by @fbac in #773
• Update Protos by @github-actions in #775
• Bump the gomod-updates group with 2 updates by @dependabot in #776
• Set payer expiration all the way through from client to XMTPD database by @mkysel in #769
• Initial prune implementation by @mkysel in #774
• Update Protos by @github-actions in #782
• Add multi-chain support by @fbac in #755
• Derive DB name from primary key in pruner by @mkysel in #778
• Test pruner and refactor newDB by @mkysel in #788
• Migrate test cleanup functions to use Go's built-in t.Cleanup mechanism across test utilities and test files by @mkysel in #789
• Add prune release to rel from tag by @mkysel in #791
• Fix junit-upload-github-action deprecation warning by @mkysel in #790
• Fix deployments by @fbac in #793
• Require MLS validation service by @fbac in #798
• feat: Matched Sequential Proof Implementation by @deluca-mike in #749
• Validate hex addresses by @fbac in #801
• refactor: replace context.WithCancel with t.Context in tests by @pengqiseven in #799
• Modular multi-chain indexer by @fbac in #800
• Enable openmetrics negotiation format by @mkysel in #809
• Rework compose up/down by @mkysel in #822
• Speed up generation by removing all cruft from builder by @mkysel in #821
• Use pre-baked image for all anvil-based tests by @mkysel in #823
• Propagate ctx cancellation to IndexLogs by @fbac in #811
• Fix problematic tests using risky pattern by @mkysel in #824
• Add header to metrics catalog by @mkysel in #825
• Remove paths from CI by @mkysel in #826
• Speed up CLI container construction in dev/up by @mkysel in #829
• Migrate RateRegistry and NodeRegistry contracts to 0.4.0 version with parameter registry integration and updated data types by @mkysel in #810
• Add parameter registry ABI and implement set maxcanonical by @mkysel in #830
• Migrate to V4 rates contract by @mkysel in #833
• Allow operator defined backfill block size by @mkysel in #834
• Update structure of docs by @jhaaaa in #806
• Do not require BIN for abigen by @mkysel in #853
• Use 040 contracts with ABI and new addresses by @mkysel in #854
• Update Protos by @github-actions in #856
• Add settlement chain and PayerRegistry indexing by @fbac in #847
• Start indexing at custom block height by @fbac in #827
• Load env config via JSON by @mkysel in #855
• Bump github.com/docker/docker from 28.1.1+incompatible to 28.2.2+incompatible in the gomod-updates group by @dependabot in #861
• Update Protos by @github-actions in #859
• Move to 0.4.3 contracts by @mkysel in #864
• Revamped reorg detection by @fbac in #858
• Refactor large options configs using the functional options pattern by @mkysel in #866
• Introduce XDBG integration tests by @mkysel in #865
• Use JSON-RPC ...

v0.3.0

Important Notes

• To upgrade to 0.3.0 you will need to change the smart contracts your deployed nodes point to. Please look to xmtpd-infrastructure for the latest contract addresses.
• Upgrading to 0.3.0 will wipe your local database. All sequence_id's will restart from 0, and all smart contracts will be indexed from the start.

Major Features

New Nodes Registry

We have upgraded the Nodes Registry to have more fine-grained admin roles, and better tracking of node status. This is a breaking change and requires all nodes to wipe their local database and start clean.

Metrics. Metrics. Metrics.

We have added dozens of Prometheus metrics to the node and payer services, tracking performance and reliability. We plan to release an open source Grafana dashboard to make sense of these metrics in the coming weeks.

Fee Tracking

xmtpd is now tracking fee consumption on every message, to set the network up for reaching consensus on Payer spends.

Better payer service nonce management

Payers can send a lot of blockchain transactions concurrently. We have substantially improved our nonce manager to handle this kind of workload and avoid nonce-reuse errors and long delays due to nonce gaps. The payer service can now run in HA mode with more than 1 replica.

GRPC Gateway Support

We now support HTTP clients as well as GRPC through GRPC Gateway

All PR's

• Use v5 for caching by @mkysel in #508
• Fix CLI version print by @mkysel in #509
• Improve version checking system by @mkysel in #506
• Lint generators and commit dirty changes by @mkysel in #507
• chore: update to foundry v1.0.0 by @fbac in #523
• Bump github.com/ethereum/go-ethereum from 1.14.12 to 1.14.13 in /tools by @dependabot in #526
• Some good logging by @mkysel in #525
• Bump the gomod-updates group with 2 updates by @dependabot in #539
• Fix foundry version check by @neekolas in #534
• Add 0.2.0 upgrade test by @mkysel in #545
• Add LoggingMisbehaviorService by @neekolas in #413
• Allow running without payer key by @mkysel in #547
• Verifiable payer by @mkysel in #544
• feat!: enhancements to XMTP Nodes Registry by @fbac in #524
• Add payers table by @neekolas in #535
• Link payer to gateway envelopes by @neekolas in #536
• Add fee calculation helpers by @neekolas in #537
• Add fees to UnsignedOriginatorEnvelope by @neekolas in #548
• Track unsettled usage by @neekolas in #549
• Remove error print by @mkysel in #565
• Add migration tools for node registry by @neekolas in #555
• XMTP Node Registry enhancements by @fbac in #572
• feat: Payer interface by @fbac in #558
• Drive-by fixes to logger and fatal by @mkysel in #577
• Surface xmtpd-infra as a resource to node operators by @jhaaaa in #582
• SQL Nonce Manager for HA Payer by @mkysel in #578
• Change payer envelope to bytes field by @neekolas in #553
• Post 0.2.1 release chores by @mkysel in #584
• Add initial Rates contract by @neekolas in #557
• Make RatesManager upgradeable and deployable by @neekolas in #559
• Ingest rates from smart contract by @neekolas in #573
• Add admin functions for rates contract by @neekolas in #575
• Add base sepolia output by @fbac in #585
• Prepare migrator for v1 to v2 migration by @fbac in #576
• Update Protos by @github-actions in #588
• Add CLI tool for adding rates to the contract by @neekolas in #586
• IPayerReport interface by @fbac in #581
• Calculate fees independently in sync by @neekolas in #556
• Breaking!: Integrate NodesV2 by @fbac in #589
• Update contracts deployment scripts by @fbac in #596
• Improve Grammar and Clarity in Documentation by @SITADRITA1 in #564
• Fix TestPublishIdentityUpdate test by @mkysel in #607
• Monitoring setup by @mkysel in #606
• Fix TestAddRates by @mkysel in #608
• Normalize contract deployment keys by @fbac in #600
• Add xmtp_testnet-playground environment config by @fbac in #601
• Rename minMonthlyFee to minMonthlyFeeMicroDollars by @fbac in #602
• Bump google.golang.org/grpc from 1.70.0 to 1.71.0 in the gomod-updates group by @dependabot in #599
• Update Protos by @github-actions in #594
• add grpc-gateway by @insipx in #579
• Print registrant in expected form by @mkysel in #613
• Start storing congestion per minute by @neekolas in #598
• Add env.json by @fbac in #611
• Replace geth client with Arbitrum fork by @neekolas in #618
• Disable upgrade tests by @neekolas in #619
• Bump golang.org/x/net from 0.35.0 to 0.36.0 in /tools by @dependabot in #627
• Bump golang.org/x/net from 0.35.0 to 0.36.0 by @dependabot in #626
• More nonce improvements by @mkysel in #625
• feat: contracts cleanup by @deluca-mike in #620
• Add payer metrics by @mkysel in #622
• Use testcontainers in upgrade tests by @fbac in #603
• Do not skip storing messages in indexer by @fbac in #621
• Test utility to start an anvil instance by @neekolas in #629
• Calculate congestion from last 5 minutes of data by @neekolas in #609
• Get target rate per minute from smart contract by @neekolas in #610
• Utility to get most recent 5 minutes of congestion by @neekolas in #616
• More sync metrics by @mkysel in #634
• Use real congestion rates by @neekolas in #617
• Fix CI error by @mkysel in #635
• Update migrator docs by @fbac in #590
• Bump github.com/docker/docker from 27.5.0+incompatible to 28.0.1+incompatible in the gomod-updates group by @dependabot in #638
• fix correction by @futreall in #637
• Run abigen by @neekolas in #640
• Use retry library by @mkysel in #641
• Indexer metrics + indexer refactors by @mkysel in #639
• Bump github.com/containerd/containerd from 1.7.25 to 1.7.27 in /tools by @dependabot in #644
• Improve nonce replenishment by @mkysel in #642
• Switch anvil to mixed mode mining by @mkysel in #647
• chore: fix some comments by @linghuying in #649
• Update Protos by @github-actions in #650
• Fix prom metrics by @mkysel in #648
• fix spelling errors by @Bilogweb3 in #651
• Re-enable upgrade tests by @mkysel in #657
• Bump github.com/golang-jwt/jwt/v5 from 5.2.1 to 5.2.2 by @dependabot in #662
• Bump github.com/golang-jwt/jwt/v4 from 4.5.1 to 4.5.2 in /tools by @dependabot in #663
• Update Protos by @github-actions in #664
• Fix generate identity hang and add more metrics by @mkysel in #666
• Update Protos by @github-actions in #667
• Auth as PAT in nightly automation by @fbac in #668
• docs(readme): add badge and link to lint workflow by @Ocheretovich in #677
• chore: add icon and link to release by @Ocheretovich in #678
• Rework retry and Fix Version Verifier by @mkysel in #679
• Fix GRPC KeepAlive by @mkysel in #680
• Generate payer reports by @neekolas in https://github.com/xmtp/xmtpd/p...

v0.2.3

What's Changed

• Fix generate identity hang and add more metrics by @mkysel in #666
• Fix GRPC KeepAlive by @mkysel in #680
• Fix abigen 0.2-dev by @mkysel in #673
• Cherry Pick Changes For ETH Client by @neekolas in #676
• 0.2-dev Rework retry by @mkysel in #675
• 0.2-dev Fix Version Verifier by @mkysel in #674

Full Changelog: v0.2.2...v0.2.3

v0.2.2

Full Changelog: v0.2.1...v0.2.2

Closed issues:

• API Metrics #569
• Indexer Metrics #568
• Sync Worker Metrics #567

Merged pull requests:

• Indexer metrics + indexer refactors #639 (mkysel)
• Fix prom metrics #648 (mkysel)
• Use retry library #641 (mkysel)
• More sync metrics #634 (mkysel)
• Print registrant in expected form #613 (mkysel)