From 18700462d2833b833e0aa18ded5008a9e1dc8ffe Mon Sep 17 00:00:00 2001 From: Krak Date: Mon, 19 Jan 2026 16:04:40 -0800 Subject: [PATCH 1/3] docs: clarify example-specific tasks and native adapter instructions - WORKFLOW.md: Add note clarifying lz:oft:send is a custom task defined in examples/oft/tasks/, not a core SDK task - native-oft-adapter README: Replace confusing mint instructions with accurate note about native token usage (no minting required) --- WORKFLOW.md | 315 ++++++++++++++++++++++++++ examples/native-oft-adapter/README.md | 2 +- 2 files changed, 316 insertions(+), 1 deletion(-) create mode 100644 WORKFLOW.md diff --git a/WORKFLOW.md b/WORKFLOW.md new file mode 100644 index 0000000000..2ba52e8bf9 --- /dev/null +++ b/WORKFLOW.md @@ -0,0 +1,315 @@ +# LayerZero Deployment Workflow + +This guide explains the complete workflow for deploying and configuring LayerZero OApps and OFTs. + +## The Big Picture + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Cross-Chain Message Flow │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Source Chain LayerZero Network Destination Chain │ +│ ──────────── ──────────────── ───────────────── │ +│ │ +│ ┌─────────┐ ┌─────────┐ │ +│ │ Your │ ──► ┌──────────┐ ┌─────┐ ┌──────────┐ ──► │ Your │ │ +│ │ OApp │ │ Endpoint │ ──► │ DVN │ ──► │ Endpoint │ │ OApp │ │ +│ └─────────┘ └──────────┘ └─────┘ └──────────┘ └─────────┘ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ User calls DVNs verify Executor delivers │ +│ send() the message and calls receive │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +## Transaction Model + +A LayerZero deployment requires transactions on **every chain** in your configuration. Here's the breakdown: + +### Phase 1: Deployment + +| Action | Transactions | Description | +|--------|--------------|-------------| +| Deploy contract | 1 per chain | Deploy your OApp/OFT contract | +| **Total** | **N chains** | N deployment transactions | + +### Phase 2: Wiring (Configuration) + +For each **pathway** (A ↔ B), the wire task generates: + +| Action | Transactions | Description | +|--------|--------------|-------------| +| `setPeer` | 2 (A→B, B→A) | Set peer addresses | +| `setConfig` (Send) | 2 | Configure send library (DVNs, etc.) | +| `setConfig` (Receive) | 2 | Configure receive library | +| `setEnforcedOptions` | 2 | Set minimum gas options | +| **Total per pathway** | **~8 txs** | 4 on each chain | + +### Example: 2-Chain Deployment (Base ↔ Arbitrum) + +``` +Deployment Phase: + - Deploy MyOFT on Base: 1 tx + - Deploy MyOFT on Arbitrum: 1 tx + Total: 2 txs + +Wiring Phase: + - setPeer (Base → Arb): 1 tx on Base + - setPeer (Arb → Base): 1 tx on Arbitrum + - setConfig (Base send): 1 tx on Base + - setConfig (Base receive): 1 tx on Base + - setConfig (Arb send): 1 tx on Arbitrum + - setConfig (Arb receive): 1 tx on Arbitrum + - setEnforcedOptions: 2 txs (1 per chain) + Total: ~8 txs + +Grand Total: ~10 transactions +``` + +### Example: 3-Chain Deployment (A ↔ B ↔ C) + +With 3 chains fully connected (3 pathways: A-B, A-C, B-C): +- Deployment: 3 txs +- Wiring: 3 pathways × ~8 txs = ~24 txs +- **Total: ~27 transactions** + +## Hardhat as Task Orchestration + +**Key Insight**: In this repository, Hardhat is used as a **task orchestration system**, not just a Solidity compiler. + +The LayerZero SDK exposes functionality through Hardhat tasks: + +```bash +# These are NOT just compile commands - they orchestrate multi-chain operations +npx hardhat lz:deploy # Deploys to ALL configured networks +npx hardhat lz:oapp:wire # Configures ALL pathways +npx hardhat lz:oapp:config:get # Reads config from ALL chains +``` + +### How It Works + +1. `@layerzerolabs/toolbox-hardhat` registers custom tasks +2. Tasks read your `hardhat.config.ts` for network definitions +3. Tasks read your `layerzero.config.ts` for pathway configuration +4. Tasks execute transactions across multiple networks + +## Understanding layerzero.config.ts + +The configuration file defines your **OmniGraph** - the topology of your omnichain application. + +### Structure + +```typescript +// layerzero.config.ts exports an async function +export default async function() { + return { + contracts: OmniNode[], // Which contracts on which chains + connections: OmniEdge[], // Pathways between contracts + } +} +``` + +### Why Is Config Async? + +The config fetches **live metadata** at runtime: +- DVN contract addresses per chain +- Default configurations +- Executor addresses + +This ensures your config uses the latest deployed infrastructure. + +### Key Types + +```typescript +// OmniPointHardhat - A contract location +const myContract: OmniPointHardhat = { + eid: EndpointId.BASESEP_V2_TESTNET, // Which chain + contractName: 'MyOFT', // Contract name (from hardhat-deploy) +} + +// OmniNode - A contract with its configuration +const node = { + contract: myContract, + config: { /* optional per-contract config */ } +} + +// OmniEdge - A pathway between two contracts +const edge = { + from: contractA, + to: contractB, + config: { + sendConfig: { /* DVN, executor config */ }, + receiveConfig: { /* DVN config */ }, + enforcedOptions: [ /* gas options */ ], + } +} +``` + +### Using generateConnectionsConfig() + +The helper function simplifies bidirectional pathway configuration: + +```typescript +import { generateConnectionsConfig, TwoWayConfig } from '@layerzerolabs/metadata-tools' + +const pathways: TwoWayConfig[] = [ + [ + contractA, // From + contractB, // To + [['LayerZero Labs'], []], // [requiredDVNs, [optionalDVNs, threshold]] + [1, 1], // [A→B confirmations, B→A confirmations] + [enforcedOptionsAtoB, enforcedOptionsBtoA], + ], +] + +const connections = await generateConnectionsConfig(pathways) +``` + +## Pathway Lifecycle + +A pathway goes through these states: + +``` +1. DEPLOYED + └── Contracts deployed, but not connected + └── Cannot send messages + +2. WIRED (Peer Set) + └── setPeer() called on both ends + └── Contracts know each other's addresses + └── Still cannot send without proper config + +3. CONFIGURED + └── setConfig() called for send/receive + └── DVNs and executors configured + └── setEnforcedOptions() called + +4. LIVE ✓ + └── All configuration complete + └── Messages can flow in both directions +``` + +### Checking Pathway Status + +```bash +# Check if peers are set +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts + +# Check full configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# Compare with LayerZero defaults +npx hardhat lz:oapp:config:get:default --oapp-config layerzero.config.ts +``` + +## Common Workflows + +### Workflow 1: Fresh Testnet Deployment + +```bash +# 1. Setup environment +cp .env.example .env +# Edit .env with MNEMONIC or PRIVATE_KEY + +# 2. Install and build +pnpm install +pnpm compile + +# 3. Deploy to all networks +npx hardhat lz:deploy + +# 4. Wire all pathways +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# 5. Verify configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# 6. Send test message/token (example-specific task) +# Note: lz:oft:send is a custom task defined in examples/oft/tasks/, not a core SDK task +# Each example may have its own send task implementation +npx hardhat lz:oft:send --network base-sepolia --to arbitrum-sepolia --amount 1000000000000000000 +``` + +### Workflow 2: Adding a New Chain + +1. **Update hardhat.config.ts**: +```typescript +networks: { + // Existing networks... + 'new-chain': { + eid: EndpointId.NEW_CHAIN_V2_MAINNET, + url: process.env.RPC_URL_NEW_CHAIN, + accounts, + }, +} +``` + +2. **Update layerzero.config.ts**: +```typescript +const newChainContract: OmniPointHardhat = { + eid: EndpointId.NEW_CHAIN_V2_MAINNET, + contractName: 'MyOFT', +} + +// Add to contracts array +contracts: [ + { contract: existingContract1 }, + { contract: existingContract2 }, + { contract: newChainContract }, // Add new +] + +// Add pathways to existing contracts +const pathways: TwoWayConfig[] = [ + // Existing pathways... + [existingContract1, newChainContract, ...], + [existingContract2, newChainContract, ...], +] +``` + +3. **Deploy and wire**: +```bash +# Deploy only to new network +npx hardhat deploy --network new-chain --tags MyOFT + +# Wire all pathways (including new ones) +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +### Workflow 3: Updating Configuration + +If you need to change DVNs, confirmations, or enforced options: + +1. Update `layerzero.config.ts` with new configuration +2. Run wire again - it will only update changed values: +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Environment Variables + +| Variable | Purpose | Example | +|----------|---------|---------| +| `MNEMONIC` | Wallet mnemonic phrase | `word1 word2 ... word12` | +| `PRIVATE_KEY` | Alternative to mnemonic | `0xabc123...` | +| `RPC_URL_` | RPC endpoint per network | `https://rpc.example.com` | + +### .env Example + +```bash +# Authentication (choose one) +MNEMONIC="your twelve word mnemonic phrase goes here" +# PRIVATE_KEY=0x... + +# RPC URLs +RPC_URL_BASE_SEPOLIA=https://base-sepolia.gateway.tenderly.co +RPC_URL_ARB_SEPOLIA=https://arbitrum-sepolia.gateway.tenderly.co +``` + +## See Also + +- [DEBUGGING.md](./DEBUGGING.md) - Troubleshooting guide +- [CHEATSHEET.md](./CHEATSHEET.md) - Quick reference +- [examples/oft/](./examples/oft/) - OFT example with full config +- [Official Documentation](https://docs.layerzero.network/) diff --git a/examples/native-oft-adapter/README.md b/examples/native-oft-adapter/README.md index c9f34632d9..acbbb96e14 100644 --- a/examples/native-oft-adapter/README.md +++ b/examples/native-oft-adapter/README.md @@ -95,7 +95,7 @@ To deploy your contracts to your desired blockchains, run the following command npx hardhat lz:deploy ``` -> If you need initial tokens on testnet for the EVM OFT, open `contracts/MyOFT.sol` and uncomment `_mint(msg.sender, 100000 * (10 ** 18));` in the constructor. Ensure you remove this line for production. +> **Note:** Native OFT Adapter uses native ETH (or chain's native token) on the source chain - no initial token minting is required. Simply ensure your deployer wallet has native tokens to send. More information about available CLI arguments can be found using the `--help` flag: From d74d228442805b4424e35da94c394d223c178552 Mon Sep 17 00:00:00 2001 From: Krak Date: Mon, 19 Jan 2026 16:06:18 -0800 Subject: [PATCH 2/3] docs: add CLAUDE.md and AGENTS.md documentation across packages and examples - Add root-level CLAUDE.md, DEBUGGING.md, CHEATSHEET.md guides - Add CLAUDE.md files for all examples explaining their purpose and usage - Add AGENTS.md files for key packages with CI/automation guidance - Update AGENTS.md, README.md with improved documentation - Add changesets for version tracking --- .changeset/docs-restructure-examples.md | 27 ++ .changeset/docs-restructure-packages.md | 10 + AGENTS.md | 121 +++++-- CHEATSHEET.md | 224 +++++++++++- CLAUDE.md | 172 +++++++++ DEBUGGING.md | 338 ++++++++++++++++++ README.md | 136 +++++-- examples/CLAUDE.md | 130 +++++++ examples/frontend/CLAUDE.md | 37 ++ examples/lzapp-migration/CLAUDE.md | 49 +++ examples/mint-burn-oft-adapter/CLAUDE.md | 49 +++ examples/native-oft-adapter/CLAUDE.md | 50 +++ examples/oapp-aptos-move/CLAUDE.md | 50 +++ examples/oapp-read/AGENTS.md | 43 +++ examples/oapp-read/CLAUDE.md | 59 +++ examples/oapp-solana/CLAUDE.md | 53 +++ examples/oapp/AGENTS.md | 50 +++ examples/oapp/CLAUDE.md | 118 ++++++ examples/oft-adapter-aptos-move/CLAUDE.md | 37 ++ examples/oft-adapter-initia/CLAUDE.md | 32 ++ examples/oft-adapter/AGENTS.md | 50 +++ examples/oft-adapter/CLAUDE.md | 114 ++++++ examples/oft-alt/CLAUDE.md | 33 ++ examples/oft-aptos-move/AGENTS.md | 48 +++ examples/oft-aptos-move/CLAUDE.md | 66 ++++ examples/oft-composer-library/CLAUDE.md | 45 +++ examples/oft-evm-solana-move/CLAUDE.md | 43 +++ examples/oft-hyperliquid/CLAUDE.md | 32 ++ examples/oft-initia/CLAUDE.md | 32 ++ .../oft-solana-composer-library/CLAUDE.md | 37 ++ examples/oft-solana/AGENTS.md | 49 +++ examples/oft-solana/CLAUDE.md | 73 ++++ examples/oft-tron/CLAUDE.md | 43 +++ examples/oft-upgradeable/CLAUDE.md | 61 ++++ examples/oft/AGENTS.md | 50 +++ examples/oft/CLAUDE.md | 95 +++++ examples/omni-call/CLAUDE.md | 46 +++ examples/onft721-zksync/CLAUDE.md | 46 +++ examples/onft721/AGENTS.md | 43 +++ examples/onft721/CLAUDE.md | 49 +++ examples/ovault-evm/CLAUDE.md | 39 ++ examples/uniswap-read/CLAUDE.md | 46 +++ examples/view-pure-read/CLAUDE.md | 39 ++ packages/CLAUDE.md | 185 ++++++++++ packages/devtools-evm-hardhat/AGENTS.md | 44 +++ packages/devtools-evm-hardhat/CLAUDE.md | 119 ++++++ packages/oapp-evm/AGENTS.md | 46 +++ packages/oapp-evm/CLAUDE.md | 155 ++++++++ packages/oft-evm/AGENTS.md | 45 +++ packages/oft-evm/CLAUDE.md | 122 +++++++ packages/test-devtools-ton/README.md | 53 +++ packages/toolbox-hardhat/AGENTS.md | 38 ++ packages/toolbox-hardhat/CLAUDE.md | 84 +++++ packages/toolbox-hardhat/README.md | 49 ++- packages/ua-devtools-evm-hardhat/AGENTS.md | 45 +++ packages/ua-devtools-evm-hardhat/CLAUDE.md | 90 +++++ 56 files changed, 3966 insertions(+), 73 deletions(-) create mode 100644 .changeset/docs-restructure-examples.md create mode 100644 .changeset/docs-restructure-packages.md create mode 100644 CLAUDE.md create mode 100644 DEBUGGING.md create mode 100644 examples/CLAUDE.md create mode 100644 examples/frontend/CLAUDE.md create mode 100644 examples/lzapp-migration/CLAUDE.md create mode 100644 examples/mint-burn-oft-adapter/CLAUDE.md create mode 100644 examples/native-oft-adapter/CLAUDE.md create mode 100644 examples/oapp-aptos-move/CLAUDE.md create mode 100644 examples/oapp-read/AGENTS.md create mode 100644 examples/oapp-read/CLAUDE.md create mode 100644 examples/oapp-solana/CLAUDE.md create mode 100644 examples/oapp/AGENTS.md create mode 100644 examples/oapp/CLAUDE.md create mode 100644 examples/oft-adapter-aptos-move/CLAUDE.md create mode 100644 examples/oft-adapter-initia/CLAUDE.md create mode 100644 examples/oft-adapter/AGENTS.md create mode 100644 examples/oft-adapter/CLAUDE.md create mode 100644 examples/oft-alt/CLAUDE.md create mode 100644 examples/oft-aptos-move/AGENTS.md create mode 100644 examples/oft-aptos-move/CLAUDE.md create mode 100644 examples/oft-composer-library/CLAUDE.md create mode 100644 examples/oft-evm-solana-move/CLAUDE.md create mode 100644 examples/oft-hyperliquid/CLAUDE.md create mode 100644 examples/oft-initia/CLAUDE.md create mode 100644 examples/oft-solana-composer-library/CLAUDE.md create mode 100644 examples/oft-solana/AGENTS.md create mode 100644 examples/oft-solana/CLAUDE.md create mode 100644 examples/oft-tron/CLAUDE.md create mode 100644 examples/oft-upgradeable/CLAUDE.md create mode 100644 examples/oft/AGENTS.md create mode 100644 examples/oft/CLAUDE.md create mode 100644 examples/omni-call/CLAUDE.md create mode 100644 examples/onft721-zksync/CLAUDE.md create mode 100644 examples/onft721/AGENTS.md create mode 100644 examples/onft721/CLAUDE.md create mode 100644 examples/ovault-evm/CLAUDE.md create mode 100644 examples/uniswap-read/CLAUDE.md create mode 100644 examples/view-pure-read/CLAUDE.md create mode 100644 packages/CLAUDE.md create mode 100644 packages/devtools-evm-hardhat/AGENTS.md create mode 100644 packages/devtools-evm-hardhat/CLAUDE.md create mode 100644 packages/oapp-evm/AGENTS.md create mode 100644 packages/oapp-evm/CLAUDE.md create mode 100644 packages/oft-evm/AGENTS.md create mode 100644 packages/oft-evm/CLAUDE.md create mode 100644 packages/test-devtools-ton/README.md create mode 100644 packages/toolbox-hardhat/AGENTS.md create mode 100644 packages/toolbox-hardhat/CLAUDE.md create mode 100644 packages/ua-devtools-evm-hardhat/AGENTS.md create mode 100644 packages/ua-devtools-evm-hardhat/CLAUDE.md diff --git a/.changeset/docs-restructure-examples.md b/.changeset/docs-restructure-examples.md new file mode 100644 index 0000000000..4b11bef3e7 --- /dev/null +++ b/.changeset/docs-restructure-examples.md @@ -0,0 +1,27 @@ +--- +"@layerzerolabs/oft-example": patch +"@layerzerolabs/oapp-example": patch +"@layerzerolabs/oft-adapter-example": patch +"@layerzerolabs/onft721-example": patch +"@layerzerolabs/oapp-read-example": patch +"@layerzerolabs/oft-solana-example": patch +"@layerzerolabs/oft-aptos-move-example": patch +"@layerzerolabs/oapp-aptos-example": patch +"@layerzerolabs/oapp-solana-example": patch +"@layerzerolabs/mint-burn-oft-adapter-example": patch +"@layerzerolabs/native-oft-adapter-example": patch +"@layerzerolabs/oft-adapter-aptos-move-example": patch +"@layerzerolabs/oft-adapter-initia-example": patch +"@layerzerolabs/oft-initia-example": patch +"@layerzerolabs/oft-hyperliquid-example": patch +"@layerzerolabs/oft-alt-example": patch +"@layerzerolabs/onft721-zksync-example": patch +"@layerzerolabs/omni-call-example": patch +"@layerzerolabs/lzapp-migration-example": patch +"@layerzerolabs/uniswap-read-example": patch +"@layerzerolabs/view-pure-read-example": patch +"@layerzerolabs/ovault-evm-example": patch +"@layerzerolabs/oft-upgradeable-example": patch +--- + +docs: add CLAUDE.md and AGENTS.md files for AI agent context, create missing READMEs diff --git a/.changeset/docs-restructure-packages.md b/.changeset/docs-restructure-packages.md new file mode 100644 index 0000000000..db7bbd1380 --- /dev/null +++ b/.changeset/docs-restructure-packages.md @@ -0,0 +1,10 @@ +--- +"@layerzerolabs/toolbox-hardhat": patch +"@layerzerolabs/ua-devtools-evm-hardhat": patch +"@layerzerolabs/devtools-evm-hardhat": patch +"@layerzerolabs/oft-evm": patch +"@layerzerolabs/oapp-evm": patch +"@layerzerolabs/test-devtools-ton": patch +--- + +docs: add CLAUDE.md and AGENTS.md files for AI agent context, enhance README with full task reference diff --git a/AGENTS.md b/AGENTS.md index 24945ce27b..e4a52615b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,48 @@ notifications: --- -## 2. Environment Setup +## 2. Package Relationship Diagram + +``` + toolbox-hardhat + (main entry point) + │ + ┌───────────────┼───────────────┐ + │ │ │ + ▼ ▼ ▼ + ua-devtools- devtools-evm- protocol-devtools- + evm-hardhat hardhat evm + │ │ │ + └───────┬───────┴───────┬───────┘ + │ │ + ▼ ▼ + devtools-evm devtools + (core types) +``` + +**Key Packages:** +- `toolbox-hardhat` - Main entry point, re-exports everything +- `ua-devtools-evm-hardhat` - OApp/OFT wiring tasks +- `devtools-evm-hardhat` - Deploy tasks, HRE utilities +- `devtools` - Core types (OmniPoint, OmniGraph) + +--- + +## 3. Directory-Specific AGENTS.md Files + +Codex will apply the most specific `AGENTS.md` under: + +| Directory | Contains | +|-----------|----------| +| `examples/AGENTS.md` | Example-specific guidelines, structure templates | +| `packages/AGENTS.md` | Package-specific guidelines, naming conventions | +| `tests/AGENTS.md` | Test-specific guidelines | +| `examples/*/AGENTS.md` | Per-example build/test commands | +| `packages/*/AGENTS.md` | Per-package build/test commands | + +--- + +## 4. Environment Setup 1. **Setup Script** (internet + proxy phase) @@ -52,38 +93,36 @@ notifications: * `cache/metadata/dvns.json`: Contains DVN (Decentralized Verifier Network) records with contract addresses and endpoint IDs * `cache/metadata/defaultConfig.json`: Contains default cross-chain configuration settings between Endpoints - * Benefits: - * Setup captures latest metadata during internet access - * Code-mode runs fully offline using local JSON snapshots - * Provides reference data for metadata-tools package and LayerZero configurations - --- -## 3. Repo Structure Overview +## 5. Repo Structure Overview ``` / ├── examples/ ← standalone demo projects -│ ├── oapp/ ← LayerZero OApp examples -│ ├── oft/ ← OFT implementation examples -│ └── onft/ ← ONFT implementation examples -| └── .../ +│ ├── oapp/ ← OApp example (start here for messaging) +│ ├── oft/ ← OFT example (start here for tokens) +│ ├── oft-adapter/ ← Wrap existing ERC20 +│ └── .../ ├── packages/ ← reusable libraries & plugins -│ ├── devtools/ ← core devtools package -│ ├── oft-evm/ ← OFT implementations -│ └── onft-evm/ ← ONFT implementations -│ └── .../ +│ ├── toolbox-hardhat/ ← Main entry point +│ ├── devtools/ ← Core types +│ ├── devtools-evm-hardhat/ ← Deploy tasks +│ ├── ua-devtools-evm-hardhat/ ← OApp/OFT tasks +│ ├── oft-evm/ ← OFT contracts +│ └── .../ ├── tests/ ← integration & helper suites -| └── .../ -├── .gitignore ├── turbo.json ← Turbo Pipeline config ├── package.json ← monorepo root +├── WORKFLOW.md ← Deployment workflow guide +├── DEBUGGING.md ← Troubleshooting guide +├── CHEATSHEET.md ← Quick reference └── AGENTS.md ← this file ``` --- -## 4. JS Tooling & Build +## 6. JS Tooling & Build * **Package Manager**: pnpm v8.15.6 (via Corepack or `npm install -g pnpm@8.15.6`). * **Monorepo Runner**: Turbo (`turbo.json`). @@ -101,7 +140,21 @@ notifications: --- -## 5. Agent Workflow +## 7. Common Hardhat Tasks + +| Task | Description | Package | +|------|-------------|---------| +| `lz:deploy` | Deploy contracts to all configured networks | devtools-evm-hardhat | +| `lz:oapp:wire` | Wire OApp pathways (setPeer, setConfig) | ua-devtools-evm-hardhat | +| `lz:oapp:config:get` | Get current on-chain configuration | ua-devtools-evm-hardhat | +| `lz:oapp:config:get:default` | Get LayerZero default configuration | ua-devtools-evm-hardhat | +| `lz:oapp:peers:get` | Get peer relationships | ua-devtools-evm-hardhat | +| `lz:read:wire` | Wire OApp Read channels | ua-devtools-evm-hardhat | +| `lz:errors:decode` | Decode LayerZero error messages | ua-devtools-evm-hardhat | + +--- + +## 8. Agent Workflow 1. **Initial Setup** * Run `pnpm install` to install dependencies @@ -109,7 +162,7 @@ notifications: 2. **Development Phase** * Make necessary code changes - * Follow platform-specific guidelines in respective CODEX.md files + * Follow platform-specific guidelines in respective AGENTS.md files * Ensure changes are properly documented 3. **Pre-Submission Checks** @@ -127,7 +180,19 @@ notifications: --- -## 6. Versioning & Changesets +## 9. Common Troubleshooting Patterns + +| Issue | Diagnostic | Solution | +|-------|------------|----------| +| "Peer not set" | `lz:oapp:peers:get` | Run `lz:oapp:wire` | +| "InvalidNonce" | Check message lifecycle | Verify DVN verification | +| Config mismatch | `lz:oapp:config:get` | Compare with expected config | +| Build fails | `pnpm build --filter ` | Check dependencies | +| Deploy fails | Check `.env` | Verify RPC URLs, credentials | + +--- + +## 10. Versioning & Changesets After modifying any packages under `examples/`, `packages/`, or `tests/`: @@ -139,7 +204,7 @@ Generates and stages a changeset for versioning & changelog. --- -## 7. Commit & PR Guidelines +## 11. Commit & PR Guidelines * **Commits**: semantic scope: @@ -152,15 +217,3 @@ Generates and stages a changeset for versioning & changelog. 2. What changed 3. How to verify (build/test commands) * **Footer**: link to changeset, list breaking changes. - ---- - -## 8. Directory-Specific Overrides - -Codex will apply the most specific `AGENTS.md` under: - -* `examples/AGENTS.md` -* `packages/AGENTS.md` -* `tests/AGENTS.md` - -Each sub-directory's AGENTS.md provides platform-specific guidelines while maintaining consistency with this root configuration. \ No newline at end of file diff --git a/CHEATSHEET.md b/CHEATSHEET.md index ad105316e4..8da93a0221 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -10,6 +10,116 @@

