SDK

This page is the reference for the TypeScript SDK (@interfold/sdk) and the React hook package (@interfold/react). It is for developers who write an E3 client or a coordination server. It covers installation, the client class, requests, the committee public key, encryption, events, enums, utilities, and errors. The samples come from the default template (templates/default) and the SDK README. Every export on this page exists in version 0.18.0.

Packages

Both packages are in this repository.

Install

Add the SDK. Add the React package only if you use React.

pnpm add @interfold/sdk
pnpm add @interfold/react

@interfold/react has two peer dependencies: react (^18.2.0) and wagmi (^2.14.16).

The encryption functions use WebAssembly. In a Vite project, add vite-plugin-wasm and vite-plugin-top-level-await, and exclude @interfold/wasm from dependency optimization. This configuration comes from the SDK README:

import { defineConfig } from 'vite'
import wasm from 'vite-plugin-wasm'
import topLevelAwait from 'vite-plugin-top-level-await'
 
export default defineConfig({
  optimizeDeps: {
    exclude: ['@interfold/wasm'],
  },
  plugins: [wasm(), topLevelAwait()],
})

The template client uses the same two plugins in client/vite.config.ts.

Create a client

With viem clients

new InterfoldSDK(config) creates the client. No separate initialize call is necessary.

The constructor throws an SDKError with the code MISSING_PUBLIC_CLIENT, INVALID_ADDRESS, or INVALID_THRESHOLD_BFV_PARAMS_PRESET_NAME when the configuration is not valid.

import { InterfoldSDK } from '@interfold/sdk'
import { createPublicClient, createWalletClient, custom, http } from 'viem'
import { sepolia } from 'viem/chains'
 
const publicClient = createPublicClient({ chain: sepolia, transport: http(RPC_URL) })
 
// The SDK signs with walletClient.account, so create the wallet client with an account.
const [account] = await createWalletClient({
  chain: sepolia,
  transport: custom(window.ethereum!),
}).requestAddresses()
const walletClient = createWalletClient({
  account,
  chain: sepolia,
  transport: custom(window.ethereum!),
})
 
const sdk = new InterfoldSDK({
  publicClient,
  walletClient,
  contracts: {
    interfold: INTERFOLD_ADDRESS,
    ciphernodeRegistry: REGISTRY_ADDRESS,
    feeToken: FEE_TOKEN_ADDRESS,
  },
  chain: sepolia,
  thresholdBfvParamsPresetName: 'SECURE_THRESHOLD_8192',
})

With the factory

InterfoldSDK.create(options) creates the viem clients for you. It is useful on a server.

A ws:// or wss:// URL gives a WebSocket transport with a 30-second keep-alive and five reconnect attempts at 2-second intervals. Other URLs give an HTTP transport. This sample comes from templates/default/server/index.ts:

import { InterfoldSDK } from '@interfold/sdk'
import { hardhat } from 'viem/chains'
 
const sdk = InterfoldSDK.create({
  rpcUrl: RPC_URL,
  privateKey: PRIVATE_KEY as `0x${string}`,
  contracts: {
    interfold: INTERFOLD_CONTRACT as `0x${string}`,
    ciphernodeRegistry: CIPHERNODE_REGISTRY_CONTRACT as `0x${string}`,
    feeToken: FEE_TOKEN_CONTRACT as `0x${string}`,
  },
  chain: hardhat,
  thresholdBfvParamsPresetName: 'INSECURE_THRESHOLD_64',
})

BFV presets

The preset selects the BFV parameters that the client uses to encrypt. It must match the paramSet of the E3.

The insecure preset has no production security. Use it only for tests. ThresholdBfvParamsPresetNames lists both names, and DEFAULT_THRESHOLD_BFV_PARAMS_PRESET_NAME is INSECURE_THRESHOLD_64.

Request an E3

The request takes three calls: quote the fee, approve the fee token, and send the request. This sample is trimmed from templates/default/client/src/pages/steps/RequestComputation.tsx. It adds maxFee.

import {
  DEFAULT_COMPUTE_PROVIDER_PARAMS,
  DEFAULT_E3_CONFIG,
  calculateInputWindow,
  encodeComputeProviderParams,
} from '@interfold/sdk'
 
const publicClient = sdk.getPublicClient()
const inputWindow = await calculateInputWindow(publicClient, 100) // 100 seconds
 
const requestParams = {
  committeeSize: DEFAULT_E3_CONFIG.committeeSize, // CommitteeSize.Minimum
  inputWindow,
  e3Program: E3_PROGRAM_ADDRESS,
  paramSet: 0, // insecure-64, for local development
  computeProviderParams: encodeComputeProviderParams(DEFAULT_COMPUTE_PROVIDER_PARAMS),
}
 
