docs: update Hardhat plugin guide for nox-hardhat-plugin v0.2.0 by claude[bot] · Pull Request #93 · iExec-Nox/documentation

claude · 2026-07-30T12:37:29Z

Requested by Pierre Jeanjacquot · Slack thread

What changed

Updates the Hardhat plugin guide (src/guides/build-confidential-smart-contracts/hardhat.md) to match the breaking changes shipped in @iexec-nox/nox-hardhat-plugin v0.2.0.

nox.connect() signature and return shape
- Before: const { viem } = await nox.connect(); — zero-arg call, returned the augmented network connection (viem/ethers + a handleClient).
- After: const connection = await network.getOrCreate('default'); const { publicDecrypt } = await nox.connect(connection); — takes a Hardhat NetworkConnection and returns a plain 5-member object (noxComputeAddress, handleGatewayUrl, encryptInput, decrypt, publicDecrypt). viem/ethers, provider, and close() now come from the connection you passed in, not from the return value.
nox.publicDecrypt(handle) is no longer a top-level method — it's destructured off the object returned by nox.connect(connection), same as encryptInput/decrypt. Updated in both the Viem and Ethers examples.
hardhat test no longer auto-boots the offchain stack (the plugin no longer overrides the test task). The "Running tests" section now shows calling nox.connect(connection) explicitly in a before hook.
Removed the skipTestOverride plugin option (nothing left to skip). Replaced the "Plugin options" section with the new additive per-network nox config (a nox block with noxComputeAddress/handleGatewayUrl on an http-type network entry under networks), for pointing the plugin at an already-running stack.
Rewrote the "nox API" reference table to document that nox.connect(connection) takes a Hardhat NetworkConnection and returns a Promise resolving to a NoxConnection object with the 5-member shape above, and to note that viem/ethers/provider/close() live on the NetworkConnection, not the NoxConnection.

Why

@iexec-nox/nox-hardhat-plugin v0.2.0 is a breaking release (see release notes). The previous docs described the pre-0.2.0 API and would no longer work against the current plugin.

Only src/guides/build-confidential-smart-contracts/hardhat.md was touched — other noxComputeAddress/encryptInput/decrypt/publicDecrypt references in the repo belong to the unrelated @iexec-nox/handle SDK or the docs site's own Networks page and were left as-is.

Test plan

npm run build (vitepress build) succeeds
npm run format applied, npm run check-format passes clean

…ing changes - nox.connect() now requires a NetworkConnection argument and returns a 5-member NoxConnection (noxComputeAddress, handleGatewayUrl, encryptInput, decrypt, publicDecrypt) instead of the augmented network connection - The plugin no longer overrides the `test` task, so tests must call nox.connect(connection) explicitly to boot the offchain stack - Replace the removed `skipTestOverride` option with the new per-network `nox` config block for pointing at an already-running stack - Rewrite the Viem/Ethers examples and the nox API reference table to match Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YJwNXv7Mce9fhyZdLJimfr

vercel · 2026-07-30T12:37:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nox-documentation	Ready	Preview	Jul 30, 2026 3:23pm

Copilot

Pull request overview

Note

Copilot could not run the full agentic suite for this review because it was automatically requested on a bot-authored pull request. Request a review from Copilot under Reviewers to retry with the full agentic suite. Improved support for bot-authored pull requests is coming soon.

Updates the Hardhat guide to reflect the plugin’s newer connection model: explicit nox.connect(connection) usage (instead of implicit test task overrides) and per-network configuration for attaching to an existing offchain stack.

Changes:

Document per-network networks.<name>.nox configuration for connecting to an already-running stack.
Update test instructions/examples to explicitly obtain a Hardhat NetworkConnection and call nox.connect(connection).
Refresh the nox API section to describe the NoxConnection returned by nox.connect().

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+By default the plugin boots a local offchain stack for whichever network you
+connect to. If you'd rather point it at an already-running stack (for example a
+shared staging deployment), add a `nox` block to that network's entry under
+`networks` in your config:


