Lattice is an open-source public good. Contributions are welcome: new modules, bug fixes, tests and documentation.
This file is the human summary. AGENTS.md is the canonical project guide, and where the two differ, AGENTS.md wins. SECURITY.md covers vulnerability reports: never file them as public issues.
git clone https://github.com/dadadave80/lattice.git
cd lattice
make install # git submodule update --init --recursive (diamond-lib, forge-std, ...)
make build
make testmake help lists every target. test/README.md explains the test layout, naming and the
recipe-built test setup.
- Base every PR on
dev. GitHub's default branch ismain, which is the release branch. Only release promotions target it. See AGENTS.md: Git workflow. - Branch names are descriptive and conventional:
feat/...,fix/...,docs/...,test/...,ci/.... - Commit subjects and the PR title use Conventional Commits.
Release Please builds the changelog from these types (see
release-please-config.json):
feat,fix,perf,refactoranddocsare listed;test,build,ciandchoreare hidden. A subject in any other form is left out of the changelog. Add a scope where it helps (fix(crosschain): ...). - Breaking changes use
!after the type or scope and aBREAKING CHANGE:footer saying what integrators must change:fix(vaults)!: .... A changed interfaceId, ABI or storage layout counts. - PRs into
devare squash-merged. The PR title becomes the commit subject and the PR body its message, so the PR title is the changelog line. A merge commit would repeat the title next to the branch's own commits and list the change twice. End a breaking PR's body with itsBREAKING CHANGE:footer. Release promotions and back-merges betweendevandmainuse merge commits. - Sign your commits. The branch rulesets require signed commits, so an unverified commit cannot land.
- Keep each PR to one concern, and say in the description what changed, why, and how you validated it. The PR template has the sections and the steps most often missed.
- Name each completed issue on its own
Closes #Nline in the PR body, and useRefs #Nfor partial work.
Modules follow a three-layer pattern. The full rules are in AGENTS.md: Solidity architecture and storage, and the reasons behind them are in the architecture decision records.
- Interface (
src/interfaces/<area>/I<Module>.sol): ABI, errors and events. - Library (
src/<area>/libraries/<Module>Lib.sol): all logic, storage through one ERC-7201 namespace,registerInterface()and__<Module>_init. - Facet (
src/<area>/<Module>.sol): thin and stateless. It forwards to the library and exports its selectors (ERC-8153exportSelectors()).
Storage policy, as AGENTS.md states it:
- State lives in the diamond, never in a facet. Every module gets a unique, precomputed ERC-7201 namespace and ERC-165 map slot, recorded in STORAGE_REGISTRY.md.
- An upgrade that keeps existing state needs a compatible layout (normally append-only) or a designed and tested migration. Reordering, removing or retyping a field must never silently corrupt a live instance.
- Before the first major release, a necessary layout change is allowed for a fresh deployment. Say that a fresh deployment is required, update the baseline and the consumers, and do not present the change as safe for an existing deployment.
- A namespace or interfaceId is frozen once it is live on any network, including a downstream project's deployment. From then on a layout change is append-only or a tested migration, as AGENTS.md states.
make storage-check compares every @custom:storage-location erc7201: struct in src/ against the
committed baseline. The struct list is derived from those annotations, so a new struct is checked
automatically. It must also be imported into
script/upgrades/StorageLayoutProbe.sol and declared there as a
state variable (the checker rejects a copy of the struct by its compiler AST id), and its library must
hold the namespace's slot as a literal, or the check fails. After an intended layout change, run
make storage-update and review the baseline diff.
On a pull request, CI also requires the layout to be an append-only extension of the baseline at the PR
base, so a regenerated baseline cannot hide a reorder, retype, removal or nested change; run
make storage-check BASE_REF=origin/dev to check this locally. A layout change for a fresh deployment of a
module that is live nowhere needs the reset line the failure prints, added to
script/upgrades/storage-layout.resets in the same pull request and reviewed with the change. A line that
matches the base but waives nothing fails the check. The line names the old layout, so later pull requests
into dev only note that it has no effect; keep it until the dev → main release pull request that
carries the change has merged (that pull request compares with main, which still holds the old layout),
then delete it. Never reset a live namespace. The
storage-safety Action README describes the rules.
Two conventions have exact forms in AGENTS.md: the
external-source attribution line and the
registerInterface standard.
Run make ci. It runs CI's Solidity gates, in CI's order:
| Target | Gate |
|---|---|
make fmt-check |
forge fmt --check |
make sizes |
EIP-170 size limit under FOUNDRY_PROFILE=ci |
make via-ir |
IR-pipeline build |
make storage-check |
ERC-7201 storage-layout baseline |
make test-ci |
full test suite under FOUNDRY_PROFILE=ci |
make snapshot-check |
gas snapshots in snapshots/ match the committed files (make snapshot regenerates them) |
CI also runs checks that make ci leaves out:
- a size gate under via-ir (
make via-ironly compiles); - Slither (
make slither), which fails on any High result that is not suppressed or triaged. Confirm a new one is a false positive first. Suppress a statement-level result with// slither-disable-next-line <detector> <reason>directly above the flagged line: a triaged id embeds that line's numbers, so it would resurface whenever the file shifts. Triage function-level results, and results in files that must stay byte-exact, withmake slither-triage, then give each newslither.db.jsonentry a one-linereason; - Anvil deploy checks:
make test-grant-runner,make example-ens-grant-m2 LOCAL=1andmake check-atomic-deploy. The last one fails if any file inscript/callsnew Latticeor a separateinitialize. To run them, startmake anvilin one shell, then run them in another.
Fork suites (test/fork/) need RPC URLs and skip their lanes cleanly without them. They pin historical
blocks, so use archive endpoints (see .env.example); the Scheduled workflow runs them weekly against
archive secrets. Add a new fork suite to its lane in script/fork-lanes.sh, or make scripts-check
fails; ./script/fork-lanes.sh run <lane> runs one lane the way the workflow does. Say in the PR which lanes you ran. Behavior changes need regression tests through a real
diamond built from the module's recipe.
Optional, local only: make mutation runs the Gambit mutation pilot
on ERC4626Lib, StrategyManagerLib, AccessManagerLib, LatticeRegistry and LatticeFactory and reports
which mutants the tests miss. It needs gambit on your PATH, is not part of make ci or any workflow, and
takes one to two hours on a laptop (TARGETS= runs a subset). See
test/README.md for how it works and the pilot results.
Work through this list in order. The example is EmergencyStop (security area). Several of these steps
fail silently when missed, so do every one.
Source
-
Interface
src/interfaces/<area>/I<Module>.sol: functions, errors, events. Example:src/interfaces/security/IEmergencyStop.sol. -
Library
src/<area>/libraries/<Module>Lib.solwith:- the storage-slot constant (
EMERGENCY_STOP_STORAGE_SLOT) for namespacelattice.storage.<Module>.cast index-erc7201 lattice.storage.<Module>prints the value; - the struct with
/// @custom:storage-location erc7201:lattice.storage.<Module>on the line directly abovestruct <Module>Storage {. The storage guard pairs the two lines; ERC165_MAP_I<MODULE>_SLOTwith its@devderivation,registerInterface(), and__<Module>_init(), in the form theregisterInterfacestandard shows. Skip all three for a module with no storage to seed and an error-only interface (interfaceId0x00000000).
Do not copy
EMERGENCY_STOP_ERC165_STORAGE_LOCATIONfrom the example: it is an unused local copy of the ERC-165 storage root, which the standard forbids.CCTPBridgeAdapterLibshows the correct form.A module with no state (for example
HederaPrngAdapter) has no slot constant or struct. It skips the storage-slot test, the probe import andmake storage-update, but still needs the ERC-165 map slot, its slot test and a registry row. - the storage-slot constant (
-
Facet
src/<area>/<Module>.sol: one-line forwards to the library, plusexportSelectors()returning the packed selectors fromforge inspect <Module> methodIdentifiers, in that order, withoutexportSelectors()itself (0x0ef22643). Add@custom:lattice-versionset to the release that first ships the facet, and@custom:lattice-sourceset toLattice originalor, for ported code, the upstream and its version (OpenZeppelin v5.6.1). #200 may replace the version tag. -
NatSpec:
@authoron each new file, plus the attribution line if the code is ported or adapted. -
Init: compose
__<Module>_initin the recipe's local<Module>RecipeInit(EmergencyStop does). Add a standalonesrc/<area>/<Module>Init.solonly when other recipes need it (for exampleChainlinkAdapterInit).
Registration
- Release inventory
script/lib/FacetInventory.sol: add the name and the"<file>:<Name>"path at the same index, then raise the count everywhere it appears (string[N]twice,new string[](N)twice, the loop bound and the@notice). Update the count thattest/unit/DeployReleaseTest.t.solpins ("inventory count drifted") to match. An entry here is what ships the facet and puts it under the parity gate. Prove it:make test MATCH=ExportSelectorsParityTestandmake test MATCH=DeployReleaseTest. - Slot test
test/unit/StorageSlotVerificationTest.t.sol: import both constants, addtest_<Module>StorageSlotandtest_Erc165MapI<Module>Slot, append both constants to_allStorageSlots()and_allErc165MapSlots(), and raise those arrays' sizes. A failing assertion prints the expected value, which is also how to check a new map-slot constant. Prove it:make test MATCH=StorageSlotVerificationTest. - Storage guard
script/upgrades/StorageLayoutProbe.sol: import<Module>Storageand declare it as a state variable. Thenmake storage-update, check the baseline diff only adds your section, andmake storage-check. - Registry STORAGE_REGISTRY.md: add the module's row (namespace, storage slot, interface, interfaceId, ERC-165 map slot).
Recipe and tests
- Recipe
script/base/<area>/Deploy<Module>.s.sol:buildCuts(...)returns the cuts and init, andrun(...)deploys with_assemble. Nevernew Latticeor a separateinitializecall inscript/. Example:script/base/security/DeployEmergencyStop.s.sol. Prove it:make anvilin one shell, thenmake check-atomic-deploy. - Test base
test/base/<Module>TestBase.solbuilds the diamond frombuildCuts. Put test-only facets intest/helpers/. - Unit tests
test/unit/<Module>Test.t.sol, including an ERC-165 registration test through the diamond (test_ERC165RegisteredIEmergencyStop; most modules call ittest_SupportsInterface). Prove it:make test MATCH=<Module>Test. - Recipe guard: add
test_Upgradeable_<Module>to the matchingtest/composability/RecipeUpgradeability<Group>Test.t.sol. Nothing enforces one guard per recipe, so only this list catches a missing one. - Docs: add the module to the README Modules table, backticked (
make readme-checkfails without it), and thesrc/layout comment. - Gates:
make fmt(it also sorts imports), thenmake ci.