xmtp/smart-contracts

<explanation>

Below is a step‑by‑step guide tailored to the XMTP Contracts project. Follow these instructions to produce a clear, comprehensive system design diagram that captures all the essential architecture and workflows.

1. Identify the Project Type and Purpose

- XMTP Contracts is a Solidity smart‑contract repository for a decentralized messaging network.

- It uses the Foundry framework to compile, test, and deploy on EVM‑compatible chains.

- Core functionality: GroupMessageBroadcaster, IdentityUpdateBroadcaster, NodeRegistry, RateRegistry contracts.

2. Analyze the File Structure

- src/: Solidity contracts (core business logic).

- src/interfaces/: Contract interface definitions.

- test/: Forge/Foundry unit tests.

- artifacts/: Compiled bytecode and ABIs.

- deployments/: JSON deployment manifests for each network (playground, staging, testnet).

- lib/ (git submodules): Third‑party libraries (OpenZeppelin, Solady, erc20‑helper).

- dev/: Dockerfile and helper scripts for local dev (Anvil snapshots, env templates).

- script/: Forge scripts for upgrades and utility tasks.

- .github/: CI workflows (build, test, release).

3. Examine the README for Additional Insights

- Confirms Foundry is the build/test framework.

- Describes developer toolchain: forge, slither, solhint, prettier, Node.js for scripting.

- Lists environment variables for deployment scripts.

4. Main Components to Show in the Diagram

a. Developer Environment

• Local machine with Foundry, Node.js, Docker (Anvil)

• Git (with submodules)

b. Build & Test

• Foundry compiler → artifacts (bytecode, ABI)

• Forge tests → test reports, coverage

• Static analysis (Slither, Solhint)

c. Smart Contracts (On‑Chain)

• GroupMessageBroadcaster

• IdentityUpdateBroadcaster

• NodeRegistry

• RateRegistry

• (Optionally: upgradeable proxies via OZ)

d. Deployment Targets

• Local (Anvil)

• Testnet‑Playground

• Testnet‑Staging

• Testnet

• Each with its own JSON manifest under /deployments

e. External Services

• EVM node providers (e.g. Infura, Alchemy)

• Notion‑based documentation (off‑chain reference)

5. Relationships and Data Flows

- Developer → Forge build → artifacts

- Artifacts + env vars → Forge deploy scripts → EVM node → on‑chain contracts

- Contracts interact on‑chain:

• NodeRegistry tracks network participants

• RateRegistry governs messaging rates

• Broadcasters emit events for group messages & identity updates

- Tests run against local Anvil chain; coverage/gas reports feed back to developer.

6. Architectural Patterns & Principles

- Modular contract design: each contract has a single responsibility.

- Upgradeable pattern: usage of OpenZeppelin upgradeable libraries (via lib/oz‑upgradeable).

- Git submodules for dependency management (ensures reproducible builds).

- Separation of concerns: build, test, deploy, and analysis tools clearly isolated.

7. Technologies & Libraries

- Foundry (forge, anvil)

- Solidity v0.8.x

- OpenZeppelin (upgradeable contracts)

- Solady (gas‑optimized utilities)

- Slither & Solhint for static analysis

- Node.js & npm/yarn for scripting

- Docker (optional for dev environment)

8. Guidelines for Tailoring Your Diagram

- Use separate swimlanes or zones for: Developer Toolchain, Build/Test Pipeline, On‑Chain Contracts, Deployment Targets.

- For each contract, show its ABI & bytecode as build outputs.

- Group the four main contracts together, illustrating inter‑contract calls or shared state as arrows.

- Illustrate upgradeable proxies if used (Proxy → Logic).

- Show Git submodules feeding into the compile step.

9. Diagram Elements to Include

- Clear labels: e.g., “Forge Compile,” “GroupMessageBroadcaster Contract,” “Testnet‑Staging.”

- Directional arrows:

• Rightward for build → deploy → on‑chain

• Circular arrows for test cycles (test → fix → retest)

- Color coding/shapes:

• Blue rectangles for off‑chain components (Developer, Build tools)

• Green cylinders for on‑chain contracts

• Gray parallelograms for artifacts (ABI/bytecode, JSON manifests)

• Dashed ellipses for external services (EVM node, Notion docs)

10. Final Tips

- Be as granular as possible: list individual scripts (e.g., script/upgrades/…) if they play distinct roles.

- Capture environment configs under dev/ and deployments/ to show how different networks are targeted.

- Don’t overthink: a clear division into “Repo → Build → Deploy → Chain” plus the four core contracts will cover the essentials.

By following these steps and incorporating the components and relationships outlined above, you will produce a detailed, accurate architecture diagram for XMTP Contracts, tailored for both on‑chain deployment flows and the local developer experience.

</explanation>