@@ -16,7 +16,48 @@ notifications:
1616
1717---
1818
19- ## 2. Environment Setup
19+ ## 2. Package Relationship Diagram
20+
21+ ` ` `
22+ toolbox-hardhat
23+ (main entry point)
24+ │
25+ ┌───────────────┼───────────────┐
26+ │ │ │
27+ ▼ ▼ ▼
28+ ua-devtools- devtools-evm- protocol-devtools-
29+ evm-hardhat hardhat evm
30+ │ │ │
31+ └───────┬───────┴───────┬───────┘
32+ │ │
33+ ▼ ▼
34+ devtools-evm devtools
35+ (core types)
36+ ```
37+
38+ ** Key Packages:**
39+ - ` toolbox-hardhat ` - Main entry point, re-exports everything
40+ - ` ua-devtools-evm-hardhat ` - OApp/OFT wiring tasks
41+ - ` devtools-evm-hardhat ` - Deploy tasks, HRE utilities
42+ - ` devtools ` - Core types (OmniPoint, OmniGraph)
43+
44+ ---
45+
46+ ## 3. Directory-Specific AGENTS.md Files
47+
48+ Codex will apply the most specific ` AGENTS.md ` under:
49+
50+ | Directory | Contains |
51+ | -----------| ----------|
52+ | ` examples/AGENTS.md ` | Example-specific guidelines, structure templates |
53+ | ` packages/AGENTS.md ` | Package-specific guidelines, naming conventions |
54+ | ` tests/AGENTS.md ` | Test-specific guidelines |
55+ | ` examples/*/AGENTS.md ` | Per-example build/test commands |
56+ | ` packages/*/AGENTS.md ` | Per-package build/test commands |
57+
58+ ---
59+
60+ ## 4. Environment Setup
2061
21621 . ** Setup Script** (internet + proxy phase)
2263
@@ -52,38 +93,36 @@ notifications:
5293 * ` cache/metadata/dvns.json`
5394 * ` cache/metadata/defaultConfig.json`
5495
55- * Benefits:
56- * Setup captures latest metadata during internet access
57- * Code-mode runs fully offline using local JSON snapshots
58- * Provides reference data for metadata-tools package and LayerZero configurations
59-
6096---
6197
62- # # 3 . Repo Structure Overview
98+ # # 5 . Repo Structure Overview
6399
64100```
65101/
66102├── examples/ ← standalone demo projects
67- │ ├── oapp/ ← LayerZero OApp examples
68- │ ├── oft/ ← OFT implementation examples
69- │ └ ── onft/ ← ONFT implementation examples
70- | └── .../
103+ │ ├── oapp/ ← OApp example (start here for messaging)
104+ │ ├── oft/ ← OFT example (start here for tokens)
105+ │ ├ ── oft-adapter/ ← Wrap existing ERC20
106+ │ └── .../
71107├── packages/ ← reusable libraries & plugins
72- │ ├── devtools/ ← core devtools package
73- │ ├── oft-evm/ ← OFT implementations
74- │ └── onft-evm/ ← ONFT implementations
75- │ └── .../
108+ │ ├── toolbox-hardhat/ ← Main entry point
109+ │ ├── devtools/ ← Core types
110+ │ ├── devtools-evm-hardhat/ ← Deploy tasks
111+ │ ├── ua-devtools-evm-hardhat/ ← OApp/OFT tasks
112+ │ ├── oft-evm/ ← OFT contracts
113+ │ └── .../
76114├── tests/ ← integration & helper suites
77- | └── .../
78- ├── .gitignore
79115├── turbo.json ← Turbo Pipeline config
80116├── package.json ← monorepo root
117+ ├── WORKFLOW.md ← Deployment workflow guide
118+ ├── DEBUGGING.md ← Troubleshooting guide
119+ ├── CHEATSHEET.md ← Quick reference
81120└── AGENTS.md ← this file
82121```
83122
84123---
85124
86- ## 4 . JS Tooling & Build
125+ ## 6 . JS Tooling & Build
87126
88127* **Package Manager**: pnpm v8.15.6 (via Corepack or `npm install -g pnpm@8.15.6`).
89128* **Monorepo Runner**: Turbo (`turbo.json`).
@@ -101,15 +140,29 @@ notifications:
101140
102141---
103142
104- ## 5. Agent Workflow
143+ ## 7. Common Hardhat Tasks
144+
145+ | Task | Description | Package |
146+ |------|-------------|---------|
147+ | `lz:deploy` | Deploy contracts to all configured networks | devtools-evm-hardhat |
148+ | `lz:oapp:wire` | Wire OApp pathways (setPeer, setConfig) | ua-devtools-evm-hardhat |
149+ | `lz:oapp:config:get` | Get current on-chain configuration | ua-devtools-evm-hardhat |
150+ | `lz:oapp:config:get:default` | Get LayerZero default configuration | ua-devtools-evm-hardhat |
151+ | `lz:oapp:peers:get` | Get peer relationships | ua-devtools-evm-hardhat |
152+ | `lz:read:wire` | Wire OApp Read channels | ua-devtools-evm-hardhat |
153+ | `lz:errors:decode` | Decode LayerZero error messages | ua-devtools-evm-hardhat |
154+
155+ ---
156+
157+ ## 8. Agent Workflow
105158
1061591. **Initial Setup**
107160 * Run `pnpm install` to install dependencies
108161 * Ensure all required system tools are available
109162
1101632. **Development Phase**
111164 * Make necessary code changes
112- * Follow platform-specific guidelines in respective CODEX .md files
165+ * Follow platform-specific guidelines in respective AGENTS .md files
113166 * Ensure changes are properly documented
114167
1151683. **Pre-Submission Checks**
@@ -127,7 +180,19 @@ notifications:
127180
128181---
129182
130- ## 6. Versioning & Changesets
183+ ## 9. Common Troubleshooting Patterns
184+
185+ | Issue | Diagnostic | Solution |
186+ |-------|------------|----------|
187+ | "Peer not set" | `lz:oapp:peers:get` | Run `lz:oapp:wire` |
188+ | "InvalidNonce" | Check message lifecycle | Verify DVN verification |
189+ | Config mismatch | `lz:oapp:config:get` | Compare with expected config |
190+ | Build fails | `pnpm build --filter <pkg>` | Check dependencies |
191+ | Deploy fails | Check `.env` | Verify RPC URLs, credentials |
192+
193+ ---
194+
195+ ## 10. Versioning & Changesets
131196
132197After modifying any packages under `examples/`, `packages/`, or `tests/`:
133198
@@ -139,7 +204,7 @@ Generates and stages a changeset for versioning & changelog.
139204
140205---
141206
142- ## 7 . Commit & PR Guidelines
207+ ## 11 . Commit & PR Guidelines
143208
144209* ** Commits** : semantic scope:
145210
@@ -152,15 +217,3 @@ Generates and stages a changeset for versioning & changelog.
152217 2 . What changed
153218 3 . How to verify (build/test commands)
154219* ** Footer** : link to changeset, list breaking changes.
155-
156- ---
157-
158- ## 8. Directory-Specific Overrides
159-
160- Codex will apply the most specific ` AGENTS.md ` under:
161-
162- * ` examples/AGENTS.md `
163- * ` packages/AGENTS.md `
164- * ` tests/AGENTS.md `
165-
166- Each sub-directory's AGENTS.md provides platform-specific guidelines while maintaining consistency with this root configuration.
0 commit comments