![](\"./media/fhnx_cover.svg#gh-light-mode-only\")
\n\n \n
\n The JavaScript SDK for Fhenix\n
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/fhenixjs\")
![\"ci\"](\"https://github.com/fhenixprotocol/fhenix.js/actions/workflows/test.yml/badge.svg?branch=main\"){kind=icon}
\n
\n Explore the Docs ยป\n
\n\n## General\n\nfhenix.js allows developers to add support for encrypted data when developing dApps on Fhenix.\nfhenix.js includes easy helpers for encryption, unsealing and helpers to create apps that utilize private data.\n\n## Installation\n\n### NodeJS\n\n(only node 20+ is supported until I fix this)\n\n```bash\n# Using npm\nnpm install fhenixjs\n```\n\n### Browser Installation (or simpler bundling)\n\nFor browsers or environments that don't want to mess with WASM bundling, we recommend installing the prepackaged versions directly\nwhich is available in the ./dist/ folder in this repo.\n\nYou can also install from a CDN e.g.\n\n`https://cdn.jsdelivr.net/npm/fhenixjs@0.3.0-alpha.1/dist/fhenix.umd.min.js`\n\n#### ESM\n\nYou can install as a module:\n\n```\n\n```\n\n#### UMD\n\nOr from a UMD:\n\n```\n\n```\n\n#### NextJS WASM Bundling\n\nFhenixJS uses WASM for all the FHE goodness. If you're using the non-prepackaged version you'll need to configure next.js to properly use WASM via the `next.config.js` file. \n\nOtherwise, you can use the prepackaged version above that avoids having to bundle WASM.\n\nHere's a working config I managed to conjure up from various Github and StackOverflow issues (please suggest improvements):\n\n```javascript\n/** @type {import('next').NextConfig} */\n\nmodule.exports = {\n webpack: (config, { isServer }) => {\n \n patchWasmModuleImport(config, isServer);\n\n if (!isServer) {\n config.output.environment = { ...config.output.environment, asyncFunction: true };\n }\n return config\n }\n}\n\nfunction patchWasmModuleImport(config, isServer) {\n config.experiments = Object.assign(config.experiments || {}, {\n asyncWebAssembly: true,\n layers: true,\n topLevelAwait: true\n });\n\n config.optimization.moduleIds = 'named';\n\n config.module.rules.push({\n test: /\\.wasm$/,\n type: 'asset/resource',\n });\n\n // TODO: improve this function -> track https://github.com/vercel/next.js/issues/25852\n if (isServer) {\n config.output.webassemblyModuleFilename = './../static/wasm/tfhe_bg.wasm';\n } else {\n config.output.webassemblyModuleFilename = 'static/wasm/tfhe_bg.wasm';\n }\n}\n```\n\n#### Other Bundlers/Frameworks\n\nIf you have any problems with bundlers or frameworks, please open an issue in this repo and/or reach out on Discord/TG.\n\nAlso, if you had to fiddle with a bundler or config to get it working, please share the config with us so we can add it as a reference for others!\n\n\n#### Mobile Support\n\nCompletely untested. Maybe yes, maybe no, maybe both.\n\n## fhenix.js sdk\n\n`cofhejs` is designed to make interacting with FHE enabled blockchains typesafe and as streamlined as possible by providing utility functions for inputs, permits (permissions), and outputs. The sdk is an opinionated implementation of the underling `Permit` class, therefor if the sdk is too limiting for your use case (e.g. multiple active users), you can easily drop down into the core `Permit` class to extend its functionality.\n\nNOTE: `cofhejs` is still in beta, and while we will try to avoid it, we may release breaking changes in the future if necessary.\n\n### Environment-specific Imports\n\ncofhejs offers environment-specific entry points to ensure optimal compatibility across different platforms:\n\n#### Browser Environments\n\nFor web applications, use the browser-specific entry point:\n\n```typescript\nimport { cofhejs } from \"cofhejs/web\";\n```\n\nThis entry point is optimized for browser environments and handles WASM loading properly in frontend frameworks like React, Vue, or vanilla JavaScript applications.\n\n#### Node.js Environments\n\nFor Node.js applications, serverless functions, or test environments like Hardhat scripts:\n\n```typescript\nimport { cofhejs } from \"cofhejs/node\";\n```\n\nThis entry point is optimized for Node.js environments and ensures proper WASM loading without browser-specific dependencies.\n\n### Initialization\n\nBefore interacting with your users' permits and encrypted data, initialize the sdk:\n\n```typescript\n// Basic initialization with provider and signer\nawait cofhejs.initialize({\n provider: userProvider, // Implementation of AbstractAccount in `types.ts`\n signer: userSigner, // Implementation of AbstractSigner in `types.ts`\n})\n```\n\nSee \n\n#### Re-initialization on User Change\n\nWhen the user changes (e.g., wallet switch), re-initialize the sdk with the updated credentials:\n\n```typescript\n// Listen for account changes in your wallet connector\nonAccountsChanged(async (accounts) => {\n const newAddress = accounts[0];\n // Get updated provider/signer for the new account\n const newProvider = getUpdatedProvider(newAddress);\n const newSigner = getUpdatedSigner(newAddress);\n \n // Re-initialize cofhejs with the new user\n await cofhejs.initialize({\n provider: newProvider,\n signer: newSigner\n });\n});\n```\n\n### Creating and Managing Permits\n\nPermits are a critical component for FHE interactions, allowing users to access their encrypted data:\n\n```typescript\n// Create a permit with default options (self-permit for the current user)\nawait cofhejs.createPermit()\n\n// Create a permit with custom options\nawait cofhejs.createPermit({\n type: \"self\", // \"self\" | \"third-party\" | \"authorized\"\n issuer: userAddress, // The address issuing this permit\n expiration: 3600, // Optional: Expiration time in seconds\n allowedFunctions: [ // Optional: Restrict to specific functions\n \"getBalance\",\n \"transfer\"\n ]\n})\n\n// Get the current active permit\nconst permit = cofhejs.getPermit()\n\n// Extract permission data for contract calls\nconst permission = permit.getPermission()\n```\n\n### Encrypting Data for Contracts\n\nTo interact with FHE-enabled contracts, plaintext values must be encrypted before sending:\n\n```typescript\n// Encrypting a single value\nconst encryptedValue = cofhejs.encrypt(Encryptable.uint32(42))\n\n// Encrypting multiple values in a single call\nconst encryptedArgs = cofhejs.encrypt([\n Encryptable.uint8(5),\n Encryptable.uint256(\"1000000000000000000\"), // 1 ETH\n Encryptable.bool(true)\n])\n\n// Complex data structures with automatic permission injection\nconst encryptedData = cofhejs.encrypt({\n permission: \"permission\", // Special string that gets replaced with the active permission\n amount: Encryptable.uint128(1000),\n recipients: [\n {\n address: \"0x123...\",\n value: Encryptable.uint64(500)\n },\n {\n address: \"0x456...\",\n value: Encryptable.uint64(500)\n }\n ],\n memo: \"Payment split\" // Non-encrypted fields pass through unchanged\n})\n```\n\n#### Available Encryption Types\n\ncofhejs supports all FHE data types:\n\n```typescript\n// Integer types\nEncryptable.uint8(value)\nEncryptable.uint16(value)\nEncryptable.uint32(value)\nEncryptable.uint64(value)\nEncryptable.uint128(value)\nEncryptable.uint256(value)\n\n// Boolean type\nEncryptable.bool(value)\n\n// Address type (experimental)\nEncryptable.address(value)\n```\n\n### Handling Encrypted Outputs (Unsealing)\n\nWhen contracts return sealed encrypted data, use the `unseal` method to decrypt it:\n\n```typescript\n// Simple unsealing from a contract call\nconst sealedBalance = await myContract.getEncryptedBalance(permission)\nconst balance = await cofhejs.unseal(sealedBalance)\n// balance is now a plain JavaScript value\n\n// Unsealing multiple values from a structured response\nconst response = await myContract.getMultipleValues(permission)\nconst unsealed = await cofhejs.unseal(response)\n// unsealed will maintain the same structure as response, but with decrypted values\n```\n\n### Integration with Popular Web3 Libraries\n\n#### Using with ethers.js\n\n```typescript\nimport { ethers } from \"ethers\";\nimport { cofhejs } from \"cofhejs/web\";\nimport MyContractABI from \"./MyContract.json\";\n\n// Setup\nconst provider = new ethers.providers.Web3Provider(window.ethereum);\nconst signer = provider.getSigner();\nconst contract = new ethers.Contract(contractAddress, MyContractABI, signer);\n\n// Initialize cofhejs\nawait cofhejs.initialize({ provider, signer });\nawait cofhejs.createPermit();\nconst permission = cofhejs.getPermit().getPermission();\n\n// Encrypt data and send transaction\nconst encryptedAmount = cofhejs.encrypt(Encryptable.uint64(1000));\nconst tx = await contract.deposit(permission, encryptedAmount);\nawait tx.wait();\n\n// Retrieve and unseal data\nconst sealedBalance = await contract.getBalance(permission);\nconst balance = await cofhejs.unseal(sealedBalance);\nconsole.log(\"Balance:\", balance);\n```\n\n#### Using with viem\n\n```typescript\nimport { createWalletClient, custom, getContract } from \"viem\";\nimport { privateKeyToAccount } from \"viem/accounts\";\nimport { cofhejs } from \"cofhejs/web\";\nimport { fhenixNetwork } from \"cofhejs/chains\";\nimport MyContractABI from \"./MyContract.json\";\n\n// Setup\nconst account = privateKeyToAccount(\"0x...\");\nconst client = createWalletClient({\n account,\n chain: fhenixNetwork,\n transport: custom(window.ethereum)\n});\n\nconst contract = getContract({\n address: contractAddress,\n abi: MyContractABI,\n client\n});\n\n// Initialize cofhejs\nawait cofhejs.initialize({ provider: client, signer: account });\nawait cofhejs.createPermit();\nconst permission = cofhejs.getPermit().getPermission();\n\n// Encrypt and send transaction\nconst encryptedVote = cofhejs.encrypt(Encryptable.bool(true));\nawait contract.write.castVote([permission, encryptedVote]);\n\n// Get and unseal results\nconst sealedResults = await contract.read.getResults([permission]);\nconst results = await cofhejs.unseal(sealedResults);\nconsole.log(\"Voting results:\", results);\n```\n\n### Advanced Usage: Working with Raw Permits\n\nFor applications requiring more fine-grained control:\n\n```typescript\nimport { Permit } from \"cofhejs/core\";\n\n// Create a permit manually\nconst permit = new Permit({\n provider,\n signer,\n chainId: 42069\n});\n\n// Generate a new permit\nawait permit.generate({\n type: \"third-party\",\n issuer: userAddress,\n delegatee: receiverAddress,\n expiration: 86400 // 24 hours\n});\n\n// Sign the permit\nawait permit.sign();\n\n// Get permission for contract calls\nconst permission = permit.getPermission();\n\n// Export permit for storage\nconst serialized = permit.serialize();\nlocalStorage.setItem(\"savedPermit\", serialized);\n\n// Import previously saved permit\nconst savedPermit = localStorage.getItem(\"savedPermit\");\nif (savedPermit) {\n await permit.deserialize(savedPermit);\n}\n```\n\nFor more advanced use cases and detailed API documentation, please refer to our [full documentation](https://fhenixjs.fhenix.zone).\n","readmeFilename":"README.md"}