diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 21b3e06b..34281dfa 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -38,6 +38,9 @@ - [Branching in FHE](guides/conditions.md) - [Generate random numbers](guides/random.md) - [Error handling](guides/error_handling.md) + - [Gas estimation](guides/gas.md) + - [Trivial encrypt](guides/trivial_encrypt.md) + - [Debug decrypt](guides/debug_decrypt.md) - [Frontend](guides/frontend/README.md) - [Build a web application](guides/frontend/webapp.md) - [Build with Node](guides/frontend/node.md) diff --git a/docs/guides/debug_decrypt.md b/docs/guides/debug_decrypt.md new file mode 100644 index 00000000..778c7a9d --- /dev/null +++ b/docs/guides/debug_decrypt.md @@ -0,0 +1,125 @@ +# Debugging with `debug.decryptXX` + +This guide explains how to use the `debug.decryptXX` functions for debugging encrypted data in mocked environments during development with fhEVM. These functions allow developers to decrypt encrypted values locally for testing purposes. However, they should not be used in production as they rely on private keys. + +--- + +## Overview + +The `debug.decryptXX` functions allow you to decrypt encrypted handles into plaintext values. This feature is useful for debugging encrypted operations such as transfers, balance checks, and other computations involving FHE-encrypted data. + +### Key Points: + +- **Environment**: These functions work **only in mocked environments** (e.g., `hardhat` network). +- **Production Limitation**: In production, decryption is performed asynchronously via the Gateway and requires an authorized on-chain request. +- **Encrypted Types**: Supports various encrypted types, including integers, booleans, and `ebytesXX`. + +--- + +## Supported functions + +### Integer decryption + +Decrypts encrypted integers of different bit-widths (`euint4`, `euint8`, ..., `euint256`). + +| Function Name | Returns | Encrypted Type | +| ------------- | -------- | -------------- | +| `decrypt4` | `bigint` | `euint4` | +| `decrypt8` | `bigint` | `euint8` | +| `decrypt16` | `bigint` | `euint16` | +| `decrypt32` | `bigint` | `euint32` | +| `decrypt64` | `bigint` | `euint64` | +| `decrypt128` | `bigint` | `euint128` | +| `decrypt256` | `bigint` | `euint256` | + +### Boolean decryption + +Decrypts encrypted booleans (`ebool`). + +| Function Name | Returns | Encrypted Type | +| ------------- | --------- | -------------- | +| `decryptBool` | `boolean` | `ebool` | + +### Byte array decryption + +Decrypts encrypted byte arrays of various sizes (`ebytesXX`). + +| Function Name | Returns | Encrypted Type | +| ------------------ | -------- | -------------- | +| `decryptEbytes64` | `string` | `ebytes64` | +| `decryptEbytes128` | `string` | `ebytes128` | +| `decryptEbytes256` | `string` | `ebytes256` | + +### Address decryption + +Decrypts encrypted addresses. + +| Function Name | Returns | Encrypted Type | +| ---------------- | -------- | -------------- | +| `decryptAddress` | `string` | `eaddress` | + +--- + +## Function Usage + +### Example: decrypting encrypted values + +```typescript +import { debug } from "./debug"; + +// Decrypt a 64-bit encrypted integer +const handle64: bigint = await this.erc20.balanceOf(this.signers.alice); +const plaintextValue: bigint = await debug.decrypt64(handle64); +console.log("Decrypted Balance:", plaintextValue); +``` + +For a more complete example, refer to the [ConfidentialERC20 test file](https://github.com/zama-ai/fhevm-hardhat-template/blob/f9505a67db31c988f49b6f4210df47ca3ce97841/test/confidentialERC20/ConfidentialERC20.ts#L181-L205). + +### Example: decrypting byte arrays + +```typescript +// Decrypt a 128-byte encrypted value +const ebytes128Handle: bigint = ...; // Get handle for the encrypted bytes +const decryptedBytes: string = await debug.decryptEbytes128(ebytes128Handle); +console.log("Decrypted Bytes:", decryptedBytes); +``` + +--- + +## **How it works** + +### Verifying types + +Each decryption function includes a **type verification step** to ensure the provided handle matches the expected encrypted type. If the type is mismatched, an error is thrown. + +```typescript +function verifyType(handle: bigint, expectedType: number) { + const typeCt = handle >> 8n; + if (Number(typeCt % 256n) !== expectedType) { + throw "Wrong encrypted type for the handle"; + } +} +``` + +### Environment checks + +The functions only work in the `hardhat` network. Attempting to use them in a production environment will result in an error. + +```typescript +if (network.name !== "hardhat") { + throw Error("This function can only be called in mocked mode"); +} +``` + +--- + +## **Best Practices** + +1. **Use Only for Debugging**: + These functions require access to private keys and are meant exclusively for local testing and debugging. + +2. **Production Decryption**: + For production, always use the asynchronous Gateway-based decryption. + +3. **Validate Inputs**: + Ensure the provided handle is valid and corresponds to the correct encrypted type. diff --git a/docs/guides/frontend/webpack.md b/docs/guides/frontend/webpack.md index 38a2c234..533073cf 100644 --- a/docs/guides/frontend/webpack.md +++ b/docs/guides/frontend/webpack.md @@ -18,9 +18,13 @@ resolve: { }, ``` -## Error message: ReferenceError: Buffer is not defined +## Buffer not defined -If you encounter this issue with the Node Buffer object, you should offer an alternative solution. Similar issues might arise with different Node objects. In such cases, install the corresponding browserified npm package and include the fallback as follows. +**Error message:** `ReferenceError: Buffer is not defined` + +**Cause:** This error occurs when the Node.js `Buffer` object is used in a browser environment where it is not natively available. + +**Possible sultions:** To resolve this issue, you need to provide browser-compatible fallbacks for Node.js core modules. Install the necessary browserified npm packages and configure Webpack to use these fallbacks. ```javascript resolve: { @@ -31,22 +35,26 @@ resolve: { path: require.resolve('path-browserify'), }, }, - ``` ## Issue with importing ESM version -With a bundler such as Webpack or Rollup, imports will be replaced with the version mentioned in the `"browser"` field of the `package.json`. If you encounter issue with typing, you can use this [tsconfig.json](https://github.com/zama-ai/fhevmjs-react-template/blob/main/tsconfig.json) using TypeScript 5. +**Error message:** Issues with importing ESM version -If you encounter any other issue, you can force import of the browser package. +**Cause:** With a bundler such as Webpack or Rollup, imports will be replaced with the version mentioned in the `"browser"` field of the `package.json`. This can cause issues with typing. -```javascript -import { initFhevm, createInstance } from "fhevmjs/web"; -``` +**Possible solutions:** + +1. If you encounter issues with typing, you can use this [tsconfig.json](https://github.com/zama-ai/fhevmjs-react-template/blob/main/tsconfig.json) using TypeScript 5. +2. If you encounter any other issue, you can force import of the browser package. ## Use bundled version -If you have an issue with bundling the library (for example with some SSR framework), you can use the prebundled version available in `fhevmjs/bundle`. Just embed the library with a `