Add @nomicfoundation/hardhat-solx plugin

.changeset/warm-solx-plugin.md

@@ -0,0 +1,6 @@
+---
+"@nomicfoundation/hardhat-solx": major
+"@nomicfoundation/hardhat-errors": patch
+---
+
+Add `@nomicfoundation/hardhat-solx` plugin for solx compiler support in test builds ([#8034](https://github.com/NomicFoundation/hardhat/pull/8034))

.peer-bumps.json

@@ -7,6 +7,11 @@
     "packages/config"
   ],
   "bumps": [
+    {
+      "package": "@nomicfoundation/hardhat-solx",
+      "peer": "hardhat",
+      "reason": "It depends on the new SolidityHooks#downloadCompilers and SolidityHooks#getCompiler hooks"
+    },
     {
       "package": "@nomicfoundation/hardhat-ignition-viem",
       "peer": "@nomicfoundation/hardhat-ignition",

packages/hardhat-errors/src/descriptors.ts

@@ -328,6 +328,19 @@ export const ERROR_CATEGORIES: {
       },
     },
   },
+  HARDHAT_SOLX: {
+    min: 110000,
+    max: 119999,
+    pluginId: "hardhat-solx",
+    websiteTitle: "Hardhat Solx",
+    CATEGORIES: {
+      GENERAL: {
+        min: 110000,
+        max: 110099,
+        websiteSubTitle: "General errors",
+      },
+    },
+  },
 };
 
 export const ERRORS = {
@@ -3063,4 +3076,34 @@ Check the error message for more details and verify your foundry.toml configurat
       },
     },
   },
+  HARDHAT_SOLX: {
+    GENERAL: {
+      UNSUPPORTED_PLATFORM: {
+        number: 110000,
+        messageTemplate: `solx is not available for the current platform ({platform}/{arch}).
+
+solx supports: linux/x64, linux/arm64, darwin (macOS), windows/x64.`,
+        websiteTitle: "Unsupported platform",
+        websiteDescription: `The solx compiler is not available for your current operating system and architecture combination.
+
+solx supports: linux/x64, linux/arm64, darwin (macOS), windows/x64.`,
+      },
+      DOWNLOAD_FAILED: {
+        number: 110001,
+        messageTemplate: `Failed to download solx {version} after {attempts} attempts: {reason}`,
+        websiteTitle: "solx download failed",
+        websiteDescription: `The solx compiler binary could not be downloaded from the solx releases mirror used by Hardhat.
+
+Check your internet connection, ensure that the solx releases mirror (https://solx-releases-mirror.hardhat.org) is reachable from your environment, and verify that the requested solx version exists.`,
+      },
+      BINARY_NOT_FOUND: {
+        number: 110002,
+        messageTemplate: `solx binary not found at {path}`,
+        websiteTitle: "solx binary not found",
+        websiteDescription: `The configured custom path for the solx binary does not exist.
+
+Verify that the path in your Hardhat config points to a valid solx binary.`,
+      },
+    },
+  },
 } as const;

packages/hardhat-solx/.gitignore

@@ -0,0 +1,14 @@
+# Node modules
+/node_modules
+
+# Compilation output
+/dist
+
+# pnpm deploy output
+/bundle
+
+# test coverage output
+coverage
+
+# all the tmp folders in the fixture projects
+/test/fixture-projects/tmp/

packages/hardhat-solx/.prettierignore

@@ -0,0 +1,6 @@
+/node_modules
+/dist
+/coverage
+CHANGELOG.md
+/test/fixture-projects/**/artifacts
+/test/fixture-projects/**/cache

packages/hardhat-solx/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nomic Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/hardhat-solx/README.md

