@iexec-nox/nox-protocol-contracts 0.1.0-beta.9 → 0.2.0

package/README.md

@@ -1,63 +1,100 @@
-# Nox Protocol Contracts
+# Nox · nox-protocol-contracts
 
-Smart contracts for the Nox protocol, including on-chain access control for encrypted handles and the compute gateway for confidential operations.
+[![License](https://img.shields.io/badge/license-BUSL--1.1-blue)](./LICENSE)
+[![Docs](https://img.shields.io/badge/docs-nox--protocol-purple)](https://docs.iex.ec)
+[![Discord](https://img.shields.io/badge/chat-Discord-5865F2)](https://discord.com/invite/5TewNUnJHN)
+[![Tag](https://img.shields.io/github/v/tag/iExec-Nox/nox-protocol-contracts?label=tag)](https://github.com/iExec-Nox/nox-protocol-contracts/releases)
+[![npm](https://img.shields.io/npm/v/@iexec-nox/nox-protocol-contracts?label=npm)](https://www.npmjs.com/package/@iexec-nox/nox-protocol-contracts)
+[![codecov](https://codecov.io/gh/iExec-Nox/nox-protocol-contracts/graph/badge.svg?token=8uANxipzVv)](https://codecov.io/gh/iExec-Nox/nox-protocol-contracts)
 
-## What’s inside
+> Solidity contracts for the Nox protocol: manage encrypted handles, validate proofs, and trigger confidential computations.
 
-- `INoxCompute`: TEE compute entry point (handle validation, plaintext → encrypted conversion, arithmetic ops).
-- `Nox` SDK library: convenience wrapper for app contracts that call `NoxCompute`.
+## Table of Contents
 
-## Requirements
+- [Nox · nox-protocol-contracts](#nox--nox-protocol-contracts)
+    - [Table of Contents](#table-of-contents)
+    - [Overview](#overview)
+    - [Prerequisites](#prerequisites)
+    - [Getting Started](#getting-started)
+    - [Environment Variables](#environment-variables)
+    - [Testing](#testing)
+    - [Deployment](#deployment)
+    - [Verification](#verification)
+    - [Configuration notes](#configuration-notes)
+    - [Related Repositories](#related-repositories)
+    - [Contributing](#contributing)
+        - [Code style](#code-style)
+    - [License](#license)
 
-- Node.js version from `.nvmrc`
-- `pnpm` (see `packageManager` in `package.json`)
+## Overview
 
-## Setup
+**nox-protocol-contracts** is the Solidity layer of the Nox protocol. It provides:
+
+- **NoxCompute**: the main UUPS-upgradeable contract that manages the Access Control List (ACL) for encrypted handles, validates handle proofs issued by a trusted gateway, facilitates plaintext-to-encrypted conversions, and triggers off-chain TEE computations through event emissions.
+- **INoxCompute**: the public interface consumed by application contracts and off-chain services.
+- **Nox SDK library** (`contracts/sdk/Nox.sol`): a convenience wrapper that resolves the NoxCompute proxy address per chain and exposes typed helper functions for application contracts.
+
+## Prerequisites
+
+- Node.js >= 24 (see `.nvmrc`)
+- pnpm >= 10 (see `packageManager` in `package.json`)
+- Hardhat >= 3
+
+## Getting Started
 
 ```bash
+git clone https://github.com/iExec-Nox/nox-protocol-contracts.git
+cd nox-protocol-contracts
+
+# Use the correct Node version
 nvm install && nvm use
-pnpm install
-```
 
-## Build
+# Install dependencies
+pnpm install
 
-```bash
+# Build contracts
 pnpm run build
 ```
 
-## Test
+## Environment Variables
 
-```bash
-pnpm run test
-```
+| Variable            | Description                                    | Required          | Default |
+| ------------------- | ---------------------------------------------- | ----------------- | ------- |
+| `RPC_URL`           | JSON-RPC endpoint for the target network       | For remote deploy | -       |
+| `PRIVATE_KEY`       | Deployer private key                           | For remote deploy | -       |
+| `ETHERSCAN_API_KEY` | API key for contract verification on Etherscan | For verification  | -       |
 
-## Coverage
+## Testing
 
 ```bash
-pnpm run coverage
-```
+# Run all tests (unit + integration)
+pnpm run test
 
-## Formatting
+# Run tests with gas stats
+pnpm run test:gas
 
-```bash
-pnpm run format
-pnpm run format:check
+# Run coverage
+pnpm run coverage
 ```
 
 ## Deployment
 
-The default network is a local EDR simulation. For external networks, configure the required variables:
-
-- `RPC_URL`
-- `PRIVATE_KEY`
+The default network is a local EDR simulation. For external networks, set `RPC_URL` and `PRIVATE_KEY`:
 
 ```bash
+# Local deploy
 pnpm run deploy
+
+# Production deploy (optimizer + viaIR)
+pnpm run deploy:production
+
+# Upgrade an existing proxy
+pnpm run upgrade
 ```
 
-## Verify
+## Verification
 
-Verify deployed contracts on Etherscan. Requires `ETHERSCAN_API_KEY`
+Verify deployed contracts on Etherscan. Requires `ETHERSCAN_API_KEY`:
 
 ```bash
 pnpm run verify arbitrumSepolia --network arbitrumSepolia
@@ -65,18 +102,46 @@ pnpm run verify arbitrumSepolia --network arbitrumSepolia
 
 ## Configuration notes
 
-- Create2 salt is defined in [config/config.ts](config/config.ts).
-- Default owner addresses and KMS public keys per network are also defined in [config/config.ts](config/config.ts).
-- The SDK constants in [contracts/sdk/Nox.sol](contracts/sdk/Nox.sol) must match the deployed proxy addresses.
+- CREATE2 salt is defined in [`config/config.ts`](config/config.ts).
+- Default owner addresses and KMS public keys per network are also defined in [`config/config.ts`](config/config.ts).
+- The SDK constants in [`contracts/sdk/Nox.sol`](contracts/sdk/Nox.sol) must match the deployed proxy addresses.
+- OpenZeppelin manifest files in `.openzeppelin/` track proxy deployments.
+
+## Related Repositories
+
+| Repository                                                                      | Description                                         |
+| ------------------------------------------------------------------------------- | --------------------------------------------------- |
+| [nox-handle-sdk](https://github.com/iExec-Nox/nox-handle-sdk)                   | TypeScript SDK for handle encryption/decryption     |
+| [nox-offchain-deployment](https://github.com/iExec-Nox/nox-offchain-deployment) | Off-chain services (gateway, KMS, runner, ingestor) |
+
+## Contributing
+
+Contributions are welcome. Please open an issue first to discuss your proposed changes.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+### Code style
+
+```bash
+# Format all files
+pnpm run format
+
+# Check formatting
+pnpm run format:check
+```
 
 ## License
 
-The Nox Protocol source code is released under the Business Source License 1.1 (BUSL-1.1).
+The Nox Protocol source code is released under the [Business Source License 1.1 (BUSL-1.1)](./LICENSE).
 
 The license will automatically convert to the MIT License under the conditions described in the LICENSE file.
 
-The full text of the MIT License is provided in the LICENSE-MIT file.
+The full text of the MIT License is provided in the [LICENSE-MIT](./LICENSE-MIT) file.
 
-However, some files are dual licensed under `MIT`:
+Some files are dual-licensed under MIT:
 
-- All files in `contracts/interfaces/`, `contracts/shared/`, `contracts/sdk/` may also be licensed under `MIT` (as indicated in their SPDX headers).
+- All files in `contracts/interfaces/`, `contracts/shared/`, `contracts/sdk/` may also be licensed under MIT (as indicated in their SPDX headers).

package/contracts/sdk/Nox.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.27;
 
+import {HandleUtils} from "../shared/HandleUtils.sol";
 import {TEEType, TypeUtils} from "../shared/TypeUtils.sol";
 import {INoxCompute} from "../interfaces/INoxCompute.sol";
 import "encrypted-types/EncryptedTypes.sol";
@@ -33,7 +34,7 @@ library Nox {
         }
         // Local development chain
         if (block.chainid == 31337) {
-            return 0x39847AeBa923Cc7367d4684194091D022B3F8548;
+            return 0x44C00793aD4975617b3B5Fc27D4FB78E772c8236;
         }
         revert("Nox: Unsupported chain");
     }
@@ -47,7 +48,7 @@ library Nox {
      * Public handles are already accessible by everyone and don't need ACL.
      */
     function _allowIfNotPublic(bytes32 handle, address account) private {
-        if (!TypeUtils.isPublicHandle(handle)) {
+        if (!HandleUtils.isPublicHandle(handle)) {
             _noxComputeContract().allow(handle, account);
         }
     }
@@ -57,7 +58,7 @@ library Nox {
      * Public handles are already accessible by everyone and don't need ACL.
      */
     function _allowTransientIfNotPublic(bytes32 handle, address account) private {
-        if (!TypeUtils.isPublicHandle(handle)) {
+        if (!HandleUtils.isPublicHandle(handle)) {
             _noxComputeContract().allowTransient(handle, account);
         }
     }
@@ -67,7 +68,7 @@ library Nox {
      * Public handles are already accessible by everyone and don't need ACL.
      */
     function _disallowTransientIfNotPublic(bytes32 handle, address account) private {
-        if (!TypeUtils.isPublicHandle(handle)) {
+        if (!HandleUtils.isPublicHandle(handle)) {
             _noxComputeContract().disallowTransient(handle, account);
         }
     }
@@ -84,16 +85,6 @@ library Nox {
         return ebool.unwrap(handle) != 0;
     }
 
-    /**
-     * @dev Checks if an encrypted address handle is initialized.
-     * This is a basic check and does not guarantee that the handle
-     * is valid or recognized by the ACL.
-     * @param handle encrypted address handle
-     */
-    function isInitialized(eaddress handle) internal pure returns (bool) {
-        return eaddress.unwrap(handle) != 0;
-    }
-
     /**
      * @dev Checks if an encrypted uint16 handle is initialized.
      * This is a basic check and does not guarantee that the handle
@@ -203,15 +194,6 @@ library Nox {
         return ebool.wrap(handle);
     }
 
-    function fromExternal(
-        externalEaddress externalHandle,
-        bytes calldata handleProof
-    ) internal returns (eaddress) {
-        bytes32 handle = externalEaddress.unwrap(externalHandle);
-        _noxComputeContract().validateInputProof(handle, msg.sender, handleProof, TEEType.Address);
-        return eaddress.wrap(handle);
-    }
-
     function fromExternal(
         externalEuint16 externalHandle,
         bytes calldata handleProof
@@ -901,14 +883,6 @@ library Nox {
         _allowIfNotPublic(ebool.unwrap(value), account);
     }
 
-    /**
-     * @dev Allows the use of value for the address account.
-     * Silently skips public handles (they are already accessible by everyone).
-     */
-    function allow(eaddress value, address account) internal {
-        _allowIfNotPublic(eaddress.unwrap(value), account);
-    }
-
     /**
      * @dev Allows the use of value for the address account.
      * Silently skips public handles (they are already accessible by everyone).
@@ -949,14 +923,6 @@ library Nox {
         _allowIfNotPublic(ebool.unwrap(value), address(this));
     }
 
-    /**
-     * @dev Allows the use of value for this address (address(this)).
-     * Silently skips public handles (they are already accessible by everyone).
-     */
-    function allowThis(eaddress value) internal {
-        _allowIfNotPublic(eaddress.unwrap(value), address(this));
-    }
-
     /**
      * @dev Allows the use of value for this address (address(this)).
      * Silently skips public handles (they are already accessible by everyone).
@@ -997,14 +963,6 @@ library Nox {
         _allowTransientIfNotPublic(ebool.unwrap(value), account);
     }
 
-    /**
-     * @dev Allows the use of value by address account for this transaction.
-     * Silently skips public handles (they are already accessible by everyone).
-     */
-    function allowTransient(eaddress value, address account) internal {
-        _allowTransientIfNotPublic(eaddress.unwrap(value), account);
-    }
-
     /**
      * @dev Allows the use of value by address account for this transaction.
      * Silently skips public handles (they are already accessible by everyone).
@@ -1045,14 +1003,6 @@ library Nox {
         _disallowTransientIfNotPublic(ebool.unwrap(value), account);
     }
 
-    /**
-     * @dev Revokes transient access to value for address account within the current transaction.
-     * Silently skips public handles (they are already accessible by everyone).
-     */
-    function disallowTransient(eaddress value, address account) internal {
-        _disallowTransientIfNotPublic(eaddress.unwrap(value), account);
-    }
-
     /**
      * @dev Revokes transient access to value for address account within the current transaction.
      * Silently skips public handles (they are already accessible by everyone).
@@ -1092,13 +1042,6 @@ library Nox {
         return _noxComputeContract().isAllowed(ebool.unwrap(handle), account);
     }
 
-    /**
-     * @dev Checks if the handle is allowed for the account.
-     */
-    function isAllowed(eaddress handle, address account) internal view returns (bool) {
-        return _noxComputeContract().isAllowed(eaddress.unwrap(handle), account);
-    }
-
     /**
      * @dev Checks if the handle is allowed for the account.
      */
@@ -1136,13 +1079,6 @@ library Nox {
         _noxComputeContract().addViewer(ebool.unwrap(value), viewer);
     }
 
-    /**
-     * @dev Adds a viewer for an eaddress handle.
-     */
-    function addViewer(eaddress value, address viewer) internal {
-        _noxComputeContract().addViewer(eaddress.unwrap(value), viewer);
-    }
-
     /**
      * @dev Adds a viewer for an euint16 handle.
      */
@@ -1178,13 +1114,6 @@ library Nox {
         return _noxComputeContract().isViewer(ebool.unwrap(handle), viewer);
     }
 
-    /**
-     * @dev Checks if the viewer can view the handle.
-     */
-    function isViewer(eaddress handle, address viewer) internal view returns (bool) {
-        return _noxComputeContract().isViewer(eaddress.unwrap(handle), viewer);
-    }
-
     /**
      * @dev Checks if the viewer can view the handle.
      */
@@ -1222,13 +1151,6 @@ library Nox {
         _noxComputeContract().allowPublicDecryption(ebool.unwrap(value));
     }
 
-    /**
-     * @dev Marks an eaddress handle as publicly decryptable.
-     */
-    function allowPublicDecryption(eaddress value) internal {
-        _noxComputeContract().allowPublicDecryption(eaddress.unwrap(value));
-    }
-
     /**
      * @dev Marks an euint16 handle as publicly decryptable.
      */
@@ -1264,13 +1186,6 @@ library Nox {
         return _noxComputeContract().isPubliclyDecryptable(ebool.unwrap(handle));
     }
 
-    /**
-     * @dev Checks if the handle is publicly decryptable.
-     */
-    function isPubliclyDecryptable(eaddress handle) internal view returns (bool) {
-        return _noxComputeContract().isPubliclyDecryptable(eaddress.unwrap(handle));
-    }
-
     /**
      * @dev Checks if the handle is publicly decryptable.
      */
@@ -1317,21 +1232,6 @@ library Nox {
         return result[0] != 0x00;
     }
 
-    /**
-     * @dev Verifies a decryption proof and returns the decrypted address value.
-     */
-    function publicDecrypt(
-        eaddress handle,
-        bytes calldata decryptionProof
-    ) internal view returns (address plaintextValue) {
-        bytes memory result = _noxComputeContract().validateDecryptionProof(
-            eaddress.unwrap(handle),
-            decryptionProof
-        );
-        require(result.length == 20, MalformedDecryptedData(result));
-        return address(bytes20(result));
-    }
-
     /**
      * @dev Verifies a decryption proof and returns the decrypted uint16 value.
      */
@@ -1402,6 +1302,6 @@ library Nox {
         bytes32 handle,
         TEEType teeType
     ) private view returns (bytes32) {
-        return handle == bytes32(0) ? TypeUtils.zeroHandle(teeType) : handle;
+        return handle == bytes32(0) ? HandleUtils.zeroHandle(teeType) : handle;
     }
 }

package/contracts/shared/HandleUtils.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import {TEEType} from "./TypeUtils.sol";
+
+library HandleUtils {
+    /// @dev Bit 0 of the attrs byte. When set, the handle is guaranteed unique on-chain.
+    bytes1 internal constant ATTR_IS_UNIQUE_HANDLE = 0x01;
+
+    /**
+     * @notice Checks if a handle is a public handle (isUniqueHandle bit == 0).
+     * A public handle wraps a plaintext value known on-chain, has no ACL,
+     * and is accessible by everyone.
+     * @param handle The handle to check
+     * @return True if the handle is a public handle
+     */
+    function isPublicHandle(bytes32 handle) internal pure returns (bool) {
+        return (handle[6] & ATTR_IS_UNIQUE_HANDLE) == 0;
+    }
+
+    /**
+     * @notice Returns the zero handle for the given TEE type on the current chain.
+     * The zero handle represents the default zero value for a given type and is a public handle.
+     * It follows the standard handle format but with a zeroed pre-handle:
+     *   [0]=version(0x00)  [1-4]=chainId  [5]=teeType  [6]=attrs(0x00)  [7-31]=0x00..00
+     * @param teeType The TEE type to encode
+     * @return The typed null handle
+     */
+    function zeroHandle(TEEType teeType) internal view returns (bytes32) {
+        return
+            // [0]=version is implicitly 0x00
+            (bytes32(bytes4(uint32(block.chainid))) >> (1 * 8)) |
+            (bytes32(bytes1(uint8(teeType))) >> (5 * 8));
+    }
+}

package/contracts/shared/TypeUtils.sol

@@ -116,8 +116,18 @@ error NonArithmeticType();
 error UnsupportedArithmeticType();
 
 library TypeUtils {
-    /// @dev Bit 0 of the attrs byte. When set, the handle is guaranteed unique on-chain.
-    bytes1 internal constant ATTR_IS_UNIQUE_HANDLE = 0x01;
+    /**
+     * Returns the list of all currently supported TEE types.
+     * @dev Update this list when new types are supported.
+     */
+    function allCurrentlySupportedTypes() internal pure returns (TEEType[] memory types) {
+        types = new TEEType[](5);
+        types[0] = TEEType.Bool;
+        types[1] = TEEType.Uint16;
+        types[2] = TEEType.Uint256;
+        types[3] = TEEType.Int16;
+        types[4] = TEEType.Int256;
+    }
 
     /**
      * @notice Extracts the TEE type from a handle.
@@ -129,17 +139,6 @@ library TypeUtils {
         return TEEType(uint8(handle[5]));
     }
 
-    /**
-     * @notice Checks if a handle is a public handle (isUniqueHandle bit == 0).
-     * A public handle wraps a plaintext value known on-chain, has no ACL,
-     * and is accessible by everyone.
-     * @param handle The handle to check
-     * @return True if the handle is a public handle
-     */
-    function isPublicHandle(bytes32 handle) internal pure returns (bool) {
-        return (handle[6] & ATTR_IS_UNIQUE_HANDLE) == 0;
-    }
-
     /**
      * @notice Validates that a TEE type is supported for arithmetic operations.
      * Only the following arithmetic types are supported:
@@ -154,25 +153,11 @@ library TypeUtils {
     function validateArithmeticType(TEEType teeType) internal pure {
         uint8 t = uint8(teeType);
         require(t >= uint8(TEEType.Uint8) && t <= uint8(TEEType.Int256), NonArithmeticType());
-        bool supportedType = teeType == TEEType.Uint16 ||
-            teeType == TEEType.Uint256 ||
-            teeType == TEEType.Int16 ||
-            teeType == TEEType.Int256;
+        bool supportedType =
+            teeType == TEEType.Uint16 ||
+                teeType == TEEType.Uint256 ||
+                teeType == TEEType.Int16 ||
+                teeType == TEEType.Int256;
         require(supportedType, UnsupportedArithmeticType());
     }
-
-    /**
-     * @notice Returns the zero handle for the given TEE type on the current chain.
-     * The zero handle represents the default zero value for a given type.
-     * It follows the standard handle format but with a zeroed pre-handle:
-     *   [0]=version(0x00)  [1-4]=chainId  [5]=teeType  [6]=attrs(0x00)  [7-31]=0x00..00
-     * @param teeType The TEE type to encode
-     * @return The typed null handle
-     */
-    function zeroHandle(TEEType teeType) internal view returns (bytes32) {
-        return
-            // [0]=version is implicitly 0x00
-            (bytes32(bytes4(uint32(block.chainid))) >> (1 * 8)) |
-            (bytes32(bytes1(uint8(teeType))) >> (5 * 8));
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iexec-nox/nox-protocol-contracts",
-  "version": "0.1.0-beta.9",
+  "version": "0.2.0",
   "description": "Nox protocol smart contracts",
   "keywords": [
     "Nox",
@@ -26,8 +26,8 @@
     "deploy:production": "pnpm hardhat run scripts/deploy.ts --build-profile production",
     "set-gateway": "pnpm hardhat run scripts/set-gateway.ts",
     "set-kms-public-key": "pnpm hardhat run scripts/set-kms-public-key.ts",
-    "upgrade": "pnpm hardhat run scripts/upgrade.ts",
-    "upgrade:production": "pnpm hardhat run scripts/upgrade.ts --build-profile production",
+    "upgrade": "bash scripts/upgrade.sh",
+    "upgrade:production": "bash scripts/upgrade.sh --build-profile production",
     "verify": "pnpm hardhat ignition verify",
     "format": "pnpm prettier --write .",
     "format:check": "pnpm prettier --check ."
@@ -44,19 +44,19 @@
   },
   "devDependencies": {
     "@nomicfoundation/hardhat-ethers": "^4.0.6",
-    "@nomicfoundation/hardhat-ignition": "^3.0.9",
-    "@nomicfoundation/hardhat-toolbox-viem": "^5.0.2",
+    "@nomicfoundation/hardhat-ignition": "^3.1.0",
+    "@nomicfoundation/hardhat-toolbox-viem": "^5.0.3",
     "@openzeppelin/hardhat-upgrades": "4.0.0-alpha.0",
-    "@types/node": "^22.19.13",
+    "@types/node": "^25.5.0",
     "ethers": "^6.16.0",
     "forge-std": "github:foundry-rs/forge-std#v1.15.0",
-    "hardhat": "^3.1.11",
+    "hardhat": "^3.2.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.3.1",
+    "lint-staged": "^16.4.0",
     "prettier": "^3.8.1",
-    "prettier-plugin-solidity": "^2.2.1",
-    "typescript": "^5.9.3",
-    "viem": "^2.46.3"
+    "prettier-plugin-solidity": "^2.3.1",
+    "typescript": "^6.0.2",
+    "viem": "^2.47.6"
   },
   "homepage": "https://github.com/iExec-Nox/nox-protocol-contracts#readme",
   "repository": {