# [PROPOSAL] Hardhat Cross-Chain Simulator Plugin

- Space: [Wormhole](https://snapshot.box/s:wormholegovernance.eth.md)
- Author: 0x07805C591785C33d3C66C46F8c5c2f0DCA13F9B7
- State: Passed
- Voting type: Basic
- Start: 2025-09-09 10:26 UTC
- End: 2025-09-12 10:26 UTC
- Votes: 16
- Quorum: 115,000,000 voting power
- Discussion: https://forum.wormhole.com/t/proposal-hardhat-cross-chain-simulator-plugin/827/1
- Open in Snapshot: https://snapshot.box/#/s:wormholegovernance.eth/proposal/0xf936fd1a8da352ea921d99ff5d69329aba1b49209a8d330d0f7a1773e28bfa52

## Results

- For: 93,418,790.96 voting power, 70.4%
- Against: 0 voting power, 0.0%
- Abstain: 39,214,181.58 voting power, 29.6%

## Proposal

Hardhat Cross-Chain Simulator Plugin
[PROPOSAL] Hardhat Cross-Chain Simulator Plugin
### **Abstract**

This proposal aims to develop a lightweight Hardhat plugin that simulates Wormhole cross-chain messaging locally, enabling developers to test cross-chain flows in JavaScript/TypeScript environments without relying on Tilt or manual CLI scripting. The outcome will be a fully automated, developer-friendly plugin that boosts test coverage, speeds development, and increases reliability for dApps building with Wormhole.

### **Motivation**
**JavaScrip**t is the most-used programming language, with **61% of developers using it in 2024** ([JetBrains](https://www.jetbrains.com/lp/devecosystem-2024/#)). It has ranked first in Stack Overflow’s most-used languages list for over a decade [(Stack Overflow 2023).](https://survey.stackoverflow.co/2024/technology?utm_source)

**Hardhat** is the leading framework for JavaScript-based smart contract development, with over **830,000 downloads per week** ([npm](https://www.npmjs.com/package/hardhat)). But developers using Hardhat with Wormhole lack native tooling for testing cross-chain flows.

The **official Wormhole Tilt devnet requires 4 CPU cores, 16 GB of RAM**, and Docker with Kubernetes configured. Booting the environment can take **15 to 25 minutes** depending on system specs and internet connection ([Wormhole Tilt Devnet](https://medium.com/%40thenfh/a-developers-intro-to-wormhole-and-product-ideas-8c727050ac5a)). This setup is too heavy for most CI pipelines and slows local development.

**Pigeon**, the only available cross-chain simulator, supports only the Foundry framework ([Pigeon GitHub](https://github.com/exp-table/pigeon?tab=readme-ov-file#readme)). Hardhat developers must manually run worm generate and worm submit to simulate messages, which is error-prone. Common issues include incorrect VAA formatting or message replay errors ([Example GitHub Issue](https://github.com/wormhole-foundation/wormhole/discussions/categories/problems-bugs?utm_source)).

A mis-relayed VAA can block asset transfers or stall cross-chain protocols that rely on timely message delivery, including token bridging and DAO execution. The **Hardhat Cross-Chain Simulator Plugin** replaces this workflow with one helper call: `await relayVAA(tx)`. It captures emitted events, signs a mock VAA using the Wormhole SDK , and delivers it locally to the target chain. This removes the need for Docker, Kubernetes, and CLI scripts, giving Hardhat developers fast and reliable cross-chain testing out of the box.

### **Rationale**

This initiative directly supports Wormhole’s broader mission to expand cross-chain interoperability by:

* Empowering developers to build confidently with faster iteration loops
* Reducing developer friction and technical barriers in JavaScript-heavy environments
* Enabling open-source, community-led tooling that multiplies the value of existing SDKs and CLI infrastructure
* Demonstrating responsible use of funds via a scoped, maintainable, high-utility tool

### **Proposed Activities & Goals**

|Milestone (Activity) |Outcome|
| --- | --- |
|Build Hardhat plugin for local cross-chain simulation|Allow end-to-end tests of cross-chain messaging with no Tilt or manual CLI steps for the developer|
|Integrate CLI/SDK logic under the hood|Reuse existing tooling, ensure version compatibility|
|Develop example tests and demos|Provide ready-made use cases for projects and hackathons|
|Publish on npm and GitHub|Promote discoverability and adoption|


### Steps to Implement:
**Technical Architecture** 
![Hardhat Cross-chain simulator Plugin set up|690x460](upload://e766O8BNsjnx3C4MwQmKrvZiqch.png)
* Your test calls `sendMessage()` on a source contract; Wormhole’s core bridge emits **`LogMessagePublished`**.
* The **Hardhat-Wormhole plugin** catches that event, uses the Wormhole TypeScript SDK to build a VAA signed with a **mock guardian key**, and (if needed) falls back to the `worm generate` CLI.
* The plugin then submits that VAA to the target network, invoking your receiver contract’s standard **`receiveWormholeMessages`** method.
* Mocha/Chai assertions run once the VAA is processed, letting you confirm state changes, all without Tilt, external relayers, or manual CLI steps.

### **Project Impact & Measurement**

**KPIs**:

* ≥100 npm installs in 3 months post-release
* ≥10 open-source repos using the plugin publicly
* ≥5 dApp teams integrate plugin into CI pipelines
* Time-to-debug cross-chain flows reduced by 50–80% based on user feedback

**Reporting**:
* Project updates published at milestones (monthly)
* Usage metrics shared publicly (GitHub activity, downloads, adoption examples)
### **Timeline:**
| Milestone                                | Deliverables                                                                                       | Target Date    |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------- |
| **1.  Architecture & Scaffold (2 wks)** | Repo skeleton, Hardhat plugin entry-point, multi-network config template, detailed technical spec  | 31 Jul 2025    |
| **2.  Core Plugin Logic (4 wks)**       | Event listener for `LogMessagePublished`, SDK-based VAA builder, mock-guardian signing, unit tests | 30 Aug 2025    |
| **3.  Relay Helper + Examples (3 wks)** | `relayVAA()` helper, receiver contract integration, full E2E test suite, sample spec file          | 20 Sep 2025    |
| **4.  Docs & Release (2 wks)**          | README, API docs, quick-start guide, npm & GitHub release, community announcement                  | 04 Oct 2025    |
| **Post-Launch Review (1 wk)**            | Usage metrics, bug triage list, roadmap update                                                     | 11 Oct 2025    |
| **Maintenance Window (6 mo)**            | Patch releases for SDK/CLI changes and community-reported issues                                   | Oct – Mar 2026 |

### Overall Cost / Budget

| Activity                      | Scope / Outputs                                                                    | Cost         |
| --------------------------------- | ---------------------------------------------------------------------------------- | ------------ |
| **Code Scaffold & Spec**          | repo setup, multi-network config scripts, detailed tech spec                       | **\$2 500**  |
| **Core Feature Development**      | event listener, SDK-based VAA builder, mock-guardian signing logic, unit tests     | **\$8 500**  |
| **Relay Helper & Example Tests**  | `relayVAA()` API, receiver-contract wiring, full end-to-end test suite             | **\$5 500**  |
| **Documentation & DevRel**        | README, API docs, quick-start guide, tutorial video, launch blog post              | **\$2 500**  |
| **CI + QA Automation**            | GitHub Actions matrix, linting, coverage, release pipeline                         | **\$2 000**  |
| **Maintenance Buffer (6 months)** | bug fixes, SDK/CLI version bumps, community PR reviews, support through March 2026 | **\$6 000**  |
| **Total**                         |                                                                                    | **\$27 000** |

**Source of funds:** Foundation grant

## About the Team – Dapps Over Apps

**[Dapps Over Apps](https://www.x.com/dappsoverapps)** is a collective focused on advancing Web3 through developer tooling, education, and ecosystem enablement. We create open-source tools that improve the developer experience and lead initiatives that onboard and empower new builders across blockchain ecosystems.

Our work spans:

* Developer tooling contributions to **Arbitrum, Filecoin, Polkadot, StarkNet, Solana**, and **Bitcoin-DeFi** integrations
* Cross-chain educational resources and validator guides
* Hackathons, workshops, and technical onboarding events in Canada, Africa, and global Web3 communities

**Abdulkareem Oyeneye – Project Lead**
Experienced developer marketer and technical program lead with a strong track record in Web3 growth and infrastructure tooling. Led multiple ecosystem projects and specializes in identifying developer needs and delivering scalable product solutions.
[LinkedIn](https://www.linkedin.com/in/abdulkareem-oyeneye-82a6aa277)

**Gospel Ifeadi – Smart Contract Engineer**
Proficient in Rust, C++, JavaScript, and Python. Brings deep experience across smart contract development, backend engineering, and blockchain R&D.
[Twitter](https://x.com/gospel70800)

**Emmanuel Charles – Blockchain Developer & QA Engineer**
Expert in Rust, TypeScript, and C++, focused on secure smart contract development and blockchain system testing.
[LinkedIn](https://www.linkedin.com/in/emmanuel-charles-0b0023250)

**Bolaji Ahmad – Full Stack Engineer**
Full stack and infrastructure engineer with contributions to foundational tooling in the Polkadot ecosystem. Skilled in backend systems and Web3 interfaces.
[LinkedIn](https://linkedin.com/in/bolajahmad)

**Musa Abdulkareem – Blockchain Engineer**
Focused on building robust tooling and SDKs for protocol-level integrations. Supports multi-chain engineering efforts.
[LinkedIn](https://www.linkedin.com/in/wisemrmusa)

### **Contact:**
- Team@dappsoverapps.com
- [X/twitter](https://www.x.com/dappsoverapps)
- [Telegram](https://t.me/+JGur_ErNHq44MTM8)

---

To vote or create proposals from an AI assistant, connect the Snapshot MCP at https://mcp.snapshot.box

