AGENTS.md

Framework for LayerZero Developer Documentation

---

1. Purpose and Philosophy

LayerZero documentation serves smart contract engineers building omnichain applications. Every page exists to accelerate their journey from concept to production deployment across multiple blockchain networks.

Core Mission

Get developers from zero to production as quickly and safely as possible, while maintaining flexibility across different blockchain virtual machines (EVM, Solana, Aptos Move).

Documentation Layers

• Conceptual: Understanding LayerZero architecture and design principles
• Implementation: Platform-specific guides for each blockchain VM
• Reference: Technical specifications, APIs, and deployment addresses
• Operational: Tools, monitoring, and troubleshooting

Source Code References

This documentation is based on the official LayerZero source code available at:

• LayerZero DevTools: Contains all contract standards (OApp, OFT, ONFT), examples, CLI tools, and developer utilities
• LayerZero V2 Protocol: Core protocol contracts including Endpoints, Message Libraries, DVNs, and Executors

When updating documentation:

• Verify code examples against the latest versions in these repositories
• Ensure import paths match the package structure in devtools
• Check for new features or breaking changes in recent commits
• Reference specific contract files when documenting technical details

---

2. Documentation Structure

2.1 Directory Organization

docs/
├── home/                      # Landing pages and introduction
│   └── intro.md              # Main entry point
├── concepts/                  # Architecture and theory
│   ├── getting-started/      # What is LayerZero
│   ├── protocol/             # Core protocol concepts
│   ├── applications/         # OApp, OFT, ONFT standards
│   ├── modular-security/     # DVN architecture
│   └── technical-reference/  # Deep technical details
├── get-started/              # Quick start guides
│   └── create-lz-oapp/       # CLI setup and first app
├── developers/               # Platform-specific implementation
│   ├── evm/                  # Solidity/EVM chains
│   │   ├── oapp/            # OApp standard
│   │   ├── oft/             # OFT standard
│   │   ├── onft/            # ONFT standard
│   │   ├── lzread/          # Read standard
│   │   ├── composer/        # Composer pattern
│   │   ├── configuration/   # Security config
│   │   └── troubleshooting/ # Debug guides
│   ├── solana/              # Rust/Anchor framework
│   ├── aptos-move/          # Move language
│   └── hyperliquid/         # Hyperliquid L1
├── deployments/             # Contract addresses & configs
│   ├── chains/              # Chain-specific info
│   └── evm-chains/          # EVM quickstarts
├── tools/                   # Developer tools
│   ├── layerzeroscan/       # Block explorer
│   └── api/                 # API references
└── workers/                 # DVN and Executor docs

2.2 Content Type by Location

Directory	Primary Content	Key Files
/concepts/	Theory, architecture, design	overview.md, technical explanations
/developers/{platform}/	Implementation guides	overview.md, quickstart.md, patterns
/deployments/	Addresses, configs, chain data	Chain-specific deployment info
/tools/	External tools & APIs	Tool documentation, API specs
/get-started/	First-time user guides	CLI setup, hello world

2.3 Standard File Patterns

Each contract standard (OApp, OFT, ONFT, etc.) should have:

1. overview.md - Architecture, concepts, when to use
2. quickstart.md - 5-minute implementation guide
3. [feature]-patterns.md - Advanced implementation patterns
4. [specific-topic].md - Deep dives on specific features

2.4 Code Example Sources

When creating or updating code examples:

1. Contract Standards: Reference implementations from devtools/packages/

   • oapp-evm/ for OApp contracts
   • oft-evm/ for OFT contracts
   • onft-evm/ for ONFT contracts

2. Examples: Use tested examples from devtools/examples/

   • Full working implementations
   • Deployment scripts
   • Test suites

3. Protocol Contracts: Reference layerzero-v2/packages/ for:

   • Endpoint interfaces
   • Message library implementations
   • DVN and Executor contracts

---

3. The 5-Expand-Debug Framework (Adapted)

3.1 Quickstart (5 Minutes)

File: quickstart.md or embedded in overview.md

Structure:

---
title: LayerZero V2 [Standard] Quickstart
sidebar_label: [Human-Friendly Name]
---

[1-2 sentence description of what this enables]

## Installation

