### Install Project Dependencies

Source: https://github.com/iexec-nox/documentation/blob/main/README.md

Run this command in your terminal to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Solidity Library Installation

Source: https://context7.com/iexec-nox/documentation/llms.txt

Install the Nox Solidity library to build confidential smart contracts with encrypted types and TEE-backed computation.

```APIDOC
## Solidity Library Installation

Install the Nox Solidity library to build confidential smart contracts with encrypted types and TEE-backed computation.

```sh
npm install @iexec-nox/nox-protocol-contracts
```

```solidity
import {Nox, euint256, externalEuint256} from "@iexec-nox/nox-protocol-contracts/contracts/sdk/Nox.sol";
```
```

--------------------------------

### Viem Example

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/public-decryption.md

Example of how to call the `allowPublicDecryption` function using Viem.

```APIDOC
## Viem Example

### Description
This code snippet demonstrates how to interact with the Nox protocol contract to allow public decryption of a handle using the Viem library.

### Method
`walletClient.writeContract` with `functionName: 'allowPublicDecryption'`

### Parameters
#### Path Parameters
- **handle** (bytes32) - Required - The handle to make publicly decryptable.

### Request Example
```typescript
import {
  createWalletClient,
  http,
  custom,
  type WalletClient,
  type Chain,
} from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const CHAIN: Chain = arbitrumSepolia as Chain;
const handle = '0xHandle';
const walletClient: WalletClient = createWalletClient({
  transport: custom((window as any).ethereum),
  chain: CHAIN,
});
const NOX_CONTRACT_ADDRESS: `0x${string}` = '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
    ],
    name: 'allowPublicDecryption',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
] as const;

const [userAddress] = await walletClient.getAddresses();

await walletClient.writeContract({
  account: userAddress,
  chain: CHAIN,
  address: NOX_CONTRACT_ADDRESS,
  abi: NOX_CONTRACT_ABI,
  functionName: 'allowPublicDecryption',
  args: [handle],
});
```

### Response
Transaction receipt after successful execution.
```

--------------------------------

### Start Development Server

Source: https://github.com/iexec-nox/documentation/blob/main/README.md

Execute this command to launch the development server. The documentation site will be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### JS SDK Installation

Source: https://context7.com/iexec-nox/documentation/llms.txt

Install the JavaScript SDK for encrypting values and decrypting handles without dealing with cryptographic complexity.

```APIDOC
## JS SDK Installation

Install the JavaScript SDK for encrypting values and decrypting handles without dealing with cryptographic complexity.

```sh
npm install @iexec-nox/handle
```
```

--------------------------------

### Install Nox JS SDK with bun

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Install the Nox JS SDK using bun. Ensure you have Node.js 18+ or Bun.

```sh
bun add @iexec-nox/handle
```

--------------------------------

### Ethers.js Example

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/public-decryption.md

Example of how to call the `allowPublicDecryption` function using ethers.js.

```APIDOC
## Ethers.js Example

### Description
This code snippet demonstrates how to interact with the Nox protocol contract to allow public decryption of a handle using the ethers.js library.

### Method
`noxContract.allowPublicDecryption(handle)`

### Parameters
#### Path Parameters
- **handle** (bytes32) - Required - The handle to make publicly decryptable.

### Request Example
```typescript
import { BrowserProvider, Contract, type AbstractSigner, type Provider } from 'ethers';

const signer: BrowserProvider | AbstractSigner<Provider> = new BrowserProvider((window as any).ethereum);
const handle = '0xHandle';
const NOX_CONTRACT_ADDRESS: `0x${string}` = '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
    ],
    name: 'allowPublicDecryption',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
] as const;

const noxContract = new Contract(NOX_CONTRACT_ADDRESS, NOX_CONTRACT_ABI, signer);
const tx = await noxContract.allowPublicDecryption(handle);
await tx.wait();
```

### Response
Transaction receipt after successful execution.
```

--------------------------------

### Install Nox JS SDK with npm

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Install the Nox JS SDK using npm. Ensure you have Node.js 18+ or Bun.

```sh
npm install @iexec-nox/handle
```

--------------------------------

### Install Nox Confidential Contracts

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/build-confidential-tokens/erc7984-token.md

Install the necessary package for confidential token contracts using your preferred package manager.

```sh
pnpm add @iexec-nox/nox-confidential-contracts
```

```sh
npm install @iexec-nox/nox-confidential-contracts
```

```sh
yarn add @iexec-nox/nox-confidential-contracts
```

```sh
bun add @iexec-nox/nox-confidential-contracts
```

--------------------------------

### Usage Example

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/fromExternal.md

