Merge pull request #149 from OpenZeppelin/zama-integration-improvements

chore: Improve Zama Relayer integration docs

Author: zeljkoX

content/relayer/1.4.x/guides/zama-fhevm-counter-guide.mdx

@@ -4,20 +4,29 @@ title: Zama FHEVM Counter Guide
 
 ## Overview
 
-This guide walks through an end-to-end integration between OpenZeppelin Relayer and a Zama FHEVM contract, using the counter example shipped with the [OpenZeppelin Relayer SDK](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk). The counter contract is deployed from [Zama's fhevm-hardhat-template](https://github.com/zama-ai/fhevm-hardhat-template) and demonstrates the two relayer responsibilities in an FHEVM flow:
+This guide walks through an end-to-end integration between the OpenZeppelin Relayer and a Zama FHEVM contract, using the counter example shipped with the [OpenZeppelin Relayer SDK](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk). The counter contract is deployed from [Zama's fhevm-hardhat-template](https://github.com/zama-ai/fhevm-hardhat-template) and demonstrates the two OpenZeppelin Relayer responsibilities in an FHEVM flow:
 
 - **Transaction submission**: sending an encrypted `increment()` call on-chain.
 - **EIP-712 signing**: signing the typed-data payload that authorizes user decryption of the counter's encrypted state.
 
+<Callout type="info">
+
+**Terminology.** In this guide:
+
+- **OpenZeppelin Relayer** (or "OZ Relayer") — this service. It holds an EVM signer, submits on-chain transactions, and signs EIP-712 payloads.
+- **Zama Relayer** — the Zama-operated service that the [`@zama-fhe/relayer-sdk`](https://www.npmjs.com/package/@zama-fhe/relayer-sdk) talks to under the hood. It serves FHE public keys and routes decryption requests to the Zama KMS / coprocessor. Applications interact with it only indirectly through the Zama Relayer SDK. It holds no OpenZeppelin key material and does not sign EIP-712.
+
+</Callout>
+
 By the end of this guide you will have:
 
 - Configured a Zama FHE instance in your application.
 - Read and decrypted an encrypted counter value from the contract.
-- Submitted an encrypted increment through the relayer and waited for confirmation.
+- Submitted an encrypted increment through the OpenZeppelin Relayer and waited for confirmation.
 - Re-read and decrypted the updated value.
 
 <Callout>
-The FHE encryption/decryption primitives run in your application using the Zama SDK. The relayer never sees cleartext values or your decryption keypair — it only sends transactions and signs EIP-712 payloads.
+The FHE encryption/decryption primitives run in your application using the Zama Relayer SDK. The OpenZeppelin Relayer never sees cleartext values or your decryption keypair — it only sends transactions and signs EIP-712 payloads.
 </Callout>
 
 ## Prerequisites
@@ -42,29 +51,32 @@ The rest of this guide explains the moving parts, references the example files,
 
 Four components participate in the flow:
 
-- **Your script**: orchestrates the flow and prints progress.
-- **OpenZeppelin Relayer**: signs typed data and submits transactions.
-- **Zama Relayer SDK instance**: encrypts inputs and manages decryption flows.
-- **FHEVM contract**: stores encrypted state on-chain.
+- **Your script** — orchestrates the flow and prints progress.
+- **OpenZeppelin Relayer** — signs typed data and submits transactions. The only component holding an EVM signer.
+- **Zama Relayer SDK (client)** + **Zama Relayer (service)** — the SDK encrypts inputs, generates keypairs for user decryption, and builds EIP-712 payloads; the Zama Relayer service serves FHE public keys and routes decryption requests to the Zama KMS / coprocessor. The application only interacts with it indirectly through the SDK.
+- **FHEVM contract** — stores encrypted state on-chain.
 
-The key boundary is that the relayer does not do any encryption. The Zama SDK handles encryption and decryption primitives; the relayer provides transaction execution and signature authorization.
+The key boundary is that the OpenZeppelin Relayer does not do any encryption or decryption. The Zama Relayer SDK (and, behind it, the Zama Relayer service) handles all FHE primitives; the OpenZeppelin Relayer only provides EVM transaction execution and EIP-712 signing.
 
 ```
-┌─────────────┐       ┌───────────────────────┐       ┌──────────────┐
-│  Your app   │──────▶│ OpenZeppelin Relayer  │──────▶│ FHEVM network│
-│ (Zama SDK)  │       │  sendTransaction +    │       │  Sepolia /   │
-│             │◀──────│  signTypedData        │       │  Mainnet     │
-└─────────────┘       └───────────────────────┘       └──────────────┘
+┌─────────────┐       ┌─────────────────────────┐       ┌──────────────┐
+│  Your app   │──────▶│  OpenZeppelin Relayer   │──────▶│ FHEVM network│
+│ (Zama SDK)  │       │  sendTransaction +      │       │  Sepolia /   │
+│             │◀──────│  signTypedData          │       │  Mainnet     │
+└─────────────┘       └─────────────────────────┘       └──────────────┘
       │
       ▼
-  Zama Gateway
- (public decrypt /
-  user decrypt)
+┌─────────────────────────────┐
+│        Zama Relayer         │
+│  FHE public keys +          │
+│  decryption request routing │
+│  (accessed via Zama SDK)    │
+└─────────────────────────────┘
 ```
 
-## Relayer Configuration
+## OpenZeppelin Relayer Configuration
 
-Zama FHEVM contracts live on standard EVM networks, so the relayer is configured as a regular `evm` relayer.
+Zama FHEVM contracts live on standard EVM networks, so the OpenZeppelin Relayer is configured as a regular `evm` relayer.
 
 ```json
 {
@@ -96,9 +108,9 @@ Zama FHEVM contracts live on standard EVM networks, so the relayer is configured
 
 **Important notes:**
 
-- The relayer signer is used both for submitting the encrypted transaction and for signing the EIP-712 payload consumed by the Zama Gateway during user decryption. The same key backs both operations.
+- The OpenZeppelin Relayer's signer is used both for submitting the encrypted transaction and for signing the EIP-712 payload that the Zama Relayer SDK requires for user decryption. The same key backs both operations.
 - For production, prefer a hosted signer (AWS KMS, Google Cloud KMS, Turnkey, CDP) over `local`.
-- The relayer must be funded on the target network so it can pay gas for FHEVM contract calls.
+- The OpenZeppelin Relayer must be funded on the target network so it can pay gas for FHEVM contract calls.
 
 ## Installation
 
@@ -130,7 +142,7 @@ RELAYER_BASE_PATH=http://localhost:8080
 # ZAMA_PRIVATE_KEY=
 ```
 
-- `RELAYER_BASE_PATH` defaults to `http://localhost:8080` if not set.
+- `RELAYER_BASE_PATH` defaults to `http://localhost:8080` if not set. This points at your OpenZeppelin Relayer.
 - `RPC_URL` defaults to the public Sepolia RPC if not set.
 - If `ZAMA_PUBLIC_KEY` and `ZAMA_PRIVATE_KEY` are not set, the script generates a fresh decryption keypair on each run. Reusing the same keypair is useful for consistent user-decryption behavior across runs.
 
@@ -145,8 +157,8 @@ npx ts-node examples/relayers/zama/counter.ts
 The script should:
 
 1. Read the encrypted counter handle from the contract.
-2. Attempt decryption (public first, then user decryption with a relayer-signed EIP-712 payload).
-3. Submit an encrypted `increment()` through the relayer and poll until the transaction is mined or confirmed.
+2. Attempt decryption (public first, then user decryption with an OpenZeppelin Relayer signed EIP-712 payload).
+3. Submit an encrypted `increment()` through the OpenZeppelin Relayer and poll until the transaction is mined or confirmed.
 4. Re-read and decrypt the updated counter value.
 
 ## Generating a Reusable Decryption Keypair
@@ -160,14 +172,14 @@ npx ts-node examples/relayers/zama/generate-keypair.ts
 Copy the printed `ZAMA_PUBLIC_KEY` and `ZAMA_PRIVATE_KEY` values into your `.env` file.
 
 <Callout>
-The decryption keypair is an application-side secret. Do not pass the private key to the relayer; it is only used by the Zama SDK to decrypt results returned by the Gateway.
+The decryption keypair is an application side secret. Do not pass the private key to the OpenZeppelin Relayer; it is only used by the Zama Relayer SDK to decrypt results returned by the Zama Relayer.
 </Callout>
 
 ## Walkthrough
 
-The following snippets show the relayer-specific integration points from `counter.ts`. Full code is in the [SDK repository](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk/tree/main/examples/relayers/zama).
+The following snippets show the OpenZeppelin Relayer's specific integration points from `counter.ts`. Full code is in the [SDK repository](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk/tree/main/examples/relayers/zama).
 
-### 1. Initialize the relayer client and Zama SDK
+### 1. Initialize the OpenZeppelin Relayer client and Zama SDK
 
 ```typescript
 import { Configuration, RelayersApi } from '@openzeppelin/relayer-sdk';
@@ -190,9 +202,9 @@ const provider = new JsonRpcProvider(process.env.RPC_URL!);
 const instance = await createInstance(zamaConfig);
 ```
 
-### 2. Fetch the relayer's on-chain address
+### 2. Fetch the OpenZeppelin Relayer's on-chain address
 
-The relayer's EVM address is needed both when building encrypted inputs and when authorizing user decryption.
+The OpenZeppelin Relayer's EVM address is needed both when building encrypted inputs and when authorizing user decryption.
 
 ```typescript
 const relayerInfo = await relayersApi.getRelayer(process.env.RELAYER_ID!);
@@ -201,7 +213,7 @@ const relayerAddress = getAddress(relayerInfo.data.data!.address!);
 
 ### 3. Read and decrypt the encrypted counter
 
-The contract exposes a `getCount()` view that returns the encrypted handle. Decoding the handle is a plain EVM call — no relayer involvement.
+The contract exposes a `getCount()` view that returns the encrypted handle. Decoding the handle is a plain EVM call — no OpenZeppelin Relayer involvement.
 
 ```typescript
 import { Interface } from 'ethers';
@@ -218,9 +230,9 @@ async function getCount(contractAddress: string): Promise<string> {
 
 The script first attempts public decryption. If the handle is not publicly decryptable, it falls back to user decryption (covered in [Decryption Model](#decryption-model) below).
 
-### 4. Submit an encrypted `increment()` via the relayer
+### 4. Submit an encrypted `increment()` via the OpenZeppelin Relayer
 
-Encryption happens locally with the Zama SDK. The encrypted handle plus input proof are encoded into a normal EVM transaction and handed to `sendTransaction`.
+Encryption happens locally with the Zama Relayer SDK. The encrypted handle plus input proof are encoded into a normal EVM transaction and handed to the OpenZeppelin Relayer's `sendTransaction`.
 
 ```typescript
 import { Speed } from '@openzeppelin/relayer-sdk';
@@ -244,7 +256,7 @@ const transactionId = txResponse.data.data!.id!;
 
 ### 5. Poll for confirmation
 
-Poll `getTransactionById` until the transaction reaches `mined` or `confirmed`:
+Poll `getTransactionById` on the OpenZeppelin Relayer until the transaction reaches `mined` or `confirmed`:
 
 ```typescript
 import type { EvmTransactionResponse } from '@openzeppelin/relayer-sdk';
@@ -256,7 +268,7 @@ async function waitForConfirmation(transactionId: string): Promise<string | unde
     const status = await relayersApi.getTransactionById(process.env.RELAYER_ID!, transactionId);
     const tx = status.data.data as EvmTransactionResponse | undefined;
 
-    if (!tx) throw new Error(`Transaction ${transactionId} not returned by relayer`);
+    if (!tx) throw new Error(`Transaction ${transactionId} not returned by the OpenZeppelin Relayer`);
     if (tx.status === 'mined' || tx.status === 'confirmed') return tx.hash;
     if (tx.status === 'failed' || tx.status === 'canceled' || tx.status === 'expired') {
       throw new Error(`Transaction ${tx.status}: ${tx.status_reason ?? 'unknown'}`);
@@ -272,16 +284,16 @@ Zama FHEVM supports two decryption paths, and the example tries them in this ord
 
 ### 1. Public Decryption
 
-If an encrypted handle is marked as publicly decryptable on-chain, the Zama SDK can decrypt it directly, with no authorization from the relayer.
+If an encrypted handle is marked as publicly decryptable on-chain, the Zama Relayer SDK can decrypt it directly via the Zama Relayer, with no involvement from the OpenZeppelin Relayer.
 
 ```typescript
 const result = await instance.publicDecrypt([encryptedHandle]);
 const clear = result.clearValues[encryptedHandle as `0x${string}`];
 ```
 
-### 2. User Decryption (relayer-signed)
+### 2. User Decryption (OpenZeppelin Relayer's signed EIP-712)
 
-When decryption requires authorization, the Zama SDK builds an EIP-712 payload and the relayer signs it via `signTypedData`. The signature is then passed to `userDecrypt`, which retrieves the cleartext from the Zama Gateway.
+When decryption requires authorization, the Zama Relayer SDK builds an EIP-712 payload and the **OpenZeppelin Relayer** signs it via `signTypedData`. The resulting signature is passed to `userDecrypt`, which uses it to authorize the Zama Relayer to return the cleartext.
 
 ```typescript
 import { TypedDataEncoder } from 'ethers';
@@ -299,7 +311,7 @@ const eip712 = instance.createEIP712(
   durationDays,
 );
 
-// Hash the domain and struct, then ask the relayer to sign.
+// Hash the domain and struct, then ask the OpenZeppelin Relayer to sign.
 const domainSeparator = TypedDataEncoder.hashDomain(eip712.domain);
 const { EIP712Domain, ...structTypes } = eip712.types;
 const messageHash = TypedDataEncoder.hashStruct(
@@ -326,13 +338,13 @@ const decrypted = await instance.userDecrypt(
 );
 ```
 
-The EIP-712 domain separator and message hash are computed locally using `ethers` so the relayer only has to sign the final hashes via its `signTypedData` endpoint.
+The EIP-712 domain separator and message hash are computed locally using `ethers` so the OpenZeppelin Relayer only has to sign the final hashes via its `signTypedData` endpoint.
 
 ## Using on Mainnet
 
 The example defaults to Sepolia. To run against Ethereum mainnet:
 
-1. In `counter.ts`, use `MainnetConfig` instead of `SepoliaConfig` and provide the Zama Gateway API key:
+1. In `counter.ts`, use `MainnetConfig` instead of `SepoliaConfig` and provide the Zama Relayer API key:
 
    ```typescript
    import {
@@ -355,26 +367,26 @@ The example defaults to Sepolia. To run against Ethereum mainnet:
    RPC_URL=https://ethereum-rpc.publicnode.com
    ```
 
-3. Point `ZAMA_CONTRACT_ADDRESS` at your mainnet contract and configure the relayer for Ethereum mainnet.
+3. Point `ZAMA_CONTRACT_ADDRESS` at your mainnet contract and configure the OpenZeppelin Relayer for Ethereum mainnet.
 
 <Callout>
-Mainnet requires API key authentication with the Zama Gateway. See the [Zama mainnet API key guide](https://docs.zama.org/protocol/relayer-sdk-guides/fhevm-relayer/mainnet-api-key) for instructions on obtaining one.
+Mainnet requires API key authentication with the Zama Relayer. See the [Zama mainnet API key guide](https://docs.zama.org/protocol/relayer-sdk-guides/fhevm-relayer/mainnet-api-key) for instructions on obtaining one.
 </Callout>
 
 ## Current Limitations
 
 - The example is hardcoded for Sepolia via `SepoliaConfig` plus an explicit Sepolia RPC URL.
 - It assumes a counter contract shape compatible with the included ABI.
 - Logging and error handling are intentionally simple — this is a demo script, not production code.
-- It does not cover relayer creation or contract deployment.
+- It does not cover OpenZeppelin Relayer creation or contract deployment.
 
 ## Troubleshooting
 
 - **`Missing required environment variable`**: one of the required values in `.env` is unset.
-- **`did not return an address`**: the configured relayer id is valid for the API, but the response did not include an EVM address. Check that the relayer is fully provisioned and the signer is reachable.
+- **`did not return an address`**: the configured `RELAYER_ID` is valid for the API, but the response did not include an EVM address. Check that the OpenZeppelin Relayer is fully provisioned and the signer is reachable.
 - **`Public decryption failed`**: this can be expected depending on the contract and permissions. The script will then try user decryption.
-- **`User decryption failed`**: check that the relayer can sign typed data correctly and that the contract address and decryption keypair are the ones you expect. Confirm the EIP-712 `startTimeStamp`/`durationDays` window is valid.
-- **Transaction polling timeout**: the transaction may still be pending, the relayer may be unhealthy, or the target chain may be slow. Inspect `getTransactionById` directly and check relayer logs.
+- **`User decryption failed`**: check that the OpenZeppelin Relayer can sign typed data correctly and that the contract address and decryption keypair are the ones you expect. Confirm the EIP-712 `startTimeStamp` / `durationDays` window is valid.
+- **Transaction polling timeout**: the transaction may still be pending, the OpenZeppelin Relayer may be unhealthy, or the target chain may be slow. Inspect `getTransactionById` directly and check OpenZeppelin Relayer logs.
 
 ## Additional Resources