@interfold/sdk 0.2.0

package/LICENSE.md

@@ -0,0 +1,134 @@
+GNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> Everyone is permitted to copy
+and distribute verbatim copies of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the terms and conditions of
+version 3 of the GNU General Public License, supplemented by the additional permissions listed
+below.
+
+0.  Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the
+"GNU GPL" refers to version 3 of the GNU General Public License.
+
+"The Library" refers to a covered work governed by this License, other than an Application or a
+Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided by the Library, but which is
+not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed
+a mode of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an Application with the Library. The
+particular version of the Library with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the
+Combined Work, excluding any source code for portions of the Combined Work that, considered in
+isolation, are based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the object code and/or source code
+for the Application, including any data and utility programs needed for reproducing the Combined
+Work from the Application, but excluding the System Libraries of the Combined Work.
+
+1.  Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License without being bound by section
+3 of the GNU GPL.
+
+2.  Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a facility refers to a function or
+data to be supplied by an Application that uses the facility (other than as an argument passed when
+the facility is invoked), then you may convey a copy of the modified version:
+
+a) under this License, provided that you make a good faith effort to ensure that, in the event an
+Application does not supply the function or data, the facility still operates, and performs whatever
+part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of this License applicable to that
+copy.
+
+3.  Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from a header file that is part of
+the Library. You may convey such object code under terms of your choice, provided that, if the
+incorporated material is not limited to numerical parameters, data structure layouts and accessors,
+or small macros, inline functions and templates (ten or fewer lines in length), you do both of the
+following:
+
+a) Give prominent notice with each copy of the object code that the Library is used in it and that
+the Library and its use are covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license document.
+
+4.  Combined Works.
+
+You may convey a Combined Work under terms of your choice that, taken together, effectively do not
+restrict modification of the portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of the following:
+
+a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that
+the Library and its use are covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license document.
+
+c) For a Combined Work that displays copyright notices during execution, include the copyright
+notice for the Library among these notices, as well as a reference directing the user to the copies
+of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+      0) Convey the Minimal Corresponding Source under the terms of this
+      License, and the Corresponding Application Code in a form
+      suitable for, and under terms that permit, the user to
+      recombine or relink the Application with a modified version of
+      the Linked Version to produce a modified Combined Work, in the
+      manner specified by section 6 of the GNU GPL for conveying
+      Corresponding Source.
+
+      1) Use a suitable shared library mechanism for linking with the
+      Library.  A suitable mechanism is one that (a) uses at run time
+      a copy of the Library already present on the user's computer
+      system, and (b) will operate properly with a modified version
+      of the Library that is interface-compatible with the Linked
+      Version.
+
+e) Provide Installation Information, but only if you would otherwise be required to provide such
+information under section 6 of the GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the Combined Work produced by recombining or
+relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the
+Installation Information must accompany the Minimal Corresponding Source and Corresponding
+Application Code. If you use option 4d1, you must provide the Installation Information in the manner
+specified by section 6 of the GNU GPL for conveying Corresponding Source.)
+
+5.  Combined Libraries.
+
+You may place library facilities that are a work based on the Library side by side in a single
+library together with other library facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your choice, if you do both of the
+following:
+
+a) Accompany the combined library with a copy of the same work based on the Library, uncombined with
+any other library facilities, conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it is a work based on the Library,
+and explaining where to find the accompanying uncombined form of the same work.
+
+6.  Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General
+Public License from time to time. Such new versions will be similar in spirit to the present
+version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library as you received it specifies
+that a certain numbered version of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and conditions either of that published
+version or of any later version published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser General Public License, you may
+choose any version of the GNU Lesser General Public License ever published by the Free Software
+Foundation.
+
+If the Library as you received it specifies that a proxy can decide whether future versions of the
+GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any
+version is permanent authorization for you to choose that version for the Library.

package/README.md

