build(edr_napi): migrate to napi-rs v3

[nebasuke]

PR to migrate to napi-rs v3 with accompanying Hardhat 3 test PR: NomicFoundation/hardhat#8258

I also tested Hardhat 2 locally with Verdaccio and this works. I've left out the PR as it needs a good amount of fixes not relating to this PR to be able to match the newest EDR version.

I've left one migration behind the compat-mode, as that might need some design.

I've tried to keep APIs the same where possible, relying on a new napi-cli release to preserve const string enum behaviour.

Note that the ThreadsafeFunction teardown bug gets worse in Node 20, and a little bit in Node 22. I would suggest merging this AFTER migrating away from Node 20 (#1393), and to consider a reduced Node 22 test matrix or a test suite pass on failed exit given that we have now filed it as a known Hardhat 3 issue: NomicFoundation/hardhat#8322.

Update (2026-07-02): the intermittent bindings crashes are now diagnosed and fixed in this PR. The known Node TSFN teardown bug was only the first of three stacked memory-safety bugs — the other two (a napi-rs custom-GC use-after-free, and JS-derived napi::Errors dropped off the JS thread) persisted on every Node version. See "The flaky bindings crash: three stacked bugs" below. A first-chance-gdb stress harness on native arm64 went from ~7% crashes per suite run to 0/200 (musl) and 0/300 (gnu) with the two fix commits.

Will follow-up if/when napi-rs/napi-rs#3370 is in. See napi-rs/napi-rs#3368.

Claude summary

Migrate edr_napi to napi-rs v3

Migrates edr_napi and edr_napi_core from napi-rs v2 to v3 (napi/napi-derive 3.x, @napi-rs/cli ^3.7.0), moving the bindings onto napi-rs's current major version line and its lifetime-typed API. The JS API surface is preserved except for two documented changes (see "Consumer-visible changes"); both Hardhat 2 and Hardhat 3 work without modification, apart from a 14-line test-fixture adjustment in Hardhat 3 (hardhat#8258).

The first commit is the bulk mechanical migration; every later commit is a single focused concern (rebase adaptations, error propagation, tests, style). Reviewing commit-by-commit should work well.

Consumer-visible changes

The full list — everything else is byte-compatible at the API level:

1. TestResult.reason / .counterexample / .valueSnapshotGroups are now class getters typed T | undefined (previously optional class fields readonly reason?: T, runtime contract unchanged: absent → undefined). v3 emits every TestResult member as a getter, but only these three — formerly optional — change structural required-ness: TypeScript treats getters as required, so object literals satisfying TestResult must spell these keys out. The only consumer impact found (Hardhat 3 test fixtures).
2. SuiteResult is now a plain object (interface) instead of a class — same field shapes, read identically. It is no longer a runtime value, though: module.exports.SuiteResult is dropped, so new SuiteResult / instanceof SuiteResult stop working (Hardhat only reads fields).
3. JS exceptions thrown by decodeConsoleLogInputsCallback / printLineCallback now surface as JSON-RPC internal-error responses on the triggering request, carrying the JS error message. Previously they were swallowed (print) or crashed the process (decode). This is the one intentional runtime behavior change in Rust code; covered by new regression tests.

Not changed, by design: all 15 napi enums keep their runtime-enum shape (--runtime-string-enum, new in @napi-rs/cli 3.7.0 via napi-rs/napi-rs#3284, restores it for the 3 string enums that v3 would otherwise demote to type-only unions); MineOrdering.Fifo-style value access keeps working everywhere.

What changed, by layer

Typed surface (bulk of the diff, mechanical)

• JsFunction → Function<'env, Args, Ret>; the 'env lifetime propagates through 7 #[napi(object)] config structs and 4 napi-exposed methods (which now take env: &'env Env so the returned Object<'env> can borrow from it).
• JsObject → Object<'env> for deferred-promise returns; JsUnknown → Unknown<'_>; Vec<JsString> → Vec<JsString<'env>> (the no-Debug/Display/Serialize private-key-leak guard is unchanged).
• v3 removed Clone from JS-typed wrappers: #[derive(Clone)] dropped from ~25 #[napi(object)] data carriers (verified none are cloned); manual deep-copy Clone impls on FuzzCase/BaseCounterExample via Uint8Array::with_data_copied.
• v3 removed &str: FromNapiValue: 4 pub kind: &'static str tag fields → String (round-trip pinned by a mocha test).
• #[napi(async_runtime)] on the 5 sync entry points that call tokio::runtime::Handle::current(), including the EdrContext constructor — v3 no longer enters the tokio runtime context implicitly for sync #[napi] functions.

ThreadsafeFunction call sites (6 + 1)

All rewritten to the v3 builder (build_threadsafe_function().weak::<true>().build_callback(...)). Weak/strong semantics are preserved exactly: the 6 callbacks that v2 unref(env)'d are weak; the test-suite-completion TSFN stays strong (keeps the process alive during a Solidity test run). ErrorStrategy::Fatal maps to the v3 builder default (CalleeHandled = false). v3's call_with_return_value now delivers the JS outcome as a napi::Result — the logger sites forward it through their result channels (consumer-visible change 3 above); the coverage/gas-report sites already did.

Build & packaging

• napi/napi-derive = 3 (lockfile: 3.10.0/3.5.7; 3.10.0 is a same-day release but carries the napi-rs#3357 memory-safety fix, so it's cooldown-allowlisted — see the bindings-crash section); napi-build stays 2.3 (no v3 exists).
• dyn-symbols re-enabled (a napi default that our default-features = false silently dropped): N-API symbols resolve at runtime via libloading instead of link-time externs. Required for cargo test binaries to link now that edr_napi_core has unit tests; also how every default-configured napi-rs package (and all MSVC builds) already works. Failure-mode nuance: a host missing a symbol fails at first call (stderr message + error status) instead of at dlopen — unreachable in practice for napi8 on Node ≥ 20.
• build_edr_napi.sh: --no-const-enum kept (const enums can't be value-imported under isolatedModules), --runtime-string-enum added, -- --locked separator replaces --cargo-flags.
• prepublish.sh: v3 flag names, plus explicit --skip-optional-publish --no-gh-release so publish/release safety doesn't depend on call-site ordering or an absent GITHUB_TOKEN.
• package.json: napi.name → binaryName, triples → targets, napi universal → universalize.

CI

• cargo llvm-cov jobs pin CARGO_BUILD_TARGET=$(rustc --print host-tuple) (3 jobs, identical comment): v3's napi build implicitly passes --target=<host>, redirecting cdylib output to target/<triple>/; without the pin, profraws and the .node land in different subtrees and napi-crate coverage reports 0%.

Design decisions to weigh in on

1. ArrayBuffer annotation with Uint8Array runtime for the two Hardhat-2-facing callbacks (setCallOverrideCallback, decodeConsoleLogInputsCallback): the .d.ts matches Hardhat 2's typings; producing a real ArrayBuffer is impossible (lifetime-carrying type vs 'static TSFN args). Buffer.from(x) accepts both. Documented at both sites; exercised end-to-end by mocha tests asserting on the actual runtime values.
2. Either<T, ()> instead of Option<T> on the three TestResult getters: napi-rs serializes Option::None as null, but consumers test === undefined; () serializes as undefined.
3. SuiteResult POJO / TestResult class: SuiteResult has no methods, and Hardhat reads three of its four fields multiple times per suite (testResults ×3, id ×3, warnings ×2; durationNs is currently unread) — as a class, each testResults read would re-clone the entire Vec<TestResult>. The eager conversion is shallow: testResults becomes an array of TestResult class handles, so per-test state stays lazy. TestResult keeps methods (stackTrace(), callTraces()) over un-serializable Rust state, so it stays a class with per-getter clones (same cost profile as v2's field codegen).
4. compat-mode feature enabled: v3's typed Object<'_> doesn't implement ToNapiValue by value, making it unusable as TSFN args (CallJsBackArgs: 'static); the deprecated JsObject is the remaining sanctioned way to build the subscription-event object inside a TSFN callback. Scoped to one module (#![allow(deprecated)] with rationale). Follow-up planned to remove it; first candidate is v3's ObjectRef (a 'static reference wrapper that implements ToNapiValue by value).
5. Vec<JsString<'env>> kept for owned_accounts rather than a String newtype: JsString isn't deprecated, the leak-prevention property is intact, and a newtype costs ~20 lines of manual trait impls plus an allocation per element for no gain.

Suggested review focus

• crates/edr_napi/src/logger.rs + crates/edr_napi_core/src/logger.rs — the error-propagation change (typed LoggerError variants, fallible DecodeConsoleLogInputsFn). The only deliberate runtime behavior change.
• crates/edr_napi/src/solidity_tests/test_results.rs — densest file: getter pattern, manual Clone deep-copies, kind: String tags.
• crates/edr_napi_core/src/subscription.rs + crates/edr_napi/src/subscription.rs — compat-mode/JsObject usage and the Arc-wrapped TSFN (v3 ThreadsafeFunction isn't Clone).
• The committed index.d.ts diff — fastest way to audit the consumer surface: export enum → export declare enum (cosmetic), the TestResult/SuiteResult changes above, new SolidityStackTraceEntry/SolidityStackTrace aliases (fixes a dangling type reference in the generated typings), no drops or renames.

The flaky bindings crash: three stacked bugs (all fixed)

The intermittent bindings-test crashes on this PR (SIGSEGV / SIGTRAP / Check failed: node->IsInUse(), arm64-clustered, scattered across Node versions) were three independent memory-safety bugs sharing one symptom pool. Diagnosed with a first-chance-gdb stress harness on native arm64 runners — post-mortem cores were useless, because signal-exit re-raises fatal signals via process.kill and destroys the faulting stack.

1. Node: napi_threadsafe_function teardown data race (nodejs/node#55706) — fixed upstream by Mika Fischer (landed bff6ea49, Node 25+, backported to 24.13.1; never to the 20/22 LTS lines). Covered by the Node 24/26 matrix bump (build: add support for Node v24 (new default) & v26 #1507); user-facing tracker hardhat#8322. This was the originally-suspected (and only known) cause; it masked the two below, which kept crashing on Node 24/26.
2. napi-rs ≤ 3.9.4: custom-GC use-after-free for buffers dropped off the JS thread (napi-rs#3357) — napi-rs recycles the napi_ref behind every Buffer/TypedArray dropped off the JS thread through an internal TSFN with a racy destroyed-flag check, and deletes refs the env already invalidated at teardown → V8 GlobalHandles corruption. EDR triggers this constantly (Uint8Arrays dropped on tokio/deallocator threads). Fixed upstream in napi 3.10.0; adopted here via lockfile bump + a cooldown-allowlist entry (same-day release, but it is the memory-safety fix).
3. JS-derived napi::Error dropped off the JS thread — a napi::Error from a JS throw (TSFN callback) or promise rejection owns a napi_ref to the JS error object, is (unsafely) Send, and its Drop deletes that ref on whatever thread runs it. This PR's error bridges shipped such errors across channels and awaited rejections on the tokio runtime → the same GlobalHandles corruption; this was the dominant cause. v2 was immune only because throwing callbacks were swallowed or crashed the process, so the errors never crossed threads. Fixed in this PR: errors cross threads as Strings only — stringified in the TSFN result closures (JS thread), and via napi_error::reason_and_forget (extract message + mem::forget, a bounded leak of one JS error object per failed callback) where rejections materialize on tokio threads. An upstream napi-rs issue will follow; the fix shape is routing Error-ref deletion through their new per-env custom-GC handle, like buffers.

Evidence (bindings suite looped on native arm64, per configuration):

Configuration	musl (200×)	gnu (300×)
napi 3.9.4 (bugs 2 + 3 live)	19 crashes	15 crashes
+ napi 3.10.0 (bug 2 fixed)	8	14
+ napi::Error fix (bug 3 fixed)	0	0

One bad napi_delete_reference corrupts V8's GlobalHandles free-list, and the next handle operation crashes — wherever it happens to be. That's why crash sites wandered (mid-run inside createProvider, at-exit in the TSFN close sweep) and why each single-cause theory only lowered the rate instead of eliminating it.

Verification

• Hardhat 3 end-to-end: a release-profile build of this branch published via local Verdaccio into Hardhat 3 — build clean with zero TS errors and no patches, 272 tests passing across network-manager/edr (incl. JSON-RPC provider e2e), gas-analytics, and solidity-test (incl. real EVM execution). Hardhat-side diff: hardhat#8258 (test fixtures only).
• Bindings crash: root-caused and fixed — see "The flaky bindings crash: three stacked bugs" above. Validated by a first-chance-gdb stress harness on native arm64 (musl + gnu): 0 crashes in 500 combined suite iterations with both fix commits, versus ~7% per iteration before.

Follow-ups (out of scope)

• File the upstream napi-rs issue for napi::Error's unsound Send impl (env-bound napi_ref deleted in Drop on whatever thread runs it — see bug 3 above); once fixed upstream, napi_error::reason_and_forget can be retired.
• Remove compat-mode once an alternative TSFN-args idiom is chosen (see design decision 4); ObjectRef is the first candidate to spike.
• Evaluate v3's experimental napi build --cross-compile to replace the Docker-based Linux release legs.
• #[napi(module_exports)] instead of napi-build::setup() (cosmetic).

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ea61b6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@nomicfoundation/edr	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​napi@​2.16.17 ⏵ 3.10.0	-18
	npm/​@​napi-rs/​cli@​3.7.2
	cargo/​napi-derive@​2.16.13 ⏵ 3.5.7	+2

View full report

[codecov]

Codecov Report

❌ Patch coverage is 74.14248% with 98 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.66%. Comparing base (d2e5ae8) to head (0ea61b6).

Files with missing lines	Patch %	Lines
crates/edr_napi/src/config.rs	69.56%	20 Missing and 8 partials ⚠️
crates/edr_napi/src/logger.rs	57.62%	20 Missing and 5 partials ⚠️
crates/edr_napi/src/solidity_tests/test_results.rs	73.58%	14 Missing ⚠️
crates/edr_napi/src/call_override.rs	68.29%	9 Missing and 4 partials ⚠️
crates/edr_napi/src/context.rs	85.41%	4 Missing and 3 partials ⚠️
crates/edr_napi/src/trace/debug.rs	0.00%	5 Missing ⚠️
crates/edr_napi/src/subscription.rs	89.74%	1 Missing and 3 partials ⚠️
crates/edr_napi/src/trace/solidity_stack_trace.rs	66.66%	1 Missing ⚠️
crates/edr_napi_core/src/subscription.rs	83.33%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1385      +/-   ##
==========================================
+ Coverage   79.43%   79.66%   +0.22%     
==========================================
  Files         446      446              
  Lines       76644    76618      -26     
  Branches    76644    76618      -26     
==========================================
+ Hits        60881    61036     +155     
+ Misses      13636    13466     -170     
+ Partials     2127     2116      -11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Wodann]

Some suggestions. I'm working on resolving them

[Wodann]

I addressed the most pressing comments I left. The other ones are nice-to-haves; so feel free to merge, if you're okay with the changes.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 44 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[Wodann]

/bench

[github-actions]

⏳ EDR CI for this commit hasn't passed yet, so the regression benchmark was not started. Comment /bench again once CI is green.

[Wodann]

/bench

[github-actions]

🚀 Starting regression benchmark for a1d1f87b4747 against Hardhat main.

[github-actions]

✅ Regression benchmark passed for a1d1f87b4747 against Hardhat main.

View workflow run

[Wodann]

I've left one migration behind the compat-mode, as that might need some design.

I was able to remove compat-mode

[nebasuke]

Looks good to me! I'll rebase/merge in main to make sure we're not hitting any of the new ESLints, and then I'm happy to move forward.