@@ -0,0 +1,104 @@
+# Hardhat Solx plugin
+
+This plugin enables the [solx](https://github.com/NomicFoundation/solx) Solidity compiler in Hardhat 3.
+
+The `solx` compiler is currently experimental and is not ready for production use-cases. We recommend using the compiler for test builds and test execution locally, and continuing to use `solc` for production use-cases (including during deployment for example with `hardhat-ignition` and in your CI). Care should be taken before enabling compilation with `solx` in other build profiles, see configuration flags further below.
+
+## Installation
+
+```bash
+npm install --save-dev @nomicfoundation/hardhat-solx
+```
+
+Then add the plugin to your `hardhat.config.ts` and create a `solx` build profile. You must use the build profiles config format, which requires both a `default` and a `solx` profile:
+
+```typescript
+import { defineConfig } from "hardhat/config";
+import hardhatSolx from "@nomicfoundation/hardhat-solx";
+
+export default defineConfig({
+  plugins: [hardhatSolx],
+  solidity: {
+    profiles: {
+      default: {
+        version: "0.8.29",
+      },
+      solx: {
+        type: "solx",
+        version: "0.8.34",
+      },
+    },
+  },
+});
+```
+
+The `default` profile uses solc as usual. The `solx` profile uses the solx compiler, identified by `type: "solx"`. Your `.sol` files should have compatible pragmas, for example `pragma solidity ^0.8.29;`. Strict pragmas for unsupported Solidity versions, for example `pragma solidity 0.8.28;`, will currently not compile with this hardhat-solx plugin. See more details below for the currently supported Solidity versions and EVM versions.
+
+## Usage
+
+Run tests or compile using the solx-powered build profile:
+
+```bash
+hardhat test --build-profile solx
+hardhat build --build-profile solx
+```
+
+The default profile continues to use solc as usual:
+
+```bash
+hardhat build    # uses solc (default profile)
+```
+
+## Configuration
+
+### Multi-version example
+
+You can configure the `solx` profile with multiple compilers. Compilers without `type: "solx"` will use solc:
+
+```typescript
+export default defineConfig({
+  plugins: [hardhatSolx],
+  solidity: {
+    profiles: {
+      default: {
+        compilers: [{ version: "0.8.34" }, { version: "0.8.20" }],
+      },
+      solx: {
+        compilers: [
+          { type: "solx", version: "0.8.34" },
+          { version: "0.8.20" }, // uses solc, solx doesn't support this version
+        ],
+      },
+    },
+  },
+});
+```
+
+### Options
+
+- `dangerouslyAllowSolxInProduction` (`boolean`, default: `false`), allows compiler type `"solx"` in build profiles other than `solx`. By default, using `type: "solx"` in any other profile (e.g. `default`, `production`) will produce a validation error.
+
+```typescript
+export default defineConfig({
+  plugins: [hardhatSolx],
+  solidity: {
+    profiles: {
+      default: {
+        type: "solx", // returns a validation error.
+        version: "0.8.34",
+      },
+    },
+  },
+  solx: {
+    dangerouslyAllowSolxInProduction: false, // default false, switching this to true will allow `type: "solx"` on the default profile.
+  },
+});
+```
+
+### Supported Solidity versions
+
+solx maps each Solidity version to a specific solx binary version internally. Currently supported: `0.8.33` (solx 0.1.3), `0.8.34` (solx 0.1.4).
+
+### EVM version support
+
+solx supports EVM versions `cancun`, `prague`, and `osaka`. Using an older EVM target (e.g., `paris`, `shanghai`) with compiler type `"solx"` will result in a validation error.

packages/hardhat-solx/eslint.config.js

@@ -0,0 +1,3 @@
+import { createConfig } from "../config/eslint.config.js";
+
+export default createConfig(import.meta.filename);

packages/hardhat-solx/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@nomicfoundation/hardhat-solx",
+  "private": true,
+  "version": "2.0.0",
+  "description": "Hardhat plugin for using solx compiler in test builds",
+  "homepage": "https://github.com/NomicFoundation/hardhat/tree/main/packages/hardhat-solx",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NomicFoundation/hardhat",
+    "directory": "packages/hardhat-solx"
+  },
+  "author": "Nomic Foundation",
+  "license": "MIT",
+  "type": "module",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "keywords": [
+    "ethereum",
+    "smart-contracts",
+    "hardhat",
+    "solx",
+    "compiler"
+  ],
+  "scripts": {
+    "lint": "pnpm prettier --check && pnpm eslint",
+    "lint:fix": "pnpm prettier --write && pnpm eslint --fix",
+    "eslint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prettier": "prettier \"**/*.{ts,js,md,json}\"",
+    "test": "node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "test:only": "node --import tsx/esm --test --test-only --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "test:coverage": "c8 --reporter html --reporter text --all --exclude test --exclude \"src/**/{types,type-extensions}.ts\" --src src node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "pretest": "pnpm build",
+    "pretest:only": "pnpm build",
+    "build": "tsc --build .",
+    "prepublishOnly": "pnpm build",
+    "clean": "rimraf dist"
+  },
+  "files": [
+    "dist/src/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@nomicfoundation/hardhat-node-test-reporter": "workspace:^3.0.0",
+    "@nomicfoundation/hardhat-test-utils": "workspace:^",
+    "@types/debug": "^4.1.7",
+    "@types/node": "^22.0.0",
+    "c8": "^9.1.0",
+    "eslint": "9.25.1",
+    "prettier": "3.2.5",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.19.3",
+    "typescript": "~5.8.0",
+    "hardhat": "workspace:^3.1.6"
+  },
+  "dependencies": {
+    "@nomicfoundation/hardhat-errors": "workspace:^3.0.3",
+    "@nomicfoundation/hardhat-utils": "workspace:^3.0.5",
+    "@nomicfoundation/hardhat-zod-utils": "workspace:^3.0.0",
+    "debug": "^4.3.2",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "hardhat": "workspace:^3.1.6"
+  }
+}

packages/hardhat-solx/src/index.ts

@@ -0,0 +1,14 @@
+import type { HardhatPlugin } from "hardhat/types/plugins";
+
+import "./type-extensions.js";
+
+const hardhatSolxPlugin: HardhatPlugin = {
+  id: "hardhat-solx",
+  npmPackage: "@nomicfoundation/hardhat-solx",
+  hookHandlers: {
+    config: () => import("./internal/hook-handlers/config.js"),
+    solidity: () => import("./internal/hook-handlers/solidity.js"),
+  },
+};
+
+export default hardhatSolxPlugin;

packages/hardhat-solx/src/internal/constants.ts

@@ -0,0 +1,30 @@
+import type { SolidityCompilerType } from "hardhat/types/config";
+
+/**
+ * The compiler type identifier registered by this plugin.
+ * Typed as SolidityCompilerType for type-safe comparisons.
+ */
+export const SOLX_COMPILER_TYPE: SolidityCompilerType = "solx";
+
+export const SOLX_RELEASES_BASE_URL =
+  "https://solx-releases-mirror.hardhat.org";
+
+export const SUPPORTED_SOLX_EVM_VERSIONS: readonly string[] = [
+  "cancun",
+  "prague",
+  "osaka",
+] as const;
+
+export const DEFAULT_SOLX_SETTINGS: Record<string, unknown> = {
+  viaIR: false,
+  LLVMOptimization: "1",
+};
+
+/**
+ * Maps Solidity compiler versions to the solx version that embeds them.
+ * Only stable solx releases are included.
+ */
+export const SOLIDITY_TO_SOLX_VERSION_MAP: Record<string, string> = {
+  "0.8.33": "0.1.3",
+  "0.8.34": "0.1.4",
+};