```bash
npx create-lz-oapp@latest
```

Quick Deploy (3 minutes)

// Minimal working example
contract MyOFT is OFT {
    constructor() OFT("Token", "TKN", endpoint, owner) {}
}

Send Your First Message

npm run deploy
npm run send --from sepolia --to arbsepolia

Verify Success

[How to confirm it worked - Explorer link, logs, etc.]

Next Steps

• Configure security →
• Add advanced features →

### 3.2 Overview (Conceptual + Expand)

**File**: `overview.md`

**Structure**:
```markdown
---
title: [Standard] Overview
sidebar_label: Overview
---

[Visual diagram if applicable]

## What is [Standard]?

[2-3 paragraphs explaining the concept]

## Core Concepts

### [Concept 1]
[Explanation with code example]

### [Concept 2]
[Explanation with diagram]

## When to Use [Standard]

[Decision matrix or use cases]

## Architecture

[Technical details, inheritance diagrams]

## Getting Started

[Link to quickstart or embed simple example]

3.3 Troubleshooting (Debug)

Location: /troubleshooting/ directory or bottom of overview

Structure:

## Troubleshooting

### Common Issues

#### Error: [Specific Error]

**Symptoms**: [What user sees]
**Cause**: [Why it happens]
**Solution**:

```solidity
// ❌ Incorrect
[bad code]

// ✅ Correct
[good code]
```

Issue: [Common Problem]

Quick Fix: [One-liner solution] Prevention: [Best practice]

---

## 4. Platform-Specific Considerations

### 4.1 EVM Documentation

**Location**: `/developers/evm/`

**Required Sections**:
- Foundry setup and configuration
- Hardhat alternative setup
- Gas optimization patterns
- Chain-specific quirks (in `/deployments/chains/`)

**Code Style**:
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import { OApp } from "@layerzerolabs/oapp-evm/contracts/OApp.sol";

contract MyOApp is OApp {
    // Implementation
}

Import Path Verification: Always verify import paths against the actual package structure in devtools:

• @layerzerolabs/oapp-evm/contracts/ → packages/oapp-evm/contracts/
• @layerzerolabs/oft-evm/contracts/ → packages/oft-evm/contracts/

4.2 Solana Documentation

Location: /developers/solana/

Required Sections:

• Anchor framework setup
• Account model explanations
• CPI patterns for LayerZero
• Rent and account size considerations

Code Style:

use anchor_lang::prelude::*;
use oapp::instructions::*;

#[program]
pub mod my_oapp {
    // Implementation
}

4.3 Aptos Move Documentation

Location: /developers/aptos-move/

Required Sections:

• Move module structure
• Resource vs struct patterns
• Gas considerations
• Multi-chain deployment scripts

---

5. Documentation Templates (Updated)

5.1 Contract Standard Overview Template

---
title: LayerZero V2 [Standard Name]
sidebar_label: [Short Name]
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

[One paragraph explaining what this standard enables]

## Core Concepts

[2-3 key concepts with visual aids]

## Quick Example

Use platform-specific examples to demonstrate functionality:

**EVM Example:**

```solidity
// Minimal example code here
contract MyOApp is OApp {
    // Implementation
}
```

Solana Example:

// Minimal example code here
use anchor_lang::prelude::*;
#[program]
pub mod my_oapp {
    // Implementation
}

Installation

[Platform-specific installation steps]

Basic Usage

[Step-by-step implementation]

Advanced Patterns

[Link to patterns doc or embed 1-2 examples]

Configuration

[Security setup, DVN configuration]

Troubleshooting

[Common issues and solutions]

### 5.2 Chain-Specific Documentation Template

**Location**: `/deployments/chains/[chain-name].mdx`

```markdown
---
title: [Chain Name]
---

import { ChainId } from '@layerzerolabs/lz-definitions';

## Network Information

| Parameter | Mainnet | Testnet |
|-----------|---------|---------|
| Endpoint V2 | `0x1a44...` | `0x6EDC...` |
| Chain ID | [Native ID] | [Native ID] |
| LZ Chain ID | `{ChainId.[CHAIN]}` | `{ChainId.[CHAIN]_TESTNET}` |

## Quick Start