An example demonstrating how to use the fromExternal function within a Solidity contract to validate an encrypted amount before using it in a deposit function.

```APIDOC
## Usage

```solidity
function deposit(externalEuint256 encryptedAmount, bytes calldata proof) external {
    // Validate the user's encrypted input
    euint256 amount = Nox.fromExternal(encryptedAmount, proof);

    // Now use the validated handle in computations
    euint256 newBalance = Nox.add(_balances[msg.sender], amount);
    Nox.allowThis(newBalance);
    Nox.allow(newBalance, msg.sender);
    _balances[msg.sender] = newBalance;
}
```
```

--------------------------------

### Add Viewer with viem

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/viewers.md

Example of how to call the `addViewer` function using the viem library.

```APIDOC
## addViewer with viem

### Description
Demonstrates how to use viem to interact with the Nox protocol contract to add a viewer.

### Method
`walletClient.writeContract` with `functionName: 'addViewer'`

### Endpoint
N/A (Smart contract interaction)

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle identifier.
- **viewerAddress** (string) - Required - The address of the viewer to add.

### Request Example
```ts
const handle = '0xHandle';
const viewerAddress = '0xViewerAddress';
await walletClient.writeContract({
  account: userAddress,
  chain: CHAIN,
  address: NOX_CONTRACT_ADDRESS,
  abi: NOX_CONTRACT_ABI,
  functionName: 'addViewer',
  args: [handle, viewerAddress],
});
```

### Response
Transaction receipt upon successful execution.
```

--------------------------------

### Add Viewer using viem

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/viewers.md

Example of adding a viewer to a handle using the viem library. This requires setting up a wallet client and specifying the chain.

```typescript
import {
  createWalletClient,
  http,
  custom,
  type WalletClient,
  type Chain,
} from 'viem';
import { arbitrumSepolia } from 'viem/chains';

/**
 * Current network.
 */
const CHAIN: Chain = arbitrumSepolia as Chain;

const handle = '0xHandle';
const viewerAddress = '0xViewerAddress';

const walletClient: WalletClient = createWalletClient({
  transport: custom((window as any).ethereum),
  chain: CHAIN,
});

/**
 * Nox protocol contract address, depending on the network.
 *
 * See deployment page for more details.
 */
const NOX_CONTRACT_ADDRESS: `0x${string}` =
  '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';

/**
 * `addViewer` ABI fragment
 */
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
      {
        internalType: 'address',
        name: 'viewer',
        type: 'address',
      },
    ],
    name: 'addViewer',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
] as const;
// ---cut---
const [userAddress] = await walletClient.getAddresses();

await walletClient.writeContract({
  account: userAddress,
  chain: CHAIN,
  address: NOX_CONTRACT_ADDRESS,
  abi: NOX_CONTRACT_ABI,
  functionName: 'addViewer',
  args: [handle, viewerAddress],
});
```

--------------------------------

### Install Nox JS SDK with yarn

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Install the Nox JS SDK using yarn. Ensure you have Node.js 18+ or Bun.

```sh
yarn add @iexec-nox/handle
```

--------------------------------

### Install Nox JS SDK with pnpm

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Install the Nox JS SDK using pnpm. Ensure you have Node.js 18+ or Bun.

```sh
pnpm add @iexec-nox/handle
```

--------------------------------

### Signed Integer Division Examples with safeDiv

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/safe-arithmetic.md

Illustrates signed integer division using safeDiv, covering division by zero, signed overflow, and truncated results.

```solidity
SafeDiv(100, 0)
```

```solidity
SafeDiv(0, 0)
```

```solidity
SafeDiv(-128, -1)
```

```solidity
SafeDiv(-7, 2)
```

```solidity
SafeDiv(50, 5)
```

--------------------------------

### Project File Structure

Source: https://github.com/iexec-nox/documentation/blob/main/CONTRIBUTING.md

Overview of the project's directory structure, including components, guides, and assets.

```text
src/
├── components/          # Reusable Vue components
├── get-started/         # Getting started guides
├── guides/              # Detailed guides
├── protocol/            # Protocol documentation
├── references/          # API references
└── assets/              # Images and resources
```

--------------------------------

### Install Nox Protocol Contracts with bun

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/getting-started.md

Install the Nox protocol contracts package using bun. This package includes the necessary libraries for working with encrypted types in Solidity.

```sh
bun add @iexec-nox/nox-protocol-contracts
```

--------------------------------

### Unsigned Integer Division Examples with safeDiv

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/safe-arithmetic.md

Demonstrates various scenarios of unsigned integer division using safeDiv, including division by zero, normal division, and truncated results.

```solidity
SafeDiv(255, 0)
```

```solidity
SafeDiv(0, 0)
```

