thericardoli Zama SDK
@zama-fhe/sdk and @zama-fhe/react-sdk are the TypeScript SDKs for integrating Zama Protocol FHEVM / confidential smart contracts at the application layer. They cover browser dApps, React/wagmi frontends, Node.js scripts or backends, local cleartext development, and common ERC7984 confidential token product flows.
Official GitHub repository: https://github.com/zama-ai/sdk
Included Content
This skill primarily organizes the following topics:
- SDK initialization: relayer runtime, signer, storage, and network transport.
- React integration:
ZamaProvider, wagmi, TanStack Query hooks, and Next.js client/server boundaries. - Custom FHE contracts: encrypted inputs, input proofs, contract writes, user decryption, and public decryption.
- ERC7984 tokens: shield, confidential balances, confidential transfers, operator approvals, unshield, and registry discovery.
- Node and local development:
RelayerNode, request-scoped storage, proxies, andRelayerCleartext. - Product integration: activity feeds, wallet/exchange displays, delegated decryption, typed errors, and troubleshooting.
How to Use
- First decide whether you are implementing an ERC7984 token flow or a custom FHE contract flow.
- Then identify the runtime environment: React/browser, vanilla TypeScript, Node backend/script, or local cleartext.
- Choose the reference for that environment, set up the SDK/Provider first, then implement the specific business action.
- When an API name or parameter shape is uncertain, check
references/api-reference.md, then inspect the installednode_modules/@zama-fhe/*types in the target project.
Reference Index
| File | When to Read |
|---|---|
references/getting-started.md |
First integration in a new project; quickly understand what the SDK does, which packages to install, and how to write minimal React/Node/local examples. |
references/configuration.md |
Configure relayers, network presets, API keys, backend proxies, signers, storage, registry overrides, and artifact caching. |
references/session-security.md |
Handle wallet signature prompts, decrypt credentials, TTLs, session lifecycle, browser security, and API key boundaries. |
references/custom-contracts.md |
The target contract is not an ERC7984 token, but custom encrypted state such as auctions, vaults, counters, or voting. |
references/react-wagmi-nextjs.md |
React, wagmi, or Next.js projects that need provider wiring, hooks, authorization gates, and SSR/client boundaries. |
references/node-and-local.md |
Node scripts, backend services, server-side relayer auth, request isolation, and local cleartext runtime. |
references/token-workflows.md |
ERC7984 confidential token shield, balance, transfer, approve, unshield, registry, and token hooks. |
references/activity-wallet-integration.md |
Wallets, portfolios, exchanges, or dashboards that need activity feeds, wrapper discovery, and operator/delegation UX. |
references/errors-events.md |
Typed error handling, matchZamaError, SDK lifecycle events, event decoders, and activity helpers. |
references/api-reference.md |
Look up import paths, class/hook names, parameter shapes, query factories, and local type entry points. |
references/troubleshooting.md |
Debug import, worker/WASM, relayer auth, decrypt, token balance, registry, and cleartext issues. |
Workflow
- First read the target project's
package.json, lockfile, Node version, framework, and wallet stack. - Pick the most relevant reference from the index above; there is no need to read the full documentation set end to end.
- Choose the runtime by environment: use
RelayerWebfor browser/React,RelayerNodefor Node backends/scripts, andRelayerCleartextfor local cleartext. - For new projects, query the real published
@zama-fhe/sdk/@zama-fhe/react-sdkversions from the pnpm registry instead of copying stale versions. - Choose the signer by wallet stack: try
WagmiSignerfirst for wagmi; if the current SDK/wagmi combination fails to build, immediately switch to the customGenericSignerfallback in this skill; useViemSignerfor viem andEthersSignerfor ethers. - Choose storage by data lifecycle:
indexedDBStoragefor browsers,memoryStoragefor tests or one-off scripts, andasyncLocalStoragefor request isolation in Node. - Set up the SDK/Provider before implementing business flows; avoid mixing network configuration, wallet state, contract ABIs, and UI state in the same step.
- Split token tasks into shield, balance, transfer, operator approval, unshield, and activity feed work; route custom contract tasks through the encrypt/decrypt documentation.
- Finally check contract address, user address, chain id, handle, input proof, ACL, API key exposure, session TTL, browser security headers, and SSR boundaries.