const fee = await sdk.getE3Quote(requestParams)
const approveTx = await sdk.approveFeeToken(fee)
await publicClient.waitForTransactionReceipt({ hash: approveTx })
 
const hash = await sdk.requestE3({ ...requestParams, maxFee: fee })

E3RequestParams in the SDK has these fields:

requestE3 fills the fields that the contract needs and the SDK knows:

• expectedFeeToken is the feeToken address from the SDK configuration.
• expectedCryptoConfigId is the configuration ID for paramSet 0 or 2. Other values fail.
• committeeSize must be 0, 1, or 2.

requestE3 simulates the call first, then sends it, and returns the transaction hash. To get the E3 ID, watch InterfoldEventType.E3_REQUESTED and read event.data.e3Id. For the contract rules behind each field, see The Interfold Contract.

Get the committee public key

The registry does not store the full public key. Committee members publish the serialized key in CommitteePublicKeyChunkPublished events. Each event carries the proven public key commitment (pkCommitment). The client joins the chunks, then checks the key against the commitment.

This sample comes from templates/default/server/index.ts:

import { CommitteePublicKeyAssembler } from '@interfold/sdk'
import { RegistryEventType } from '@interfold/sdk/events'
import { hexToBytes } from 'viem'
 
const committeeKeyAssembler = new CommitteePublicKeyAssembler()
 
await sdk.onInterfoldEvent(
  RegistryEventType.COMMITTEE_PUBLIC_KEY_CHUNK_PUBLISHED,
  async (event) => {
    const assembled = committeeKeyAssembler.add(event.data)
    if (!assembled) return
 
    const isBoundKey = await sdk.validatePublicKeyCommitment(
      assembled.publicKey,
      hexToBytes(assembled.pkCommitment),
    )
    if (!isBoundKey) return
 
    committeeKeyAssembler.clear(assembled.e3Id)
    // assembled.publicKey is the committee public key for assembled.e3Id.
  },
)

CommitteePublicKeyAssembler works as follows:

• add(event.data) returns an AssembledCommitteePublicKey (e3Id, nodes, pkCommitment, publicKey) when a candidate is complete and its Keccak-256 hash matches. Otherwise it returns undefined.
• It accepts only the first candidate from each publisher.
• It rejects keys larger than MAX_COMMITTEE_PUBLIC_KEY_BYTES (512 KiB). Each chunk is at most MAX_COMMITTEE_PUBLIC_KEY_CHUNK_BYTES (90 KiB).
• It tracks 128 E3s by default. clear(e3Id) removes the state for one E3.

sdk.getE3PublicKey(e3Id) returns the 32-byte public key commitment from the registry. It is not the key. The call fails with GET_E3_PUBLIC_KEY_FAILED before the committee publishes.

Encrypt inputs

The SDK has each encryption function in two forms. The instance method uses the preset from the configuration. The standalone function takes the preset name as its last argument.

A key from generatePublicKey is not a committee key. The committee cannot decrypt data that is encrypted to it. For the full encrypt and submit flow, see Encrypt and submit.

Encryption proofs

The *AndGenProof functions and generateProof use circuits that ship in the SDK. The SDK compiles them with the insecure-64 preset and the minimum committee (packages/interfold-sdk/scripts/compile-circuits.sh). The proofs target recursive verification (noir-recursive-no-zk), not a Solidity verifier.

In Node.js, generateProof checks the circuit stamp file (.active-preset.json) when it finds one. It fails with one of these codes when the stamp does not match:

• SDK_CIRCUIT_STAMP_MISSING or SDK_CIRCUIT_STAMP_INVALID: the stamp file is missing or broken.
• SDK_CIRCUIT_COMMITTEE_MISMATCH: the circuits are not for the minimum committee.
• SDK_CIRCUIT_PRESET_MISMATCH: the circuits are not for insecure-64.

For another preset, another committee size, or an on-chain verifier, compile your own circuits. Use encryptNumberAndGenInputs or encryptVectorAndGenInputs to get the witness for your prover. See Noir circuits. The CRISP repository (opens in a new tab) shows a complete custom pipeline.

Submodule imports

Each subpath exports part of the SDK. The main entry point exports everything, except the type CiphertextOutputReferencePublishedData, which only @interfold/sdk/events exports.

import { encryptNumber, generatePublicKey } from '@interfold/sdk/crypto'
import { ContractClient } from '@interfold/sdk/contracts'
import { EventListener, InterfoldEventType } from '@interfold/sdk/events'

