Getting Started

The Nox JS SDK lets you encrypt values and decrypt handles for use with confidential smart contracts, without dealing directly with the Handle Gateway or the underlying cryptography. It manages encryption, proof generation, EIP-712 signatures, and key exchange transparently.

How It Works

Working with confidential data on Nox follows a three-step workflow:

1. Encrypt — You encrypt a plaintext value (a balance, a vote, a flag…) using encryptInput. The SDK sends the value to the Handle Gateway, which returns a handle (a 32-byte on-chain identifier pointing to the encrypted data) and a handleProof (an EIP-712 signed proof that the handle was created by a legitimate Gateway).

2. Compute — Your smart contract receives the handle and proof, verifies them, and performs operations on encrypted data. Handles are composable: they can be stored, transferred, or combined in contract logic without ever exposing the underlying values.

3. Decrypt — When a user needs to read the actual value, there are two paths depending on the handle's visibility:

   • ACL-protected handles — Use decrypt. The SDK signs an EIP-712 authorization message (no gas required). If the on-chain ACL authorizes the request, the plaintext is securely returned to the caller.
   • Publicly decryptable handles — Use publicDecrypt. No ACL check or EIP-712 signature is needed: anyone can decrypt the value as long as the handle has been marked as publicly decryptable on-chain.

Prerequisites

• Node.js 18+ or Bun
• A wallet library: Ethers.js v6 or Viem v2

Installation

npm

npm install @iexec-nox/handle

yarn

yarn add @iexec-nox/handle

pnpm

pnpm add @iexec-nox/handle

bun

bun add @iexec-nox/handle

Initialization

The SDK exposes a dedicated factory function for each supported wallet library. Pick the one that matches your stack — each is async and returns a Promise<HandleClient>.

Factory	Wallet library	Accepted client
createEthersHandleClient	Ethers.js v6	BrowserProvider or AbstractSigner with Provider
createViemHandleClient	Viem v2	WalletClient or SmartAccount (ERC-4337 account abstraction)
createHandleClient	Any	Auto-detects ethers or viem (including SmartAccount)

With Ethers.js

Browser

import { createEthersHandleClient } from '@iexec-nox/handle';
import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(window.ethereum);
const handleClient = await createEthersHandleClient(provider);

NodeJS

import { createEthersHandleClient } from '@iexec-nox/handle';
import { JsonRpcProvider, Wallet } from 'ethers';

const provider = new JsonRpcProvider(RPC_URL);
const signer = new Wallet(PRIVATE_KEY, provider);
const handleClient = await createEthersHandleClient(signer);

With Viem

Browser

import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';

const walletClient = createWalletClient({
  transport: custom(window.ethereum),
});
const handleClient = await createViemHandleClient(walletClient);

NodeJS

import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

const walletClient = createWalletClient({
  account: privateKeyToAccount(PRIVATE_KEY),
  transport: http(RPC_URL),
});
const handleClient = await createViemHandleClient(walletClient);

With Viem Smart Account (ERC-4337)

The SDK supports viem Smart Accounts for account abstraction. Pass a SmartAccount instance directly to the factory.

import { createViemHandleClient } from '@iexec-nox/handle';
import { createPublicClient, http } from 'viem';
import { arbitrumSepolia } from 'viem/chains';
import { toSimple7702SmartAccount } from 'viem/account-abstraction';
import { privateKeyToAccount } from 'viem/accounts';

const publicClient = createPublicClient({
  chain: arbitrumSepolia,
  transport: http(RPC_URL),
});

const smartAccount = await toSimple7702SmartAccount({
  owner: privateKeyToAccount(PRIVATE_KEY),
  client: publicClient,
});

const handleClient = await createViemHandleClient(smartAccount as any);

TIP

Smart Account support enables ERC-4337 account abstraction workflows. The SDK handles EIP-712 signature generation through the Smart Account's signTypedData method, and the Handle Gateway verifies signatures using ERC-1271 isValidSignature on-chain.

With Auto-Detection

createHandleClient inspects the provided client at runtime and delegates to the appropriate adapter.

WARNING

Bundle size: This factory imports both the ethers and viem adapters. If you only use one library, prefer createEthersHandleClient or createViemHandleClient to keep your bundle smaller.

Ethers

import { createHandleClient } from '@iexec-nox/handle';
import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(window.ethereum);
const handleClient = await createHandleClient(provider);

Viem

import { createHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';

const walletClient = createWalletClient({
  transport: custom(window.ethereum),
});
const handleClient = await createHandleClient(walletClient);

Next Steps

• Learn about encryptInput — encrypt values and create handles for smart contracts
• Explore decrypt — retrieve plaintext from encrypted handles
• Use publicDecrypt — decrypt publicly decryptable handles with a verifiable proof
• Inspect permissions with viewACL — view the Access Control List of a handle
• Configure advanced options in Advanced Configuration