Skip to content

Commit 9613fb8

Browse files
nazreenshankars99
nazreen
authored and
shankars99
committed
DEVREL-549 docs: example READMEs specs + examples/oft README revamp (#1596)
1 parent ad717b6 commit 9613fb8

37 files changed

Lines changed: 2495 additions & 819 deletions

‎.changeset/odd-carrots-stare.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@layerzerolabs/oapp-example": minor
3+
---
4+
5+
reduce to 2 chains and revamp README

‎.changeset/perfect-bobcats-complain.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@layerzerolabs/mint-burn-oft-adapter-example": patch
3+
---
4+
5+
fix any type usage

‎.changeset/serious-beds-fetch.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@layerzerolabs/oft-example": minor
3+
---
4+
5+
revamp README, add mock deploy script, reduce to 2 chains

‎.changeset/tiny-books-drive.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@layerzerolabs/oft-adapter-example": minor
3+
---
4+
5+
revamp README, add mock deploy script, reduce to 2 chains

‎.changeset/wise-numbers-hammer.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@layerzerolabs/oft-upgradeable-example": minor
3+
---
4+
5+
revamp README, add mock deploy script, reduce to 2 chains, add send scripts

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Welcome to the **LayerZero Developer Tools Hub**. This repository houses everyth
3030
Visit our <a href="https://docs.layerzero.network/" style="color: #a77dff">developer docs</a> to get started building omnichain applications.
3131

3232
## Repository Structure
33+
3334
The primary folders that smart contract developers will find most useful are:
3435

3536
`examples/`: Contains various example projects demonstrating how to build with `OApp.sol` (Omnichain App Standard), `OFT.sol` (Omnichain Fungible Tokens), `ONFT.sol` (Omnichain Non-Fungible Tokens), and more. These examples serve as templates and learning resources.
@@ -88,7 +89,7 @@ pnpm build
8889

8990
This will build all the packages and examples in the repository.
9091

91-
Review the README for each individual `examples/` project to learn how to interact with and use each sample project.
92+
Review the README for each individual `examples/` project to learn how to interact with and use each sample project.
9293

9394
## Contributing
9495

‎docs/EXAMPLES_SPECS.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Example Specs
2+
3+
## Table of Contents
4+
5+
- [Audience](#audience)
6+
- [README Structure](#readme-structure)
7+
- [Example README Principles](#example-readme-principles)
8+
- [Example Code Principles](#example-code-principles)
9+
10+
## Audience
11+
12+
This guide is intended for both:
13+
- **Developers** maintaining or contributing to `/examples`
14+
- **Coding agents** (e.g. Cursor, Copilot, GPT) that assist with editing, reviewing, or scaffolding examples
15+
16+
AI agents should be pointed to this file via `AGENTS.md` or `.cursor/rules`.
17+
18+
Currently, this document will only detail the structure for the READMEs of the examples.
19+
20+
## README Structure
21+
22+
1. **Header**
23+
- Goal: Branding + promote docs site + entrypoint
24+
- Contents: LayerZero logo + links to docs and dev portal
25+
26+
2. **Example Title**
27+
- Goal: What the example will teach
28+
- Contents: Title + 1–2 sentence goal-style description
29+
30+
3. **Table of Contents**
31+
- Goal: Allow user to easily navigate the README
32+
- Contents: TOC of all headings
33+
34+
4. **Prerequisite Knowledge**
35+
- Goal: What to understand before running the example
36+
- Contents: e.g., What is an OApp? What is an OFT?
37+
38+
5. **Introduction** _(optional)_
39+
- Goal: High-level context on what this example covers
40+
- Contents: Brief explanation; skip if title + prerequisites suffice
41+
42+
6. **Requirements**
43+
- Goal: What needs to be installed
44+
- Contents: Tools + versions; optionally call out testnet funding needs
45+
46+
7. **Scaffold this example**
47+
- Goal: How to initialize the example
48+
- Contents: `pnpm dlx create-lz-oapp@latest --example <name>` (Some examples require a feature flag. Refer to `packages/create-lz-oapp/src/config.ts` to verify)
49+
50+
8. **Helper Tasks (inline notice)**
51+
- Goal: Let users know helpers exist
52+
- Contents: Single-line pointer to helper tasks section
53+
54+
9. **Setup**
55+
- Goal: What to configure before building
56+
- Contents: `.env` setup, deployer account prep
57+
58+
10. **Build**
59+
- Goal: How to compile contracts/programs/modules
60+
- Contents: Build commands
61+
62+
11. **Deploy**
63+
- Goal: How to deploy contracts/programs/modules
64+
- Contents: Deploy command + minting instructions (if applicable)
65+
66+
12. **Enable Messaging**
67+
- Goal: How to wire/configure OApps for messaging
68+
- Contents: LZ config, init, and wiring steps
69+
70+
13. **Sending Message/OFT/ONFT**
71+
- Goal: Trigger a cross-chain action
72+
- Contents: CLI command to triffer send, both/all directions. E.g. for examples/oft, it is `pnpm hardhat lz:oft:send --src-eid 40232 --dst-eid 40231 --amount 1 --to <EVM_ADDRESS>`
73+
74+
14. **Next Steps**
75+
- Goal: What to know after completing the deployment
76+
- Contents: Production Deployment Checklist + links (Security Stack, Message Options)
77+
78+
15. **Production Deployment Checklist**
79+
- Goal: Prep for production usage
80+
- Contents: Gas profiling, DVN config, confirmation settings
81+
82+
16. **Appendix**
83+
- Goal: Mark end of core deployment steps
84+
- Contents: Additional topics and configuration
85+
86+
16.1. **Running tests**
87+
- Goal: How to test contracts/programs
88+
- Contents: Test commands
89+
90+
16.2. **Adding other chains**
91+
- Goal: Expand the example to more networks
92+
- Contents: Add logic, update `hardhat.config.ts`
93+
94+
16.3. **Using Multisigs**
95+
- Goal: Deploy using a multisig wallet
96+
- Contents: Command param diffs, multi-VM notes
97+
98+
16.4. **LayerZero Hardhat Helper Tasks (detailed)**
99+
- Goal: Understand all helper tasks
100+
- Contents: Link to docs + list of built-in and local tasks
101+
102+
16.5. **Contract/Program Verification**
103+
- Goal: Verify deployments
104+
- Contents: VM-specific verification docs
105+
106+
16.6. **Troubleshooting**
107+
- Goal: Resolve errors and setup issues
108+
- Contents: Link to general troubleshooting + local fixes
109+
110+
Any sections that don't appear in the above list should be considered for removal.
111+
112+
113+
---
114+
115+
## Example README Principles
116+
117+
1. Example READMEs should focus on required commands, with elaborations linked to docs.
118+
2. Avoid duplicating explanations of general concepts (e.g., OFTs)—link to docs instead.
119+
3. The first mention of concepts like Endpoint IDs, Wiring, etc. should link to the glossary: https://docs.layerzero.network/v2/home/glossary
120+
4. TODO: Every README should invite partners to provide feedback to drive improvements.
121+
122+
---
123+
124+
## Example Code Principles
125+
126+
1. **Options-first**: Enforced Options implementation and instructions should be included by default (e.g. in `layerzero.config.ts`).
127+
2. **Two chains only**: Examples should use only 2 chains by default to reduce testnet setup friction; use “Add other chains” section to scale up if needed.

‎docs/package.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"name": "@layerzerolabs/devtools-docs",
3+
"version": "0.0.1",
4+
"private": true,
5+
"description": "Documentation for LayerZero devtools",
6+
"scripts": {
7+
"build": "echo 'No build needed for docs'",
8+
"clean": "echo 'No clean needed for docs'",
9+
"lint": "echo 'No lint needed for docs'",
10+
"test": "echo 'No tests for docs'"
11+
}
12+
}

‎examples/mint-burn-oft-adapter/tasks/utils.ts‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
1-
import { createLogger } from '@layerzerolabs/io-devtools'
21
import { endpointIdToNetwork } from '@layerzerolabs/lz-definitions'
32
import { Options } from '@layerzerolabs/lz-v2-utilities'
43

5-
const logger = createLogger()
6-
74
export const deploymentMetadataUrl = 'https://metadata.layerzero-api.com/v1/metadata/deployments'
85

96
/**
@@ -14,7 +11,7 @@ export async function getBlockExplorerLink(srcEid: number, txHash: string): Prom
1411
const network = endpointIdToNetwork(srcEid) // e.g. "ethereum-mainnet"
1512
const res = await fetch(deploymentMetadataUrl)
1613
if (!res.ok) return
17-
const all = (await res.json()) as Record<string, any>
14+
const all = (await res.json()) as Record<string, { blockExplorers?: { url: string }[] }>
1815
const meta = all[network]
1916
const explorer = meta?.blockExplorers?.[0]?.url
2017
if (explorer) {

0 commit comments

Comments
 (0)