{"id":10884,"library":"ffjavascript","title":"ffjavascript","description":"ffjavascript is a Finite Field Library implemented in JavaScript, designed for cryptographic applications, particularly those involving zk-SNARKs and other zero-knowledge proof systems. It provides core functionalities for performing arithmetic operations within finite fields, which are fundamental building blocks for many advanced cryptographic primitives. The library is currently at version 0.3.1 and sees an active, though not rapid, release cadence with minor updates and fixes. It is distinguished by its broad environment compatibility, supporting NodeJS, browser environments, Chrome Extensions, and Metamask Snaps (with SES compatibility), making it versatile for both backend and frontend cryptographic computations. Its primary differentiator is its focus on providing the underlying finite field arithmetic necessary for complex cryptographic protocols, often serving as a dependency for higher-level SNARK libraries.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/iden3/ffjavascript","tags":["javascript","Finite","Field","Javascript","Snark","Cryptography","Library"],"install":[{"cmd":"npm install ffjavascript","lang":"bash","label":"npm"},{"cmd":"yarn add ffjavascript","lang":"bash","label":"yarn"},{"cmd":"pnpm add ffjavascript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for building WebAssembly modules, likely for performance-critical finite field operations.","package":"wasmbuilder","optional":false},{"reason":"Provides WebAssembly optimized elliptic curve operations, which are often built upon finite field arithmetic.","package":"wasmcurves","optional":false},{"reason":"Enables multi-threading for computationally intensive tasks, improving performance in supported environments.","package":"web-worker","optional":false}],"imports":[{"note":"ffjavascript is primarily an ESM module since v0.3.0. CommonJS require() should be avoided for newer Node.js versions or browser builds. This function builds the BN128 elliptic curve finite field.","wrong":"const { buildBn128 } = require('ffjavascript');","symbol":"buildBn128","correct":"import { buildBn128 } from 'ffjavascript';"},{"note":"This is a named export for building the Baby Jubjub elliptic curve finite field. Attempting a default import will result in 'TypeError: buildBabyJub is not a function'.","wrong":"import buildBabyJub from 'ffjavascript';","symbol":"buildBabyJub","correct":"import { buildBabyJub } from 'ffjavascript';"},{"note":"ThreadManager is used for managing worker threads for parallel computation. Ensure your environment supports Web Workers if using in a browser context.","wrong":"const ThreadManager = require('ffjavascript').ThreadManager;","symbol":"ThreadManager","correct":"import { ThreadManager } from 'ffjavascript';"}],"quickstart":{"code":"import { buildBn128 } from 'ffjavascript';\n\nasync function runFieldOperations() {\n  console.log('Initializing BN128 Finite Field...');\n  const Fr = await buildBn128();\n  console.log('Field initialized successfully.');\n\n  // Create some field elements\n  const a = Fr.e(10);\n  const b = Fr.e(20);\n  const c = Fr.e('1234567890123456789012345678901234567890'); // Larger number as string\n\n  console.log(`a: ${Fr.toString(a)}`);\n  console.log(`b: ${Fr.toString(b)}`);\n  console.log(`c: ${Fr.toString(c)}`);\n\n  // Perform basic arithmetic operations\n  const sum = Fr.add(a, b);\n  const product = Fr.mul(a, b);\n  const diff = Fr.sub(b, a);\n  const inv = Fr.inv(a);\n  const div = Fr.div(b, a);\n\n  console.log(`a + b = ${Fr.toString(sum)}`);\n  console.log(`a * b = ${Fr.toString(product)}`);\n  console.log(`b - a = ${Fr.toString(diff)}`);\n  console.log(`1 / a = ${Fr.toString(inv)}`);\n  console.log(`b / a = ${Fr.toString(div)}`);\n\n  // Check if elements are equal\n  const isEqual = Fr.eq(sum, Fr.e(30));\n  console.log(`(a + b) === 30: ${isEqual}`);\n\n  console.log('Demonstration complete.');\n}\n\nrunFieldOperations().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to initialize the BN128 finite field and perform basic arithmetic operations with field elements like addition, multiplication, subtraction, inverse, and division."},"warnings":[{"fix":"Disable the `splitChunks` optimization in your Webpack configuration. Add `optimization: { splitChunks: false }` to your `module.exports` object in `webpack.config.js` or `next.config.js`.","message":"When using ffjavascript in Webpack-based projects (e.g., Next.js, Angular), you may encounter issues related to module chunking. The library's internal structure or dependencies might conflict with Webpack's default `splitChunks` optimization.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Developers targeting SES environments should test their integrations thoroughly after upgrading to v0.3.0+. Ensure no code directly or indirectly relies on dynamic `eval` calls that are not compatible with SES strictures. For non-SES environments, this change is largely backward compatible.","message":"Version 0.3.0 introduced a fix that renames internal `eval` usage to ensure compatibility with SES (Secure EcmaScript) environments, such as Metamask Snaps. This change might break applications that relied on specific internal behaviors of `eval` or were not prepared for a more restricted execution environment.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"For new projects, prefer ESM `import` statements. For Node.js, ensure your `package.json` has `\"type\": \"module\"` or explicitly use `.mjs` extensions for ESM files. If you must use CJS, verify that your bundler or Node.js setup correctly resolves the CJS entry point specified in `package.json`'s `exports` map (e.g., `\"require\": \"./build/main.cjs\"`).","message":"ffjavascript transitioned to being primarily an ES Module (ESM) after version 0.3.0, while still providing CommonJS (CJS) compatibility for Node.js via its `exports` field. Incorrect import syntax (e.g., using `require()` for ESM-only contexts or `import` in CJS-only environments) can lead to module resolution errors.","severity":"gotcha","affected_versions":">=0.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your webpack configuration disables `splitChunks` by adding `optimization: { splitChunks: false }` to your `module.exports` in `webpack.config.js` or equivalent.","cause":"Webpack or other bundlers are failing to resolve the `ffjavascript` module, often due to chunking optimizations or incorrect module resolution paths.","error":"Error: Module not found: Error: Can't resolve 'ffjavascript' in '[your-project-path]'"},{"fix":"Always use `await` when calling `buildBn128()` or similar field builder functions, as they are asynchronous. Example: `const Fr = await buildBn128();`.","cause":"The field builder function (e.g., `buildBn128`) often returns a Promise that needs to be awaited before the field object can be used.","error":"TypeError: Cannot read properties of undefined (reading 'e') at Function.buildBn128"}],"ecosystem":"npm"}