@@ -0,0 +1,478 @@
+# Interfold TypeScript SDK
+
+A powerful, type-safe TypeScript SDK for interacting with Interfold smart contracts. This SDK
+provides real-time event listening, contract interaction methods, and comprehensive error handling.
+
+## Features
+
+- **Event-driven architecture**: Listen to smart contract events in real-time
+- **Type-safe**: Built with TypeScript and uses generated types from contracts
+- **Easy contract interactions**: Simple methods for reading from and writing to contracts
+- **React integration**: Includes React hooks for easy frontend integration (via `@interfold/react`)
+- **Modular architecture**: Tree-shakeable sub-modules for contracts, events, and encryption
+- **Encryption helpers**: Standalone FHE encryption functions with optional ZK proof generation
+- **Error handling**: Comprehensive error handling with custom error types
+- **Gas estimation**: Built-in gas estimation for transactions
+- **Event polling**: Support for both WebSocket and polling-based event listening
+
+## Installation
+
+```bash
+pnpm add @interfold/sdk
+```
+
+## Quick Start
+
+```typescript
+import { InterfoldSDK, InterfoldEventType, RegistryEventType } from '@interfold/sdk'
+import { createPublicClient, createWalletClient, http, custom } from 'viem'
+import { sepolia } from 'viem/chains'
+
+// Initialize clients
+const publicClient = createPublicClient({
+  chain: sepolia,
+  transport: http('YOUR_RPC_URL'),
+})
+
+const walletClient = createWalletClient({
+  chain: sepolia,
+  transport: custom(window.ethereum),
+})
+
+// Create SDK instance
+const sdk = new InterfoldSDK({
+  publicClient,
+  walletClient,
+  contracts: {
+    interfold: '0x...', // Your Interfold contract address
+    ciphernodeRegistry: '0x...', // Your CiphernodeRegistry contract address
+    feeToken: '0x...', // Your ERC-20 fee token address
+  },
+  chain: sepolia,
+  // Use 'SECURE_THRESHOLD_8192' for production; 'INSECURE_THRESHOLD_512' for local dev only
+  thresholdBfvParamsPresetName: 'SECURE_THRESHOLD_8192',
+})
+
+// Listen to events with the unified event system
+sdk.onInterfoldEvent(InterfoldEventType.E3_REQUESTED, (event) => {
+  console.log('E3 Requested:', event.data)
+})
+
+sdk.onInterfoldEvent(RegistryEventType.COMMITTEE_REQUESTED, (event) => {
+  console.log('Committee Requested:', event.data)
+})
+
+// Interact with contracts
+const hash = await sdk.requestE3({
+  threshold: [1, 3],
+  inputWindow: [BigInt(0), BigInt(100)],
+  e3Program: '0x...',
+  e3ProgramParams: '0x...',
+  computeProviderParams: '0x...',
+  customParams: '0x...',
+})
+```
+
+### Factory Method
+
+For a simpler setup (especially on the server), use the static `InterfoldSDK.create()` factory:
+
+```typescript
+import { InterfoldSDK } from '@interfold/sdk'
+import { sepolia } from 'viem/chains'
+
+const sdk = InterfoldSDK.create({
+  rpcUrl: 'wss://sepolia.example.com',
+  contracts: {
+    interfold: '0x...',
+    ciphernodeRegistry: '0x...',
+    feeToken: '0x...',
+  },
+  chain: sepolia,
+  privateKey: '0x...', // optional — omit for read-only
+  // Use 'SECURE_THRESHOLD_8192' for production; 'INSECURE_THRESHOLD_512' for local dev only
+  thresholdBfvParamsPresetName: 'SECURE_THRESHOLD_8192',
+})
+```
+
+The factory auto-detects HTTP vs WebSocket transports and creates the appropriate viem clients.
+
+## Usage within a browser
+
+Usage within a typescript project should work out of the box, however in order to use wasm related
+functionality of the SDK within the browser vite you must do the following:
+
+- Use `vite`
+- Use the `vite-plugin-top-level-await` plugin
+- Use the `vite-plugin-wasm` plugin
+- Exclude the `@interfold/wasm` package from bundling optimization.
+
+This will enable `vite` to correctly bundle and serve the wasm bundle we use effectively.
+
+```
+import { defineConfig } from 'vite'
+import wasm from 'vite-plugin-wasm'
+import topLevelAwait from 'vite-plugin-top-level-await'
+
+export default defineConfig({
+  // other config ...
+  optimizeDeps: {
+    exclude: ['@interfold/wasm'],
+  },
+  plugins: [wasm(), topLevelAwait()],
+})
+```
+
+## Event System
+
+The SDK uses a unified event system with TypeScript enums for type safety:
+
+### Interfold Events
+
+```typescript
+enum InterfoldEventType {
+  // E3 Lifecycle
+  E3_REQUESTED = 'E3Requested',
+  CIPHERTEXT_OUTPUT_PUBLISHED = 'CiphertextOutputPublished',
+  PLAINTEXT_OUTPUT_PUBLISHED = 'PlaintextOutputPublished',
+
+  // E3 Program Management
+  E3_PROGRAM_ENABLED = 'E3ProgramEnabled',
+  E3_PROGRAM_DISABLED = 'E3ProgramDisabled',
+
+  // Encryption Scheme Management
+  ENCRYPTION_SCHEME_ENABLED = 'EncryptionSchemeEnabled',
+  ENCRYPTION_SCHEME_DISABLED = 'EncryptionSchemeDisabled',
+
+  // Configuration
+  CIPHERNODE_REGISTRY_SET = 'CiphernodeRegistrySet',
+  MAX_DURATION_SET = 'MaxDurationSet',
+  ALLOWED_E3_PROGRAMS_PARAMS_SET = 'AllowedE3ProgramsParamsSet',
+  OWNERSHIP_TRANSFERRED = 'OwnershipTransferred',
+  INITIALIZED = 'Initialized',
+}
+```
+
+### Registry Events
+
+```typescript
+enum RegistryEventType {
+  COMMITTEE_REQUESTED = 'CommitteeRequested',
+  COMMITTEE_PUBLISHED = 'CommitteePublished',
+  COMMITTEE_FINALIZED = 'CommitteeFinalized',
+  INTERFOLD_SET = 'InterfoldSet',
+  OWNERSHIP_TRANSFERRED = 'OwnershipTransferred',
+  INITIALIZED = 'Initialized',
+}
+```
+
+### Event Data Structure
+
+Each event follows a consistent structure:
+
+```typescript
+interface InterfoldEvent<T extends AllEventTypes> {
+  type: T
+  data: EventData[T] // Typed based on event type
+  log: Log // Raw viem log
+  timestamp: Date
+  blockNumber: bigint
+  transactionHash: string
+}
+```
+
+## React Integration
+
+The SDK includes a React hook via the `@interfold/react` package:
+
+```bash
+pnpm add @interfold/react
+```
+
+```typescript
+import { useInterfoldSDK } from '@interfold/react'
+
+function MyComponent() {
+  const {
+    sdk,
+    isInitialized,
+    error,
+    requestE3,
+    onInterfoldEvent,
+    off,
+    InterfoldEventType,
+    RegistryEventType,
+  } = useInterfoldSDK({
+    contracts: {
+      interfold: '0x...',
+      ciphernodeRegistry: '0x...',
+      feeToken: '0x...',
+    },
+    autoConnect: true,
+    // Use 'SECURE_THRESHOLD_8192' for production; 'INSECURE_THRESHOLD_512' for local dev only
+    thresholdBfvParamsPresetName: 'SECURE_THRESHOLD_8192',
+  })
+
+  useEffect(() => {
+    if (isInitialized) {
+      const handler = (event) => {
+        console.log('New E3 request:', event)
+      }
+      onInterfoldEvent(InterfoldEventType.E3_REQUESTED, handler)
+      return () => off(InterfoldEventType.E3_REQUESTED, handler)
+    }
+  }, [isInitialized])
+
+  return (
+    <div>
+      {error && <p>Error: {error}</p>}
+      {!isInitialized && <p>Initializing...</p>}
+      {/* Your UI */}
+    </div>
+  )
+}
+```
+
+The hook uses wagmi's `usePublicClient` and `useWalletClient` under the hood, so your app must be
+wrapped in a wagmi provider.
+
+## Encryption Functions
+
+The SDK provides standalone encryption functions for FHE (Fully Homomorphic Encryption) operations.
+These can be used via the SDK instance or imported directly for tree-shaking:
+
+### Via the SDK instance
+
+```typescript
+// Generate a public key
+const publicKey = await sdk.generatePublicKey()
+
+// Encrypt a single number
+const encrypted = await sdk.encryptNumber(42n, publicKey)
+
+// Encrypt a vector
+const encryptedVec = await sdk.encryptVector(BigUint64Array.from([1n, 2n, 3n]), publicKey)
+
+// Encrypt with ZK proof generation
+const { encryptedData, proof } = await sdk.encryptNumberAndGenProof(42n, publicKey)
+```
+
+### Standalone imports
+
+```typescript
+import {
+  generatePublicKey,
+  encryptNumber,
+  encryptVector,
+  encryptNumberAndGenProof,
+  encryptVectorAndGenProof,
+  encryptNumberAndGenInputs,
+  encryptVectorAndGenInputs,
+  computePublicKeyCommitment,
+  getThresholdBfvParamsSet,
+} from '@interfold/sdk'
+
+// Use 'SECURE_THRESHOLD_8192' for production; 'INSECURE_THRESHOLD_512' for local dev only
+const presetName = 'SECURE_THRESHOLD_8192'
+
+const publicKey = await generatePublicKey(presetName)
+const encrypted = await encryptNumber(42n, publicKey, presetName)
+const { encryptedData, proof } = await encryptNumberAndGenProof(42n, publicKey, presetName)
+```
+
+## Modular Imports
+
+The SDK is organized into three sub-modules that can be imported independently for tree-shaking:
+
+```typescript
+// Encryption functions and types
+import { generatePublicKey, encryptNumber } from '@interfold/sdk/crypto'
+
+// Contract client and types
+import { ContractClient } from '@interfold/sdk/contracts'
+import type { ContractAddresses, E3 } from '@interfold/sdk/contracts'
+
+// Event listener and types
+import { EventListener, InterfoldEventType, RegistryEventType } from '@interfold/sdk/events'
+```
+
+All sub-module exports are also re-exported from the main `@interfold/sdk` entry point for
+convenience.
+
+## API Reference
+
+### Core Methods
+
+#### Contract Interactions
+
+```typescript
+// Approve fee token spending
+await sdk.approveFeeToken(amount: bigint);
+
+// Request a new E3 computation
+await sdk.requestE3({
+  threshold: [number, number],
+  inputWindow: [bigint, bigint],
+  e3Program: `0x${string}`,
+  e3ProgramParams: `0x${string}`,
+  computeProviderParams: `0x${string}`,
+  customParams?: `0x${string}`,
+  gasLimit?: bigint
+});
+
+// Publish ciphertext output
+await sdk.publishCiphertextOutput(e3Id: bigint, ciphertextOutput: `0x${string}`, proof: `0x${string}`, gasLimit?: bigint);
+
+// Read operations
+const e3Data = await sdk.getE3(e3Id: bigint);
+const publicKey = await sdk.getE3PublicKey(e3Id: bigint);
+const quote = await sdk.getE3Quote(params: E3RequestParams);
+const stage = await sdk.getE3Stage(e3Id: bigint);
+const reason = await sdk.getFailureReason(e3Id: bigint);
+```
+
+#### Event Handling
+
+```typescript
+sdk.onInterfoldEvent(eventType: AllEventTypes, callback: EventCallback);
+
+sdk.off(eventType: AllEventTypes, callback: EventCallback);
+
+sdk.once(eventType: AllEventTypes, callback: EventCallback);
+
+const logs = await sdk.getHistoricalEvents(
+  eventType: AllEventTypes,
+  fromBlock?: bigint,
+  toBlock?: bigint
+);
+
+// Event polling (if websockets unavailable)
+await sdk.startEventPolling();
+sdk.stopEventPolling();
+```
+
+#### Encryption
+
+```typescript
+// Get BFV parameter set
+const params = await sdk.getThresholdBfvParamsSet();
+
+// Key generation
+const publicKey = await sdk.generatePublicKey();
+const commitment = await sdk.computePublicKeyCommitment(publicKey);
+
+// Encrypt data
+const encrypted = await sdk.encryptNumber(data: bigint, publicKey: Uint8Array);
+const encryptedVec = await sdk.encryptVector(data: BigUint64Array, publicKey: Uint8Array);
+
+// Encrypt with proof inputs (for ZK verification)
+const { encryptedData, circuitInputs } = await sdk.encryptNumberAndGenInputs(data, publicKey);
+const { encryptedData, circuitInputs } = await sdk.encryptVectorAndGenInputs(data, publicKey);
+
+// Encrypt with full ZK proof generation
+const { encryptedData, proof } = await sdk.encryptNumberAndGenProof(data, publicKey);
+const { encryptedData, proof } = await sdk.encryptVectorAndGenProof(data, publicKey);
+```
+
+#### Utilities
+
+```typescript
+// Gas estimation
+const gas = await sdk.estimateGas(functionName, args, contractAddress, abi, value?);
+
+// Transaction waiting
+const receipt = await sdk.waitForTransaction(hash);
+
+// Cleanup
+sdk.cleanup();
+```
+
+## Configuration
+
+```typescript
+interface SDKConfig {
+  publicClient: PublicClient
+  walletClient?: WalletClient
+  contracts: {
+    interfold: `0x${string}`
+    ciphernodeRegistry: `0x${string}`
+    feeToken: `0x${string}`
+  }
+  chain?: Chain
+  thresholdBfvParamsPresetName: ThresholdBfvParamsPresetName
+}
+```
+
+`thresholdBfvParamsPresetName` selects the BFV parameter set used for encryption. It must match the
+on-chain `paramSet` index registered in the Interfold contract:
+
+| Preset name                | On-chain `paramSet` index | Use case                                                                                                    |
+| -------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `'INSECURE_THRESHOLD_512'` | `0`                       | Local development and testing only — small polynomial degree (N=512), fast but not cryptographically secure |
+| `'SECURE_THRESHOLD_8192'`  | `1`                       | Production — full security parameters (N=8192, L=4 CRT moduli)                                              |
+
+Always use `'SECURE_THRESHOLD_8192'` in production. The insecure preset exists solely to speed up
+local dev cycles.
+
+## Error Handling
+
+The SDK includes comprehensive error handling:
+
+```typescript
+import { SDKError } from '@interfold/sdk'
+
+try {
+  await sdk.requestE3(params)
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.error(`SDK Error (${error.code}): ${error.message}`)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+## Development
+
+### Building the SDK
+
+```bash
+cd packages/interfold-sdk
+pnpm build
+```
+
+### Running the Demo
+
+```bash
+cd examples/basic/client
+pnpm install
+pnpm dev
+```
+
+The demo showcases all SDK features including real-time event listening and contract interactions.
+
+### Testing
+
+```bash
+cd packages/interfold-sdk
+pnpm test
+```
+
+## Architecture
+
+The SDK is organized into a modular architecture with three domain-specific sub-modules:
+
+- **InterfoldSDK** (`interfold-sdk.ts`): Main orchestrator class that delegates to sub-modules
+- **Contracts** (`contracts/`): `ContractClient` for contract read/write operations, type
+  definitions for contract addresses and E3 data
+- **Events** (`events/`): `EventListener` for real-time and historical event subscriptions, typed
+  event enums and data interfaces
+- **Encryption** (`encryption/`): Standalone FHE encryption functions, BFV parameter management, ZK
+  proof generation
+- **Utils** (`utils.ts`): Helper functions, error classes, encoding utilities
+
+Each sub-module has its own `index.ts` entry point and can be imported independently.
+
+## License
+
+This project is licensed under the MIT License.