Developer Cheatsheet

+## Quick Commands + +### Project Setup +```bash +# Create new project +npx create-lz-oapp@latest + +# Install dependencies +pnpm install + +# Build +pnpm compile +``` + +### Deployment & Wiring +```bash +# Deploy to all configured networks +npx hardhat lz:deploy + +# Wire all pathways +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# Check configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# Check peers +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +### Monorepo Development +```bash +# Build all packages +pnpm build + +# Test +pnpm test:local + +# Lint +pnpm lint:fix + +# Create changeset +pnpm changeset +``` + +--- + +## Task Reference + +### Core Tasks (devtools-evm-hardhat) + +| Task | Description | Usage | +|------|-------------|-------| +| `lz:deploy` | Deploy contracts to all configured networks | `npx hardhat lz:deploy` | +| `lz:healthcheck:validate-rpcs` | Validate RPC endpoint connectivity | `npx hardhat lz:healthcheck:validate-rpcs` | +| `lz:export:deployments:typescript` | Export deployments as TypeScript | `npx hardhat lz:export:deployments:typescript` | + +### OApp Tasks (ua-devtools-evm-hardhat) + +| Task | Description | Usage | +|------|-------------|-------| +| `lz:oapp:wire` | Wire OApp pathways (setPeer, setConfig, etc.) | `npx hardhat lz:oapp:wire --oapp-config ` | +| `lz:oapp:config:get` | Get current on-chain configuration | `npx hardhat lz:oapp:config:get --oapp-config ` | +| `lz:oapp:config:get:default` | Get LayerZero default configuration | `npx hardhat lz:oapp:config:get:default --oapp-config ` | +| `lz:oapp:config:get:executor` | Get executor configuration | `npx hardhat lz:oapp:config:get:executor --oapp-config ` | +| `lz:oapp:config:init` | Initialize a new layerzero.config.ts | `npx hardhat lz:oapp:config:init` | +| `lz:oapp:peers:get` | Get peer relationships | `npx hardhat lz:oapp:peers:get --oapp-config ` | +| `lz:oapp:enforced:opts:get` | Get enforced options | `npx hardhat lz:oapp:enforced:opts:get --oapp-config ` | + +### OApp Read Tasks + +| Task | Description | Usage | +|------|-------------|-------| +| `lz:read:wire` | Wire OApp Read channels | `npx hardhat lz:read:wire --oapp-config ` | +| `lz:read:config:get` | Get OApp Read configuration | `npx hardhat lz:read:config:get --oapp-config ` | +| `lz:read:config:get:channel` | Get read channel configuration | `npx hardhat lz:read:config:get:channel --oapp-config ` | + +### Utility Tasks + +| Task | Description | Usage | +|------|-------------|-------| +| `lz:errors:decode` | Decode LayerZero error messages | `npx hardhat lz:errors:decode --error ` | +| `lz:errors:list` | List all known LayerZero errors | `npx hardhat lz:errors:list` | +| `lz:ownable:transfer:ownership` | Transfer contract ownership | `npx hardhat lz:ownable:transfer:ownership` | + +--- + +## Environment Variables + +| Variable | Purpose | Example | +|----------|---------|---------| +| `MNEMONIC` | Wallet mnemonic (12 or 24 words) | `word1 word2 ... word12` | +| `PRIVATE_KEY` | Alternative to mnemonic | `0xabc123...` | +| `RPC_URL_` | RPC URL for specific network | `https://rpc.example.com` | + +### Example .env +```bash +# Authentication (choose one) +MNEMONIC="your twelve word mnemonic phrase goes here" +# PRIVATE_KEY=0x... + +# RPC URLs +RPC_URL_ETHEREUM_MAINNET=https://eth.llamarpc.com +RPC_URL_BASE_MAINNET=https://mainnet.base.org +RPC_URL_ARB_MAINNET=https://arb1.arbitrum.io/rpc +RPC_URL_BASE_SEPOLIA=https://sepolia.base.org +RPC_URL_ARB_SEPOLIA=https://sepolia-rollup.arbitrum.io/rpc +``` + +--- + ## Glossary | Name | Package | Meaning | @@ -22,6 +132,9 @@ | `OmniError` | `@layerzerolabs/devtools` | Wraps an arbitrary `error` object to add information about where that error happened. Consists of `error` and `point` | | `OmniContract` | `@layerzerolabs/devtools-evm` | Wraps an `ethers` `Contract` instance to add information about the endpoint. Consists of `eid` and `contract` | | `OmniPointHardhat` | `@layerzerolabs/devtools-evm-hardhat` | Hardhat-specific variation of `OmniPoint`. Since in hardhat we can get a contract address by its name (from `deployments`), this version of `OmniPoint` allows us to use `contractName` instead of `address` | +| `EndpointId` (eid) | `@layerzerolabs/lz-definitions` | Unique identifier for each chain in LayerZero. Used in hardhat.config.ts to map network names to LayerZero endpoints. | +| `DVN` | N/A | Decentralized Verifier Network - verifies cross-chain messages | +| `Executor` | N/A | Delivers verified messages to destination chain | ## Conventions @@ -34,6 +147,8 @@ The packages are laid out according to the [principle of least knowledge](https: The only exceptions to this rule are packages that need to follow an existing naming convention (`create-lz-oapp`) or packages for which the name needs to appeal or be intuitive/familiar to the user (`toolbox-hardhat`) +--- + ## Recipes ### `*-hardhat` packages @@ -70,7 +185,7 @@ import { createGetHreByEid } from "@layerzerolabs/devtools-evm-hardhat"; const getEnvironment = createGetHreByEid(); const eid = EndpointId.AVALANCHE_TESTNET; -const environment = await getNetworkRuntimeEnvironmentByEid(eid); +const environment = await getEnvironment(eid); ``` #### Getting a contract instance @@ -86,11 +201,11 @@ const createContract = createContractFactory(); const eid = EndpointId.BST_MAINNET; -// We can ask for the contract by its name and eid -const contract = await createContract({ eid: address: '0x' }) +// We can ask for the contract by its address and eid +const contract = await createContract({ eid, address: '0x...' }) -// Or its name -const contract = await createContract({ eid: contractName: 'MyOApp' }) +// Or its name and eid +const contract = await createContract({ eid, contractName: 'MyOApp' }) ``` ##### Connected, with a provider @@ -105,8 +220,105 @@ const createContract = createConnectedContractFactory(); const eid = EndpointId.BST_MAINNET; // We can ask for the contract by its address and eid -const contract = await createContract({ eid, address: "0x" }); +const contract = await createContract({ eid, address: "0x..." }); // Or its name and eid const contract = await createContract({ eid, contractName: "MyOApp" }); ``` + +--- + +## Config File Templates + +### hardhat.config.ts + +```typescript +import 'dotenv/config' +import '@layerzerolabs/toolbox-hardhat' +import { HardhatUserConfig } from 'hardhat/types' +import { EndpointId } from '@layerzerolabs/lz-definitions' + +const MNEMONIC = process.env.MNEMONIC +const PRIVATE_KEY = process.env.PRIVATE_KEY + +const accounts = MNEMONIC + ? { mnemonic: MNEMONIC } + : PRIVATE_KEY + ? [PRIVATE_KEY] + : undefined + +const config: HardhatUserConfig = { + solidity: { + version: '0.8.22', + settings: { optimizer: { enabled: true, runs: 200 } }, + }, + networks: { + 'base-sepolia': { + eid: EndpointId.BASESEP_V2_TESTNET, + url: process.env.RPC_URL_BASE_SEPOLIA || 'https://sepolia.base.org', + accounts, + }, + 'arbitrum-sepolia': { + eid: EndpointId.ARBSEP_V2_TESTNET, + url: process.env.RPC_URL_ARB_SEPOLIA || 'https://sepolia-rollup.arbitrum.io/rpc', + accounts, + }, + }, +} + +export default config +``` + +### layerzero.config.ts + +```typescript +import { EndpointId } from '@layerzerolabs/lz-definitions' +import { ExecutorOptionType } from '@layerzerolabs/lz-v2-utilities' +import { generateConnectionsConfig, TwoWayConfig } from '@layerzerolabs/metadata-tools' +import type { OmniPointHardhat, OAppEnforcedOption } from '@layerzerolabs/toolbox-hardhat' + +const baseContract: OmniPointHardhat = { + eid: EndpointId.BASESEP_V2_TESTNET, + contractName: 'MyOFT', +} + +const arbitrumContract: OmniPointHardhat = { + eid: EndpointId.ARBSEP_V2_TESTNET, + contractName: 'MyOFT', +} + +const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [ + { + msgType: 1, + optionType: ExecutorOptionType.LZ_RECEIVE, + gas: 80000, + value: 0, + }, +] + +const pathways: TwoWayConfig[] = [ + [ + baseContract, + arbitrumContract, + [['LayerZero Labs'], []], + [1, 1], + [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], + ], +] + +export default async function () { + const connections = await generateConnectionsConfig(pathways) + return { + contracts: [{ contract: baseContract }, { contract: arbitrumContract }], + connections, + } +} +``` + +--- + +## See Also + +- [WORKFLOW.md](./WORKFLOW.md) - Complete deployment workflow +- [DEBUGGING.md](./DEBUGGING.md) - Troubleshooting guide +- [Official Documentation](https://docs.layerzero.network/) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..0af3c08bfd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,172 @@ +# CLAUDE.md - DevTools SDK + +This directory contains the **public SDK and tooling** for building on LayerZero. + +## Quick Context + +DevTools is a **monorepo** containing packages and examples for building omnichain applications with LayerZero. The main workflow is: + +1. **Deploy** contracts to multiple chains using `npx hardhat lz:deploy` +2. **Wire** pathways between chains using `npx hardhat lz:oapp:wire` +3. **Send** cross-chain messages or tokens + +**Key Insight**: Hardhat here is used as a **task orchestration system**, not just a Solidity compiler. Most LayerZero functionality is exposed as Hardhat tasks. + +## Purpose + +DevTools provides: +- Reusable packages for OApp/OFT development +- Example implementations as reference +- Deployment and configuration tooling +- Testing utilities + +## Directory Structure + +``` +devtools/ +├── packages/ # Reusable libraries +│ ├── toolbox-hardhat/ # Main entry point - import this +│ ├── devtools/ # Core types (OmniPoint, OmniGraph) +│ ├── devtools-evm-hardhat/ # Hardhat integration +│ ├── ua-devtools-evm-hardhat/ # OApp/OFT tasks +│ ├── oft-evm/ # OFT contracts & SDK +│ ├── oapp-evm/ # OApp contracts & SDK +│ ├── onft-evm/ # ONFT contracts & SDK +│ └── ... +│ +├── examples/ # Reference implementations +│ ├── oapp/ # OApp example (start here for messaging) +│ ├── oft/ # OFT example (start here for tokens) +│ ├── oft-adapter/ # Wrap existing tokens +│ └── ... +│ +└── tests/ # Integration tests +``` + +## Package Naming Convention + +Packages follow `[domain-][-modifier]`: + +| Package | Description | +|---------|-------------| +| `devtools` | Core types, no chain specifics | +| `devtools-evm` | EVM-specific, no framework | +| `devtools-evm-hardhat` | EVM + Hardhat integration | +| `ua-devtools-evm-hardhat` | User Application (OApp/OFT) tasks | +| `oft-evm` | OFT contracts and types | +| `toolbox-hardhat` | **Main entry point** - aggregates all Hardhat tools | + +**Rule of thumb**: Most users should `import {} from '@layerzerolabs/toolbox-hardhat'` + +## Common User Questions + +| Question | Answer | +|----------|--------| +| "How do I start a new OFT?" | Use `npx create-lz-oapp@latest` or clone `examples/oft` | +| "Where is `layerzero.config.ts` documented?" | See `WORKFLOW.md` and `examples/oft/layerzero.config.ts` | +| "What tasks are available?" | Run `npx hardhat --help` with toolbox-hardhat imported | +| "How do I wire contracts?" | `npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts` | +| "What is `eid`?" | Endpoint ID - unique identifier for each chain in LayerZero | +| "How do I check my config?" | `npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts` | +| "How do I deploy?" | `npx hardhat lz:deploy` (uses hardhat-deploy under the hood) | + +## Key Files to Check + +| Task | Check These Files | +|------|-------------------| +| Understanding deployment | `examples/oft/deploy/MyOFT.ts`, `packages/devtools-evm-hardhat/src/tasks/deploy.ts` | +| Understanding wiring | `packages/ua-devtools-evm-hardhat/src/tasks/oapp/wire/` | +| Understanding config | `examples/oft/layerzero.config.ts`, `packages/metadata-tools/` | +| Finding task implementations | `packages/ua-devtools-evm-hardhat/src/tasks/` | +| Understanding types | `packages/devtools/src/` (OmniPoint, OmniGraph, etc.) | + +## Development Commands + +```bash +# Install dependencies +pnpm install + +# Build all packages +pnpm build + +# Run tests +pnpm test:local # Fast local tests +pnpm test:ci # Full CI test suite +pnpm test:user # E2E user flow tests + +# Linting +pnpm lint:fix + +# Create changeset for version bump +pnpm changeset +``` + +## Package Manager + +- **pnpm v8.15.6** - Required version +- **Turbo** - Monorepo task runner (see `turbo.json`) + +## Key Patterns + +### The OmniGraph Model + +LayerZero configuration uses an **OmniGraph** - a graph of contracts and connections: + +```typescript +// layerzero.config.ts exports an async function +export default async function() { + return { + contracts: [ // OmniNode[] - contracts on each chain + { contract: baseContract }, + { contract: arbitrumContract }, + ], + connections: [...] // OmniEdge[] - pathways between contracts + } +} +``` + +**Why async?** The config fetches on-chain metadata (DVN addresses, default configs) at runtime. + +### Creating an OFT + +```typescript +// See examples/oft/ for complete implementation +// 1. Deploy with hardhat-deploy +// 2. Configure in layerzero.config.ts +// 3. Wire with: npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +### Creating an OApp + +```typescript +// See examples/oapp/ for complete implementation +// Implement _lzReceive for incoming messages +// Use _lzSend for outgoing messages +``` + +## Extending SDK + +1. Create new package in `packages/` +2. Follow existing package structure +3. Add to `pnpm-workspace.yaml` +4. Reference from examples if needed + +## Testing Strategy + +- **Unit tests**: Per-package in `packages/*/test/` +- **Integration tests**: In `tests/` directory +- **Example tests**: Each example has its own test suite + +## Relationship to Other Repos + +- **Implements**: Interfaces from `core/layerzero-v2/` +- **Consumed by**: `core/monorepo-internal/` for deployments +- **References**: Contract addresses from `core/address-book/` + +## Warnings + +1. **Run `pnpm changeset`** when modifying packages +2. **Check examples/** for reference before implementing +3. **AGENTS.md exists** - see it for CI/agent-specific guidance +4. **Version compatibility** - ensure package versions align +5. **Config is async** - `layerzero.config.ts` must export an async function diff --git a/DEBUGGING.md b/DEBUGGING.md new file mode 100644 index 0000000000..ce548d6404 --- /dev/null +++ b/DEBUGGING.md @@ -0,0 +1,338 @@ +# LayerZero Debugging Guide + +This guide helps troubleshoot common issues when deploying and operating LayerZero applications. + +## Message Lifecycle + +Understanding where messages can get stuck: + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Message Lifecycle & Failure Points │ +├──────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Source Chain Destination Chain │ +│ ──────────── ───────────────── │ +│ │ +│ 1. User calls send() │ +│ │ │ +│ ▼ │ +│ 2. OApp._lzSend() ─────────────────────────┐ │ +│ │ │ │ +│ │ ❌ FAIL: Insufficient fee │ │ +│ │ ❌ FAIL: Peer not set │ │ +│ │ ❌ FAIL: Invalid options │ │ +│ │ │ │ +│ ▼ │ │ +│ 3. Endpoint.send() │ │ +│ │ │ │ +│ │ ❌ FAIL: Config not set │ │ +│ │ │ │ +│ ▼ │ │ +│ 4. PacketSent event emitted │ │ +│ │ │ │ +│ │ ══════════════════════════════════════│══════════════════════ │ +│ │ Off-chain (DVN verification) │ │ +│ │ ══════════════════════════════════════│══════════════════════ │ +│ │ │ │ +│ │ ⏳ STUCK: DVN not verifying │ │ +│ │ ⏳ STUCK: Confirmations pending │ │ +│ │ │ │ +│ ▼ ▼ │ +│ 5. ────────────────────────────────────► Executor picks up │ +│ │ │ +│ │ ❌ FAIL: Executor gas too low │ +│ │ │ +│ ▼ │ +│ 6. Endpoint.lzReceive() │ +│ │ │ +│ │ ❌ FAIL: _lzReceive reverts │ +│ │ ❌ FAIL: Out of gas │ +│ │ │ +│ ▼ │ +│ 7. Message delivered ✓ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────┘ +``` + +## Diagnostic Tools + +### Check Peer Configuration + +```bash +# See all peer relationships +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +Expected output: +``` +┌─────────────────┬─────────────────┬────────────────────────────────────────────┐ +│ From │ To │ Peer Address │ +├─────────────────┼─────────────────┼────────────────────────────────────────────┤ +│ base-sepolia │ arbitrum-sepolia│ 0x1234...5678 │ +│ arbitrum-sepolia│ base-sepolia │ 0xabcd...efgh │ +└─────────────────┴─────────────────┴────────────────────────────────────────────┘ +``` + +**Issue**: If peer is `0x0000...0000`, the pathway is not wired. + +### Check Full Configuration + +```bash +# See complete on-chain configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +``` + +This shows: +- Send library configuration (DVNs, confirmations) +- Receive library configuration +- Enforced options + +### Compare with Defaults + +```bash +# See what LayerZero defaults are +npx hardhat lz:oapp:config:get:default --oapp-config layerzero.config.ts +``` + +### Decode Error Messages + +```bash +# Decode a revert error +npx hardhat lz:errors:decode --error 0x12345678 + +# List all known errors +npx hardhat lz:errors:list +``` + +## Common Issues + +### Issue: "Peer not set" / LZ_InvalidPath + +**Symptom**: Transaction reverts with `LZ_InvalidPath` or similar + +**Cause**: `setPeer()` was not called + +**Solution**: +```bash +# Run wire task +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# Verify peers +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +### Issue: "InvalidNonce" + +**Symptom**: Message delivery fails with nonce error + +**Cause**: Messages delivered out of order or duplicate delivery attempt + +**Solution**: +1. Check LayerZero Scan for message status +2. If stuck, may need to clear nonce via recovery mechanism +3. Ensure you're not sending from the same address simultaneously + +### Issue: Message Stuck / Not Delivered + +**Symptom**: `PacketSent` event on source but no delivery on destination + +**Possible Causes**: + +1. **DVN not verifying** + - Check DVN configuration matches for both chains + - Verify DVN is operational + +2. **Confirmations not reached** + - Check required confirmation count + - Wait for block confirmations + +3. **Executor gas too low** + - Check `enforcedOptions` gas settings + - Increase gas in configuration + +**Diagnostic Steps**: +```bash +# 1. Get the source transaction hash +# 2. Look up on LayerZero Scan: https://layerzeroscan.com/tx/ +# 3. Check status: "Inflight", "Delivered", "Failed" +``` + +### Issue: DVN Not Verifying + +**Symptom**: Message shows "Waiting for DVN" on LayerZero Scan + +**Possible Causes**: +- DVN configuration mismatch between chains +- Required DVN is not operational on that route +- Insufficient confirmations on source chain + +**Solution**: +```bash +# Check your DVN configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# Compare send config (source) with receive config (destination) +# DVNs must match! +``` + +### Issue: "_lzReceive Reverts" + +**Symptom**: Message verified but execution fails + +**Possible Causes**: +- Insufficient gas in executor options +- Bug in your `_lzReceive` implementation +- External call in `_lzReceive` failing + +**Solution**: +1. Increase gas in `enforcedOptions`: +```typescript +const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [ + { + msgType: 1, + optionType: ExecutorOptionType.LZ_RECEIVE, + gas: 200000, // Increase this + value: 0, + }, +] +``` + +2. Test `_lzReceive` locally with mock data +3. Check for external calls that might fail + +### Issue: "Insufficient Fee" + +**Symptom**: Send transaction reverts with fee error + +**Cause**: Not enough native token sent for gas + +**Solution**: +```typescript +// Quote the fee first +const fee = await oft.quoteSend(params, false) + +// Send with the quoted fee (add buffer for gas price fluctuation) +await oft.send(params, fee, { value: fee.nativeFee * 110n / 100n }) +``` + +### Issue: Deploy Fails + +**Symptom**: `lz:deploy` fails on a network + +**Possible Causes**: +- Missing RPC URL in `.env` +- Insufficient balance on deployer +- Network not in `hardhat.config.ts` + +**Diagnostic**: +```bash +# Check network connectivity +npx hardhat test --network + +# Check balance +cast balance --rpc-url +``` + +### Issue: Wire Task Generates No Transactions + +**Symptom**: `lz:oapp:wire` completes but says "0 transactions" + +**Possible Causes**: +- Configuration already matches on-chain state +- Config file not properly loaded + +**Diagnostic**: +```bash +# Check if config matches +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +``` + +## LayerZero Scan Integration + +[LayerZero Scan](https://layerzeroscan.com/) is the primary tool for tracking cross-chain messages. + +### Using LayerZero Scan + +1. **Find your transaction**: Search by source transaction hash +2. **Check status**: + - `Inflight`: Message sent, awaiting DVN verification + - `Delivered`: Successfully delivered to destination + - `Failed`: Delivery attempted but failed + +3. **View details**: + - Source chain and transaction + - Destination chain and transaction + - DVN verification status + - Executor delivery status + +### Common Scan Statuses + +| Status | Meaning | Action | +|--------|---------|--------| +| `Inflight` | Awaiting verification | Wait, or check DVN config | +| `Delivered` | Complete | None needed | +| `Failed` | Delivery reverted | Check gas, check `_lzReceive` | +| `Blocked` | Nonce issue | May need recovery | + +## Chain-Specific Issues + +### Solana + +| Issue | Solution | +|-------|----------| +| "Account not found" | Initialize accounts before sending | +| "Invalid mint authority" | Ensure program has mint authority | +| PDA derivation fails | Check seed derivation matches | + +### Aptos/Move + +| Issue | Solution | +|-------|----------| +| "Module not published" | Publish with `aptos move publish` | +| "Capability not found" | Check resource permissions | +| Type argument mismatch | Verify generic types | + +### zkSync + +| Issue | Solution | +|-------|----------| +| Bytecode mismatch | Use zkSync-specific compiler | +| Verification fails | Use zkSync explorer, not Etherscan | + +## Reading Wire Task Output + +The wire task provides detailed output: + +``` +Generating transactions for OApp configuration... + +Network: base-sepolia + ┌─ setPeer(arbitrum-sepolia) → 0x1234... + ├─ setConfig(send, uln302) → 0x5678... + ├─ setConfig(receive, uln302) → 0xabcd... + └─ setEnforcedOptions → 0xefgh... + +Network: arbitrum-sepolia + ┌─ setPeer(base-sepolia) → 0x1234... + ├─ setConfig(send, uln302) → 0x5678... + ├─ setConfig(receive, uln302) → 0xabcd... + └─ setEnforcedOptions → 0xefgh... + +Total: 8 transactions +``` + +If a transaction fails, the task will show the error and stop. + +## Getting Help + +1. **Check documentation**: https://docs.layerzero.network/ +2. **Search existing issues**: https://github.com/LayerZero-Labs/devtools/issues +3. **Discord**: LayerZero Discord server +4. **LayerZero Scan**: https://layerzeroscan.com/ + +## See Also + +- [WORKFLOW.md](./WORKFLOW.md) - Deployment workflow guide +- [CHEATSHEET.md](./CHEATSHEET.md) - Quick reference +- [Official Documentation](https://docs.layerzero.network/) diff --git a/README.md b/README.md index c529d3e099..947d40eddb 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

