layerzero-labs/layerzero-v2

1. What this repo is

LayerZero V2 is a multi-chain protocol monorepo. The architecture is not one application, but several chain-specific implementations of the same cross-chain messaging system: protocol core, message libraries, worker/verifier components, and example OApp/OFT application layers.

2. Primary architectural pattern

The core flow is consistent across chains:

sender app → endpoint/protocol contract → message library → fee quoting → verification network (DVN) + executor → destination endpoint → app callback/compose handling.

The repo is organized around these boundaries rather than around one shared runtime.

3. Move-based chain families

The aptos, initia, iota, and sui trees are parallel Move implementations. They all contain the same conceptual subsystems:

- endpoint-v2 / endpoint_v2: the protocol entrypoint and packet lifecycle

- message-libs / msglib: library selection and verification logic

- workers: DVN/executor identities, hashes, fee logic, and registry

- oapps: OApp/OFT application code

- ptb-builders: transaction-building helpers for chains that require structured transaction construction

- utils / endpoint_v2_common: shared codecs, packet types, and config types

4. Move protocol boundary

In the Move chains, the endpoint is the on-chain control plane. It maintains channel state, message receipts, registration, timeouts, and message composer state through internal modules. The message library layer is the policy/transport abstraction that decides how packets are quoted, verified, and delivered.

5. Move worker subsystem

The workers and worker_peripherals packages model the off-chain actors on-chain:

- DVN modules and fee libs for verification pricing and signatures

- Executor modules and fee libs for delivery pricing and execution options

- worker registry / worker-common / multisig stores for authorization and metadata

- price feed modules/routers for dynamic fee conversion

These are separate from the endpoint so verification and execution policy can be swapped or extended.

6. Move application layer

The oapps and oft_common packages are the app-facing surface. OApp handles generic cross-chain messages and peer/enforced-option configuration; OFT adds token-transfer-specific codecs, limits, fees, and compose-message logic. layerzero_views exposes read-only helpers over endpoint and ULN state.

7. EVM implementation

The evm folder mirrors the same architecture in Solidity. It splits into:

- protocol: immutable endpoint/protocol contracts and shared libs

- messagelib: ULN implementations, DVN adapters, read libs, upgradeable proxy support

- oapp: application standards and OFT/precrime helpers

The EVM side includes Foundry-based test suites and an upgradeable boundary, which is a material difference from the Move deployments.

8. Solana implementation

The Solana subtree is Anchor/Rust-based and is the most explicit runtime split:

- programs/endpoint, programs/uln, programs/simple-messagelib, programs/executor, programs/pricefeed, programs/oft

- libs/* shared CPI/codec helpers

- worker-interface for worker interaction contracts

The Solana architecture separates state accounts, instruction handlers, and codec helpers, with build.rs and Anchor/Xargo tooling driving compilation.

9. TON implementation

The TON tree uses FunC and a more granular contract layout:

- protocol/endpoint, protocol/msglibs, protocol/msglibs/ultralightnode

- workers/* for DVN, executor, proxy, and price feed cache

- apps/* for OApp-style application contracts

- multisig, jettons/zro, and funC++ support libraries

TON’s architecture is heavily message-based, with explicit handler/interface/storage separation in each contract package.

10. Cross-chain codecs and type packages

A major shared concern is serialization. Every chain has dedicated packet/message codecs and type packages for:

- packet v1 encoding/decoding

- messaging fees and receipts

- worker options and config types

- endpoint/send/receive/quote call payloads

This is important for diagramming because most subsystem boundaries are enforced by codec layers, not by direct object sharing.

11. Testing and verification strategy

The repo is test-heavy and organizes tests next to each package, often mirroring production module names. There are also chain-specific harnesses:

- run_tests.sh for Move packages

- Foundry tests for EVM

- Anchor/Rust tests for Solana

- TS/Jest and FunC test scaffolding for TON

This suggests each chain package is independently buildable and testable, not a single centralized build graph.

12. Tooling and repo orchestration

Root-level yarn, .yarnrc.yml, and GitHub Actions indicate a workspace-level orchestration layer, but the actual contract ecosystems use their native toolchains: Move, Foundry, Anchor/Rust, and TON FunC. .gitmodules and lib/forge-std support external testing dependencies.

13. How to draw the diagram

A good architecture diagram should show:

- separate chain runtimes as first-class vertical lanes

- within each lane: endpoint/protocol, message library, workers, and app layer

- shared horizontal concerns: codecs, fee config, verification, and tests

- arrows from OApp/OFT to endpoint, then to message lib, then to DVN/executor, and back to destination receive/compose handlers

The key is that LayerZero V2 is a replicated protocol architecture across chains, not a single deployed system.