FHE SDK

TypeScript SDK for FHE encrypt/decrypt flows over gRPC services.

Install

npm install @primuslabs/fhe-sdk

For local development:

npm install
npm run build
npm test

Required Environment

• ALPHA_TRION_RPC_URL_URL: gRPC target for FhevmService (for example: 127.0.0.1:50051)
• PRIVATE_KEY: signer private key (required by high-level helpers such as encryptor.* and decrypt)

Import

import * as fhe from "@primuslabs/fhe-sdk";

Public API

requestEncryption(wallet, value, fheType, options?)

Low-level encrypt API using a provided wallet.

• Accepts number | bigint
• Also supports batch input:
  • requestEncryption(wallet, [{ value, fheType }, ...], options?)
• Sends UploadCiphertext over gRPC
• In batch mode, all ciphertext bytes are concatenated into one signature message
• Retries on:
  • ERROR_CODE_INCORRECT_ENCRYPTION_KEY (with one PK refresh)
  • ERROR_CODE_COMPUTING
• wallet: signer used to produce request signature
• fheType: one of FheType.ve_bool|ve_uint8|ve_uint16|ve_uint32|ve_uint64|ve_uint128|ve_uint256
• options.timeout / options.interval: retry/poll window
• options.pkType / options.refreshPk: key selection and refresh behavior
• options.fhevmRpcUrl: override FHEVM RPC target
• options.signMode: signature mode (eip191, eip191_digest, eth_sign)

Returns:

• Single input: Promise<UnverifiedEncryptData>
• Batch input: Promise<UnverifiedEncryptData[]>

encryptor.{bool|u8|u16|u32|u64|u128|u256}(value, options?)

High-level encrypt helpers that use signer from environment.

Returns: Promise<UnverifiedEncryptData>

requestDecryption(wallet, handleOrHandles, options?)

Low-level decrypt API using a provided wallet.

• Supports a single handle:
  • handle: string -> Promise<bigint>
• Supports multiple handles in one request:
  • handles: string[] -> Promise<bigint[]>
• Retries on ERROR_CODE_COMPUTING
• options.timeout / options.interval: retry/poll window
• options.pkType: request decryption against specific pk type
• options.decryptionUrl: override decryption service target
• options.fhevmRpcUrl: used for system info resolution

decrypt(handleOrHandles, options?)

High-level decrypt helper using signer from environment.

• decrypt(string) -> Promise<bigint>
• decrypt(string[]) -> Promise<bigint[]>

requestComputationStatus(transactionHash, options?)

Query computation completion by transaction hash.

• waitUntilCompleteWithTimeout=false: snapshot query
• waitUntilCompleteWithTimeout=true: polling mode
• Retries on ERROR_CODE_COMPUTING
• transactionHash: accepts both 0x... and non-prefixed hex
• options.timeout / options.interval: polling config
• options.fhevmRpcUrl: override RPC target

Returns: Promise<boolean>

estimateFheFee(contractAddress, functionName, options?)

Utility for fee estimation in FHE transaction flow.

• analyzes verified contract source and AST to count FHE ops
• resolves on-chain op prices and computes total fee
• options.blockscoutUrl: custom explorer endpoint
• options.forceRecompile: ignore AST cache and recompile
• options.chainId: chain-specific behavior (includes special handling for 133/177)
• options.verbose: debug verbosity

Returns: Promise<FheFeeEstimate>

Types

SDK exports:

• FheType
• PayloadType
• UnverifiedEncryptData

Quick Example

import * as fhe from "@primuslabs/fhe-sdk";
import { Wallet } from "ethers";

async function run() {
  // High-level encrypt (uses PRIVATE_KEY signer from env)
  const encrypted = await fhe.encryptor.u32(3517, { interval: 1000, timeout: 30000 });
  const handleHex = `0x${Buffer.from(encrypted.handle).toString("hex")}`;

  // High-level decrypt (single + batch)
  const one = await fhe.decrypt(handleHex);
  const many = await fhe.decrypt([handleHex, handleHex]);

  console.log(one.toString());
  console.log(many.map((v) => v.toString()));

  // Low-level API with explicit wallet
  const wallet = Wallet.createRandom();
  await fhe.requestEncryption(wallet, 7, fhe.FheType.ve_uint8, { timeout: 30000, interval: 1000 });
}

CLI

CLI source files are under cli/ (for example cli/encrypt_cli.ts).

Print resolved system info (with cache support):

npm run system-info -- --rpc 127.0.0.1:50051

For TLS endpoint:

npm run system-info -- --rpc <ALPHA_TRION_RPC_URL> --ca src/cert/ca.cert.pem --refresh

When endpoint is accessed by IP but certificate CN/SAN is a domain, set TLS server name:

npm run system-info -- --rpc <ALPHA_TRION_RPC_URL> --ca src/cert/ca.cert.pem --server-name <cert-domain> --refresh

Optional flags:

• --refresh: bypass cache and force gRPC fetch
• --max-age-ms <ms>: custom cache freshness window
• --ca <pem-file>: root CA file for TLS gRPC endpoints
• --server-name <host>: TLS SNI/authority override when dialing by IP

Print/download public key:

npm run public-key -- --rpc 127.0.0.1:50051 --pk-type v2 --out .cache/server_pk.bin --refresh

For TLS endpoint:

npm run public-key -- --rpc <ALPHA_TRION_RPC_URL> --pk-type v2 --ca src/cert/ca.cert.pem --server-name <cert-domain> --refresh

Encrypt a plaintext into handle:

npm run encrypt -- --value 3517 --type u32 --rpc <ALPHA_TRION_RPC_URL> --ca src/cert/ca.cert.pem --server-name <cert-domain>

Encrypt multiple values in one request:

npm run encrypt -- --item 7:u8 --item 9:u16 --rpc <ALPHA_TRION_RPC_URL> --ca src/cert/ca.cert.pem --server-name <cert-domain>

Decrypt one or more handles:

npm run decrypt -- --handle 0xabc...
npm run decrypt -- --handles 0xabc...,0xdef...

Query computation status:

npm run computation-status -- --tx 0x1234... --wait --rpc <ALPHA_TRION_RPC_URL> --ca src/cert/ca.cert.pem --server-name <cert-domain>

All CLIs also support:

• --verbose <0|1|2...>: enable request-level debug output