+import { before, describe, it } from 'node:test';
+import { network } from 'hardhat';
 import { nox } from '@iexec-nox/nox-hardhat-plugin';

 describe('MyConfidentialToken', () => {
  it('resolves a publicly decryptable total supply', async () => {
-    const { viem } = await nox.connect();
+    const connection = await network.getOrCreate('default');


+import { before, describe, it } from 'node:test';
+import { network } from 'hardhat';
 import { nox } from '@iexec-nox/nox-hardhat-plugin';

 describe('MyConfidentialToken', () => {
  it('resolves a publicly decryptable total supply', async () => {
-    const { ethers } = await nox.connect();
+    const connection = await network.getOrCreate('default');


+The plugin exposes a `nox` helper. Call `nox.connect(connection)` with a Hardhat
+`NetworkConnection` to boot (or attach to) the offchain stack; it resolves to an
+object exposing a pre-configured
+[Handle SDK](/references/js-sdk/getting-started) client so your tests can
+encrypt and decrypt without any manual setup. Get `viem`/`ethers` from the
+`connection` you passed in, not from `nox.connect()`'s return value.


- Move connection/nox.connect() setup into a before() hook in both the Viem and Ethers "Writing a test" examples, matching the pattern used in "Running tests" and fixing the unused before import. - Reword the NoxConnection description to list its actual methods (encryptInput, decrypt, publicDecrypt, noxComputeAddress, handleGatewayUrl) instead of implying a separate Handle SDK client. - Clarify that the offchain stack boots when nox.connect(connection) is called, not merely from connecting to a network.

PierreJeanjacquot

v0.2.0 change the way developers can use the plugin, usage is no longer restricted to hardhat test on edr-simulated network, the documentation should not focus on this sole use case.
see my comments for issues to fix and suggestions.

Generalize the guide beyond the hardhat test / edr-simulated-only use case: add the nox-protocol-contracts peer dep to install instructions, drop the now-unneeded chainType: 'op' from config examples, rename "Plugin options" to "Connecting to an http network" and clarify that connect() only auto-boots on edr-simulated networks (and rejects without a nox config on http networks), rename "Running tests" to "Running hardhat scripts" with generalized wording, scope the image-pull note to edr-simulated connections, simplify the nox.connect() resolution paragraph, and keep connection/noxClient in scope instead of destructuring in the examples.

PierreJeanjacquot

good job, we almost there, see my comments

PierreJeanjacquot · 2026-07-30T14:32:25Z


 ```sh [pnpm]
-pnpm add -D @iexec-nox/nox-hardhat-plugin
+pnpm add -D @iexec-nox/nox-hardhat-plugin @iexec-nox/nox-protocol-contracts


If the user is working with nox @iexec-nox/nox-protocol-contracts is likely a direct dependency, it should not be added as a dev dep. Remove it from dev deps in the examples.

PierreJeanjacquot · 2026-07-30T14:35:10Z

+## Running hardhat scripts

-With the plugin configured, run your test suite as usual:
+Any Hardhat script can use the `nox` plugin — not just tests. Call


not worth to add — not just tests

PierreJeanjacquot · 2026-07-30T14:39:00Z

+  before(async () => {
+    const connection = await network.getOrCreate('default');
+    await nox.connect(connection);
+  });


in this example connection and nox.connect(connection) are not available in the it scope, define the in them as let connection and let noxClient in the common parent scope.

PierreJeanjacquot · 2026-07-30T14:44:51Z

+  let noxClient: Awaited<ReturnType<typeof nox.connect>>;
+
+  before(async () => {
+    connection = await network.getOrCreate('default');


don't hardcode used network in example

Suggested change

connection = await network.getOrCreate('default');

connection = await network.getOrCreate();

PierreJeanjacquot · 2026-07-30T14:44:55Z

+  let noxClient: Awaited<ReturnType<typeof nox.connect>>;
+
+  before(async () => {
+    connection = await network.getOrCreate('default');


don't hardcode used network in example

Suggested change

connection = await network.getOrCreate('default');

connection = await network.getOrCreate();

PierreJeanjacquot · 2026-07-30T14:46:37Z

+`connection.viem`/`connection.ethers`, along with `connection.provider` and
+`connection.close()`, remain on the `NetworkConnection` you passed in — they are
+not part of the `NoxConnection` returned by `nox.connect()`.


remove reference to old implementation

Suggested change

`connection.viem`/`connection.ethers`, along with `connection.provider` and

`connection.close()`, remain on the `NetworkConnection` you passed in — they are

not part of the `NoxConnection` returned by `nox.connect()`.

PierreJeanjacquot · 2026-07-30T14:50:51Z

-| `skipTestOverride` | `boolean` | `false` | When `true`, `hardhat test` runs the original Hardhat action without booting the offchain stack or etching `NoxCompute`. Useful for tests without the Nox stack or to target an already-running stack. |
+The plugin only boots the local offchain stack automatically when connecting on
+an `edr-simulated` network. When you call `nox.connect(connection)` on an `http`
+network — for example a shared staging deployment — the plugin instead reads


remove the edr-simulated reference from http section

The plugin only boots the local offchain stack automatically when connecting on an edr-simulated network.

add a "### Connecting to an edr-simulated network" section before the http section, mention "The plugin boots the local offchain stack automatically when connecting on an edr-simulated network."

PierreJeanjacquot · 2026-07-30T14:53:24Z

  networks: {
    default: {
      type: 'edr-simulated',
-      chainType: 'op',
    },
  },


this example of network configuration is edr-simulated specific, it should be added to the ### Connecting to an edr-simulated network section to create.

PierreJeanjacquot · 2026-07-30T14:56:25Z

+The first connection to an `edr-simulated` network pulls the offchain service
+images from DockerHub and may take a while; subsequent runs reuse existing
+images.


this should live in the ### Connecting to an edr-simulated network section to create.

PierreJeanjacquot · 2026-07-30T15:08:03Z

+Any Hardhat script can use the `nox` plugin — not just tests. Call
+`nox.connect(connection)` with a `NetworkConnection` obtained from Hardhat to
+boot (or attach to) the offchain stack wherever you need it. In a test file,
+this typically happens in a setup step:
+
+```ts
+import { before, describe, it } from 'node:test';
+import { network } from 'hardhat';
+import { nox } from '@iexec-nox/nox-hardhat-plugin';

-```sh
-pnpm hardhat test
+describe('MyConfidentialToken', () => {
+  before(async () => {
+    const connection = await network.getOrCreate('default');
+    await nox.connect(connection);
+  });
+
+  it('resolves a publicly decryptable total supply', async () => {
+    // ...
+  });
+});
 ```


the test example can be removed as the subject in tackled in the following section

Suggested change

Any Hardhat script can use the `nox` plugin — not just tests. Call

`nox.connect(connection)` with a `NetworkConnection` obtained from Hardhat to

boot (or attach to) the offchain stack wherever you need it. In a test file,

this typically happens in a setup step:

```ts

import { before, describe, it } from 'node:test';

import { network } from 'hardhat';

import { nox } from '@iexec-nox/nox-hardhat-plugin';

```sh

pnpm hardhat test

describe('MyConfidentialToken', () => {

before(async () => {

const connection = await network.getOrCreate('default');

await nox.connect(connection);

});

it('resolves a publicly decryptable total supply', async () => {

// ...

});

});

```

Any Hardhat script can use the `nox` plugin. Call

`nox.connect(connection)` with a `NetworkConnection` obtained from Hardhat to

boot (or attach to) the offchain stack wherever you need it.

here is a more generic example inspired from the hardhat 3 doc to replace

import hre from "hardhat"; import { nox } from "@iexec-nox/nox-hardhat-plugin"; const connection = await hre.network.getOrCreate(); const noxCient = await nox.connect(connection);

It may be worth adding a hint for the user: we are using network.getOrCreate() and not network.create() this reuse the same connection and ephemeral nox stack on all getOrCreate(). spinning up isolated nox stack on isolated connection is currently not supported, hence the use of getOrCreate() instead of create().

- Install nox-protocol-contracts as a regular dependency, not a dev dep - Add a dedicated "Connecting to an edr-simulated network" section (auto-boot behavior, network config example, first-run image pull note, Docker tip), sibling to "Connecting to an http network" - Drop the edr-simulated callout from the http section intro - Trim "not just tests" wording in "Running hardhat scripts" - Replace the redundant test-shaped example in "Running hardhat scripts" with a generic script snippet, plus a note on why getOrCreate() is used over create() - Stop hardcoding the network name in network.getOrCreate() calls - Remove the leftover comparison to the pre-v0.2.0 API in the nox API section Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YJwNXv7Mce9fhyZdLJimfr

PierreJeanjacquot

LGTM 👍

Copilot AI review requested due to automatic review settings July 30, 2026 12:37

Copilot AI reviewed Jul 30, 2026

View reviewed changes

claude Bot requested a review from PierreJeanjacquot July 30, 2026 12:38

vercel Bot deployed to Preview July 30, 2026 12:39 View deployment

vercel Bot deployed to Preview July 30, 2026 12:50 View deployment

PierreJeanjacquot requested changes Jul 30, 2026

View reviewed changes

vercel Bot deployed to Preview July 30, 2026 14:21 View deployment

claude Bot requested a review from PierreJeanjacquot July 30, 2026 14:24

PierreJeanjacquot requested changes Jul 30, 2026

View reviewed changes

claude Bot requested a review from PierreJeanjacquot July 30, 2026 15:21

vercel Bot deployed to Preview July 30, 2026 15:23 View deployment

PierreJeanjacquot approved these changes Jul 30, 2026

View reviewed changes

PierreJeanjacquot merged commit e218355 into main Jul 30, 2026
5 checks passed

PierreJeanjacquot deleted the docs/nox-hardhat-plugin-v0.2.0 branch July 30, 2026 15:48

	connection = await network.getOrCreate('default');
	connection = await network.getOrCreate();

	`connection.viem`/`connection.ethers`, along with `connection.provider` and
	`connection.close()`, remain on the `NetworkConnection` you passed in — they are
	not part of the `NoxConnection` returned by `nox.connect()`.

Uh oh!

Conversation

claude Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Why

Test plan

Uh oh!

vercel Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

PierreJeanjacquot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PierreJeanjacquot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PierreJeanjacquot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

claude Bot commented Jul 30, 2026 •

edited

Loading

vercel Bot commented Jul 30, 2026 •

edited

Loading