How analog-labs/analog-gmp works
1. Repository purpose
- This is a Solidity smart contract repository for Analog’s cross-chain messaging stack, centered on the Analog General Message Passing (GMP) protocol.
- The repo is organized as a Foundry project, so the primary runtime is the EVM and the main build/test loop is forge.
2. Top-level contract package
- The root src/ directory is the main onchain contract code for the protocol.
- The presence of src/storage/ suggests the contracts separate state layout / storage definitions from higher-level protocol logic, which is important for upgradeable or tightly structured Solidity systems.
3. GMP subproject
- The gmp/ directory is a second Foundry package with its own foundry.toml and README.md.
- Architecturally, this looks like a nested module or companion package for the General Message Passing components, likely used to isolate reusable protocol contracts, interfaces, or examples from the root package.
4. Testing boundary
- The test/ directory contains the Solidity tests for the contracts.
- The CI workflow in .github/workflows/test.yml indicates the expected verification path is to compile and run Foundry tests on every change, so test coverage is a first-class part of the repo architecture.
5. Storage as a distinct concern
- src/storage/ is a clear boundary between persistent contract state and business logic.
- That usually means the project is designed to keep storage schemas explicit and stable, which matters in protocol contracts where layout compatibility is critical.
6. Build and developer tooling
- foundry.toml at the root and inside gmp/ define separate build configurations, showing the repository supports more than one Solidity package boundary.
- remappings.txt and soldeer.lock point to dependency management and import mapping as part of the project’s compilation model.
7. Gas analysis workflow
- plot_gas.py and forge snapshot in the README show the repo includes gas regression tracking.
- This matters architecturally because contract changes are likely evaluated not just for correctness but also for execution cost.
8. Documentation pipeline
- The repo can generate docs with forge doc -b, and the README references mdbook for browsing them.
- That implies the codebase is intended to be navigated as a protocol library, not just deployed contracts, with generated contract docs serving as a companion artifact.
9. CI / quality gate
- .github/workflows/test.yml is the main automated gate visible in the tree.
- The workflow likely mirrors local developer commands: build, test, and possibly formatting or snapshot checks.
10. External integration context
- The only external system implied by the repo structure is the Analog GMP protocol itself, which is the cross-chain messaging layer these contracts target.
- There are no signs of a frontend, API server, or offchain microservice architecture in this repository; the focus is on onchain protocol contracts and their verification tooling.
11. How the pieces fit together
- Source contracts in src/ define the protocol behavior and storage.
- The gmp/ package holds related GMP-specific artifacts.
- Tests in test/ validate behavior.
- Foundry and CI handle compilation, regression checks, and packaging of documentation.
12. Architecture summary for a diagram
- Draw this repo as a Solidity protocol workspace with two contract packages (root and gmp), a dedicated storage layer, a test/CI lane, and a gas-analysis/doc generation toolchain around the core contract code.
Main entry points: src Protocol logic · gmp GMP package · test Tests · foundry.toml Foundry config
Components 14
Protocol
Onchain Solidity contract packages and state layout
- Root package · Main Solidity workspace for the GMP protocol
- Protocol logic · Primary contract behavior in the root src tree
src - Storage layout · Explicit persistent storage definitions separated from logic
src/storage - GMP package · Secondary Foundry package for GMP-related contracts and artifacts
gmp - GMP contracts · GMP-specific source code in the nested package
gmp/src
Verification
Tests, CI, and gas regression checks
- Tests · Solidity test suite for contract behavior
test - CI workflow · Automated build and test gate
.github/workflows/test.yml - Gas profile · Gas snapshot and regression tracking via Python/Forge
plot_gas.py
Tooling
Build, dependency, and documentation support
- Foundry config · Root Foundry project configuration
foundry.toml - GMP config · Separate Foundry configuration for the nested GMP package
gmp/foundry.toml - Remappings · Solidity import resolution rules
remappings.txt - Dependencies · Pinned package resolution state for Solidity dependencies
soldeer.lock - Protocol docs · Repository usage, build, and documentation entry point
README.md - GMP docs · Package-specific documentation for the nested GMP module
gmp/README.md
Connections 16
- Root package → Protocol logic: contains · Root workspace houses the main contract implementation
- Protocol logic → Storage layout: uses · Protocol behavior reads and writes explicit storage definitions
- Root package → GMP package: includes · Repository contains a nested GMP-focused Foundry package
- GMP package → GMP contracts: contains · Nested package holds GMP-specific source code
- Foundry config → Root package: builds · Root Foundry config drives compilation of the main package
- GMP config → GMP package: builds · Nested Foundry config drives compilation of the GMP package
- Remappings → Root package: supports · Import mappings help resolve Solidity references
- Dependencies → Root package: pins · Dependency lockfile stabilizes builds for the root workspace
- Tests → Protocol logic: verifies · Forge tests exercise the main protocol contracts
- Tests → GMP contracts: verifies · Tests also cover GMP-specific behavior
- CI workflow → Tests: runs · CI executes the test suite on changes
- CI workflow → Foundry config: uses · Workflow relies on Foundry compilation and test commands
- Gas profile → Protocol logic: measures · Gas snapshots track protocol execution cost
- Protocol docs → Foundry config: documents · Repository guide explains the main Foundry workflow
- Protocol docs → Gas profile: documents · README references gas regression checks and snapshots
- GMP docs → GMP package: documents · Nested README explains the GMP subpackage