```bash
npx hardhat lz:deploy --network [chain-name]

Configuration

[Default security config, recommended gas limits]

Known Issues

[Chain-specific quirks, workarounds]

---

## 6. Quality Standards

### 6.1 Code Examples

**Requirements**:
- ✅ Complete, runnable code (not snippets)
- ✅ Include all imports
- ✅ Show deployment commands
- ✅ Include verification steps
- ✅ Comment complex logic
- ✅ Show both success and error cases
- ✅ Verify against source repositories

**Example**:
```solidity
// ❌ Bad: Incomplete snippet
function send() {
    endpoint.send(params);
}

// ✅ Good: Complete, runnable
import { OApp } from "@layerzerolabs/oapp-evm/contracts/OApp.sol";
import { OptionsBuilder } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";

contract MyOApp is OApp {
    using OptionsBuilder for bytes;

    function send(uint32 _dstEid, string memory _message) external payable {
        bytes memory options = OptionsBuilder.newOptions()
            .addExecutorLzReceiveOption(200000, 0);

        _lzSend(_dstEid, abi.encode(_message), options, msg.sender);
    }
}

6.2 Visual Standards

Diagrams:

• Use Mermaid for flow diagrams
• Include both light/dark mode versions of images
• Keep diagrams simple and focused

Code Highlighting:

• Use appropriate language tags
• Highlight important lines with comments
• Show diff format for before/after

6.3 Navigation

Every page must have:

• Clear breadcrumb via sidebar structure
• "Next Steps" section at bottom
• Links to related concepts
• Links to troubleshooting if applicable

6.4 Source Code Verification

Before publishing any code example:

1. Verify the code compiles against the latest contracts
2. Check that import paths are correct
3. Ensure constructor parameters match current implementation
4. Test deployment scripts work with current CLI tools
5. Confirm gas estimates are reasonable

---

7. File Naming Conventions

Standard Patterns

Content Type	File Name	Example
Overview	overview.md	/oapp/overview.md
Quick Start	quickstart.md	/oft/quickstart.md
Patterns	[topic]-patterns.md	/oft/oft-patterns-extensions.md
Configuration	[aspect]-config.md	/configuration/dvn-executor-config.md
Troubleshooting	[topic].md in /troubleshooting/	/troubleshooting/error-messages.md
Chain Info	[chain-name].mdx	/chains/ethereum.mdx

Special Files

• start.md - Entry point for multi-page guides
• api.md or api-reference.md - API documentation
• glossary.md - Term definitions
• faq.md - Frequently asked questions

---

8. Cross-Platform Content Strategy

Shared Concepts

Place in /concepts/ when:

• Theory applies to all platforms
• Architecture is platform-agnostic
• General LayerZero protocol information

Platform-Specific Implementation

Place in /developers/[platform]/ when:

• Code examples are platform-specific
• Setup instructions vary by platform
• Different patterns or best practices apply

Hybrid Approach

For features available across platforms:

1. Create conceptual overview in /concepts/applications/
2. Create platform-specific guides in /developers/[platform]/[feature]/
3. Link between them prominently

---

9. Maintenance Guidelines

Weekly Tasks

• Review and update contract addresses in /deployments/
• Check for broken links in quickstart guides
• Update chain configs for new deployments
• Monitor source repositories for breaking changes

Monthly Tasks

• Audit code examples for latest contract versions
• Review troubleshooting guides for new issues
• Update gas recommendations based on usage
• Sync with latest releases from devtools and layerzero-v2

Per Release

• Update all quickstart guides
• Add migration guides if breaking changes
• Update API references
• Test all code examples
• Verify new features are documented

Source Repository Monitoring

• Watch devtools releases for new features
• Monitor layerzero-v2 releases for protocol updates
• Check example updates for new patterns
• Review PR descriptions for documentation needs

---

10. Success Metrics

Quantitative

• Time to first successful transaction < 10 minutes
• Code example success rate > 95%
• Page load time < 2 seconds
• Search result relevance > 80%

Qualitative

• Developer feedback via Discord/GitHub
• Support ticket reduction
• Community-contributed examples
• Clear navigation without confusion

---

This framework ensures LayerZero documentation remains the definitive resource for building omnichain applications, regardless of the blockchain platform chosen.