```solidity
SafeDiv(100, 3)
```

```solidity
SafeDiv(1, 2)
```

```solidity
SafeDiv(0, 5)
```

--------------------------------

### Basic Arithmetic Operations Example

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/arithmetic.md

Demonstrates the basic usage of arithmetic operations like add, sub, mul, and div with encrypted uint256 values.

```Solidity
euint256 total = Nox.add(balance, deposit);
euint256 remaining = Nox.sub(total, fee);
euint256 reward = Nox.mul(remaining, rate);
euint256 share = Nox.div(reward, participantCount);
Nox.allowThis(share);
```

--------------------------------

### Install Nox Protocol Contracts with npm

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/getting-started.md

Install the Nox protocol contracts package using npm. This package includes the necessary libraries for working with encrypted types in Solidity.

```sh
npm install @iexec-nox/nox-protocol-contracts
```

--------------------------------

### Combined Component Usage Example

Source: https://github.com/iexec-nox/documentation/blob/main/CONTRIBUTING.md

Demonstrates combining Banner, VitePress native containers, CardWithBorder, and CardWithoutBorder for a structured page layout.

```markdown
<Banner>

## Installation Guide

</Banner>

::: info Prerequisites Make sure you have Node.js installed before continuing.
:::

<CardWithBorder>

### Step 1: Installation

```bash npm install ```

</CardWithBorder>

<CardWithoutBorder>

### Step 2: Configuration

Create your .env file based on .env.example.

</CardWithoutBorder>

::: tip Success! Your installation is now complete! :::
```

--------------------------------

### Install Nox Protocol Contracts with yarn

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/getting-started.md

Install the Nox protocol contracts package using yarn. This package includes the necessary libraries for working with encrypted types in Solidity.

```sh
yarn add @iexec-nox/nox-protocol-contracts
```

--------------------------------

### Install Nox Protocol Contracts with pnpm

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/getting-started.md

Install the Nox protocol contracts package using pnpm. This package includes the necessary libraries for working with encrypted types in Solidity.

```sh
pnpm add @iexec-nox/nox-protocol-contracts
```

--------------------------------

### Commit Message Examples

Source: https://github.com/iexec-nox/documentation/blob/main/CONTRIBUTING.md

Follow these patterns for commit messages to categorize changes effectively. Examples include adding new features, updating content, fixing issues, removing obsolete content, and documentation-only changes.

```text
Add: CardWithBorder component usage guide
```

```text
Update: VitePress container recommendations
```

```text
Fix: broken links in getting started guide
```

--------------------------------

### Encrypt Input and Get Handle

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/encryptInput.md

Initializes the Handle client and encrypts a value, returning a handle and its proof. Ensure your wallet is connected and the correct chain is selected.

```typescript
declare global {
  interface Window {
    ethereum: any;
  }
}
// ---cut---
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});

const handleClient = await createViemHandleClient(walletClient);

const { handle, handleProof } = await handleClient.encryptInput(
  100_000_000n,
  'uint256',
  '0x123...abc' // applicationContract - the contract that will use this handle
);
```

--------------------------------

### Add Viewer using ethers.js

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/viewers.md

Example of adding a viewer to a handle using the ethers.js library. Ensure you have the correct contract address and ABI.

```typescript
import {
  BrowserProvider,
  Contract,
  type AbstractSigner,
  type Provider,
} from 'ethers';

const signer: BrowserProvider | AbstractSigner<Provider> = new BrowserProvider(
  (window as any).ethereum
);

const handle = '0xHandle';
const viewerAddress = '0xViewerAddress';

/**
 * Nox protocol contract address, depending on the network.
 *
 * See deployment page for more details.
 */
const NOX_CONTRACT_ADDRESS: `0x${string}` =
  '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';

/**
 * `addViewer` ABI fragment
 */
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
      {
        internalType: 'address',
        name: 'viewer',
        type: 'address',
      },
    ],
    name: 'addViewer',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
] as const;
// ---cut---
const noxContract = new Contract(
  NOX_CONTRACT_ADDRESS,
  NOX_CONTRACT_ABI,
  signer
);
const tx = await noxContract.addViewer(handle, viewerAddress);
await tx.wait();
```

--------------------------------

### Add Viewer with ethers.js

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/viewers.md

Example of how to call the `addViewer` function using the ethers.js library.

