Skip to content

chore: Improve Zama Relayer integration docs #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zeljkoX merged 4 commits into from
Apr 29, 2026
Merged

chore: Improve Zama Relayer integration docs #149

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f36cf63
chore: Improve Zama Relayer integration docs
zeljkoX Apr 23, 2026
2114d5d
chore: Improvements
zeljkoX Apr 23, 2026
9e0962f
chore: Apply suggestions
zeljkoX Apr 27, 2026
1f4df86
chore: apply PR suggestions
zeljkoX Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 57 additions & 45 deletions content/relayer/1.4.x/guides/zama-fhevm-counter-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
{
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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).
Comment thread
zeljkoX marked this conversation as resolved.
Outdated
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
Expand All @@ -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.
Comment thread
zeljkoX marked this conversation as resolved.
Outdated
</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-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).
Comment thread
zeljkoX marked this conversation as resolved.
Outdated

### 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';
Expand All @@ -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!);
Expand All @@ -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';
Expand All @@ -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';
Expand All @@ -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';
Expand All @@ -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'}`);
Expand All @@ -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-signed EIP-712)
Comment thread
zeljkoX marked this conversation as resolved.
Outdated

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';
Expand All @@ -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(
Expand All @@ -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 {
Expand All @@ -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

Expand Down
Loading
Loading