For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Delegated decryption

Grant another address the right to decrypt confidential balances, then read those balances as a delegate, in TypeScript, React, Go, or Rust.

Delegation lets one address grant another address the right to decrypt its confidential balances. The delegate never receives the delegator's private keys — they use their own transport key pair and a delegated EIP-712 flow to prove they have permission.

Common use cases:

  • Portfolio dashboards — a read-only service decrypts balances across wallets without holding keys.

  • Auditors — a third party verifies holdings without the token owner being online.

This guide uses sdk.delegations and token.decryptBalanceAs in the core SDK, or the useDelegateDecryption and useDecryptBalanceAs hooks in React. Before starting, make sure your project is set up following the Configuration guide.

Example

Available in the Core SDK and React SDK.

A complete delegation flow — grant, then decrypt as delegate (the SDK rides out ACL propagation for you):

import { createConfig, ZamaSDK } from "@zama-fhe/sdk";
import { sepolia } from "@zama-fhe/sdk/chains";

const sdk = new ZamaSDK(config); // config from createConfig()
const token = sdk.createToken("0xConfidentialToken");

// 1. Delegator grants decryption rights
const { txHash } = await sdk.delegations.delegateDecryption({
  contractAddress: token.address,
  delegateAddress: "0xDelegate",
});

// 2. Delegate reads the delegator's balance — no wait needed. Propagation
//    usually completes within ~10 blocks (a few seconds), and the SDK retries
//    across that window internally.
const balance = await token.decryptBalanceAs({ delegatorAddress: "0xDelegator" });
import { useDelegateDecryption, useDecryptBalanceAs } from "@zama-fhe/react-sdk";

const TOKEN = "0xConfidentialToken";

// 1. Delegator grants decryption rights
const { mutateAsync: delegate } = useDelegateDecryption(TOKEN);
await delegate({ delegateAddress: "0xDelegate" });

// 2. Delegate reads the delegator's balance — the SDK rides out ACL propagation
const { mutateAsync: decryptAs } = useDecryptBalanceAs(TOKEN);
const balance = await decryptAs({ delegatorAddress: "0xDelegator" });

Steps

1. Grant delegation

The token owner grants a delegate the right to decrypt their balance for a specific contract. Each call grants delegation for a single (contractAddress, delegateAddress) pair and submits one on-chain transaction, returning { txHash, receipt }.

2. ACL propagation (handled for you)

After the delegation transaction is mined, the Zama Gateway (on Arbitrum) syncs the ACL state via cross-chain event propagation — usually within ~10 blocks (a few seconds). You don't need to wait or poll: the delegated-decrypt path rides out that window with a bounded internal retry (~30s), so a decrypt issued right after granting simply waits for sync.

DelegationNotPropagatedError (DELEGATION_NOT_PROPAGATED) only surfaces if propagation outlasts the retry budget (rare) — or if you opt out of the wait with waitForPropagation: false on sdk.decryption.delegatedDecryptValues to fail fast instead.

3. Decrypt as delegate

The delegate reads the delegator's balance. The delegate signs with their own wallet, and the relayer verifies the on-chain delegation before decrypting.

Pass the encrypted balance your application read from the token contract.

Pass the encrypted balance your application read from the token contract.

Clear values are cached in storage, keyed by (accountAddress, token, encryptedValue). Every on-chain balance change produces a new encrypted value, so stale cache entries are never served.

4. Check delegation status (optional)

Query whether a delegation is currently active between a delegator and a delegate, along with its expiry:

5. Batch decryption across tokens (optional)

Decrypt balances across multiple tokens in a single call. The result is a Map<Address, bigint>.

Pass one encrypted balance per token. Each item carries its own value or error, so one failing token does not reject the batch.

Pass one encrypted balance per token. Each item carries its own value or error, so one failing token does not reject the batch.

6. Delegate for all contracts with the wildcard address (optional)

Instead of granting delegation one contract at a time, pass WILDCARD_CONTRACT as contractAddress. The delegation then applies to any confidential contract, including ones deployed later. It does not widen access: the delegate can only read what the delegator can already read on each contract. WILDCARD_CONTRACT is only valid as contractAddress. isActive and getStatus (and useDelegationStatus) for a specific contract also reflect a wildcard-only grant, so existing status checks keep working. getExpiry returns only the raw per-contract expiry; query it with WILDCARD_CONTRACT to read the wildcard grant's expiry.

Wildcard and per-contract delegations to the same delegate can coexist — ACL.sol honors both. If a per-contract grant would be redundant because the delegate already holds an active wildcard grant, delegateDecryption logs a warning; it still submits the transaction.

7. Revoke delegation (optional)

8. Handle errors (optional)

Delegation operations can throw several error types. The most common:

See Handle errors for full error-handling patterns and Error types for the complete list.

Next steps

Last updated