XMTP Contracts

• Repository layout
• Usage
  • Prerequisites
  • Initialize project
• Developer tools
• Developer documentation

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

This repository contains all the smart contracts that underpin the XMTP decentralized network.

Repository layout

Path	Contents	Deep entry point
src/	Solidity sources — settlement-chain, app-chain, any-chain	src/settlement-chain/README.md
script/	Foundry scripts driving deployments, upgrades, parameters, admin	—
test/	Foundry tests	—
doc/	Protocol documentation (architecture, contracts, actors)	doc/README.md
doc/runbooks/	Operator runbooks — upgrades, deployments, parameters, admin	doc/runbooks/README.md
config/, environments/	Per-environment JSON configs and deployment manifests	—
dev/	Shell helpers for greenfield environment rollout	doc/deployment.md

Usage

The project is built with the Foundry framework, and dependency management is handled using native git submodules.

Additionally, it uses slither for static analysis.

Prerequisites

Install foundry

Install slither

Install node

Install prettier

Optionally, install yarn or any other preferred JS package manager.

Initialize project

Initialize the project dependencies:

yarn install # if using yarn

Initialize foundry:

forge update

Developer tools

The following can be run using npm, yarn and similar JS package managers.

# Forge scripts
build:          Builds the contracts.
test:           Tests the contracts.
clean:          Cleans the forge environment.
coverage:       Shows the test coverage.
gas-report:     Shows the gas costs.
doc:            Serves the project documentation at http://localhost:4000

# Static analysis
slither:        Runs slither static analysis.

# Linters
solhint:        Runs solhint.
solhint-fix:    Runs solhint in fix mode, potentially modifying files.
lint-staged:    Runs linters only on files that are staged in git.

# Formatters
prettier:       Runs prettier in write mode, potentially modifying files.
prettier-check: Runs prettier in check mode.

Developer documentation

The Foundry book can be found hosted on the contracts documentation page.

To dive deeper into the protocol and its architecture, read the documentation index. For step-by-step day-two operations (upgrades, single-contract deployments, parameters, admin), go straight to the operator runbooks.