[PROPOSAL] Hardhat Cross-Chain Simulator Plugin

Proposals
1

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

JavaScript is the most-used programming language, with 61% of developers using it in 2024 (JetBrains). It has ranked first in Stack Overflow’s most-used languages list for over a decade (Stack Overflow 2023).

Hardhat is the leading framework for JavaScript-based smart contract development, with over 830,000 downloads per week (npm). 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). 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). 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).

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
Hardhat Cross-chain simulator Plugin set up3840Ă—2562 253 KB

  • 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 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

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

Emmanuel Charles – Blockchain Developer & QA Engineer
Expert in Rust, TypeScript, and C++, focused on secure smart contract development and blockchain system testing.
LinkedIn

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

Musa Abdulkareem – Blockchain Engineer
Focused on building robust tooling and SDKs for protocol-level integrations. Supports multi-chain engineering efforts.
LinkedIn

Contact:

8 Likes
2

Thank you for this proposal. This seems like a good idea upon reading, but can you help us better understand the specific user in mind for this? Would it not make sense if a more specific set of tests or an application on top of wormhole, could be converted to use this?

Thanks again, and looking forward to learning more and getting the conversation going with our more technical delegates.

4 Likes
3

I’m not technical, but this seems well-scoped and budgeted for the work involved. What I’m curious about is whether there have been concrete pain points or examples from dev teams that show real demand for this, would love to hear if that’s the case.

5 Likes
4

I second the question raised by 0xnix above. Although the proposal is well laid out, it doesn’t demonstrate that there is a real need for this kind of tooling. Ideally the proposal provides concrete user interviews that show there is a problem which would be solved with the proposed plugin.

My second question is around long-term sustainability. There is a maintenance buffer for the first six months, but not much is said about who and how will maintain this plugin beyond that. There seems to be a few options: (1) the team perpetually receives funding from the DAO to maintain it, (2) the team develops a business model and starts charging for it, (3) the Wormhole Foundation picks it up and maintains it, (4) the community picks it up and maintains it. The proposal should clearly answer these questions and lay out a plan beyond the initial build.

2 Likes
5

Hi @GFXLabs, thank you so much for taking time to review our proposal. We appreciate your questions. Below are the answers to it:

The plugin is for JavaScript and TypeScript teams using Hardhat who integrate Wormhole’s Generic Messaging for cross‑chain actions.

Why it’s needed:

  • The Tilt devnet uses Docker and Kubernetes; community reports show it often needs about 4 CPU cores, more than 10 GB RAM, and 15‑25 minutes to start, which is impractical for local setups and CI.
  • Manual CLI commands (worm generate, worm submit) are error‑prone and frequently produce “VAA not found” issues in example repos.
  • Pigeon supports only Foundry, leaving Hardhat projects without a native solution.

A reusable plugin solves this for all Hardhat projects, not just one example. Developers can add a single call like await relayVAA(tx) to their Mocha tests and run full cross‑chain checks without heavy infrastructure. As part of the work, we’ll also update the official hello-world Wormhole example to use the plugin, so teams can see exactly how it works in practice and copy the setup for their own projects. This provides a large group of Wormhole developers with a quick, reliable way to test cross‑chain logic.

We hope this makes sense. Kindly let us know if you need more clarifications. Thank you.

2 Likes
6

Hi @0xnix , thank you so much for your comment.

Yes. There’s clear, documented demand for this plugin from developers facing hard limitations today.

  • Tilt is too heavy – Wormhole’s official dev‑environment spins up every chain in Kubernetes and “usually takes 30 minutes to spin up fully,” with multi‑CPU/GB requirements that break local laptops and free CI runners Wormhole.
  • Manual CLI testing is brittle – missed parameters in worm generate / worm submit produce “Requested VAA not found in store” errors, as seen in public GitHub discussions GitHub.
  • No simulator for Hardhat – Pigeon, the only cross‑chain test toolkit, states it is “designed to work with the Foundry testing framework,” leaving JavaScript workflows uncovered GitHub.

A reusable Hardhat plugin will let the 61% of developers using JavaScript and the large weekly Hardhat users run Wormhole cross‑chain tests with a simple await relayVAA(tx) call all without Docker or Kubernetes; while we also update the official hello‑wormhole example to prove its value and speed adoption.

We hope this shed more light to your concerns. Kindy let us know if you have more questions.

Thank you.

3 Likes
7

Thanks for the context, that helped clarify the motivation and how this could support Hardhat developers.

I’d also like to echo GFX’s call for input from technical delegates.

If the grant moves forward, I think the most important thing will be having KPIs and visibility into usage post-launch. A few things that might help strengthen the proposal even further:

Concrete metrics tied to developer adoption (usage in open-source repos, install, etc)

A plan to gather feedback from Wormhole ecosystem teams or maintainers during development

Making sure the plugin and demos are easy to pick up for the average Hardhat developer

3 Likes
8

HI @flowmodule, Thank you so much for taking time to review our proposal. Below are the answers to your question.

  1. Evidence of developer need:
  1. Long-term Sustainability:
    After the initial six‑month maintenance window, our team will keep the plugin maintained as open source. We expect meaningful adoption because it addresses a clear gap for a large share of Wormhole developers who use JavaScript/Hardhat, and we’ll track that with concrete KPIs (npm downloads, CI integrations, external PRs).