```APIDOC
## addViewer with ethers.js

### Description
Demonstrates how to use ethers.js to interact with the Nox protocol contract to add a viewer.

### Method
`noxContract.addViewer(handle, viewerAddress)`

### Endpoint
N/A (Smart contract interaction)

### Parameters
#### Path Parameters
- **handle** (string) - Required - The handle identifier.
- **viewerAddress** (string) - Required - The address of the viewer to add.

### Request Example
```ts
const handle = '0xHandle';
const viewerAddress = '0xViewerAddress';
const noxContract = new Contract(NOX_CONTRACT_ADDRESS, NOX_CONTRACT_ABI, signer);
const tx = await noxContract.addViewer(handle, viewerAddress);
await tx.wait();
```

### Response
Transaction receipt upon successful execution.
```

--------------------------------

### select Method Signature and Usage

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/select.md

Demonstrates the signature of the select function and provides examples of its usage in Solidity for conditional operations on encrypted data.

```APIDOC
## select

Returns `ifTrue` when `condition` is encrypted `true`, `ifFalse` otherwise.
Since encrypted values cannot be branched on with `if`, `select` is the only way
to implement conditional logic on encrypted data. No computation is performed on
the values themselves, it is purely a selection.

**Supported types:** `euint16`, `euint256`, `eint16`, `eint256`

::: tip

`select` is the encrypted equivalent of a ternary operator
(`condition ? a : b`). Since encrypted values cannot be branched on with `if`,
use `select` for all conditional logic.

:::

### Usage

```solidity
// Confidential max(a, b)
ebool aIsGreater = Nox.gt(a, b);
euint256 maxValue = Nox.select(aIsGreater, a, b);
Nox.allowThis(maxValue);
```

```solidity
// Apply a fee only if balance exceeds threshold
ebool exceedsThreshold = Nox.gt(balance, threshold);
euint256 fee = Nox.select(exceedsThreshold, feeAmount, zeroAmount);
euint256 finalBalance = Nox.sub(balance, fee);
Nox.allowThis(fee);
Nox.allowThis(finalBalance);
```

## Signature

```solidity
function select(ebool condition, euint256 ifTrue, euint256 ifFalse) internal returns (euint256)
```

| Example                  | Result | Reason             |
| ------------------------ | ------ | ------------------ |
| `Select(true, 42, 100)`  | `42`   | Condition is true  |
| `Select(false, 42, 100)` | `100`  | Condition is false |
```

--------------------------------

### Encrypted Conditional Logic with Comparisons

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/comparisons.md

Demonstrates how to use comparison results with the `select` method for encrypted conditional logic. This example checks if a balance is sufficient before applying a transfer.

```Solidity
ebool hasEnough = Nox.ge(balance, amount);
euint256 newBalance = Nox.select(hasEnough, Nox.sub(balance, amount), balance);
Nox.allowThis(newBalance);
```

--------------------------------

### Encrypting Input Data

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/encryptInput.md

This example demonstrates how to encrypt different types of input data using the `encryptInput` method. It shows encryption for boolean, uint64, and string types, along with specifying the application contract address.

```APIDOC
## encryptInput

### Description
Encrypts input data to be used with iExec smart contracts. The function takes the data, its Solidity type, and the application contract address as arguments.

### Method Signature
`handleClient.encryptInput(value: any, solidityType: string, applicationContract: string): Promise<{ handle: Handle<T>; handleProof: string }> `

### Parameters
#### Value
- **value** (any) - Required - The data to encrypt. Can be a boolean, number (as BigInt for uint/int types), or string.
#### Solidity Type
- **solidityType** (string) - Required - The Solidity type of the data (e.g., 'bool', 'uint256', 'string'). Supported types at runtime include 'bool', 'uint16', 'uint256', 'int16', and 'int256'.
#### Application Contract
- **applicationContract** (string) - Required - The Ethereum address of the smart contract that will use this handle.

### Return Value
- **handle** (Handle<T>) - A deterministic identifier pointing to the encrypted data.
- **handleProof** (string) - An EIP-712 signed proof from the Handle Gateway attesting to the handle's legitimacy.

### Request Example
```ts
// Assuming handleClient is already initialized
const result = await handleClient.encryptInput(true, 'bool', '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');
console.log(result.handle, result.handleProof);

const uintResult = await handleClient.encryptInput(1000n, 'uint256', '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');
console.log(uintResult.handle, uintResult.handleProof);

const stringResult = await handleClient.encryptInput('Hello, Nox!', 'string', '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0');
console.log(stringResult.handle, stringResult.handleProof);
```
```

--------------------------------

### ConfidentialVault Contract Example

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library.md

Demonstrates how to use the Nox library to create a confidential vault contract. It includes functions for depositing encrypted amounts and managing balances using encrypted types.

