ffjavascript

0.3.1 · active · verified Sun Apr 19

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.

Common errors

```
Error: Module not found: Error: Can't resolve 'ffjavascript' in '[your-project-path]'
```
cause Webpack or other bundlers are failing to resolve the `ffjavascript` module, often due to chunking optimizations or incorrect module resolution paths.

fix Ensure your webpack configuration disables `splitChunks` by adding `optimization: { splitChunks: false }` to your `module.exports` in `webpack.config.js` or equivalent.
```
TypeError: Cannot read properties of undefined (reading 'e') at Function.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.

fix Always use `await` when calling `buildBn128()` or similar field builder functions, as they are asynchronous. Example: `const Fr = await buildBn128();`.

Warnings

gotcha 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.
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`.
breaking 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.
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.
gotcha 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.
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"`).

Install

npm install ffjavascript npm
yarn add ffjavascript yarn
pnpm add ffjavascript pnpm

Imports

buildBn128
wrong:
```
const { buildBn128 } = require('ffjavascript');
```
correct:
```
import { buildBn128 } from 'ffjavascript';
```
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.
buildBabyJub
wrong:
```
import buildBabyJub from 'ffjavascript';
```
correct:
```
import { buildBabyJub } from 'ffjavascript';
```
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'.
ThreadManager
wrong:
```
const ThreadManager = require('ffjavascript').ThreadManager;
```
correct:
```
import { ThreadManager } from 'ffjavascript';
```
ThreadManager is used for managing worker threads for parallel computation. Ensure your environment supports Web Workers if using in a browser context.

Quickstart

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.

import { buildBn128 } from 'ffjavascript';

async function runFieldOperations() {
  console.log('Initializing BN128 Finite Field...');
  const Fr = await buildBn128();
  console.log('Field initialized successfully.');

  // Create some field elements
  const a = Fr.e(10);
  const b = Fr.e(20);
  const c = Fr.e('1234567890123456789012345678901234567890'); // Larger number as string

  console.log(`a: ${Fr.toString(a)}`);
  console.log(`b: ${Fr.toString(b)}`);
  console.log(`c: ${Fr.toString(c)}`);

  // Perform basic arithmetic operations
  const sum = Fr.add(a, b);
  const product = Fr.mul(a, b);
  const diff = Fr.sub(b, a);
  const inv = Fr.inv(a);
  const div = Fr.div(b, a);

  console.log(`a + b = ${Fr.toString(sum)}`);
  console.log(`a * b = ${Fr.toString(product)}`);
  console.log(`b - a = ${Fr.toString(diff)}`);
  console.log(`1 / a = ${Fr.toString(inv)}`);
  console.log(`b / a = ${Fr.toString(div)}`);

  // Check if elements are equal
  const isEqual = Fr.eq(sum, Fr.e(30));
  console.log(`(a + b) === 30: ${isEqual}`);

  console.log('Demonstration complete.');
}

runFieldOperations().catch(console.error);

view raw JSON →