# layerzero-labs/layerzero-v2 architecture

> Architecture diagram of the GitHub repository layerzero-labs/layerzero-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/layerzero-labs/layerzero-v2
- Repository: https://github.com/layerzero-labs/layerzero-v2

## Overview

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.

Main entry points: [`packages/layerzero-v2/aptos/contracts`](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts) (Aptos), [`packages/layerzero-v2/solana`](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana) (Solana), [`packages/layerzero-v2/ton/src`](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src) (TON), [`packages/layerzero-v2/initia/contracts`](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/initia/contracts) (Initia)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared"]
  node_root["LayerZero V2<br/>monorepo"]
end

subgraph group_move["Move chains"]
  node_aptos["Aptos<br/>move runtime"]
  node_initia["Initia<br/>move runtime"]
  node_iota["Iota<br/>move runtime"]
  node_sui["Sui<br/>move runtime"]
  node_endpoint_move["Endpoint<br/>move protocol"]
  node_msglib_move["Msglib<br/>move transport"]
  node_workers_move["Workers"]
  node_oapps_move["OApps<br/>move apps"]
  node_codecs_move["Codecs<br/>move types"]
end

subgraph group_evm["EVM"]
  node_evm_root["EVM<br/>solidity runtime"]
  node_endpoint_evm["Endpoint<br/>solidity protocol"]
  node_msglib_evm["Msglib<br/>solidity ULN"]
  node_oapp_evm["OApp<br/>solidity apps"]
end

subgraph group_solana["Solana"]
  node_solana_root["Solana<br/>anchor runtime"]
  node_solana_endpoint["Endpoint<br/>anchor program"]
  node_solana_uln["ULN<br/>anchor program"]
  node_solana_executor["Executor<br/>anchor program"]
  node_solana_pricefeed["Price Feed<br/>anchor program"]
  node_solana_oft["OFT<br/>anchor program"]
end

subgraph group_ton["TON"]
  node_ton_root["TON<br/>func runtime"]
  node_ton_endpoint["Endpoint<br/>func protocol"]
  node_ton_msglibs["Msglibs<br/>func transport"]
  node_ton_workers["Workers"]
  node_ton_apps["Apps"]
  node_ton_codecs["Codecs<br/>func types"]
end

node_root -->|"Move lane"| node_aptos
node_root -->|"Move lane"| node_initia
node_root -->|"Move lane"| node_iota
node_root -->|"Move lane"| node_sui
node_root -->|"EVM lane"| node_evm_root
node_root -->|"Solana lane"| node_solana_root
node_root -->|"TON lane"| node_ton_root
node_aptos -->|"endpoint"| node_endpoint_move
node_aptos -->|"message libs"| node_msglib_move
node_aptos -->|"workers"| node_workers_move
node_aptos -->|"apps"| node_oapps_move
node_aptos -.->|"types"| node_codecs_move
node_initia -->|"endpoint"| node_endpoint_move
node_initia -->|"message libs"| node_msglib_move
node_initia -->|"workers"| node_workers_move
node_initia -->|"apps"| node_oapps_move
node_iota -.->|"shared utils"| node_codecs_move
node_iota -->|"workers"| node_workers_move
node_sui -.->|"shared utils"| node_codecs_move
node_sui -->|"workers"| node_workers_move
node_evm_root -->|"protocol"| node_endpoint_evm
node_evm_root -->|"messagelib"| node_msglib_evm
node_evm_root -->|"oapp"| node_oapp_evm
node_endpoint_evm -->|"select lib"| node_msglib_evm
node_msglib_evm -.->|"deliver"| node_oapp_evm
node_solana_root -->|"endpoint"| node_solana_endpoint
node_solana_root -->|"uln"| node_solana_uln
node_solana_root -->|"executor"| node_solana_executor
node_solana_root -->|"pricing"| node_solana_pricefeed
node_solana_root -->|"oft"| node_solana_oft
node_solana_endpoint -->|"verify"| node_solana_uln
node_solana_endpoint -->|"execute"| node_solana_executor
node_solana_oft -->|"send/receive"| node_solana_endpoint
node_ton_root -->|"endpoint"| node_ton_endpoint
node_ton_root -->|"msglibs"| node_ton_msglibs
node_ton_root -->|"workers"| node_ton_workers
node_ton_root -->|"apps"| node_ton_apps
node_ton_root -.->|"codecs"| node_ton_codecs
node_ton_apps -->|"send/receive"| node_ton_endpoint
node_ton_endpoint -->|"route"| node_ton_msglibs
node_ton_msglibs -->|"fee/verify"| node_ton_workers