LayerZero - + LayerZero @@ -14,20 +14,77 @@

LayerZero Developer Utilities

- Development | Cheatsheet | Examples + Workflow Guide | Debugging | Cheatsheet | Examples

--- -**Please note** that this repository is in a **beta** state and backwards-incompatible changes might be introduced in future releases. While we strive to comply to [semver](https://semver.org/), we can not guarantee to avoid breaking changes in minor releases. +## Quick Start (External Developers) + +The fastest way to start building with LayerZero: + +```bash +# Create a new project from a template +npx create-lz-oapp@latest + +# Follow the prompts to select: +# - Example template (OFT, OApp, ONFT) +# - Package manager +# - Project name +``` + +Or clone an example directly: + +```bash +git clone https://github.com/LayerZero-Labs/devtools.git +cd devtools/examples/oft +pnpm install +cp .env.example .env +# Edit .env with your credentials +pnpm compile +``` --- -## Introduction +## Key Concepts + +Before diving in, understand these core concepts: + +### Hardhat as Task Orchestration + +In this repository, Hardhat is used as a **task orchestration system**, not just a Solidity compiler. Most LayerZero operations are exposed as Hardhat tasks: + +```bash +npx hardhat lz:deploy # Deploy to ALL configured networks +npx hardhat lz:oapp:wire # Configure ALL pathways between contracts +npx hardhat lz:oapp:config:get # Read configuration from ALL chains +``` + +### The OmniGraph Configuration Model + +Your `layerzero.config.ts` defines an **OmniGraph** - a graph of contracts and their connections: + +```typescript +export default async function() { + return { + contracts: [/* which contracts on which chains */], + connections: [/* pathways between contracts */], + } +} +``` + +The config is **async** because it fetches live metadata (DVN addresses, etc.) at runtime. + +### Pathway Wiring -Welcome to the **LayerZero Developer Tools Hub**. This repository houses everything related to the LayerZero Developer Experience, including application contract standards, CLI examples, packages, scripting tools, and more. It serves as a central hub for developers to build, test, deploy, and interact with LayerZero-based omnichain applications (OApps). +A "pathway" is a bidirectional connection between two contracts. Wiring involves: +- `setPeer()` - Tell each contract about its counterpart +- `setConfig()` - Configure DVNs and executors +- `setEnforcedOptions()` - Set minimum gas requirements -Visit our developer docs to get started building omnichain applications. +See [WORKFLOW.md](./WORKFLOW.md) for detailed transaction breakdowns. + +--- ## Repository Structure @@ -37,34 +94,32 @@ The primary folders that smart contract developers will find most useful are: `packages/`: Includes a collection of NPM packages, libraries, and tools that facilitate interaction with LayerZero contracts. This includes deployment scripts, CLI tools, protocol devtools, and testing utilities. -### Examples - -Here is a list of example projects available in the `examples/` directory: +### Where to Start -``` -$ ls examples -mint-burn-oft-adapter oapp oft oft-solana omnicounter-solana onft721-zksync -native-oft-adapter oapp-read oft-adapter oft-upgradeable onft721 uniswap-read -``` +| Goal | Location | +|------|----------| +| Build a cross-chain token | `examples/oft/` | +| Build custom messaging | `examples/oapp/` | +| Wrap an existing ERC20 | `examples/oft-adapter/` | +| Build cross-chain NFT | `examples/onft721/` | +| Solana integration | `examples/oft-solana/` | +| Aptos integration | `examples/oft-aptos-move/` | -### Packages +### Key Packages -Here is a list of packages available in the `packages/` directory: +| Package | Purpose | +|---------|---------| +| `toolbox-hardhat` | **Main entry point** - import this in your hardhat config | +| `oft-evm` | OFT Solidity contracts | +| `oapp-evm` | OApp Solidity contracts | +| `devtools-evm-hardhat` | Deploy tasks, HRE utilities | +| `ua-devtools-evm-hardhat` | OApp/OFT wiring tasks | -``` -$ ls packages -build-devtools devtools-evm-hardhat oft-evm protocol-devtools-solana toolbox-hardhat -build-lz-options devtools-solana oft-evm-upgradeable test-devtools ua-devtools -create-lz-oapp export-deployments omnicounter-devtools test-devtools-evm-foundry ua-devtools-evm -decode-lz-options io-devtools omnicounter-devtools-evm test-devtools-evm-hardhat ua-devtools-evm-hardhat -devtools oapp-alt-evm onft-evm test-devtools-solana ua-devtools-solana -devtools-cli oapp-evm oapp-evm-upgradeable test-devtools-ton verify-contract -devtools-evm oapp-evm-upgradeable protocol-devtools toolbox-foundry -``` +--- -## Getting Started +## Getting Started (SDK Contributors) -To get started with the LayerZero Developer Tools, follow these steps: +To get started with the LayerZero Developer Tools repository: 1. Clone the Repository @@ -91,6 +146,19 @@ This will build all the packages and examples in the repository. Review the README for each individual `examples/` project to learn how to interact with and use each sample project. +--- + +## Documentation + +| Document | Purpose | +|----------|---------| +| [WORKFLOW.md](./WORKFLOW.md) | Complete deployment workflow and transaction model | +| [DEBUGGING.md](./DEBUGGING.md) | Troubleshooting guide for common issues | +| [CHEATSHEET.md](./CHEATSHEET.md) | Quick reference for commands and types | +| [Official Docs](https://docs.layerzero.network/) | Full protocol documentation | + +--- + ## Contributing We welcome contributions from the community! If you'd like to contribute to the LayerZero Developer Tools by adding new `examples/` or `packages/`, or by improving existing ones, please follow the guidelines below. @@ -139,7 +207,7 @@ Add or update unit tests to cover your changes. Ensure all tests pass: ``` -pnpm test +pnpm test:local ``` 5. Commit Messages @@ -171,13 +239,17 @@ Provide a clear and detailed description of your changes. If you encounter any issues or bugs with existing projects, please open an issue on GitHub under the **Issues** tab. Provide as much detail as possible, including steps to reproduce the issue. +--- + ## Additional Resources -- **Development Guide**: Check out our Development guide for more in-depth information on contributing to the repository. +- **Workflow Guide**: Check out our [WORKFLOW.md](./WORKFLOW.md) for understanding the deployment process. + +- **Debugging Guide**: Our [DEBUGGING.md](./DEBUGGING.md) helps troubleshoot common issues. -- **Cheatsheet**: Our Cheatsheet provides quick commands and tips. +- **Cheatsheet**: Our [CHEATSHEET.md](./CHEATSHEET.md) provides quick commands and tips. -- **Documentation**: Visit our official documentation for detailed guides and API references. +- **Documentation**: Visit our [official documentation](https://docs.layerzero.network/) for detailed guides and API references. By utilizing the resources in this repository, you can focus on creating innovative omnichain solutions without worrying about the complexities of cross-chain communication. diff --git a/examples/CLAUDE.md b/examples/CLAUDE.md new file mode 100644 index 0000000000..ac32fccb97 --- /dev/null +++ b/examples/CLAUDE.md @@ -0,0 +1,130 @@ +# CLAUDE.md - Examples Directory + +This directory contains **reference implementations** for building omnichain applications with LayerZero. + +## Quick Start + +For external developers, the recommended path is: + +```bash +# Create a new project from an example +npx create-lz-oapp@latest + +# Or clone this repo and use an example directly +cd examples/oft +pnpm install +pnpm compile +``` + +## Example Categories + +| Category | Examples | Use Case | +|----------|----------|----------| +| **OFT (Tokens)** | `oft`, `oft-adapter`, `oft-upgradeable`, `oft-alt` | Cross-chain fungible tokens | +| **OApp (Messaging)** | `oapp`, `oapp-read`, `omni-call` | Cross-chain message passing | +| **ONFT (NFTs)** | `onft721`, `onft721-zksync` | Cross-chain non-fungible tokens | +| **Multi-VM** | `oft-solana`, `oapp-solana`, `oft-aptos-move`, `oapp-aptos-move` | Solana, Aptos integration | +| **Specialized** | `oft-hyperliquid`, `oft-initia`, `oft-tron` | Chain-specific implementations | + +## Start Here + +| Goal | Example | +|------|---------| +| Deploy a new cross-chain token | `oft/` | +| Wrap an existing ERC20 | `oft-adapter/` | +| Build custom cross-chain messaging | `oapp/` | +| Read data from other chains | `oapp-read/` | +| Cross-chain NFT | `onft721/` | +| Solana integration | `oft-solana/` or `oapp-solana/` | +| Aptos/Move integration | `oft-aptos-move/` or `oapp-aptos-move/` | + +## Common Files in Each Example + +| File | Purpose | +|------|---------| +| `hardhat.config.ts` | Network definitions with `eid` (Endpoint ID) mapping | +| `layerzero.config.ts` | Pathway configuration - defines which chains connect | +| `contracts/` | Solidity smart contracts | +| `deploy/` | Hardhat-deploy scripts | +| `tasks/` | Custom Hardhat tasks (if any) | +| `.env.example` | Environment variables template | + +## Standard Workflow (EVM Examples) + +```bash +# 1. Setup +cp .env.example .env +# Edit .env with MNEMONIC or PRIVATE_KEY and RPC URLs + +# 2. Build +pnpm install +pnpm compile + +# 3. Deploy to all configured chains +npx hardhat lz:deploy + +# 4. Wire pathways (setPeer, setConfig, setEnforcedOptions) +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# 5. Verify configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# 6. Send test message/token (example-specific task) +npx hardhat lz:oft:send --network source-network ... +``` + +## Understanding layerzero.config.ts + +The config file defines an **OmniGraph** - the network topology of your application: + +```typescript +// Key concepts: +// - contracts: Which contracts on which chains +// - connections: Pathways between contracts (setPeer, DVN config, etc.) + +export default async function() { + const connections = await generateConnectionsConfig(pathways) + return { + contracts: [ + { contract: baseContract }, // OmniNode + { contract: arbitrumContract }, // OmniNode + ], + connections, // OmniEdge[] - generated from pathways + } +} +``` + +## Platform-Specific Notes + +### Solana Examples (`oft-solana`, `oapp-solana`) +- Requires Rust and Anchor toolchain +- Uses `anchor build` for program compilation +- EVM wiring commands work alongside Solana-specific tasks + +### Aptos/Move Examples (`oft-aptos-move`, `oapp-aptos-move`) +- Requires Aptos CLI +- Move contracts in `sources/` directory +- Separate wire commands for EVM and Move components + +### ZkSync Examples (`onft721-zksync`) +- Uses zkSync-specific compiler settings +- Additional verification steps required + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "MNEMONIC not found" | Copy `.env.example` to `.env` and set credentials | +| "Cannot find network" | Ensure network is defined in `hardhat.config.ts` with `eid` | +| "Peer not set" | Run `npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts` | +| "Config mismatch" | Check with `npx hardhat lz:oapp:config:get` | +| Build fails | Run `pnpm install` then `pnpm compile` from monorepo root | + +## Adding a New Example + +1. Copy an existing similar example +2. Update `package.json` name and dependencies +3. Update `hardhat.config.ts` networks +4. Update `layerzero.config.ts` pathways +5. Add example to root `pnpm-workspace.yaml` +6. Run `pnpm install` from monorepo root diff --git a/examples/frontend/CLAUDE.md b/examples/frontend/CLAUDE.md new file mode 100644 index 0000000000..e64d445e46 --- /dev/null +++ b/examples/frontend/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md - Frontend Example + +## What This Example Is + +A reference implementation of a **frontend application** for interacting with LayerZero OApps - demonstrates client-side integration patterns. + +## Key Files + +| File | Purpose | +|------|---------| +| `src/` | Frontend source code | +| `package.json` | Frontend dependencies | + +## Quick Start + +```bash +pnpm install +pnpm dev # or pnpm start +``` + +## What Makes This Example Different + +- **Client-side integration**: Frontend patterns for LayerZero +- Shows how to quote fees, send transactions +- User-facing application patterns + +## Key Patterns + +- Fee quoting before transactions +- Wallet connection handling +- Transaction status tracking +- LayerZero Scan integration + +## Related Examples + +- `oft/` - Backend OFT to interact with +- `oapp/` - Backend OApp to interact with diff --git a/examples/lzapp-migration/CLAUDE.md b/examples/lzapp-migration/CLAUDE.md new file mode 100644 index 0000000000..db32700418 --- /dev/null +++ b/examples/lzapp-migration/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md - LzApp Migration Example + +## What This Example Is + +A reference for **migrating from LayerZero V1 to V2** - demonstrates how to upgrade existing LzApp contracts to the new OApp standard. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | Migration contracts | +| `layerzero.config.ts` | V2 pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **V1 → V2 migration**: Shows upgrade path +- Maps old LzApp patterns to new OApp patterns +- Useful for teams with existing V1 deployments + +## Migration Changes + +| V1 (LzApp) | V2 (OApp) | +|------------|-----------| +| `_lzSend` | `_lzSend` (similar) | +| `_blockingLzReceive` | `_lzReceive` | +| `trustedRemote` | `peers` | +| `setTrustedRemote` | `setPeer` | + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Peer not found" | Use `setPeer` instead of `setTrustedRemote` | +| Config incompatible | Update to V2 config format | + +## Related Examples + +- `oapp/` - Standard V2 OApp +- `oft/` - Standard V2 OFT diff --git a/examples/mint-burn-oft-adapter/CLAUDE.md b/examples/mint-burn-oft-adapter/CLAUDE.md new file mode 100644 index 0000000000..d506ae4360 --- /dev/null +++ b/examples/mint-burn-oft-adapter/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md - Mint-Burn OFT Adapter Example + +## What This Example Is + +A reference implementation of a **Mint-Burn OFT Adapter** - an alternative adapter pattern where the adapter has mint/burn authority over the existing token. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyMintBurnOFTAdapter.sol` | Adapter with mint/burn | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## How It Differs from Standard Adapter + +| Feature | OFT Adapter | Mint-Burn Adapter | +|---------|-------------|-------------------| +| Source action | Lock tokens | Burn tokens | +| Receive action | Unlock tokens | Mint tokens | +| Token supply | Constant on source | Can decrease on source | +| Requirement | None | Adapter needs mint/burn rights | + +## What Makes This Example Different + +- **Mint/burn authority**: Adapter can mint and burn the wrapped token +- No locked tokens in adapter contract +- Requires token to support external minting/burning + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Not minter" | Grant adapter MINTER_ROLE on token | +| "Not burner" | Grant adapter BURNER_ROLE on token | + +## Related Examples + +- `oft-adapter/` - Standard lock/unlock adapter +- `native-oft-adapter/` - Native ETH adapter diff --git a/examples/native-oft-adapter/CLAUDE.md b/examples/native-oft-adapter/CLAUDE.md new file mode 100644 index 0000000000..08b631831a --- /dev/null +++ b/examples/native-oft-adapter/CLAUDE.md @@ -0,0 +1,50 @@ +# CLAUDE.md - Native OFT Adapter Example + +## What This Example Is + +A reference implementation of a **Native OFT Adapter** - wraps native ETH (or chain's native token) for cross-chain transfers. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyNativeOFTAdapter.sol` | Native token adapter | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## How It Works + +``` +Source Chain (ETH): +User sends ETH → Adapter wraps to WETH → Locks WETH + +Destination Chain: +Receives message → Mints wrapped ETH representation +``` + +## What Makes This Example Different + +- **Native token support**: Wraps ETH directly (no ERC20 needed) +- Handles WETH wrapping/unwrapping automatically +- Useful for native gas token bridges + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Insufficient ETH" | Send ETH with the transaction | +| "WETH address wrong" | Configure correct WETH for chain | + +## Related Examples + +- `oft-adapter/` - ERC20 adapter +- `mint-burn-oft-adapter/` - Mint/burn pattern diff --git a/examples/oapp-aptos-move/CLAUDE.md b/examples/oapp-aptos-move/CLAUDE.md new file mode 100644 index 0000000000..93c16992c1 --- /dev/null +++ b/examples/oapp-aptos-move/CLAUDE.md @@ -0,0 +1,50 @@ +# CLAUDE.md - OApp Aptos Move Example + +## What This Example Is + +A reference implementation of **OApp on Aptos** using Move - cross-chain messaging between Aptos and EVM chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `sources/` | Move source files | +| `Move.toml` | Move package configuration | +| `layerzero.config.ts` | Pathway configuration | + +## Prerequisites + +- Aptos CLI +- Move compiler + +## Quick Start + +```bash +cp .env.example .env +aptos move compile +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `aptos move compile` | Compile Move modules | +| `aptos move test` | Run Move tests | + +## What Makes This Example Different + +- **Aptos messaging**: Cross-chain messages to/from Aptos +- **Move language**: Uses Move for smart contracts +- Foundation for Aptos OFT + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Compile fails | Check Aptos CLI version | +| "Capability missing" | Check resource permissions | + +## Related Examples + +- `oft-aptos-move/` - Token transfers +- `oapp/` - EVM-only OApp diff --git a/examples/oapp-read/AGENTS.md b/examples/oapp-read/AGENTS.md new file mode 100644 index 0000000000..4bdec5e3be --- /dev/null +++ b/examples/oapp-read/AGENTS.md @@ -0,0 +1,43 @@ +# AGENTS.md - OApp Read Example + +## Build Commands + +```bash +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +pnpm test +pnpm test:local +``` + +## Deployment Commands + +```bash +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +# Note: Uses lz:read:wire instead of lz:oapp:wire +npx hardhat lz:read:wire --oapp-config layerzero.config.ts +``` + +## Verification Commands + +```bash +npx hardhat lz:read:config:get --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `contracts/` +- `layerzero.config.ts` +- `hardhat.config.ts` +- `deploy/` +- `tasks/` +- `test/` diff --git a/examples/oapp-read/CLAUDE.md b/examples/oapp-read/CLAUDE.md new file mode 100644 index 0000000000..f6fcd60d87 --- /dev/null +++ b/examples/oapp-read/CLAUDE.md @@ -0,0 +1,59 @@ +# CLAUDE.md - OApp Read Example + +## What This Example Is + +A reference implementation of **OApp Read** - a pattern for reading data from other chains without sending a full cross-chain message. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOAppRead.sol` | OApp Read contract | +| `layerzero.config.ts` | Read channel configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:read:wire --oapp-config layerzero.config.ts +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile contracts | +| `npx hardhat lz:deploy` | Deploy OApp Read | +| `npx hardhat lz:read:wire` | Wire read channels | +| `npx hardhat lz:read:config:get` | Check read configuration | + +## What Makes This Example Different + +- **Read-only operations**: Query data from other chains +- Uses **read channels** instead of full messaging pathways +- Different wire task: `lz:read:wire` instead of `lz:oapp:wire` + +## Read vs Send + +| Feature | OApp (Send) | OApp Read | +|---------|-------------|-----------| +| Purpose | Execute actions | Query data | +| Gas cost | Higher | Lower | +| Finality | Requires DVN verification | Lighter verification | +| Wire task | `lz:oapp:wire` | `lz:read:wire` | + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Channel not configured" | Run `lz:read:wire` | +| Read fails | Check read channel configuration | + +## Related Examples + +- `oapp/` - Full OApp messaging +- `uniswap-read/` - Real-world read example +- `view-pure-read/` - View/pure function reads diff --git a/examples/oapp-solana/CLAUDE.md b/examples/oapp-solana/CLAUDE.md new file mode 100644 index 0000000000..ff85edae62 --- /dev/null +++ b/examples/oapp-solana/CLAUDE.md @@ -0,0 +1,53 @@ +# CLAUDE.md - OApp Solana Example + +## What This Example Is + +A reference implementation of **OApp on Solana** - cross-chain messaging between Solana and EVM chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `programs/` | Solana program (Rust/Anchor) | +| `contracts/` | EVM contracts (if multi-VM) | +| `layerzero.config.ts` | Pathway configuration | +| `Anchor.toml` | Anchor configuration | + +## Prerequisites + +- Rust toolchain +- Anchor CLI +- Solana CLI + +## Quick Start + +```bash +cp .env.example .env +anchor build +# See README for full deployment steps +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `anchor build` | Build Solana program | +| `anchor test` | Run Anchor tests | + +## What Makes This Example Different + +- **Solana messaging**: Cross-chain messages to/from Solana +- **Anchor framework**: Uses Anchor for Solana development +- Foundation for Solana OFT + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Build fails | Check Anchor/Rust versions | +| "Account not found" | Initialize accounts first | + +## Related Examples + +- `oft-solana/` - Token transfers +- `oapp/` - EVM-only OApp diff --git a/examples/oapp/AGENTS.md b/examples/oapp/AGENTS.md new file mode 100644 index 0000000000..f82104b720 --- /dev/null +++ b/examples/oapp/AGENTS.md @@ -0,0 +1,50 @@ +# AGENTS.md - OApp Example + +## Build Commands + +```bash +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +pnpm test +pnpm test:local +``` + +## Deployment Commands + +```bash +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Verification Commands + +```bash +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `contracts/` +- `layerzero.config.ts` +- `hardhat.config.ts` +- `deploy/` +- `tasks/` +- `test/` + +## Files to Avoid Modifying + +- `node_modules/` +- `cache/` +- `artifacts/` +- `deployments/` (generated) diff --git a/examples/oapp/CLAUDE.md b/examples/oapp/CLAUDE.md new file mode 100644 index 0000000000..50032264b2 --- /dev/null +++ b/examples/oapp/CLAUDE.md @@ -0,0 +1,118 @@ +# CLAUDE.md - OApp Example + +## What This Example Is + +A reference implementation of an **Omnichain Application (OApp)** - the base pattern for cross-chain messaging in LayerZero. OApp is the foundation that OFT, ONFT, and other standards build upon. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOApp.sol` | OApp contract with `_lzSend` and `_lzReceive` | +| `contracts/mocks/MyOAppMock.sol` | Mock for testing | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions with `eid` mapping | +| `deploy/MyOApp.ts` | Deployment script | + +## Quick Start + +```bash +# 1. Setup +cp .env.example .env +# Set MNEMONIC or PRIVATE_KEY and RPC URLs + +# 2. Build +pnpm install +pnpm compile + +# 3. Deploy +npx hardhat lz:deploy + +# 4. Wire pathways +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# 5. Verify configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile Solidity contracts | +| `npx hardhat lz:deploy` | Deploy to configured networks | +| `npx hardhat lz:oapp:wire` | Set peers and configuration | +| `npx hardhat lz:oapp:config:get` | Check current configuration | +| `pnpm test` | Run local tests | + +## Understanding OApp + +### Sending Messages +```solidity +// In your contract +function sendMessage(uint32 _dstEid, string memory _message) external payable { + bytes memory payload = abi.encode(_message); + _lzSend(_dstEid, payload, _options, MessagingFee(msg.value, 0), payable(msg.sender)); +} +``` + +### Receiving Messages +```solidity +// Override _lzReceive +function _lzReceive( + Origin calldata _origin, + bytes32 _guid, + bytes calldata _message, + address _executor, + bytes calldata _extraData +) internal override { + string memory message = abi.decode(_message, (string)); + // Handle the message +} +``` + +## What Makes This Example Different + +- **Raw messaging pattern**: Direct `_lzSend`/`_lzReceive` implementation +- Foundation for understanding how OFT/ONFT work internally +- Demonstrates custom message encoding/decoding + +## Configuration + +### hardhat.config.ts +```typescript +networks: { + 'base-sepolia': { + eid: EndpointId.BASESEP_V2_TESTNET, + url: process.env.RPC_URL_BASE_SEPOLIA, + accounts, + }, +} +``` + +### layerzero.config.ts +```typescript +const pathways: TwoWayConfig[] = [ + [ + baseContract, + arbitrumContract, + [['LayerZero Labs'], []], // Required DVNs, optional DVNs + [1, 1], // Confirmations per direction + [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], + ], +] +``` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "LZ_InvalidPath" | Peer not set - run `lz:oapp:wire` | +| Message not received | Check DVN verification status on LayerZero Scan | +| "LZ_InsufficientFee" | Quote the fee with `quote()` before sending | + +## Related Examples + +- `oapp-read/` - Read data from other chains +- `omni-call/` - Cross-chain function calls +- `oft/` - Token transfers (builds on OApp) diff --git a/examples/oft-adapter-aptos-move/CLAUDE.md b/examples/oft-adapter-aptos-move/CLAUDE.md new file mode 100644 index 0000000000..ef6b54c3bf --- /dev/null +++ b/examples/oft-adapter-aptos-move/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md - OFT Adapter Aptos Move Example + +## What This Example Is + +A reference implementation of an **OFT Adapter on Aptos** - wraps an existing Aptos token for cross-chain transfers. + +## Key Files + +| File | Purpose | +|------|---------| +| `sources/` | Move adapter modules | +| `Move.toml` | Move package configuration | +| `contracts/` | EVM contracts (for multi-VM) | +| `layerzero.config.ts` | Pathway configuration | + +## Prerequisites + +- Aptos CLI +- Move compiler + +## Quick Start + +```bash +cp .env.example .env +aptos move compile +pnpm compile # For EVM side +``` + +## What Makes This Example Different + +- **Aptos adapter pattern**: Lock/unlock on Aptos +- Bridges existing Aptos tokens to EVM + +## Related Examples + +- `oft-aptos-move/` - Native OFT on Aptos +- `oft-adapter/` - EVM adapter pattern diff --git a/examples/oft-adapter-initia/CLAUDE.md b/examples/oft-adapter-initia/CLAUDE.md new file mode 100644 index 0000000000..e258091f43 --- /dev/null +++ b/examples/oft-adapter-initia/CLAUDE.md @@ -0,0 +1,32 @@ +# CLAUDE.md - OFT Adapter Initia Example + +## What This Example Is + +A reference implementation of an **OFT Adapter for Initia** - enables cross-chain token transfers with the Initia blockchain. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | Smart contracts | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Initia integration**: Specific to Initia blockchain +- Adapter pattern for existing Initia tokens + +## Related Examples + +- `oft-initia/` - Native OFT on Initia +- `oft-adapter/` - Standard EVM adapter diff --git a/examples/oft-adapter/AGENTS.md b/examples/oft-adapter/AGENTS.md new file mode 100644 index 0000000000..31c32663e0 --- /dev/null +++ b/examples/oft-adapter/AGENTS.md @@ -0,0 +1,50 @@ +# AGENTS.md - OFT Adapter Example + +## Build Commands + +```bash +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +pnpm test +pnpm test:local +``` + +## Deployment Commands + +```bash +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Verification Commands + +```bash +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `contracts/` +- `layerzero.config.ts` +- `hardhat.config.ts` +- `deploy/` +- `tasks/` +- `test/` + +## Files to Avoid Modifying + +- `node_modules/` +- `cache/` +- `artifacts/` +- `deployments/` (generated) diff --git a/examples/oft-adapter/CLAUDE.md b/examples/oft-adapter/CLAUDE.md new file mode 100644 index 0000000000..0247ed34d0 --- /dev/null +++ b/examples/oft-adapter/CLAUDE.md @@ -0,0 +1,114 @@ +# CLAUDE.md - OFT Adapter Example + +## What This Example Is + +A reference implementation of an **OFT Adapter** - a pattern for making an **existing ERC20 token** cross-chain compatible without modifying the original token contract. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOFTAdapter.sol` | Adapter wrapping an existing ERC20 | +| `contracts/mocks/MyERC20Mock.sol` | Mock ERC20 for testing | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | +| `deploy/MyOFTAdapter.ts` | Deployment script | + +## Quick Start + +```bash +# 1. Setup +cp .env.example .env +# Set MNEMONIC, PRIVATE_KEY, and RPC URLs + +# 2. Build +pnpm install +pnpm compile + +# 3. Deploy +npx hardhat lz:deploy + +# 4. Wire pathways +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## How OFT Adapter Works + +``` +Source Chain (has existing ERC20): +┌─────────────────┐ ┌──────────────────┐ +│ Existing ERC20 │ ←── │ OFT Adapter │ +│ (token locked) │ │ (lock/unlock) │ +└─────────────────┘ └──────────────────┘ + │ + │ LayerZero Message + ▼ +Destination Chain: +┌──────────────────┐ +│ OFT │ +│ (mint/burn) │ +└──────────────────┘ +``` + +**On source chain**: Adapter locks tokens when sending, unlocks when receiving +**On destination chains**: Regular OFT mints when receiving, burns when sending + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile contracts | +| `npx hardhat lz:deploy` | Deploy adapter and OFT | +| `npx hardhat lz:oapp:wire` | Wire pathways | +| `npx hardhat lz:oapp:config:get` | Verify configuration | + +## Configuration + +### Deploy Script Pattern +```typescript +// Source chain: Deploy adapter pointing to existing token +const adapter = await deploy('MyOFTAdapter', { + args: [existingTokenAddress, lzEndpoint, owner], +}) + +// Destination chains: Deploy regular OFT +const oft = await deploy('MyOFT', { + args: [name, symbol, lzEndpoint, owner], +}) +``` + +### layerzero.config.ts +```typescript +// Source chain uses OFTAdapter +const sourceAdapter: OmniPointHardhat = { + eid: EndpointId.ETH_MAINNET, + contractName: 'MyOFTAdapter', +} + +// Destination chains use OFT +const destOft: OmniPointHardhat = { + eid: EndpointId.ARBITRUM_MAINNET, + contractName: 'MyOFT', +} +``` + +## What Makes This Example Different + +- **Wraps existing tokens**: No need to redeploy or migrate tokens +- **Lock/unlock on source**: Tokens are escrowed, not burned +- **Mint/burn on destinations**: New OFT representation on other chains +- Useful for established tokens like USDC, WETH wrappers + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Insufficient allowance" | User must `approve()` adapter before sending | +| Token stuck in adapter | Check if destination has matching OFT deployed | +| "Not an OFT" on dest | Ensure dest has OFT (not adapter) deployed | + +## Related Examples + +- `oft/` - Native OFT (mint/burn everywhere) +- `mint-burn-oft-adapter/` - Alternative adapter pattern +- `native-oft-adapter/` - Wrap native ETH diff --git a/examples/oft-alt/CLAUDE.md b/examples/oft-alt/CLAUDE.md new file mode 100644 index 0000000000..b18ce618bc --- /dev/null +++ b/examples/oft-alt/CLAUDE.md @@ -0,0 +1,33 @@ +# CLAUDE.md - OFT Alt Example + +## What This Example Is + +A reference implementation of an **Alternative OFT** - an OFT variant using the alternative LayerZero transport mechanism. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOFTAlt.sol` | Alternative OFT contract | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Alternative transport**: Uses different transport mechanism +- May have different gas characteristics +- See `oapp-alt-evm` package for details + +## Related Examples + +- `oft/` - Standard OFT +- `oft-upgradeable/` - Upgradeable pattern diff --git a/examples/oft-aptos-move/AGENTS.md b/examples/oft-aptos-move/AGENTS.md new file mode 100644 index 0000000000..81c76dc5d4 --- /dev/null +++ b/examples/oft-aptos-move/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md - OFT Aptos Move Example + +## Prerequisites + +- Aptos CLI +- Move compiler + +## Build Commands + +```bash +# Move +aptos move compile + +# EVM contracts (if applicable) +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +aptos move test +pnpm test:local +``` + +## Deployment Commands + +```bash +# Move +aptos move publish + +# EVM +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `sources/` (Move) +- `contracts/` (EVM) +- `layerzero.config.ts` +- `Move.toml` +- `hardhat.config.ts` diff --git a/examples/oft-aptos-move/CLAUDE.md b/examples/oft-aptos-move/CLAUDE.md new file mode 100644 index 0000000000..e70ade0f37 --- /dev/null +++ b/examples/oft-aptos-move/CLAUDE.md @@ -0,0 +1,66 @@ +# CLAUDE.md - OFT Aptos Move Example + +## What This Example Is + +A reference implementation of **OFT on Aptos** using Move language - cross-chain token transfers between Aptos and EVM chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `sources/` | Move source files | +| `Move.toml` | Move package configuration | +| `contracts/` | EVM contracts (for multi-VM) | +| `layerzero.config.ts` | Pathway configuration | + +## Prerequisites + +- Aptos CLI (`aptos --version`) +- Move compiler + +## Quick Start + +```bash +cp .env.example .env + +# Build Move +aptos move compile + +# Build EVM (if applicable) +pnpm compile +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `aptos move compile` | Compile Move modules | +| `aptos move test` | Run Move tests | +| `pnpm compile` | Compile EVM contracts | + +## What Makes This Example Different + +- **Multi-VM**: Bridges Aptos and EVM ecosystems +- **Move language**: Aptos-native smart contracts +- Separate wire commands for Move vs EVM + +## Move-Specific Concepts + +| Concept | Description | +|---------|-------------| +| Module | Move's version of a contract | +| Resource | Move's storage type | +| Capability | Access control pattern | + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Compile fails | Check Move.toml dependencies | +| "Module not found" | Publish module first | + +## Related Examples + +- `oapp-aptos-move/` - OApp messaging for Aptos +- `oft-adapter-aptos-move/` - Adapter pattern for Aptos +- `oft/` - EVM-only OFT diff --git a/examples/oft-composer-library/CLAUDE.md b/examples/oft-composer-library/CLAUDE.md new file mode 100644 index 0000000000..cc8be13a04 --- /dev/null +++ b/examples/oft-composer-library/CLAUDE.md @@ -0,0 +1,45 @@ +# CLAUDE.md - OFT Composer Library Example + +## What This Example Is + +A reference implementation of an **OFT Composer** - allows composing additional logic on top of OFT transfers (e.g., swap after receive). + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | Composer contracts | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Compose pattern**: Execute additional logic after OFT transfer +- Chain actions together (transfer → swap → stake) +- Builds on OFT with lzCompose + +## Use Cases + +- Transfer then swap on destination +- Transfer then stake +- Multi-step cross-chain workflows + +## Compose Flow + +``` +Source → OFT Send → Destination OFT Receive → Composer Callback +``` + +## Related Examples + +- `oft/` - Basic OFT +- `oft-solana-composer-library/` - Solana version diff --git a/examples/oft-evm-solana-move/CLAUDE.md b/examples/oft-evm-solana-move/CLAUDE.md new file mode 100644 index 0000000000..d264c02556 --- /dev/null +++ b/examples/oft-evm-solana-move/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md - OFT EVM-Solana-Move Example + +## What This Example Is + +A reference implementation of **multi-VM OFT** - demonstrates token transfers across EVM, Solana, and Move (Aptos) chains simultaneously. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | EVM contracts (Solidity) | +| `programs/` | Solana programs (Rust/Anchor) | +| `sources/` | Move modules | +| `layerzero.config.ts` | Multi-VM pathway configuration | + +## Prerequisites + +- Node.js + pnpm (EVM) +- Rust + Anchor (Solana) +- Aptos CLI (Move) + +## Quick Start + +```bash +cp .env.example .env + +# Build all platforms +pnpm compile # EVM +anchor build # Solana +aptos move compile # Move +``` + +## What Makes This Example Different + +- **Three VMs**: EVM + Solana + Move in one example +- Complex multi-VM pathway configuration +- Shows unified token across heterogeneous chains + +## Related Examples + +- `oft/` - EVM-only OFT +- `oft-solana/` - Solana OFT +- `oft-aptos-move/` - Aptos OFT diff --git a/examples/oft-hyperliquid/CLAUDE.md b/examples/oft-hyperliquid/CLAUDE.md new file mode 100644 index 0000000000..981ba196e8 --- /dev/null +++ b/examples/oft-hyperliquid/CLAUDE.md @@ -0,0 +1,32 @@ +# CLAUDE.md - OFT Hyperliquid Example + +## What This Example Is + +A reference implementation of an **OFT on Hyperliquid** - cross-chain token transfers with the Hyperliquid L1. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | OFT contracts | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Hyperliquid integration**: Specific to Hyperliquid L1 +- Configured for Hyperliquid's environment + +## Related Examples + +- `oft/` - Standard EVM OFT +- `oft-adapter/` - Adapter pattern diff --git a/examples/oft-initia/CLAUDE.md b/examples/oft-initia/CLAUDE.md new file mode 100644 index 0000000000..eaa0c5aed9 --- /dev/null +++ b/examples/oft-initia/CLAUDE.md @@ -0,0 +1,32 @@ +# CLAUDE.md - OFT Initia Example + +## What This Example Is + +A reference implementation of an **OFT on Initia** - native cross-chain token on the Initia blockchain. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | OFT contracts | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Initia-specific**: Configured for Initia blockchain +- Native mint/burn OFT + +## Related Examples + +- `oft-adapter-initia/` - Adapter pattern +- `oft/` - Standard EVM OFT diff --git a/examples/oft-solana-composer-library/CLAUDE.md b/examples/oft-solana-composer-library/CLAUDE.md new file mode 100644 index 0000000000..a043e14375 --- /dev/null +++ b/examples/oft-solana-composer-library/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md - OFT Solana Composer Library Example + +## What This Example Is + +A reference implementation of **OFT Composer for Solana** - compose additional logic after OFT transfers on Solana. + +## Key Files + +| File | Purpose | +|------|---------| +| `programs/` | Solana composer programs | +| `Anchor.toml` | Anchor configuration | +| `layerzero.config.ts` | Pathway configuration | + +## Prerequisites + +- Rust toolchain +- Anchor CLI +- Solana CLI + +## Quick Start + +```bash +cp .env.example .env +anchor build +``` + +## What Makes This Example Different + +- **Solana compose pattern**: Post-transfer hooks on Solana +- Anchor-based implementation +- Bridges EVM compose patterns to Solana + +## Related Examples + +- `oft-solana/` - Basic Solana OFT +- `oft-composer-library/` - EVM version diff --git a/examples/oft-solana/AGENTS.md b/examples/oft-solana/AGENTS.md new file mode 100644 index 0000000000..db83065e05 --- /dev/null +++ b/examples/oft-solana/AGENTS.md @@ -0,0 +1,49 @@ +# AGENTS.md - OFT Solana Example + +## Prerequisites + +- Rust toolchain +- Anchor CLI +- Solana CLI + +## Build Commands + +```bash +# Solana program +anchor build + +# EVM contracts (if applicable) +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +anchor test +pnpm test:local +``` + +## Deployment Commands + +```bash +# Solana +anchor deploy + +# EVM +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `programs/` (Solana) +- `contracts/` (EVM) +- `layerzero.config.ts` +- `Anchor.toml` +- `hardhat.config.ts` diff --git a/examples/oft-solana/CLAUDE.md b/examples/oft-solana/CLAUDE.md new file mode 100644 index 0000000000..0e4e108795 --- /dev/null +++ b/examples/oft-solana/CLAUDE.md @@ -0,0 +1,73 @@ +# CLAUDE.md - OFT Solana Example + +## What This Example Is + +A reference implementation of **OFT on Solana** - cross-chain token transfers between Solana and EVM chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `programs/` | Solana program (Rust/Anchor) | +| `contracts/` | EVM contracts (if multi-VM) | +| `layerzero.config.ts` | Pathway configuration | +| `Anchor.toml` | Anchor configuration | + +## Prerequisites + +- Rust toolchain +- Anchor CLI (`anchor --version`) +- Solana CLI (`solana --version`) + +## Quick Start + +```bash +# Setup +cp .env.example .env + +# Build Solana program +anchor build + +# Build EVM (if applicable) +pnpm compile + +# Deploy +# (Solana deployment is more complex - see README) +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `anchor build` | Build Solana program | +| `anchor test` | Run Anchor tests | +| `pnpm compile` | Compile EVM contracts | + +## What Makes This Example Different + +- **Multi-VM**: Bridges Solana and EVM ecosystems +- **Rust/Anchor**: Solana programs in Rust +- Different deployment flow than EVM-only examples +- Token mint authority considerations + +## Solana-Specific Concepts + +| Concept | Description | +|---------|-------------| +| Program | Solana's version of a smart contract | +| PDA | Program Derived Address | +| Token Mint | SPL token definition | +| ATA | Associated Token Account | + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Program not found" | Deploy program first with `anchor deploy` | +| "Invalid mint authority" | Ensure OFT program has mint authority | +| Anchor build fails | Check Rust toolchain version | + +## Related Examples + +- `oapp-solana/` - OApp messaging for Solana +- `oft/` - EVM-only OFT diff --git a/examples/oft-tron/CLAUDE.md b/examples/oft-tron/CLAUDE.md new file mode 100644 index 0000000000..ac8fe5ae92 --- /dev/null +++ b/examples/oft-tron/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md - OFT Tron Example + +## What This Example Is + +A reference implementation of **OFT on Tron** - cross-chain token transfers with the Tron blockchain. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/` | Tron-compatible contracts | +| `layerzero.config.ts` | Pathway configuration | +| Configuration files | Tron-specific setup | + +## Prerequisites + +- TronBox or compatible tooling +- Tron wallet setup + +## Quick Start + +```bash +cp .env.example .env +pnpm install +# See README for Tron-specific deployment +``` + +## What Makes This Example Different + +- **Tron integration**: Specific to Tron blockchain +- TRC20 token standard +- Tron-specific deployment flow + +## Tron Considerations + +- Different address format (base58) +- TronBox for development +- Energy/bandwidth for transactions + +## Related Examples + +- `oft/` - Standard EVM OFT +- Multi-VM examples for other chains diff --git a/examples/oft-upgradeable/CLAUDE.md b/examples/oft-upgradeable/CLAUDE.md new file mode 100644 index 0000000000..909878c149 --- /dev/null +++ b/examples/oft-upgradeable/CLAUDE.md @@ -0,0 +1,61 @@ +# CLAUDE.md - OFT Upgradeable Example + +## What This Example Is + +A reference implementation of an **Upgradeable OFT** using the proxy pattern - allows upgrading contract logic without changing the contract address. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOFT.sol` | Upgradeable OFT implementation | +| `layerzero.config.ts` | Pathway configuration | +| `deploy/MyOFT.ts` | Proxy deployment script | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile contracts | +| `npx hardhat lz:deploy` | Deploy proxy + implementation | +| `npx hardhat lz:oapp:wire` | Wire pathways | + +## What Makes This Example Different + +- **Proxy pattern**: Uses OpenZeppelin upgradeable contracts +- `initialize()` instead of constructor +- Can upgrade implementation without redeploying + +## Upgrade Pattern + +```solidity +// Uses UUPS proxy pattern +import { OFTUpgradeable } from "@layerzerolabs/oft-evm-upgradeable"; + +contract MyOFT is OFTUpgradeable { + function initialize(...) external initializer { + __OFT_init(_name, _symbol, _lzEndpoint, _delegate); + } +} +``` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Already initialized" | Proxy already set up | +| Upgrade fails | Ensure upgrade is storage-compatible | + +## Related Examples + +- `oft/` - Non-upgradeable OFT +- `oapp-evm-upgradeable` package diff --git a/examples/oft/AGENTS.md b/examples/oft/AGENTS.md new file mode 100644 index 0000000000..108b3efb80 --- /dev/null +++ b/examples/oft/AGENTS.md @@ -0,0 +1,50 @@ +# AGENTS.md - OFT Example + +## Build Commands + +```bash +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +pnpm test +pnpm test:local +``` + +## Deployment Commands + +```bash +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Verification Commands + +```bash +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `contracts/` +- `layerzero.config.ts` +- `hardhat.config.ts` +- `deploy/` +- `tasks/` +- `test/` + +## Files to Avoid Modifying + +- `node_modules/` +- `cache/` +- `artifacts/` +- `deployments/` (generated) diff --git a/examples/oft/CLAUDE.md b/examples/oft/CLAUDE.md new file mode 100644 index 0000000000..f2b24c84fa --- /dev/null +++ b/examples/oft/CLAUDE.md @@ -0,0 +1,95 @@ +# CLAUDE.md - OFT Example + +## What This Example Is + +A reference implementation of an **Omnichain Fungible Token (OFT)** - a token that can be transferred across multiple blockchains while maintaining a unified total supply. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyOFT.sol` | OFT contract inheriting from `@layerzerolabs/oft-evm` | +| `layerzero.config.ts` | Pathway configuration (which chains connect) | +| `hardhat.config.ts` | Network definitions with `eid` mapping | +| `deploy/MyOFT.ts` | Deployment script using hardhat-deploy | +| `.env.example` | Environment variables template | + +## Quick Start + +```bash +# 1. Setup +cp .env.example .env +# Set MNEMONIC or PRIVATE_KEY and RPC URLs + +# 2. Build +pnpm install +pnpm compile + +# 3. Deploy (to all networks in hardhat.config.ts) +npx hardhat lz:deploy + +# 4. Wire pathways +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# 5. Verify configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile Solidity contracts | +| `npx hardhat lz:deploy` | Deploy to configured networks | +| `npx hardhat lz:oapp:wire` | Set peers, DVN config, enforced options | +| `npx hardhat lz:oapp:config:get` | Verify current on-chain configuration | +| `npx hardhat lz:oapp:peers:get` | Check peer relationships | + +## Understanding the Config + +### hardhat.config.ts +Defines networks with LayerZero Endpoint IDs: +```typescript +networks: { + 'base-sepolia': { + eid: EndpointId.BASESEP_V2_TESTNET, + url: process.env.RPC_URL_BASE_SEPOLIA, + accounts, + }, +} +``` + +### layerzero.config.ts +Defines the omnichain topology: +```typescript +const pathways: TwoWayConfig[] = [ + [ + baseContract, // Chain A + arbitrumContract, // Chain B + [['LayerZero Labs'], []], // DVNs + [1, 1], // Confirmations + [EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], + ], +] +``` + +## What Makes This Example Different + +- **Native OFT**: Token is created fresh on all chains (mint/burn model) +- Uses `generateConnectionsConfig()` to auto-generate bidirectional pathways +- Pre-configured for Base Sepolia and Arbitrum Sepolia testnets + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Peer not set" | Run `lz:oapp:wire` command | +| "InvalidNonce" | Check if pathway is properly wired in both directions | +| "Insufficient gas" | Increase `gas` value in `EVM_ENFORCED_OPTIONS` | +| Deploy fails | Ensure wallet has testnet ETH on both chains | + +## Related Examples + +- `oft-adapter/` - Wrap an existing ERC20 token +- `oft-upgradeable/` - Upgradeable OFT pattern +- `native-oft-adapter/` - Wrap native ETH diff --git a/examples/omni-call/CLAUDE.md b/examples/omni-call/CLAUDE.md new file mode 100644 index 0000000000..d79458d40f --- /dev/null +++ b/examples/omni-call/CLAUDE.md @@ -0,0 +1,46 @@ +# CLAUDE.md - Omni-Call Example + +## What This Example Is + +A reference implementation of **Omni-Call** - cross-chain function calls where you can invoke functions on contracts across chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/OmniCall.sol` | Cross-chain call contract | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Function calls**: Execute arbitrary function calls cross-chain +- More flexible than OFT (not just token transfers) +- General-purpose cross-chain execution + +## Use Cases + +- Cross-chain governance +- Multi-chain protocol coordination +- Arbitrary message execution + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Call fails | Check target function exists on destination | +| "Invalid selector" | Verify function signature matches | + +## Related Examples + +- `oapp/` - Basic messaging +- `oapp-read/` - Read-only operations diff --git a/examples/onft721-zksync/CLAUDE.md b/examples/onft721-zksync/CLAUDE.md new file mode 100644 index 0000000000..246af3d1a0 --- /dev/null +++ b/examples/onft721-zksync/CLAUDE.md @@ -0,0 +1,46 @@ +# CLAUDE.md - ONFT721 zkSync Example + +## What This Example Is + +A reference implementation of **ONFT721 on zkSync** - cross-chain NFT transfers optimized for zkSync Era. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyONFT721.sol` | ONFT721 for zkSync | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | zkSync network config | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **zkSync-specific**: Uses zkSync compiler settings +- zkSync Era deployment process +- Different verification flow + +## zkSync Considerations + +- Uses `@matterlabs/hardhat-zksync-solc` +- Different bytecode format +- Verification through zkSync explorer + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Compile fails | Ensure zkSync plugin configured | +| Deploy fails | Check zkSync-specific wallet setup | + +## Related Examples + +- `onft721/` - Standard ONFT721 +- `oft/` - Fungible token version diff --git a/examples/onft721/AGENTS.md b/examples/onft721/AGENTS.md new file mode 100644 index 0000000000..7743eccb8b --- /dev/null +++ b/examples/onft721/AGENTS.md @@ -0,0 +1,43 @@ +# AGENTS.md - ONFT721 Example + +## Build Commands + +```bash +pnpm install +pnpm compile +``` + +## Test Commands + +```bash +pnpm test +pnpm test:local +``` + +## Deployment Commands + +```bash +npx hardhat lz:deploy +``` + +## Wiring Commands + +```bash +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Verification Commands + +```bash +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts +``` + +## Files Safe to Modify + +- `contracts/` +- `layerzero.config.ts` +- `hardhat.config.ts` +- `deploy/` +- `tasks/` +- `test/` diff --git a/examples/onft721/CLAUDE.md b/examples/onft721/CLAUDE.md new file mode 100644 index 0000000000..ed0700b2ad --- /dev/null +++ b/examples/onft721/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md - ONFT721 Example + +## What This Example Is + +A reference implementation of an **Omnichain Non-Fungible Token (ONFT721)** - an NFT standard that can be transferred across multiple blockchains. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/MyONFT721.sol` | ONFT721 contract | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | +| `deploy/MyONFT721.ts` | Deployment script | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## Common Tasks + +| Command | Purpose | +|---------|---------| +| `pnpm compile` | Compile contracts | +| `npx hardhat lz:deploy` | Deploy ONFT721 | +| `npx hardhat lz:oapp:wire` | Wire pathways | + +## What Makes This Example Different + +- **NFT transfers**: Move ERC721 tokens across chains +- Token ID preserved across chains +- Burn on source, mint on destination + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Token doesn't exist" | Ensure token was minted on source chain | +| "Not owner" | Only token owner can initiate transfer | + +## Related Examples + +- `onft721-zksync/` - zkSync-specific ONFT721 +- `oft/` - Fungible token version diff --git a/examples/ovault-evm/CLAUDE.md b/examples/ovault-evm/CLAUDE.md new file mode 100644 index 0000000000..4f0cbbd148 --- /dev/null +++ b/examples/ovault-evm/CLAUDE.md @@ -0,0 +1,39 @@ +# CLAUDE.md - OVault EVM Example + +## What This Example Is + +A reference implementation of **OVault** - an omnichain vault pattern for cross-chain asset management. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/OVault.sol` | Omnichain vault contract | +| `layerzero.config.ts` | Pathway configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Vault pattern**: Cross-chain asset custody +- Deposit on one chain, manage across chains +- Useful for multi-chain DeFi protocols + +## Use Cases + +- Cross-chain yield aggregation +- Multi-chain treasury management +- Omnichain lending protocols + +## Related Examples + +- `oapp/` - Basic messaging +- `oft/` - Token transfers diff --git a/examples/uniswap-read/CLAUDE.md b/examples/uniswap-read/CLAUDE.md new file mode 100644 index 0000000000..cf6af991ec --- /dev/null +++ b/examples/uniswap-read/CLAUDE.md @@ -0,0 +1,46 @@ +# CLAUDE.md - Uniswap Read Example + +## What This Example Is + +A reference implementation demonstrating **OApp Read with Uniswap** - reading Uniswap pool data from other chains. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/UniswapReader.sol` | Uniswap data reader | +| `layerzero.config.ts` | Read channel configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:read:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **Real-world read use case**: Practical Uniswap integration +- Demonstrates reading DEX data cross-chain +- Read channels for efficient data queries + +## Use Cases + +- Cross-chain price feeds +- Multi-chain DEX aggregation +- Arbitrage detection + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Pool not found" | Verify Uniswap pool address | +| Read fails | Check read channel configuration | + +## Related Examples + +- `oapp-read/` - Basic OApp Read +- `view-pure-read/` - View/pure function reads diff --git a/examples/view-pure-read/CLAUDE.md b/examples/view-pure-read/CLAUDE.md new file mode 100644 index 0000000000..7876103c48 --- /dev/null +++ b/examples/view-pure-read/CLAUDE.md @@ -0,0 +1,39 @@ +# CLAUDE.md - View Pure Read Example + +## What This Example Is + +A reference implementation of **reading view/pure functions** from other chains - demonstrates calling read-only functions cross-chain. + +## Key Files + +| File | Purpose | +|------|---------| +| `contracts/ViewPureReader.sol` | View function reader | +| `layerzero.config.ts` | Read channel configuration | +| `hardhat.config.ts` | Network definitions | + +## Quick Start + +```bash +cp .env.example .env +pnpm install && pnpm compile +npx hardhat lz:deploy +npx hardhat lz:read:wire --oapp-config layerzero.config.ts +``` + +## What Makes This Example Different + +- **View/pure functions**: Read-only contract calls +- No state changes on destination +- Efficient data retrieval + +## Use Cases + +- Reading token balances across chains +- Querying contract state +- Cross-chain data aggregation + +## Related Examples + +- `oapp-read/` - Basic OApp Read +- `uniswap-read/` - Real-world read example diff --git a/packages/CLAUDE.md b/packages/CLAUDE.md new file mode 100644 index 0000000000..f0d3665bbf --- /dev/null +++ b/packages/CLAUDE.md @@ -0,0 +1,185 @@ +# CLAUDE.md - Packages Directory + +This directory contains **reusable libraries** for building and deploying LayerZero applications. + +## Quick Reference + +**Most users should start here:** +```typescript +import { ... } from '@layerzerolabs/toolbox-hardhat' +``` + +This package re-exports the most commonly used types and utilities. + +## Package Hierarchy + +``` + toolbox-hardhat (main entry point) + │ + ┌───────────────┼───────────────┐ + │ │ │ + ▼ ▼ ▼ + ua-devtools- devtools-evm- protocol-devtools- + evm-hardhat hardhat evm + (OApp/OFT (deploy, (DVN, Executor + tasks) HRE utils) config) + │ │ │ + └───────┬───────┴───────┬───────┘ + │ │ + ▼ ▼ + devtools-evm devtools + (EVM types) (core types) +``` + +## Package Categories + +### User-Facing Packages + +| Package | Purpose | When to Use | +|---------|---------|-------------| +| `toolbox-hardhat` | **Main entry point** for Hardhat projects | Always import from here first | +| `toolbox-foundry` | Foundry deployment tools | Foundry-based projects | +| `create-lz-oapp` | Project scaffolding CLI | Starting new projects | + +### Contract Packages + +| Package | Purpose | Key Exports | +|---------|---------|-------------| +| `oft-evm` | OFT token standard | `OFT.sol`, `OFTAdapter.sol` | +| `oapp-evm` | OApp messaging base | `OApp.sol`, `OAppReceiver.sol` | +| `onft-evm` | ONFT NFT standard | `ONFT721.sol` | +| `oft-evm-upgradeable` | Upgradeable OFT | `OFTUpgradeable.sol` | +| `oapp-evm-upgradeable` | Upgradeable OApp | `OAppUpgradeable.sol` | + +### Task Packages (Hardhat) + +| Package | Tasks Provided | +|---------|----------------| +| `ua-devtools-evm-hardhat` | `lz:oapp:wire`, `lz:oapp:config:get`, `lz:oapp:peers:get` | +| `devtools-evm-hardhat` | `lz:deploy`, `lz:healthcheck:validate-rpcs` | + +### Core Type Packages + +| Package | Purpose | Key Types | +|---------|---------|-----------| +| `devtools` | Core omnichain types | `OmniPoint`, `OmniGraph`, `OmniNode`, `OmniEdge` | +| `devtools-evm` | EVM-specific types | `OmniContract` | +| `devtools-evm-hardhat` | Hardhat integration | `OmniPointHardhat` | + +### Non-EVM Packages + +| Package | Purpose | +|---------|---------| +| `devtools-solana` | Solana integration | +| `devtools-move` | Aptos/Move integration | +| `devtools-ton` | TON integration | +| `oft-move` | Move OFT implementation | + +### Utility Packages + +| Package | Purpose | +|---------|---------| +| `metadata-tools` | Fetch DVN addresses, default configs | +| `io-devtools` | File I/O, prompts, logging | +| `build-lz-options` | Build LayerZero options bytes | +| `decode-lz-options` | Decode LayerZero options bytes | +| `verify-contract` | Contract verification helpers | + +## Package Naming Convention + +Format: `[domain-][-modifier]` + +- `devtools` → Core, chain-agnostic +- `devtools-evm` → EVM-specific +- `devtools-evm-hardhat` → EVM + Hardhat framework +- `ua-devtools-evm-hardhat` → User Application domain + EVM + Hardhat +- `protocol-devtools-evm` → Protocol domain + EVM + +## Key Types + +### OmniPoint +A contract location in the omnichain environment: +```typescript +interface OmniPoint { + eid: EndpointId // Chain identifier + address: string // Contract address +} +``` + +### OmniGraph +The full configuration of an omnichain application: +```typescript +interface OmniGraph { + contracts: OmniNode[] // Contracts with their configs + connections: OmniEdge[] // Pathways between contracts +} +``` + +### OmniPointHardhat +Hardhat-specific OmniPoint using contract names: +```typescript +interface OmniPointHardhat { + eid: EndpointId + contractName: string // Resolved via hardhat-deploy +} +``` + +## Development Commands + +```bash +# Build a specific package +pnpm build --filter @layerzerolabs/ + +# Test a specific package +pnpm test:local --filter @layerzerolabs/ + +# Lint a specific package +pnpm lint:fix --filter @layerzerolabs/ +``` + +## Adding a New Package + +1. Create directory under `packages/` +2. Add `package.json` with standard fields: + ```json + { + "name": "@layerzerolabs/", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "sideEffects": false + } + ``` +3. Add `tsconfig.json` extending base config +4. Add `tsup.config.ts` for bundling +5. Create `src/index.ts` as entry point +6. Run `pnpm install` from monorepo root +7. Run `pnpm changeset` after making changes + +## Common Patterns + +### Importing in Examples + +```typescript +// In hardhat.config.ts +import '@layerzerolabs/toolbox-hardhat' + +// In layerzero.config.ts +import type { OmniPointHardhat } from '@layerzerolabs/toolbox-hardhat' +``` + +### Creating Contract Factories + +```typescript +import { createConnectedContractFactory } from '@layerzerolabs/devtools-evm-hardhat' + +const contractFactory = createConnectedContractFactory() +const contract = await contractFactory({ eid, contractName: 'MyOFT' }) +``` + +### Getting HRE by Network + +```typescript +import { getHreByNetworkName } from '@layerzerolabs/devtools-evm-hardhat' + +const hre = await getHreByNetworkName('ethereum-mainnet') +``` diff --git a/packages/devtools-evm-hardhat/AGENTS.md b/packages/devtools-evm-hardhat/AGENTS.md new file mode 100644 index 0000000000..6b147cf018 --- /dev/null +++ b/packages/devtools-evm-hardhat/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md - @layerzerolabs/devtools-evm-hardhat + +## Build Commands + +```bash +pnpm build --filter @layerzerolabs/devtools-evm-hardhat +``` + +## Test Commands + +```bash +pnpm test:local --filter @layerzerolabs/devtools-evm-hardhat +``` + +## Lint Commands + +```bash +pnpm lint:fix --filter @layerzerolabs/devtools-evm-hardhat +``` + +## Type Check + +```bash +pnpm typecheck --filter @layerzerolabs/devtools-evm-hardhat +``` + +## Key Files + +- `src/tasks/deploy.ts` - lz:deploy task +- `src/runtime.ts` - HRE utilities +- `src/contracts.ts` - Contract factories + +## Files Safe to Modify + +- `src/` +- `test/` +- `package.json` +- `tsconfig.json` + +## After Changes + +```bash +pnpm changeset +``` diff --git a/packages/devtools-evm-hardhat/CLAUDE.md b/packages/devtools-evm-hardhat/CLAUDE.md new file mode 100644 index 0000000000..04acc64a8d --- /dev/null +++ b/packages/devtools-evm-hardhat/CLAUDE.md @@ -0,0 +1,119 @@ +# CLAUDE.md - @layerzerolabs/devtools-evm-hardhat + +## Package Purpose + +Provides **Hardhat integration utilities** for EVM chains - HRE helpers, contract factories, deployment tasks, and network utilities. + +## Key Exports + +```typescript +import { + // HRE helpers + getHreByNetworkName, + createGetHreByEid, + + // Contract factories + createContractFactory, + createConnectedContractFactory, + + // Types + OmniPointHardhat, +} from '@layerzerolabs/devtools-evm-hardhat' +``` + +## Tasks Provided + +| Task | Description | +|------|-------------| +| `lz:deploy` | Deploy contracts to all configured networks | +| `lz:healthcheck:validate-rpcs` | Validate RPC endpoints | +| `lz:healthcheck:validate-safe-configs` | Validate Safe configurations | +| `lz:export:deployments:typescript` | Export deployments as TypeScript | + +## When to Use + +- Getting Hardhat Runtime Environment by network name or EID +- Creating contract instances across networks +- Deploying contracts +- Validating network configurations + +## Key Utilities + +### Getting HRE by Network Name + +```typescript +import { getHreByNetworkName } from '@layerzerolabs/devtools-evm-hardhat' + +const hre = await getHreByNetworkName('ethereum-mainnet') +``` + +### Getting HRE by Endpoint ID + +```typescript +import { createGetHreByEid } from '@layerzerolabs/devtools-evm-hardhat' + +const getHreByEid = createGetHreByEid() +const hre = await getHreByEid(EndpointId.ETHEREUM_MAINNET) +``` + +### Creating Contract Factories + +```typescript +import { createConnectedContractFactory } from '@layerzerolabs/devtools-evm-hardhat' + +const factory = createConnectedContractFactory() + +// By contract name (uses hardhat-deploy) +const contract = await factory({ + eid: EndpointId.ETHEREUM_MAINNET, + contractName: 'MyOFT' +}) + +// By address +const contract = await factory({ + eid: EndpointId.ETHEREUM_MAINNET, + address: '0x...' +}) +``` + +## Hardhat Config Extension + +This package extends the Hardhat network config with `eid`: + +```typescript +// hardhat.config.ts +const config: HardhatUserConfig = { + networks: { + 'ethereum-mainnet': { + eid: EndpointId.ETHEREUM_MAINNET, // LayerZero Endpoint ID + url: '...', + accounts: [...], + }, + }, +} +``` + +## File Structure + +``` +src/ +├── tasks/ +│ ├── deploy.ts # lz:deploy task +│ ├── healthcheck/ # Validation tasks +│ └── simulation/ # Simulation utilities +├── runtime.ts # HRE utilities +├── contracts.ts # Contract factories +└── index.ts # Main exports +``` + +## Dependencies + +- `@layerzerolabs/devtools-evm` - EVM-specific types +- `hardhat` - Hardhat core +- `hardhat-deploy` - Deployment plugin + +## Testing + +```bash +pnpm test:local --filter @layerzerolabs/devtools-evm-hardhat +``` diff --git a/packages/oapp-evm/AGENTS.md b/packages/oapp-evm/AGENTS.md new file mode 100644 index 0000000000..517f670f9f --- /dev/null +++ b/packages/oapp-evm/AGENTS.md @@ -0,0 +1,46 @@ +# AGENTS.md - @layerzerolabs/oapp-evm + +## Build Commands + +```bash +pnpm build --filter @layerzerolabs/oapp-evm +``` + +## Test Commands + +```bash +pnpm test:local --filter @layerzerolabs/oapp-evm +``` + +## Lint Commands + +```bash +pnpm lint:fix --filter @layerzerolabs/oapp-evm +``` + +## Compile Contracts + +```bash +forge build +# or via hardhat in examples +``` + +## Key Contract Files + +- `contracts/oapp/OApp.sol` - Base OApp +- `contracts/oapp/OAppSender.sol` - Send-only +- `contracts/oapp/OAppReceiver.sol` - Receive-only +- `contracts/oapp/OAppCore.sol` - Core logic + +## Files Safe to Modify + +- `contracts/` +- `src/` +- `test/` +- `package.json` + +## After Changes + +```bash +pnpm changeset +``` diff --git a/packages/oapp-evm/CLAUDE.md b/packages/oapp-evm/CLAUDE.md new file mode 100644 index 0000000000..3cdd18bc68 --- /dev/null +++ b/packages/oapp-evm/CLAUDE.md @@ -0,0 +1,155 @@ +# CLAUDE.md - @layerzerolabs/oapp-evm + +## Package Purpose + +Provides the **OApp (Omnichain Application) Solidity contracts** for EVM chains - the foundational pattern for cross-chain messaging in LayerZero. + +## Key Exports + +### Contracts (Solidity) + +| Contract | Purpose | +|----------|---------| +| `OApp.sol` | Base OApp - full send/receive | +| `OAppSender.sol` | Send-only OApp | +| `OAppReceiver.sol` | Receive-only OApp | +| `OAppCore.sol` | Core logic (endpoint, delegate, peers) | + +### TypeScript + +```typescript +import { + // Types for configuration + OAppOmniGraphHardhat, + OAppFactory, +} from '@layerzerolabs/oapp-evm' +``` + +## When to Use + +- Building custom cross-chain applications +- Creating messaging protocols +- Understanding how OFT/ONFT work internally + +## Contract Inheritance + +``` + OAppCore (endpoint, peers) + ┌────┴────┐ + │ │ + OAppSender OAppReceiver + │ │ + └────┬────┘ + │ + OApp +``` + +## Usage in Solidity + +### Basic OApp + +```solidity +import { OApp } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol"; + +contract MyOApp is OApp { + constructor( + address _endpoint, + address _delegate + ) OApp(_endpoint, _delegate) {} + + // Implement _lzReceive to handle incoming messages + function _lzReceive( + Origin calldata _origin, + bytes32 _guid, + bytes calldata _payload, + address _executor, + bytes calldata _extraData + ) internal override { + // Handle message + } +} +``` + +### Sending Messages + +```solidity +function sendMessage(uint32 _dstEid, bytes memory _payload) external payable { + _lzSend( + _dstEid, + _payload, + _options, + MessagingFee(msg.value, 0), + payable(msg.sender) + ); +} +``` + +### Quoting Fees + +```solidity +function quote( + uint32 _dstEid, + bytes memory _payload, + bytes memory _options +) external view returns (MessagingFee memory) { + return _quote(_dstEid, _payload, _options, false); +} +``` + +## Message Lifecycle + +``` +Source Chain: +1. User calls your send function +2. _lzSend() submits to Endpoint +3. Endpoint emits PacketSent event + +LayerZero Network: +4. DVNs verify the message +5. Executor picks up for delivery + +Destination Chain: +6. Executor calls lzReceive on Endpoint +7. Endpoint calls your _lzReceive() +``` + +## Key Concepts + +### Peer Setup +```solidity +// Each OApp must know its counterpart on other chains +setPeer(dstEid, peer) // Sets peers[dstEid] = peer +``` + +### Endpoint Delegates +```solidity +// Delegate can configure the OApp via Endpoint +setDelegate(delegate) +``` + +## Key Functions + +| Function | Purpose | +|----------|---------| +| `_lzSend()` | Send cross-chain message | +| `_lzReceive()` | Handle incoming message (override this) | +| `_quote()` | Get fee quote | +| `setPeer()` | Set peer on destination chain | +| `setDelegate()` | Set delegate address | + +## Dependencies + +- `@layerzerolabs/lz-evm-protocol-v2` - Endpoint interfaces +- `@openzeppelin/contracts` - Ownable + +## Testing + +```bash +pnpm test:local --filter @layerzerolabs/oapp-evm +``` + +## Related Packages + +- `oft-evm` - Token transfers (builds on OApp) +- `onft-evm` - NFT transfers (builds on OApp) +- `oapp-evm-upgradeable` - Upgradeable variants diff --git a/packages/oft-evm/AGENTS.md b/packages/oft-evm/AGENTS.md new file mode 100644 index 0000000000..532c3c7b1d --- /dev/null +++ b/packages/oft-evm/AGENTS.md @@ -0,0 +1,45 @@ +# AGENTS.md - @layerzerolabs/oft-evm + +## Build Commands + +```bash +pnpm build --filter @layerzerolabs/oft-evm +``` + +## Test Commands + +```bash +pnpm test:local --filter @layerzerolabs/oft-evm +``` + +## Lint Commands + +```bash +pnpm lint:fix --filter @layerzerolabs/oft-evm +``` + +## Compile Contracts + +```bash +forge build +# or via hardhat in examples +``` + +## Key Contract Files + +- `contracts/OFT.sol` - Base OFT +- `contracts/OFTAdapter.sol` - ERC20 adapter +- `contracts/OFTCore.sol` - Core logic + +## Files Safe to Modify + +- `contracts/` +- `src/` +- `test/` +- `package.json` + +## After Changes + +```bash +pnpm changeset +``` diff --git a/packages/oft-evm/CLAUDE.md b/packages/oft-evm/CLAUDE.md new file mode 100644 index 0000000000..a220e51f40 --- /dev/null +++ b/packages/oft-evm/CLAUDE.md @@ -0,0 +1,122 @@ +# CLAUDE.md - @layerzerolabs/oft-evm + +## Package Purpose + +Provides the **OFT (Omnichain Fungible Token) Solidity contracts** for EVM chains - the standard for cross-chain token transfers in LayerZero. + +## Key Exports + +### Contracts (Solidity) + +| Contract | Purpose | +|----------|---------| +| `OFT.sol` | Base OFT - mint/burn token | +| `OFTAdapter.sol` | Adapter for existing ERC20 tokens | +| `OFTCore.sol` | Core logic (inherited by OFT) | + +### TypeScript + +```typescript +import { + // Types + OFTFactory, + OFTOmniGraphHardhat, +} from '@layerzerolabs/oft-evm' +``` + +## When to Use + +- Creating a new cross-chain token +- Wrapping an existing ERC20 for cross-chain transfers +- Building custom OFT variants + +## Contract Inheritance + +``` + OApp (messaging base) + │ + ▼ + OFTCore + ┌────┴────┐ + │ │ + OFT OFTAdapter + (mint/burn) (lock/unlock) +``` + +## OFT vs OFTAdapter + +| Feature | OFT | OFTAdapter | +|---------|-----|------------| +| Token creation | New token | Wraps existing | +| Source chain behavior | Burn | Lock | +| Destination chain behavior | Mint | Mint (new OFT) | +| Use case | New tokens | Existing tokens | + +## Usage in Solidity + +### Creating an OFT + +```solidity +import { OFT } from "@layerzerolabs/oft-evm/contracts/OFT.sol"; + +contract MyOFT is OFT { + constructor( + string memory _name, + string memory _symbol, + address _lzEndpoint, + address _delegate + ) OFT(_name, _symbol, _lzEndpoint, _delegate) {} +} +``` + +### Creating an OFT Adapter + +```solidity +import { OFTAdapter } from "@layerzerolabs/oft-evm/contracts/OFTAdapter.sol"; + +contract MyOFTAdapter is OFTAdapter { + constructor( + address _token, // Existing ERC20 + address _lzEndpoint, + address _delegate + ) OFTAdapter(_token, _lzEndpoint, _delegate) {} +} +``` + +## Cross-Chain Transfer Flow + +``` +1. User calls send() on source OFT +2. OFT burns tokens (or locks if adapter) +3. LayerZero message sent via _lzSend() +4. DVNs verify the message +5. Executor delivers to destination +6. Destination OFT receives via _lzReceive() +7. Destination OFT mints tokens (or unlocks if source adapter) +``` + +## Key Functions + +| Function | Purpose | +|----------|---------| +| `send()` | Initiate cross-chain transfer | +| `quoteSend()` | Get fee quote for transfer | +| `_debit()` | Internal - burn/lock tokens | +| `_credit()` | Internal - mint/unlock tokens | + +## Dependencies + +- `@layerzerolabs/oapp-evm` - OApp base contracts +- `@openzeppelin/contracts` - ERC20, Ownable + +## Testing + +```bash +pnpm test:local --filter @layerzerolabs/oft-evm +``` + +## Related Packages + +- `oft-evm-upgradeable` - Upgradeable OFT variants +- `oft-alt-evm` - Alternative OFT implementation +- `oapp-evm` - Base messaging contracts diff --git a/packages/test-devtools-ton/README.md b/packages/test-devtools-ton/README.md new file mode 100644 index 0000000000..b556894007 --- /dev/null +++ b/packages/test-devtools-ton/README.md @@ -0,0 +1,53 @@ +

+ + LayerZero + +

+ +

@layerzerolabs/test-devtools-ton

+ +

Helpers for testing LayerZero TON contracts

+ +## Installation + +```bash +pnpm add -D @layerzerolabs/test-devtools-ton + +yarn add -D @layerzerolabs/test-devtools-ton + +npm install -D @layerzerolabs/test-devtools-ton +``` + +## Purpose + +This package provides testing utilities and helpers for LayerZero contracts on the TON (The Open Network) blockchain. + +## Usage + +```typescript +import { ... } from '@layerzerolabs/test-devtools-ton' +``` + +## Development + +### Testing + +```bash +# Run unit tests +pnpm test + +# Run E2E tests +pnpm test:e2e +``` + +### Linting + +```bash +pnpm lint +pnpm lint:fix +``` + +## Related Packages + +- `@layerzerolabs/devtools-ton` - TON devtools +- `@layerzerolabs/test-devtools` - General testing utilities diff --git a/packages/toolbox-hardhat/AGENTS.md b/packages/toolbox-hardhat/AGENTS.md new file mode 100644 index 0000000000..56d930f749 --- /dev/null +++ b/packages/toolbox-hardhat/AGENTS.md @@ -0,0 +1,38 @@ +# AGENTS.md - @layerzerolabs/toolbox-hardhat + +## Build Commands + +```bash +pnpm build --filter @layerzerolabs/toolbox-hardhat +``` + +## Test Commands + +```bash +pnpm test:local --filter @layerzerolabs/toolbox-hardhat +``` + +## Lint Commands + +```bash +pnpm lint:fix --filter @layerzerolabs/toolbox-hardhat +``` + +## Type Check + +```bash +pnpm typecheck --filter @layerzerolabs/toolbox-hardhat +``` + +## Files Safe to Modify + +- `src/` +- `test/` +- `package.json` +- `tsconfig.json` + +## After Changes + +```bash +pnpm changeset +``` diff --git a/packages/toolbox-hardhat/CLAUDE.md b/packages/toolbox-hardhat/CLAUDE.md new file mode 100644 index 0000000000..c5f05f027b --- /dev/null +++ b/packages/toolbox-hardhat/CLAUDE.md @@ -0,0 +1,84 @@ +# CLAUDE.md - @layerzerolabs/toolbox-hardhat + +## Package Purpose + +The **main entry point** for Hardhat-based LayerZero development. This package re-exports types and utilities from multiple underlying packages, providing a single import for most use cases. + +## Key Exports + +```typescript +import { + // Types + OmniPointHardhat, + OAppEnforcedOption, + + // Endpoint IDs (re-exported from lz-definitions) + EndpointId, + + // Option builders + ExecutorOptionType, + + // Most commonly used utilities +} from '@layerzerolabs/toolbox-hardhat' +``` + +## When to Use + +- **Always start here** for Hardhat projects +- Import `@layerzerolabs/toolbox-hardhat` in your `hardhat.config.ts` +- Use in `layerzero.config.ts` for type definitions + +## What This Package Provides + +| Feature | Source Package | +|---------|----------------| +| `OmniPointHardhat` type | `devtools-evm-hardhat` | +| Hardhat tasks (`lz:*`) | `ua-devtools-evm-hardhat`, `devtools-evm-hardhat` | +| Contract factories | `devtools-evm-hardhat` | +| `EndpointId` enum | `lz-definitions` | +| Option builders | `lz-v2-utilities` | + +## Common Usage + +### In hardhat.config.ts +```typescript +import '@layerzerolabs/toolbox-hardhat' +``` + +This auto-registers all LayerZero Hardhat tasks. + +### In layerzero.config.ts +```typescript +import type { OmniPointHardhat } from '@layerzerolabs/toolbox-hardhat' + +const contract: OmniPointHardhat = { + eid: EndpointId.BASESEP_V2_TESTNET, + contractName: 'MyOFT', +} +``` + +## Tasks Registered + +When you import this package, these Hardhat tasks become available: + +| Task | Purpose | +|------|---------| +| `lz:deploy` | Deploy contracts to all configured networks | +| `lz:oapp:wire` | Configure pathways (setPeer, setConfig) | +| `lz:oapp:config:get` | Display current configuration | +| `lz:oapp:config:get:default` | Show LayerZero default config | +| `lz:oapp:peers:get` | Show peer relationships | + +## Dependencies + +This package depends on and re-exports from: +- `@layerzerolabs/devtools-evm-hardhat` +- `@layerzerolabs/ua-devtools-evm-hardhat` +- `@layerzerolabs/protocol-devtools-evm` +- `@layerzerolabs/lz-definitions` + +## Testing + +```bash +pnpm test:local --filter @layerzerolabs/toolbox-hardhat +``` diff --git a/packages/toolbox-hardhat/README.md b/packages/toolbox-hardhat/README.md index 483239f637..9e3f0f02ee 100644 --- a/packages/toolbox-hardhat/README.md +++ b/packages/toolbox-hardhat/README.md @@ -275,5 +275,52 @@ This package comes with several `hardhat` tasks to speed up your workflow. In or Wires the individual `OApp` contracts together, calling `setPeer`. ```bash -pnpm hardhat lz:oapp:wire +pnpm hardhat lz:oapp:wire --oapp-config layerzero.config.ts ``` + +### Full Task Reference + +This package provides the following Hardhat tasks: + +#### Core Tasks + +| Task | Description | +|------|-------------| +| `lz:deploy` | Deploy contracts to all configured networks | +| `lz:healthcheck:validate-rpcs` | Validate RPC endpoint connectivity | +| `lz:export:deployments:typescript` | Export deployments as TypeScript | + +#### OApp Configuration Tasks + +| Task | Description | +|------|-------------| +| `lz:oapp:wire` | Wire OApp pathways (setPeer, setConfig, setEnforcedOptions) | +| `lz:oapp:config:get` | Get current on-chain configuration | +| `lz:oapp:config:get:default` | Get LayerZero default configuration | +| `lz:oapp:config:get:executor` | Get executor configuration | +| `lz:oapp:config:init` | Initialize a new layerzero.config.ts | +| `lz:oapp:peers:get` | Get peer relationships | +| `lz:oapp:enforced:opts:get` | Get enforced options | + +#### OApp Read Tasks + +| Task | Description | +|------|-------------| +| `lz:read:wire` | Wire OApp Read channels | +| `lz:read:config:get` | Get OApp Read configuration | +| `lz:read:config:get:channel` | Get read channel configuration | + +#### Utility Tasks + +| Task | Description | +|------|-------------| +| `lz:errors:decode` | Decode LayerZero error messages | +| `lz:errors:list` | List all known LayerZero errors | +| `lz:ownable:transfer:ownership` | Transfer contract ownership | + +## Related Documentation + +- [WORKFLOW.md](../../WORKFLOW.md) - Complete deployment workflow +- [DEBUGGING.md](../../DEBUGGING.md) - Troubleshooting guide +- [CHEATSHEET.md](../../CHEATSHEET.md) - Quick reference +- [Official Documentation](https://docs.layerzero.network/) diff --git a/packages/ua-devtools-evm-hardhat/AGENTS.md b/packages/ua-devtools-evm-hardhat/AGENTS.md new file mode 100644 index 0000000000..58496c5ab5 --- /dev/null +++ b/packages/ua-devtools-evm-hardhat/AGENTS.md @@ -0,0 +1,45 @@ +# AGENTS.md - @layerzerolabs/ua-devtools-evm-hardhat + +## Build Commands + +```bash +pnpm build --filter @layerzerolabs/ua-devtools-evm-hardhat +``` + +## Test Commands + +```bash +pnpm test:local --filter @layerzerolabs/ua-devtools-evm-hardhat +``` + +## Lint Commands + +```bash +pnpm lint:fix --filter @layerzerolabs/ua-devtools-evm-hardhat +``` + +## Type Check + +```bash +pnpm typecheck --filter @layerzerolabs/ua-devtools-evm-hardhat +``` + +## Key Task Files + +- `src/tasks/oapp/wire/` - Wire task implementation +- `src/tasks/oapp/config.get.ts` - Config get task +- `src/tasks/oapp/peers.get.ts` - Peers get task +- `src/tasks/errors/` - Error handling tasks + +## Files Safe to Modify + +- `src/` +- `test/` +- `package.json` +- `tsconfig.json` + +## After Changes + +```bash +pnpm changeset +``` diff --git a/packages/ua-devtools-evm-hardhat/CLAUDE.md b/packages/ua-devtools-evm-hardhat/CLAUDE.md new file mode 100644 index 0000000000..3f3d7b650f --- /dev/null +++ b/packages/ua-devtools-evm-hardhat/CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md - @layerzerolabs/ua-devtools-evm-hardhat + +## Package Purpose + +Provides **Hardhat tasks for OApp and OFT operations** - wiring pathways, checking configuration, and managing cross-chain application state. + +## Key Exports + +This package primarily provides Hardhat tasks (auto-registered when imported). + +## Tasks Provided + +### Core Wiring Tasks + +| Task | Description | +|------|-------------| +| `lz:oapp:wire` | Main wiring task - sets peers, DVN config, enforced options | +| `lz:oapp:config:get` | Get current on-chain configuration | +| `lz:oapp:config:get:default` | Get LayerZero default configuration | +| `lz:oapp:config:get:executor` | Get executor configuration | +| `lz:oapp:peers:get` | Get peer relationships | +| `lz:oapp:enforced:opts:get` | Get enforced options | +| `lz:oapp:config:init` | Initialize a new layerzero.config.ts | + +### OApp Read Tasks + +| Task | Description | +|------|-------------| +| `lz:read:wire` | Wire OApp Read configurations | +| `lz:read:config:get` | Get OApp Read configuration | +| `lz:read:config:get:channel` | Get channel configuration | + +### Utility Tasks + +| Task | Description | +|------|-------------| +| `lz:errors:decode` | Decode LayerZero error messages | +| `lz:errors:list` | List known LayerZero errors | +| `lz:ownable:transfer:ownership` | Transfer contract ownership | + +## When to Use + +- Configuring OApp/OFT deployments +- Checking current on-chain state +- Debugging configuration mismatches +- Transferring ownership + +## Task Implementation Location + +``` +src/tasks/ +├── oapp/ +│ ├── wire/ # lz:oapp:wire implementation +│ ├── config.get.ts # lz:oapp:config:get +│ ├── peers.get.ts # lz:oapp:peers:get +│ └── ... +├── errors/ +│ ├── decode.ts # lz:errors:decode +│ └── list.ts # lz:errors:list +└── ownable/ + └── transfer.ownership.ts +``` + +## Common Usage + +```bash +# Wire all pathways from config +npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts + +# Check current configuration +npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts + +# Check peer setup +npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts + +# Decode an error +npx hardhat lz:errors:decode --error 0x12345678 +``` + +## Dependencies + +- `@layerzerolabs/ua-devtools-evm` - Core UA (User Application) logic +- `@layerzerolabs/devtools-evm-hardhat` - Hardhat integration utilities +- `@layerzerolabs/devtools` - Core types + +## Testing + +```bash +pnpm test:local --filter @layerzerolabs/ua-devtools-evm-hardhat +``` From aa68aa89564423125a7b0d3b640d2a14ece0691a Mon Sep 17 00:00:00 2001 From: Krak Date: Mon, 19 Jan 2026 16:19:58 -0800 Subject: [PATCH 3/3] fix: remove CLAUDE.md files for local-only examples and restore beta warning - Remove CLAUDE.md files for examples that only exist locally: - examples/frontend/ - examples/oft-composer-library/ - examples/oft-evm-solana-move/ - examples/oft-solana-composer-library/ - examples/oft-tron/ - Restore beta warning in README.md - Restore original navigation links (DEVELOPMENT.md) --- README.md | 6 ++- examples/frontend/CLAUDE.md | 37 --------------- examples/oft-composer-library/CLAUDE.md | 45 ------------------- examples/oft-evm-solana-move/CLAUDE.md | 43 ------------------ .../oft-solana-composer-library/CLAUDE.md | 37 --------------- examples/oft-tron/CLAUDE.md | 43 ------------------ 6 files changed, 5 insertions(+), 206 deletions(-) delete mode 100644 examples/frontend/CLAUDE.md delete mode 100644 examples/oft-composer-library/CLAUDE.md delete mode 100644 examples/oft-evm-solana-move/CLAUDE.md delete mode 100644 examples/oft-solana-composer-library/CLAUDE.md delete mode 100644 examples/oft-tron/CLAUDE.md diff --git a/README.md b/README.md index 947d40eddb..4d13250b5d 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,15 @@

LayerZero Developer Utilities

- Workflow Guide | Debugging | Cheatsheet | Examples + Development | Cheatsheet | Examples

--- +**Please note** that this repository is in a **beta** state and backwards-incompatible changes might be introduced in future releases. While we strive to comply to [semver](https://semver.org/), we can not guarantee to avoid breaking changes in minor releases. + +--- + ## Quick Start (External Developers) The fastest way to start building with LayerZero: diff --git a/examples/frontend/CLAUDE.md b/examples/frontend/CLAUDE.md deleted file mode 100644 index e64d445e46..0000000000 --- a/examples/frontend/CLAUDE.md +++ /dev/null @@ -1,37 +0,0 @@ -# CLAUDE.md - Frontend Example - -## What This Example Is - -A reference implementation of a **frontend application** for interacting with LayerZero OApps - demonstrates client-side integration patterns. - -## Key Files - -| File | Purpose | -|------|---------| -| `src/` | Frontend source code | -| `package.json` | Frontend dependencies | - -## Quick Start - -```bash -pnpm install -pnpm dev # or pnpm start -``` - -## What Makes This Example Different - -- **Client-side integration**: Frontend patterns for LayerZero -- Shows how to quote fees, send transactions -- User-facing application patterns - -## Key Patterns - -- Fee quoting before transactions -- Wallet connection handling -- Transaction status tracking -- LayerZero Scan integration - -## Related Examples - -- `oft/` - Backend OFT to interact with -- `oapp/` - Backend OApp to interact with diff --git a/examples/oft-composer-library/CLAUDE.md b/examples/oft-composer-library/CLAUDE.md deleted file mode 100644 index cc8be13a04..0000000000 --- a/examples/oft-composer-library/CLAUDE.md +++ /dev/null @@ -1,45 +0,0 @@ -# CLAUDE.md - OFT Composer Library Example - -## What This Example Is - -A reference implementation of an **OFT Composer** - allows composing additional logic on top of OFT transfers (e.g., swap after receive). - -## Key Files - -| File | Purpose | -|------|---------| -| `contracts/` | Composer contracts | -| `layerzero.config.ts` | Pathway configuration | -| `hardhat.config.ts` | Network definitions | - -## Quick Start - -```bash -cp .env.example .env -pnpm install && pnpm compile -npx hardhat lz:deploy -npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts -``` - -## What Makes This Example Different - -- **Compose pattern**: Execute additional logic after OFT transfer -- Chain actions together (transfer → swap → stake) -- Builds on OFT with lzCompose - -## Use Cases - -- Transfer then swap on destination -- Transfer then stake -- Multi-step cross-chain workflows - -## Compose Flow - -``` -Source → OFT Send → Destination OFT Receive → Composer Callback -``` - -## Related Examples - -- `oft/` - Basic OFT -- `oft-solana-composer-library/` - Solana version diff --git a/examples/oft-evm-solana-move/CLAUDE.md b/examples/oft-evm-solana-move/CLAUDE.md deleted file mode 100644 index d264c02556..0000000000 --- a/examples/oft-evm-solana-move/CLAUDE.md +++ /dev/null @@ -1,43 +0,0 @@ -# CLAUDE.md - OFT EVM-Solana-Move Example - -## What This Example Is - -A reference implementation of **multi-VM OFT** - demonstrates token transfers across EVM, Solana, and Move (Aptos) chains simultaneously. - -## Key Files - -| File | Purpose | -|------|---------| -| `contracts/` | EVM contracts (Solidity) | -| `programs/` | Solana programs (Rust/Anchor) | -| `sources/` | Move modules | -| `layerzero.config.ts` | Multi-VM pathway configuration | - -## Prerequisites - -- Node.js + pnpm (EVM) -- Rust + Anchor (Solana) -- Aptos CLI (Move) - -## Quick Start - -```bash -cp .env.example .env - -# Build all platforms -pnpm compile # EVM -anchor build # Solana -aptos move compile # Move -``` - -## What Makes This Example Different - -- **Three VMs**: EVM + Solana + Move in one example -- Complex multi-VM pathway configuration -- Shows unified token across heterogeneous chains - -## Related Examples - -- `oft/` - EVM-only OFT -- `oft-solana/` - Solana OFT -- `oft-aptos-move/` - Aptos OFT diff --git a/examples/oft-solana-composer-library/CLAUDE.md b/examples/oft-solana-composer-library/CLAUDE.md deleted file mode 100644 index a043e14375..0000000000 --- a/examples/oft-solana-composer-library/CLAUDE.md +++ /dev/null @@ -1,37 +0,0 @@ -# CLAUDE.md - OFT Solana Composer Library Example - -## What This Example Is - -A reference implementation of **OFT Composer for Solana** - compose additional logic after OFT transfers on Solana. - -## Key Files - -| File | Purpose | -|------|---------| -| `programs/` | Solana composer programs | -| `Anchor.toml` | Anchor configuration | -| `layerzero.config.ts` | Pathway configuration | - -## Prerequisites - -- Rust toolchain -- Anchor CLI -- Solana CLI - -## Quick Start - -```bash -cp .env.example .env -anchor build -``` - -## What Makes This Example Different - -- **Solana compose pattern**: Post-transfer hooks on Solana -- Anchor-based implementation -- Bridges EVM compose patterns to Solana - -## Related Examples - -- `oft-solana/` - Basic Solana OFT -- `oft-composer-library/` - EVM version diff --git a/examples/oft-tron/CLAUDE.md b/examples/oft-tron/CLAUDE.md deleted file mode 100644 index ac8fe5ae92..0000000000 --- a/examples/oft-tron/CLAUDE.md +++ /dev/null @@ -1,43 +0,0 @@ -# CLAUDE.md - OFT Tron Example - -## What This Example Is - -A reference implementation of **OFT on Tron** - cross-chain token transfers with the Tron blockchain. - -## Key Files - -| File | Purpose | -|------|---------| -| `contracts/` | Tron-compatible contracts | -| `layerzero.config.ts` | Pathway configuration | -| Configuration files | Tron-specific setup | - -## Prerequisites - -- TronBox or compatible tooling -- Tron wallet setup - -## Quick Start - -```bash -cp .env.example .env -pnpm install -# See README for Tron-specific deployment -``` - -## What Makes This Example Different - -- **Tron integration**: Specific to Tron blockchain -- TRC20 token standard -- Tron-specific deployment flow - -## Tron Considerations - -- Different address format (base58) -- TronBox for development -- Energy/bandwidth for transactions - -## Related Examples - -- `oft/` - Standard EVM OFT -- Multi-VM examples for other chains