3.1.x

createConfig, transport factories, the provider/signer split, the Token/WrappedToken hierarchy, and top-level FHE primitives.

This page covers the 3.1.x line.

3.1.0

Released 2026-06-22.

This is the release where the v3 public API reached its current shape. Configuration is now a single createConfig call, relayers are wired in through transport factories, read access and wallet authority are separated into a provider and an optional signer, and the token surface splits into Token (ERC-7984) and WrappedToken (shield/unshield). It also introduces top-level FHE primitives for apps whose contracts use encrypted types directly.

Breaking change: buildRelayer is removed from the public API.

Relayers are no longer constructed directly. Build them with the transport factories (web(), node(), cleartext()) and pass them to createConfig in a relayers map keyed by chain ID. See Configuration.

createZamaConfig was also renamed to createConfig — the package path already namespaces it. Config props are now flat (no viem: {} / ethers: {} wrapper objects).

createConfig: one call to wire everything

createConfig takes your chains, relayers, provider, and optional signer and returns a single config object you hand to ZamaSDK. Import it from the entry point that matches your Web3 library:

import { createConfig } from "@zama-fhe/sdk/viem"; // or @zama-fhe/sdk/ethers
import { ZamaSDK } from "@zama-fhe/sdk";
import { web } from "@zama-fhe/sdk/web";
import { sepolia } from "@zama-fhe/sdk/chains";

const config = createConfig({
  chains: [sepolia],
  publicClient, // viem PublicClient — read access
  walletClient, // viem WalletClient — signing (optional, see below)
  relayers: { [sepolia.id]: web() },
});

const sdk = new ZamaSDK(config);

React apps build the config with createConfig from @zama-fhe/react-sdk/wagmi and pass it to <ZamaProvider config={config}>.

Migrate from createZamaConfig / buildRelayer

Before (3.0.x)

import { createZamaConfig, buildRelayer } from "@zama-fhe/sdk";

const relayer = buildRelayer(/* ... */);
const config = createZamaConfig({
  viem: { publicClient, walletClient },
  // ...
});

After (3.1.0)

import { createConfig } from "@zama-fhe/sdk/viem";
import { web } from "@zama-fhe/sdk/web";
import { sepolia } from "@zama-fhe/sdk/chains";

const config = createConfig({
  chains: [sepolia],
  publicClient,
  walletClient,
  relayers: { [sepolia.id]: web() },
});

Transport factories per chain

Relayers tell the SDK how to run FHE operations on each chain. Pick a transport per environment and map it to the chains it serves. Chain-specific data (relayer URL, network, contract addresses) comes from the chain preset, so a bare call is all most apps need.

Transport	Environment	Import
web()	Browser	@zama-fhe/sdk/web
node()	Node.js	@zama-fhe/sdk/node
cleartext()	Local dev	@zama-fhe/sdk

import { web } from "@zama-fhe/sdk/web";
import { node } from "@zama-fhe/sdk/node";
import { cleartext } from "@zama-fhe/sdk";

// Multi-chain: map each chain ID to its transport.
relayers: {
  [sepolia.id]: web(),
  [hoodi.id]: web(),
}

Each transport factory also takes an optional options argument for per-chain tuning — in 3.1.0 this parameter was renamed from relayer to options. Its fields depend on the FHE backend; the internal backend migration and its current tuning options are documented under FHE runtime and client tuning.

See Configuration for the full list.

Provider / signer split and optional signer

The SDK now separates read access (the provider) from wallet authority (the signer). The provider handles contract reads and receipt polling; the signer handles signing and write transactions. Both are built for you by createConfig from your library's native objects.

The signer is optional. Omit it to build a read-only SDK — perfect for dashboards, indexers, or server-side balance displays that never write. Calling a method that needs to sign without a signer throws SignerRequiredError, so misuse fails loudly:

// Read-only SDK — no walletClient/signer supplied.
const config = createConfig({ chains: [sepolia], publicClient, relayers: { [sepolia.id]: web() } });
const sdk = new ZamaSDK(config);

// Reads work; writes throw SignerRequiredError.

The concrete adapters — ViemProvider / ViemSigner and EthersProvider / EthersSigner — are documented in the SDK reference. For custom integrations, implement GenericProvider and GenericSigner.

Token and WrappedToken

The token surface splits into two classes so each API only exposes what applies:

• Token — an ERC-7984 confidential token: balanceOf, confidentialTransfer, setOperator, and so on.

• WrappedToken — a Token that also wraps a public ERC-20, adding shield, unshield, and unshieldAll.

// A wrapper is itself the confidential token — pass the wrapper's own address.
const wrappedToken = sdk.createWrappedToken("0xWrapperAddress");

await wrappedToken.shield(1000n); // public ERC-20 → confidential
await wrappedToken.confidentialTransfer("0xRecipient", 500n);
await wrappedToken.unshield(500n); // confidential → public ERC-20

// For a plain ERC-7984 token that isn't a wrapper:
const token = sdk.createToken("0xConfidentialToken");

Explicit owner on token reads

Token reads now require an explicit owner address rather than implicitly using the connected account. This keeps reads deterministic and makes read-only (signer-less) usage possible:

const balance = await wrappedToken.balanceOf("0xOwnerAddress");

FHE encryption and decryption primitives

For contracts that use FHE types directly — a sealed-bid auction, a confidential vote, any non-token contract storing euint values — the SDK exposes the underlying operations. Encryption is a top-level method; decryption is grouped under the sdk.decryption namespace:

// Encrypt values for a specific contract + user, ready to submit on-chain.
const { encryptedValues, inputProof } = await sdk.encrypt({
  values: [{ value: 42n, type: "euint64" }],
  contractAddress: "0xYourContract",
  userAddress: "0xYourAddress",
});

// Decrypt a publicly-decryptable value (no signature required).
const clear = await sdk.decryption.decryptPublicValues([encryptedValue]);

// Decrypt values you're entitled to under the ACL (prompts for a permit signature).
const values = await sdk.decryption.decryptValues([
  { encryptedValue, contractAddress: "0xYourContract" },
]);

In React, use useEncrypt and useDecryptValues — see the Encrypt & decrypt guide.

SDK-level delegation primitives

Delegated decryption — letting another account decrypt your values under the ACL — is now a first-class SDK primitive. sdk.decryption.delegatedDecryptValues() decrypts on behalf of a delegator, and the on-chain delegation lifecycle is managed through sdk.delegations and the React delegation hooks. See Delegated decryption.

Automatic ERC-1363 shield routing

WrappedToken.shield() now detects whether the underlying ERC-20 implements ERC-1363 (via ERC-165) and routes accordingly — transferAndCall for a single-transaction shield when supported, or approve + wrap otherwise. This is fully transparent: your code doesn't change and you never pick a path.

// Identical call regardless of the underlying token — the SDK picks the optimal path.
await wrappedToken.shield(1000n);

See the routing table in Shield tokens.

Glossary alignment (naming)

Several public field and method names were aligned with the FHEVM glossary for consistency — decrypt wording, key/keypair terminology, and the remaining *Handle fields. The credentials model was also replaced with a keypair vault plus a permission store internally. If you referenced these names directly, update them to the current terms; the 3.2.0 codemods automate most of the mechanical renames.