Skip to main content
Leafage’s code is spread across five repositories, each of which can be developed and tested independently. This page helps you determine where a change belongs and how to get it running locally.

​
Repository map

​
Which repository a change belongs to

Before changing a cross-repository interface (Kafka messages, S3 keys, etcd keys, error codes), read the interface contracts. These formats are hard-coded in multiple repositories; a one-sided change silently breaks the data path.

​
Local development

​
Prerequisites

​
Build and test

The three Go repositories share the same Makefile targets:
leafage-evm:
Execution client forks keep the upstream build and CI entry points (make all and go run ./build/ci.go ... for go-ethereum); see their AGENTS.md for details.

​
Run a minimal setup

Most changes can be validated without connecting to production infrastructure. Use HTTP mode to connect the write node and the query node directly, skipping Kafka and S3:
See the quickstart for the full steps.

​
Commit conventions

​
Execution client forks

Follow the upstream go-ethereum conventions: commit messages use <package(s)>: description, and PR titles use the same format. The full pre-commit checklist is in the repository’s AGENTS.md. Two hard constraints: keep changes small and focused (no drive-by refactoring, no renaming of unrelated code), and do not add or remove dependencies casually. The fork has to track upstream releases over the long term, and unrelated changes amplify merge conflicts.

​
Other repositories

  • Cut feature branches from main and keep PRs small and focused
  • Run make ci locally before committing (or fmt + clippy + test for Rust)
  • New behavior needs tests; read the existing tests before changing a critical path, for example check/critical_path_test.go in consistency-checker

​
Context for AI agents

If you are assisting with these repositories from inside an agent, these entry points save the most time: A few pitfalls that are easy to hit:
  • Do not infer cross-component behavior from a single repository’s README. Some READMEs diverge from the implementation (S3 key format, method naming, license statements); the code is authoritative, and the interface contracts on this site have been checked against the code.
  • Read the tests before changing critical paths such as Process or OnCommit; they encode idempotency and retry semantics that are easy to miss by reading the implementation alone.
  • etcd key and S3 key construction is scattered across multiple repositories; when searching, locate it with fmt.Sprintf / format! plus a fragment of the key name.

​
Where to start contributing

Fill in missing configuration documentation in the component repositories, fix divergences between READMEs and the implementation, and add troubleshooting steps for common failures. These changes are low risk but highly valuable to users.
Fill in metrics missing along the path (for example S3 fetch failure rate, catch-up progress), or build Grafana dashboards for existing metrics. The data path is long, and a missing metric at any link makes troubleshooting harder.
Adding an EvmExecutor on the read side is a clearly bounded change with limited impact; follow the existing implementations in leafage-evm-chains. See Adding a new chain.
The storage layer and execution hot path of leafage-evm have a clear way to be measured: use leafage-bench to compare the eth_call latency distribution before and after a change.

​
Maintaining this documentation site

This site is built on Mintlify; the content is MDX and the navigation lives in docs.json.
GitHub Actions runs the same set of checks automatically on pull requests. New pages must also be added to the groups of the matching language under navigation.languages in docs.json (cn for Chinese, en for English), otherwise they will not appear in the sidebar. Chinese and English pages correspond one to one (English lives under en/); update both when you change either. See the repository’s AGENTS.md and README.md for writing conventions.