README.md

XMTP Network Smart Contracts — Documentation Hub

Central index for all protocol documentation, operator runbooks, and in-code references.

Table of Contents

• Protocol documentation
  • Core system understanding
  • Actor-specific guides
  • Implementation details
• Operator runbooks
  • Contract upgrades
  • Single-contract deployments
  • Parameter management
  • Node registry administration
• In-code documentation
• Quick navigation

Protocol documentation

Narrative docs that explain what the system is and why it works the way it does. Start here if you are new.

Core system understanding

Document	Description
System architecture	Start here. Dual-chain design, actors, economic model, cross-chain communication, and security model.
Contracts	All smart contracts: purpose, key components, deployment order, data flow, and design rationale.
Parameter registry	Every xmtp.* parameter key, cross-chain bridging flow (PlantUML + Mermaid), and type reference.

Actor-specific guides

Document	Description
Payers	How service providers fund the network: manual deposits, DepositSplitter, and Funding Portal.
Node operators	Node identification (NFT ID scheme), canonical network, onboarding, synchronization, and authentication.
Payer reports	Economic settlement end-to-end: report structure, EIP-712 signing, Merkle proofs, settlement, node payouts, and protocol fees.

Implementation details

Document	Description
Deployment	Greenfield environment rollout via ./dev/* shell helpers; links to Foundry runbooks for day-two operations.
Dependencies	Contract communication dependency diagram (Mermaid) and call-level breakdown per contract.
Proxies	Proxy, Factory, and Migration patterns — deterministic deploys, atomic initialization, and governance-friendly upgrades.

Operator runbooks

Step-by-step procedural guides live under doc/runbooks/. Each area has a top-level README.md and, where applicable, per-workflow variants for wallet (private key) and Fireblocks signing. The Foundry scripts they drive remain under script/.

Contract upgrades

Upgrade an existing proxy to a new implementation (same proxy address, new code).

Chain	Entry point	Wallet	Fireblocks
Settlement	runbooks/upgrades/settlement-chain/README.md	wallet.md	fireblocks.md
App chain	runbooks/upgrades/app-chain/README.md	wallet.md	fireblocks.md

For upgrades that also migrate storage, see the Custom migration guide.

Single-contract deployments

Deploy a new proxy + implementation pair for an individual contract (new address).

Guide	Description
runbooks/single-deployments/any-chain/README.md	Any-chain overview and prerequisites.
deploy-factory.md	Factory deployment via CREATE2.
runbooks/single-deployments/settlement-chain/README.md	Settlement-chain overview, three-step process, environment prerequisites.
deploy-node-registry.md	System invariant — requires human intervention. See the doc for breaking-change criteria.
deploy-payer-report-manager.md	PayerReportManager deployment and dependency updates.
deploy-distribution-manager.md	DistributionManager deployment and dependency updates.
deploy-deposit-splitter.md	DepositSplitter redeployment across testnet environments (non-upgradeable).

Parameter management

Set, read, and bridge xmtp.* parameters across chains.

Chain	Entry point
Settlement	runbooks/parameters/settlement-chain/README.md
App chain (bridging)	runbooks/parameters/app-chain/README.md

Node registry administration

Admin operations on the NodeRegistry contract (add nodes, manage canonical network, set base URI).

Guide	Description
runbooks/admin/settlement-chain/README.md	Overview and workflow selection.
wallet.md	Wallet signing commands.
fireblocks.md	Fireblocks signing commands.

In-code documentation

Location	Description
src/settlement-chain/README.md	Settlement chain contracts overview, interaction flow, and upgrade/migration mechanics.
CLAUDE.md	AI assistant guidance: build/test commands and code style guidelines.

Quick navigation

I want to...	Go to
Understand the system	System architecture
Integrate as a service provider	Payers
Run network infrastructure	Node operators
Understand the economics	Payer reports
Deploy a new environment from scratch	Deployment
Upgrade a live contract	Contract upgrades
Deploy a single new contract	Single-contract deployments
Change a parameter	Parameter management
Add or manage nodes	Node registry administration