```solidity
import {Nox, euint256, externalEuint256} from "@iexec-nox/nox-protocol-contracts/contracts/sdk/Nox.sol";

contract ConfidentialVault {
    mapping(address => euint256) private _balances;

    function deposit(externalEuint256 encryptedAmount, bytes calldata proof) external {
        euint256 amount = Nox.fromExternal(encryptedAmount, proof);
        euint256 balance = _balances[msg.sender];

        if (!Nox.isInitialized(balance)) {
            balance = Nox.toEuint256(0);
            Nox.allowThis(balance);
        }

        euint256 newBalance = Nox.add(balance, amount);
        Nox.allowThis(newBalance);
        Nox.allow(newBalance, msg.sender);
        _balances[msg.sender] = newBalance;
    }
}
```

--------------------------------

### Check Admin Access with viem

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/admins.md

Example of how to check if an account is an admin for a handle using the viem library. Ensure the correct Nox contract address and ABI are used.

```typescript
import { createPublicClient, http } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const handle = '0xHandle';
const account = '0xAccountAddress';

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

/**
 * Nox protocol contract address, depending on the network.
 *
 * See deployment page for more details.
 */
const NOX_CONTRACT_ADDRESS: `0x${string}` =
  '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';

/**
 * `isAllowed` ABI fragment
 */
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
      {
        internalType: 'address',
        name: 'account',
        type: 'address',
      },
    ],
    name: 'isAllowed',
    outputs: [
      {
        internalType: 'bool',
        name: '',
        type: 'bool',
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
] as const;
// ---cut---
const isAllowed = await publicClient.readContract({
  address: NOX_CONTRACT_ADDRESS,
  abi: NOX_CONTRACT_ABI,
  functionName: 'isAllowed',
  args: [handle, account],
});
```

--------------------------------

### Deposit using fromExternal

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/fromExternal.md

This example shows how to use `fromExternal` to validate an encrypted input before using it in a computation. It first validates the `encryptedAmount` using `Nox.fromExternal` and then uses the resulting validated `euint256` amount in a deposit function.

```solidity
function deposit(externalEuint256 encryptedAmount, bytes calldata proof) external {
    // Validate the user's encrypted input
    euint256 amount = Nox.fromExternal(encryptedAmount, proof);

    // Now use the validated handle in computations
    euint256 newBalance = Nox.add(_balances[msg.sender], amount);
    Nox.allowThis(newBalance);
    Nox.allow(newBalance, msg.sender);
    _balances[msg.sender] = newBalance;
}
```

--------------------------------

### Build Project for Production

Source: https://github.com/iexec-nox/documentation/blob/main/README.md

Use this command to create a production-ready build of the project.

```bash
npm run build
```

--------------------------------

### Configure Viem Handle Client

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/advanced-configuration.md

This snippet shows how to set up the handle client using Viem. It requires a wallet client created with your private key and RPC URL.

```typescript
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, {
  gatewayUrl: NOX_GATEWAY_URL,
  smartContractAddress: NOX_CONTRACT_ADDRESS,
  subgraphUrl: NOX_SUBGRAPH_URL,
});
```

--------------------------------

### Initialize Handle Client with Viem (Browser)

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Initialize the Handle client using Viem for browser environments. Requires a custom transport for window.ethereum.

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

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

--------------------------------

### Initialize HandleClient with Viem

Source: https://context7.com/iexec-nox/documentation/llms.txt

Create a HandleClient instance using Viem for browser or Node.js environments, including support for ERC-4337 Smart Accounts.

```APIDOC
## Initialize HandleClient with Viem

Create a HandleClient instance using Viem for browser or Node.js environments, including support for ERC-4337 Smart Accounts.

```typescript
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom, http } from 'viem';
import { arbitrumSepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

// Browser environment
const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});
const handleClient = await createViemHandleClient(walletClient);

// Node.js environment
const nodeWalletClient = createWalletClient({
  account: privateKeyToAccount('0xYOUR_PRIVATE_KEY'),
  transport: http('https://sepolia-rollup.arbitrum.io/rpc'),
});
const handleClient = await createViemHandleClient(nodeWalletClient);
```
```

--------------------------------

### Create Handle Client with Viem Wallet Client

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Set up a Handle client using a viem WalletClient. This method is suitable for integrating with viem-compatible wallets in your application.

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

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

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/iexec-nox/documentation/blob/main/CONTRIBUTING.md

Clone your forked repository and navigate into the project directory.

```bash
git clone https://github.com/iExec-Nox/documentation.git
cd documentation
```

--------------------------------

### Initialize Handle Client with Viem (NodeJS)

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Initialize the Handle client using Viem for NodeJS environments. Requires a private key and an HTTP transport.

```ts
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);
```

--------------------------------

### Initialize Handle Client and View ACL

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/viewACL.md