Events

The SDK watches events with viem watchContractEvent. It sends registry-only event names to the ciphernodeRegistry address and all other names to the interfold address. The shared names OwnershipTransferred and Initialized therefore go to the interfold address, also for a RegistryEventType key.

Each callback gets an InterfoldEvent with type, data (the decoded event arguments), log, timestamp, blockNumber, and transactionHash. timestamp is the local time when the SDK got the log. Live watchers skip a log that they already delivered.

InterfoldEventType

RegistryEventType

RandomnessProviderEventType

RANDOMNESS_FULFILLED maps to RandomnessFulfilled. The registry freezes a provider for each request. Read provider, requestId, and e3Id from CommitteeRandomnessRequested, then watch that provider:

import { RandomnessProviderEventType } from '@interfold/sdk'
 
await sdk.onRandomnessProviderEvent(
  provider,
  RandomnessProviderEventType.RANDOMNESS_FULFILLED,
  ({ data }) => {
    console.log(data.requestId, data.e3Id, data.fulfilledAt)
  },
)

A fulfillment shows only that the provider stored a response. The registry decides whether the response was on time and usable. Callers that share one provider watcher must use the same fromBlock, or omit it. A different explicit fromBlock fails with INVALID_EVENT_CONFIG.

Lifecycle enums

validateCommitteeSize(value) returns the value or throws INVALID_COMMITTEE_SIZE. Read the stage with sdk.getE3Stage(e3Id) and the reason with sdk.getFailureReason(e3Id).

Contract calls

These InterfoldSDK methods call the contracts. The write methods need a wallet client with an account.

The SDK does not call the E3 program. Call publishInput on your program with viem. See Encrypt and submit.

Utilities

The main entry point exports these utilities.

Contract addresses

ContractAddresses has three fields: interfold, ciphernodeRegistry, and feeToken. Create one SDK instance for each chain.

The template reads the addresses from interfold.config.yaml. interfold print-env --chain localhost prints them as INTERFOLD_ADDRESS, REGISTRY_ADDRESS, E3_PROGRAM_ADDRESS, FEE_TOKEN_ADDRESS, and more. With --vite, the names start with VITE_. For live networks, see Contracts & Addresses.

Errors

The SDK throws SDKError, a subclass of Error with name set to SDKError and an optional code.

A write method wraps the original error in its own code. The contract revert reason is in message. getE3Quote, getE3Stage, and getFailureReason return the viem read directly. A contract revert from these calls therefore reaches you as a viem error, not as an SDKError.

import { SDKError } from '@interfold/sdk'
 
try {
  await sdk.requestE3({ ...requestParams, maxFee: fee })
} catch (error) {
  if (error instanceof SDKError && error.code === 'REQUEST_E3_FAILED') {
    console.error(error.message) // Contains the revert, for example FeeExceedsMaximum
  }
}

React hook

useInterfoldSDK(config) creates an InterfoldSDK from the wagmi public client and wallet client. The component must be inside a WagmiProvider.

The hook returns sdk, isInitialized, error (a string), requestE3, getThresholdBfvParamsSet, onInterfoldEvent, off, InterfoldEventType, and RegistryEventType. It creates the SDK again when the wallet client changes, and it calls cleanup() on unmount. The helper functions throw SDK not initialized before the SDK exists.

The template memoizes the configuration, because the hook creates a new SDK when the contracts object changes. This sample follows client/src/context/WizardContext.tsx and client/src/utils/sdk-config.ts:

import { useMemo } from 'react'
import { useInterfoldSDK } from '@interfold/react'
 
export function useTemplateSdk() {
  const sdkConfig = useMemo(
    () => ({
      autoConnect: true,
      contracts: {
        interfold: import.meta.env.VITE_INTERFOLD_ADDRESS,
        ciphernodeRegistry: import.meta.env.VITE_REGISTRY_ADDRESS,
        feeToken: import.meta.env.VITE_FEE_TOKEN_ADDRESS,
      },
      thresholdBfvParamsPresetName: 'INSECURE_THRESHOLD_64' as const,
    }),
    [],
  )
  return useInterfoldSDK(sdkConfig)
}

@interfold/react also exports InterfoldEventType, RegistryEventType, RandomnessProviderEventType, and the common event data types from the SDK.

Application SDKs

A complex E3 program can ship its own SDK next to the Interfold SDK. CRISP uses @crisp-e3/sdk (packages/crisp-sdk (opens in a new tab) in the CRISP repository). It exports CrispSDK, vote functions such as encryptVote, prepareBallot, and decodeTally, and Merkle helpers such as generateMerkleProof.

Next steps