fhetransform-sdk

TypeScript SDK for FHETransform. It provides helpers for:

• Connecting to the FHETransform blockchain contracts
• Encrypting and decrypting values through the Jazz service
• Interacting with confidential token contracts
• Running shield / unshield flows for converter contracts

Install

npm install fhetransform-sdk

Requirements:

• Node.js >= 20 for server-side usage
• ESM-aware tooling
• A blockchain provider and signer for write operations

Environment variables

If you do not pass a provider or signer directly, the SDK can fall back to environment configuration in Node.js:

• RPC_URL or FHE_RPC_URL for the JSON-RPC endpoint
• PRIVATE_KEY for a signer
• JAZZ_URL for the Jazz API endpoint when the default is not suitable

Quick Start

Node.js

import { FheTransformSDK } from "fhetransform-sdk";
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const sdk = new FheTransformSDK({
  provider,
  signer,
  // Optional:
  // jazzUrl: process.env.JAZZ_URL,
  // mock: false,
  onEvent: (event) => {
    console.log("SDK event:", event.type);
  },
});

const token = sdk.createToken("0x0000000000000000000000000000000000000000");

console.log("Name:", await token.name());
console.log("Decimals:", await token.decimals());
console.log("Balance:", await token.balanceOf(await signer.getAddress()));

Confidential transfer

const result = await token.confidentialTransfer(
  "0x0000000000000000000000000000000000000001",
  100n
);

console.log(result.txHash);
console.log(result.transferred);

Transfer methods also accept transaction options and lifecycle callbacks:

await token.confidentialTransfer(
  "0x0000000000000000000000000000000000000001",
  100n,
  { gasLimit: 500_000n },
  {
    onEncryptComplete: () => console.log("Amount encrypted"),
    onTransferSubmitted: (txHash) => console.log("Submitted:", txHash),
    onTransferConfirmed: (receipt) => console.log("Confirmed:", receipt.hash),
    onError: (error) => console.error("Transfer failed:", error),
  }
);

Converter flow

const convert = sdk.createConvertToken("0x0000000000000000000000000000000000000002");

const shield = await convert.shield(1000n);
console.log(shield.roundedAmount);

const unshield = await convert.unshieldAndFinalize(1000n);
console.log(unshield.cleartext);

Browser

In browsers, the SDK will attempt to use MetaMask when a signer is not supplied. Pass a provider and signer explicitly if you want to control the connection flow yourself.

import { FheTransformSDK } from "fhetransform-sdk";

const sdk = new FheTransformSDK({
  onEvent: (event) => console.log(event.type),
});

Events

The SDK emits structured events for encryption, decryption, and transaction lifecycles. Subscribe by passing an onEvent listener in the config:

import { FheTransformSDK, FheTransformSDKEvents } from "fhetransform-sdk";

const sdk = new FheTransformSDK({
  provider,
  signer,
  onEvent: (event) => {
    switch (event.type) {
      case FheTransformSDKEvents.EncryptStart:
        console.log("Encryption started", event.dappAddress);
        break;
      case FheTransformSDKEvents.EncryptEnd:
        console.log(`Encryption finished in ${event.durationMs}ms`);
        break;
      case FheTransformSDKEvents.DecryptEnd:
        console.log("Decrypted values:", event.plaintexts);
        break;
      case FheTransformSDKEvents.TransactionError:
        console.error("Transaction failed:", event.error);
        break;
      case FheTransformSDKEvents.ShieldSubmitted:
        console.log("Shield transaction submitted:", event.txHash);
        break;
    }
  },
});

Every event carries a type and a timestamp. Events tied to a contract — encryption operations and events from the Token / ConvertToken wrappers — also include dappAddress, the relevant contract address. Use the exported FheTransformSDKEvents constants and the FheTransformSDKEvent type instead of hardcoding event strings.

Event types

| Event type | Payload | | --- | --- | | encrypt:start | — | | encrypt:end | durationMs | | encrypt:error | durationMs, error | | decrypt:start | encryptedValues | | decrypt:end | durationMs, encryptedValues, plaintexts | | decrypt:error | encryptedValues, error, durationMs | | transaction:end | functionName, txHash, durationMs | | transaction:error | functionName, error, durationMs | | shield:submitted / shield:confirmed / shield:end | txHash, elapsedMs or durationMs | | unshield:submitted / unshield:confirmed / unshield:end | txHash, elapsedMs or durationMs | | finalizeUnshield:submitted / finalizeUnshield:confirmed / finalizeUnshield:end | txHash, elapsedMs or durationMs |

Notes:

• Listener exceptions are caught and logged; a misbehaving subscriber never breaks SDK operations.
• Decrypt events carry decrypted plaintext values — treat them as sensitive data.
• transfer:submitted, transferFrom:submitted, and setOperator:submitted are reserved event types and are not emitted yet.
• The encryption/decryption pipelines also emit low-level progress events such as encryptWithZk:end and fetchInputProof:start; see the API reference for the full list.

Build

npm run build

This compiles the TypeScript sources into dist/, copies the native assets used by the SDK, and prepares the package for publication or local consumption.

Useful companion commands:

• npm test - run the test suite
• npm run lint - lint the source tree
• npm run format - format the TypeScript sources

API

See docs/API.md for the class reference.

Besides the SDK classes, the package exports helpers and types for events (FheTransformSDKEvents, FheTransformSDKEvent), addresses (toChecksumAddress, isZeroAddress, …), chain and fee utilities (getChainKey, estimateFheFee, …), contract operation types, and the unified error system (FheError, FheErrorCode, toFheError, …). See the Supporting exports section of the API reference for the full list.