Demonstrates how to initialize the Handle client using a Viem wallet client and then call the viewACL method to retrieve the ACL for a handle. This is the primary way to use the viewACL functionality.

```typescript
import type { Handle } from '@iexec-nox/handle';
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});

const handleClient = await createViemHandleClient(walletClient);

const { isPublic, admins, viewers } = await handleClient.viewACL(handle);
```

--------------------------------

### Initialize Encrypted State Variables with Nox

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/plaintext-to-encrypted.md

Demonstrates initializing encrypted state variables like balance, threshold, and flags using Nox's conversion functions. Use this for initializing state variables and constants. For user-provided values, prefer `fromExternal` with the JS SDK to avoid exposing plaintext on-chain.

```Solidity
euint256 initialBalance = Nox.toEuint256(0);
Nox.allowThis(initialBalance);

euint16 threshold = Nox.toEuint16(100);
Nox.allowThis(threshold);

ebool flag = Nox.toEbool(true);
Nox.allowThis(flag);
```

--------------------------------

### Initialize Handle Client with Ethers.js (NodeJS)

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Initialize the Handle client using Ethers.js for NodeJS environments. Requires a JsonRpcProvider and a Wallet.

```ts
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);
```

--------------------------------

### Initialize HandleClient with Viem

Source: https://context7.com/iexec-nox/documentation/llms.txt

Initialize the HandleClient using Viem for browser or Node.js environments, including support for ERC-4337 Smart Accounts. This client facilitates interaction with the Nox protocol.

```typescript
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom, http } from 'viem';
import { arbitrumSepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

// Browser environment
const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});
const handleClient = await createViemHandleClient(walletClient);

// Node.js environment
const nodeWalletClient = createWalletClient({
  account: privateKeyToAccount('0xYOUR_PRIVATE_KEY'),
  transport: http('https://sepolia-rollup.arbitrum.io/rpc'),
});
const handleClient = await createViemHandleClient(nodeWalletClient);
```

--------------------------------

### Allow Admin with viem

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/admins.md

This snippet demonstrates how to allow a new admin for a handle using viem. It requires setting up the wallet client and specifying the chain, contract address, ABI, and function arguments.

```typescript
import {
  createWalletClient,
  http,
  custom,
  type WalletClient,
  type Chain,
} from 'viem';
import { arbitrumSepolia } from 'viem/chains';

/**
 * Current network.
 */
const CHAIN: Chain = arbitrumSepolia as Chain;

const handle = '0xHandle';
const accountToAllow = '0xAccountAddress';

const walletClient: WalletClient = createWalletClient({
  transport: custom((window as any).ethereum),
  chain: CHAIN,
});

/**
 * Nox protocol contract address, depending on the network.
 *
 * See deployment page for more details.
 */
const NOX_CONTRACT_ADDRESS: `0x${string}` =
  '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';

/**
 * `allow` ABI fragment
 */
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
      {
        internalType: 'address',
        name: 'account',
        type: 'address',
      },
    ],
    name: 'allow',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
] as const;
// ---cut---
const [userAddress] = await walletClient.getAddresses();

await walletClient.writeContract({
  account: userAddress,
  chain: CHAIN,
  address: NOX_CONTRACT_ADDRESS,
  abi: NOX_CONTRACT_ABI,
  functionName: 'allow',
  args: [handle, accountToAllow],
});
```

--------------------------------

### Handle Creation Sequence Diagram

Source: https://github.com/iexec-nox/documentation/blob/main/src/protocol/handle-gateway.md

Illustrates the sequence of interactions for creating and storing a handle, involving the User SDK, Handle Gateway, and NoxCompute.

```mermaid
sequenceDiagram
    participant U as User (SDK)
    participant GW as Handle Gateway
    participant SC as NoxCompute

    GW->>SC: ETH call kmsPublicKey() during startup
    SC-->>GW: protocol public encryption key
    U->>GW: POST /v0/secrets (plaintext, type, owner)
    GW->>GW: ECIES encryption with KMS public key
    GW->>GW: Store (handle, ciphertext, K, nonce) in AWS S3 bucket
    GW->>GW: Sign HandleProof (EIP-712)
    GW-->>U: handle + proof
```

--------------------------------

### Initialize Handle Client with Ethers.js (Browser)

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Initialize the Handle client using Ethers.js for browser environments. Requires a BrowserProvider.

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

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

--------------------------------

### Check Admin Access with ethers.js

Source: https://github.com/iexec-nox/documentation/blob/main/src/guides/manage-handle-access/admins.md

Example of how to check if an account is an admin for a handle using the ethers.js library. Ensure the correct Nox contract address and ABI are used.