click node_aptos "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts"
click node_initia "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/initia/contracts"
click node_iota "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/iota/contracts"
click node_sui "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/sui/contracts"
click node_evm_root "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm"
click node_solana_root "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana"
click node_ton_root "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src"
click node_endpoint_move "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/endpoint_v2"
click node_msglib_move "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/msglib"
click node_workers_move "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/workers"
click node_oapps_move "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/oapps"
click node_codecs_move "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/endpoint_v2_common"
click node_endpoint_evm "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/protocol"
click node_msglib_evm "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/messagelib"
click node_oapp_evm "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/oapp"
click node_solana_endpoint "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/endpoint"
click node_solana_uln "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/uln"
click node_solana_executor "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/executor"
click node_solana_pricefeed "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/pricefeed"
click node_solana_oft "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/oft"
click node_ton_endpoint "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/protocol/endpoint"
click node_ton_msglibs "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/protocol/msglibs"
click node_ton_workers "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/workers"
click node_ton_apps "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/apps"
click node_ton_codecs "https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/classes"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root toneBlue
class node_aptos,node_initia,node_iota,node_sui,node_endpoint_move,node_msglib_move,node_workers_move,node_oapps_move,node_codecs_move toneAmber
class node_evm_root,node_endpoint_evm,node_msglib_evm,node_oapp_evm toneMint
class node_solana_root,node_solana_endpoint,node_solana_uln,node_solana_executor,node_solana_pricefeed,node_solana_oft toneRose
class node_ton_root,node_ton_endpoint,node_ton_msglibs,node_ton_workers,node_ton_apps,node_ton_codecs toneIndigo
```

## Components

### Shared

Cross-chain concerns shared by all runtimes

- **LayerZero V2**: monorepo · Multi-chain protocol monorepo with replicated endpoint, message library, worker, and app layers

### Move chains

Parallel Move implementations across Aptos, Initia, Iota, and Sui

- [Aptos](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts): move runtime · Move implementation of endpoint, message libraries, workers, and apps · `packages/layerzero-v2/aptos/contracts`
- [Initia](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/initia/contracts): move runtime · Parallel Move implementation mirroring the Aptos layout · `packages/layerzero-v2/initia/contracts`
- [Iota](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/iota/contracts): move runtime · Move implementation with PTB builders and explicit worker call types · `packages/layerzero-v2/iota/contracts`
- [Sui](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/sui/contracts): move runtime · Move implementation with PTB builders and worker subsystems · `packages/layerzero-v2/sui/contracts`
- [Endpoint](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/endpoint_v2): move protocol · On-chain control plane for channels, registration, receipts, timeouts, and composer state · `packages/layerzero-v2/aptos/contracts/endpoint_v2`
- [Msglib](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/msglib): move transport · Message library layer for quoting, configuration, verification, and delivery selection · `packages/layerzero-v2/aptos/contracts/msglib`
- [Workers](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/workers): move workers · DVN, executor, fee libraries, price feeds, and worker metadata infrastructure · `packages/layerzero-v2/aptos/contracts/workers`
- [OApps](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/oapps): move apps · App-facing OApp and OFT contracts built on endpoint and message libraries · `packages/layerzero-v2/aptos/contracts/oapps`
- [Codecs](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/aptos/contracts/endpoint_v2_common): move types · Shared packet, fee, receipt, and worker option types used across Move packages · `packages/layerzero-v2/aptos/contracts/endpoint_v2_common`

### EVM

Solidity implementation and standards

- [EVM](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm): solidity runtime · Solidity protocol, message library, and OApp standards · `packages/layerzero-v2/evm`
- [Endpoint](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/protocol): solidity protocol · Immutable endpoint and protocol contracts for send, quote, receive, and config flows · `packages/layerzero-v2/evm/protocol`
- [Msglib](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/messagelib): solidity ULN · ULN message library implementations, DVN adapters, read libs, and upgradeable support · `packages/layerzero-v2/evm/messagelib`
- [OApp](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/evm/oapp): solidity apps · Application standards including OApp, OFT, and precrime helpers · `packages/layerzero-v2/evm/oapp`

### Solana

Anchor/Rust programs and helper crates

- [Solana](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana): anchor runtime · Anchor/Rust programs for endpoint, ULN, executor, price feed, and OFT · `packages/layerzero-v2/solana`
- [Endpoint](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/endpoint): anchor program · Endpoint program handling send, quote, verify, and OApp configuration instructions · `packages/layerzero-v2/solana/programs/programs/endpoint`
- [ULN](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/uln): anchor program · ULN program for message verification, confirmations, and endpoint-linked send flows · `packages/layerzero-v2/solana/programs/programs/uln`
- [Executor](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/executor): anchor program · Executor program for quoting and executing delivered messages · `packages/layerzero-v2/solana/programs/programs/executor`
- [Price Feed](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/pricefeed): anchor program · Price feed program that prices worker fees for message delivery · `packages/layerzero-v2/solana/programs/programs/pricefeed`
- [OFT](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/solana/programs/programs/oft): anchor program · Token transfer application program built on the endpoint · `packages/layerzero-v2/solana/programs/programs/oft`

### TON

FunC-based protocol, worker, and app contracts

- [TON](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src): func runtime · FunC contracts for endpoint, ULN, workers, apps, and supporting codecs · `packages/layerzero-v2/ton/src`
- [Endpoint](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/protocol/endpoint): func protocol · TON endpoint contract split into handler, interface, storage, and tests · `packages/layerzero-v2/ton/src/protocol/endpoint`
- [Msglibs](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/protocol/msglibs): func transport · TON message library layer including simple msglib and ULN variants · `packages/layerzero-v2/ton/src/protocol/msglibs`
- [Workers](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/workers): func workers · TON DVN, executor, proxy, price feed cache, and worker fee libraries · `packages/layerzero-v2/ton/src/workers`
- [Apps](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/apps): func apps · TON application contracts such as base OApp and counter example · `packages/layerzero-v2/ton/src/apps`
- [Codecs](https://github.com/layerzero-labs/layerzero-v2/tree/main/packages/layerzero-v2/ton/src/classes): func types · TON shared message data, LZ classes, and serialization helpers · `packages/layerzero-v2/ton/src/classes`

## Connections

- LayerZero V2 → Aptos: Move lane · Workspace includes an Aptos Move implementation
- LayerZero V2 → Initia: Move lane · Workspace includes an Initia Move implementation
- LayerZero V2 → Iota: Move lane · Workspace includes an Iota Move implementation
- LayerZero V2 → Sui: Move lane · Workspace includes a Sui Move implementation
- LayerZero V2 → EVM: EVM lane · Workspace includes Solidity protocol packages
- LayerZero V2 → Solana: Solana lane · Workspace includes Anchor/Rust programs and libraries
- LayerZero V2 → TON: TON lane · Workspace includes FunC-based protocol packages
- Aptos → Endpoint: endpoint · Move runtime endpoint control plane
- Aptos → Msglib: message libs · Move runtime message library layer
- Aptos → Workers: workers · Move runtime DVN/executor and fee infrastructure
- Aptos → OApps: apps · Move runtime OApp/OFT surface
- Aptos → Codecs: types · Shared endpoint and packet codecs
- Initia → Endpoint: endpoint · Parallel Move endpoint implementation
- Initia → Msglib: message libs · Parallel Move message library layer
- Initia → Workers: workers · Parallel Move worker subsystem
- Initia → OApps: apps · Parallel Move application layer
- Iota → Codecs: shared utils · Iota relies on shared packet and option codecs
- Iota → Workers: workers · Iota mirrors worker pricing and verification concerns
- Sui → Codecs: shared utils · Sui relies on shared packet and option codecs
- Sui → Workers: workers · Sui mirrors worker pricing and verification concerns
- EVM → Endpoint: protocol · Solidity endpoint/protocol contracts
- EVM → Msglib: messagelib · Solidity ULN and adapter contracts
- EVM → OApp: oapp · Solidity application standards
- Endpoint → Msglib: select lib · Endpoint routes send/quote/receive through message libraries
- Msglib → OApp: deliver · Message library supports OApp delivery and compose handling
- Solana → Endpoint: endpoint · Endpoint program handles cross-chain send and receive
- Solana → ULN: uln · ULN program handles verification and confirmation state
- Solana → Executor: executor · Executor program handles delivery execution
- Solana → Price Feed: pricing · Price feed program computes worker fees
- Solana → OFT: oft · OFT program implements token transfer application behavior
- Endpoint → ULN: verify · Endpoint verification flows are backed by ULN
- Endpoint → Executor: execute · Endpoint delivery flows rely on executor handling
- OFT → Endpoint: send/receive · OFT uses endpoint CPI for messaging
- TON → Endpoint: endpoint · TON endpoint contract
- TON → Msglibs: msglibs · TON message library contracts
- TON → Workers: workers · TON worker contracts and fee libraries
- TON → Apps: apps · TON application contracts
- TON → Codecs: codecs · TON shared serialization and message data
- Apps → Endpoint: send/receive · Apps call into endpoint contracts
- Endpoint → Msglibs: route · Endpoint delegates through message libraries
- Msglibs → Workers: fee/verify · ULN and simple msglib flows invoke worker fee and verification logic