Sustainability plan:

  1. Our team provides core maintenance (SDK/CLI compatibility, bug fixes) beyond the buffer.
  2. Once the plugin is in use, we will approach the Wormhole Foundation to propose adding it to their recommended tooling.
  3. We will structure the repo for community contribution (CONTRIBUTING.md, CODEOWNERS, issue labels, maintainer rotation) so upkeep doesn’t depend on a single team.

Future DAO requests, if any, would most likely be for feature expansions and not to keep the MVP running. The goal is to minimize long‑term grant dependence while ensuring the tool remains reliable.

We hope this makes sense. Kindly let us know if you have any more questions or concerns. Happy to clarify.

2 Likes
9

Hi @Wormhole , @GFXLabs @0xnix @flowmodule , We hope you’re doing good. We would like to know what the next step will be for this proposal since it been a while we heard from the community. We look forward to working on this project ASAP.

Thank you.

2 Likes
10

Next step would be to find someone with enough W to post this as a vote to Snapshot. After that, it would need to move to Tally.

There would also be a KYC process with Wormhole Foundation upon a successful vote. If the vote on Tally is going well, then it may be worthwhile to request to begin that process in parallel to the voting period to save some time.

2 Likes
11

Yes, nothing much to add to GFX comment. Following WIP-2, the next step is a 3-day Snapshot vote with the 155M $W threshold.

Just a thought for the group: do we want every grantee to also go through onchain vote, given funds are still disbursed manually by the Foundation?

2 Likes
12

Hi @GFXLabs @0xnix , thank you so much for your message.
We have 1k W but we tried putting it up on Wormhole’s snapshot but it didn’t go through. Just to confirm, can we put it up ourselves or we need a Wormhole team to help us do it? We are open and grateful to receive you assistance moving this forward.
Thank you!

1 Like
13

The amount of needed $W is 1k @DappsoverApps

2 Likes
14

Hi @0xnix @GFXLabs , thank you for the support. Our proposal is now live on Snapshot: https://snapshot.box/#/s:wormholegovernance.eth/proposal/0xf936fd1a8da352ea921d99ff5d69329aba1b49209a8d330d0f7a1773e28bfa52

We look forward to receiving the community vote and moving forward with the project.

Thank you.
cc @Wormhole @flowmodule @Jose_StableLab @AranaDigital @watercup.eth

3 Likes
15

We’ll make sure to alert voters in the various delegate channels

2 Likes
16

The following reflects the views of L2BEAT’s governance team, composed of krst, @Sinkas and @Manugotsuka, and it’s based on their combined research, fact-checking, and ideation.

We voted FOR.

This plugin addresses a real gap for developers working with Wormhole in JavaScript/TypeScript. It simplifies local testing by removing the need for heavy setups like Tilt or error-prone CLI scripting, which should make development faster and more reliable. Given its relatively modest cost, it is worth supporting.

At the same time, we need to say that the scope looks limited. The tool is aimed at local testing only and will mainly benefit Hardhat users. Its real value will depend on whether developers actually adopt it in their day-to-day workflows. We encourage the team to track adoption closely and share usage data so the DAO can judge the results.

Despite these caveats, we think the benefits justify funding the project, and we are supportive of giving it a chance.

2 Likes
17

Hi @GFXLabs @0xnix , we are happy to let you know that our snapshot vote was passed. We would like to ask for the next step. Are we moving forward to Tally since the fund is with the foundation? Or moving forward with KYC? We are happy to hear from you.

Thank you.

2 Likes
18

Thank you for your vote. We are happy to know that you recognize the value and impact of this project. We are committed to building this tool to its best form and we will constantly update the DAO on the traction and adoption of this tool as soon as it goes live.

Thank you once again.

1 Like
19

That is correct. You’ll need to find a delegate/voter with sufficient power to post to Tally. In this case, there is no onchain execution required - the funds are disbursed by and KYC conducted by @wormholefoundation. So you should be able to just submit a text-only proposal without having to craft a payload.

At the Foundation’s discretion, they may choose to begin the KYC process with you before the vote, but would not expect that process to begin until the close of the vote.

You can find more information in WIP-2, which we’ve copied below to save you a click:

5. Final Proposal Submission

  • Upon successful completion of the Signaling Phase off-chain vote, formal proposals will be published to the forum. This proposal should be the final draft and should reflect any changes to the original proposal.
  • Timeline: This stage will allow for a minimum 3 days for community members to complete final review and discussion before the final vote stage.
  • Requirements: Proposals must include:
    • Title and clear objective.
    • Problem statement and proposed solution.
    • Technical or resource details.
    • Expected outcomes and KPIs.

6. Voting Phase

  • Process: Proposals advancing to this phase undergo an onchain vote using Tally, powered by MultiGov.
  • Thresholds: The quorum is set to 350M W tokens and the proposal threshold is set to 1M W tokens at initiation of Wormhole Governance.
  • Timeline: The Voting Phase is comprised of the following periods:
    • The voting delay is 2 days, to provide token holders with time to move their tokens and delegate their voting power in advance of the vote.
    • The voting period is 5 days.

7. Implementation and Monitoring

  • Execution: Approved proposals proceed to implementation. There is a timelock delay of 4 days for approved proposals.
  • Please note that proposals with onchain execution will not be accepted.
2 Likes
20

Hi @GFXLabs , thank you so much for the guidance. We have posted it as a draft on Wormhole’s Tally: Tally | Wormhole Draft Proposal

Since there’s no onchain execution required, is it still necessary to get a Sponsor to post in onchain?

We are happy to move forward with the next step and KYC verification. @wormholefoundation @Wormhole @Ossie. Thank you.

1 Like