```typescript
import { BrowserProvider, Contract, type AbstractProvider } from 'ethers';

const provider: AbstractProvider = new BrowserProvider(
  (window as any).ethereum
) as AbstractProvider;

const handle = '0xHandle';
const account = '0xAccountAddress';

/**
 * Nox protocol contract address, depending on the network.
 *
 * See deployment page for more details.
 */
const NOX_CONTRACT_ADDRESS: `0x${string}` =
  '0x5633472D35E18464CA24Ab974954fB3b1B122eA6';

/**
 * `isAllowed` ABI fragment
 */
const NOX_CONTRACT_ABI = [
  {
    inputs: [
      {
        internalType: 'bytes32',
        name: 'handle',
        type: 'bytes32',
      },
      {
        internalType: 'address',
        name: 'account',
        type: 'address',
      },
    ],
    name: 'isAllowed',
    outputs: [
      {
        internalType: 'bool',
        name: '',
        type: 'bool',
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
] as const;
// ---cut---
const noxContract = new Contract(
  NOX_CONTRACT_ADDRESS,
  NOX_CONTRACT_ABI,
  provider
);
const isAllowed: boolean = await noxContract.isAllowed(handle, account);
```

--------------------------------

### Write a Simple Piggy Bank Contract

Source: https://github.com/iexec-nox/documentation/blob/main/src/getting-started/hello-world.md

This is a standard Solidity contract for a piggy bank. The balance is publicly visible on the blockchain. Use this as a starting point before implementing confidentiality.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract PiggyBank {
    uint256 private balance;
    address public owner;

    constructor() {
        owner = msg.sender;
    }

    function deposit(uint256 amount) external {
        balance += amount;
    }

    function withdraw(uint256 amount) external {
        require(msg.sender == owner);
        require(amount <= balance);
        balance -= amount;
    }

    function getBalance() external view returns (uint256) {
        return balance;
    }
}
```

--------------------------------

### Retrieve KMS Public Key from NoxCompute

Source: https://github.com/iexec-nox/documentation/blob/main/src/protocol/nox-smart-contracts.md

Use this function to get the KMS public key for encrypting computation inputs. The key is set at deployment and can be updated by an administrator.

```solidity
function kmsPublicKey() external view returns (bytes memory);
```

--------------------------------

### Decrypt Handle and Log Value

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/decrypt.md

Decrypts a handle and logs the decrypted value along with its Solidity type. This example shows how to handle different Solidity types returned by the decryption.

```typescript
const { value, solidityType } = await handleClient.decrypt(handle);

console.log(`${solidityType}:`, value);
// e.g. "uint256: 1000n" or "bool: true"
```

--------------------------------

### Initialize HandleClient with Ethers.js

Source: https://context7.com/iexec-nox/documentation/llms.txt

Create a HandleClient instance using Ethers.js for browser or Node.js environments to interact with the Nox protocol.

```APIDOC
## Initialize HandleClient with Ethers.js

Create a HandleClient instance using Ethers.js for browser or Node.js environments to interact with the Nox protocol.

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

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

// Node.js environment
import { JsonRpcProvider, Wallet } from 'ethers';

const rpcProvider = new JsonRpcProvider('https://sepolia-rollup.arbitrum.io/rpc');
const signer = new Wallet('YOUR_PRIVATE_KEY', rpcProvider);
const handleClient = await createEthersHandleClient(signer);
```
```

--------------------------------

### Create Viem Handle Client with Smart Account

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/getting-started.md

Use this snippet to create a Handle client with a viem Smart Account for ERC-4337 account abstraction. Ensure you have the necessary viem and SDK imports.

```typescript
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);
```

--------------------------------

### Using publicDecrypt with a Specific Handle

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/publicDecrypt.md

This example demonstrates calling `publicDecrypt` with a specific handle. Remember that the handle must be publicly decryptable on-chain; otherwise, an error will be thrown. It is recommended to check the `isPublic` flag using `viewACL` before calling `publicDecrypt`.

```typescript
import { createViemHandleClient } from '@iexec-nox/handle';
import type { Handle } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});

const handleClient = await createViemHandleClient(walletClient);
declare const handle: Handle<'uint256'>;
// ---cut---
const { value, solidityType, decryptionProof } =
  await handleClient.publicDecrypt(handle); // [!code focus]
```

--------------------------------

### Usage of Safe Arithmetic Methods

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/solidity-library/methods/core-primitives/safe-arithmetic.md

Demonstrates how to use safe arithmetic methods like safeAdd and handle potential failures using Nox.select. This pattern ensures that the old balance is retained if an arithmetic operation results in an overflow or underflow.

```Solidity
(ebool ok, euint256 newBalance) = Nox.safeAdd(balance, amount);
euint256 finalBalance = Nox.select(ok, newBalance, balance);
Nox.allowThis(finalBalance);
```

--------------------------------

### Configure Ethers.js Handle Client

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/advanced-configuration.md

Use this snippet to initialize the handle client with Ethers.js. Ensure you have the necessary RPC URL, private key, and NOX contract details.

```typescript
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, {
  gatewayUrl: NOX_GATEWAY_URL,
  smartContractAddress: NOX_CONTRACT_ADDRESS,
  subgraphUrl: NOX_SUBGRAPH_URL,
});
```

--------------------------------

### Prehandle Construction for Computation Results

Source: https://github.com/iexec-nox/documentation/blob/main/src/protocol/nox-smart-contracts.md

This code demonstrates how to construct a prehandle for on-chain computation results. It includes the operator, operands, NoxCompute address, calling contract, timestamp, and output index.

```solidity
bytes32 prehandle = keccak256(abi.encodePacked(
    operator,           // Operator enum (Add, Sub, Div, ...)
    operands,           // Array of input handles
    address(this),      // NoxCompute address
    msg.sender,         // Calling contract
    block.timestamp,
    outputIndex         // For multi-output operations (0, 1, ...)
));
```

--------------------------------

### viewACL Method Usage

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/viewACL.md

Demonstrates how to use the `viewACL` method to retrieve the ACL for a handle. This includes setting up the necessary clients and calling the method.

```APIDOC
## viewACL

Retrieves the **Access Control List (ACL)** for a handle. The ACL describes who
can interact with the encrypted data: whether it is publicly decryptable, which
addresses have admin permissions, and which addresses have viewer permissions.

This method queries the protocol's subgraph, not the blockchain directly, so it
is fast and does not require gas.

### Method Signature

```ts
async viewACL(handle: Handle<T>): Promise<ACL>;
```

### Parameters

#### handle <Required />

**Type:** `Handle<T>` (a `0x`-prefixed hex string, 32 bytes)

The handle whose ACL you want to inspect.

### Return Value

**Type:** `ACL`

An object containing the ACL details:

- **isPublic** (`boolean`): `true` if the handle is publicly decryptable, `false` otherwise.
- **admins** (`string[]`): A list of Ethereum addresses with admin permissions.
- **viewers** (`string[]`): A list of Ethereum addresses with viewer permissions.

### Example Usage

```ts
import type { Handle, ACL } from '@iexec-nox/handle';
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});

const handleClient = await createViemHandleClient(walletClient);

declare const handle: Handle<'uint256'>; // Assume handle is defined elsewhere

const { isPublic, admins, viewers }: ACL = await handleClient.viewACL(handle);

if (isPublic) {
  console.log('Handle is publicly decryptable');
} else {
  console.log('Admins:', admins);
  console.log('Viewers:', viewers);
}
```
```

--------------------------------

### Create Nox Handle Client with Custom Configuration

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/advanced-configuration.md

Use this snippet to create a handle client with custom gateway, smart contract, and subgraph URLs. This is essential when targeting unsupported chains.

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

const signer = new BrowserProvider(window.ethereum);

const handleClient = await createEthersHandleClient(signer, {
  gatewayUrl: 'https://nox-gateway.custom.example.com',
  smartContractAddress: '0xCustomNoxContractAddress',
  subgraphUrl: 'https://subgraph.custom.example.com',
});
```

--------------------------------

### Local Testing Commands

Source: https://github.com/iexec-nox/documentation/blob/main/CONTRIBUTING.md

Run these commands locally to build the project and check for syntax errors before submitting changes.

```bash
# Build the project
npm run build
```

```bash
# Check syntax
npm run lint
```

--------------------------------

### Decrypt Handle with Viem

Source: https://github.com/iexec-nox/documentation/blob/main/src/references/js-sdk/methods/decrypt.md

Initializes a Viem handle client and decrypts a handle. Ensure your wallet is connected and authorized on-chain.

```typescript
import type { Handle } from '@iexec-nox/handle';
import { createViemHandleClient } from '@iexec-nox/handle';
import { createWalletClient, custom } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const walletClient = createWalletClient({
  chain: arbitrumSepolia,
  transport: custom(window.ethereum),
});

const handleClient = await createViemHandleClient(walletClient);

const { value, solidityType } = await handleClient.decrypt(handle);
```

--------------------------------

### Prehandle Construction for User Input

Source: https://github.com/iexec-nox/documentation/blob/main/src/protocol/nox-smart-contracts.md

For user inputs via the Handle Gateway, the prehandle is a random value. The handle is then validated on-chain using an EIP-712 signed `HandleProof`.

```solidity
bytes32 prehandle = randomValue;
```