R1CS Binary File Parser

Common errors

• Error: ENOENT: no such file or directory, open 'path/to/your/file.r1cs'

  cause The specified R1CS file path does not exist or is inaccessible.
  fix Verify the file path is correct and absolute, or relative to the current working directory of the script. Check file permissions to ensure the Node.js process can read the file.

• Error: Invalid R1CS header magic: 0x...

  cause The file being read is not a valid R1CS binary file, or it's corrupted, or it follows a different format.
  fix Confirm the file is a legitimate R1CS binary generated by a compatible tool like Circom. Try regenerating the R1CS file or inspecting it with a hex editor if possible to ensure its integrity.

• RangeError: Invalid array length

  cause Occurs when parsing a malformed or extremely large R1CS file, leading to attempts to allocate an array exceeding JavaScript's memory limits.
  fix Check the R1CS file for corruption or unusually large/incorrect values in its header fields (e.g., `nVars`, `nConstraints`). For very large legitimate files, consider increasing Node.js's memory limit (`node --max-old-space-size=8192 script.js`).

Warnings

• breaking Due to the package's early version (0.0.x), the API surface is not yet considered stable. Minor version bumps (e.g., 0.0.40 to 0.0.41) could potentially introduce breaking changes without adhering to semantic versioning for major versions. Always review the changelog when updating.
  Fix: Pin the exact package version in your `package.json` (e.g., `"r1csfile": "0.0.48"`) and manually test after updates. Always check the GitHub repository for breaking changes between minor versions.
• gotcha Parsing large R1CS files can be memory-intensive, especially for circuits with millions of constraints or variables. This can lead to out-of-memory errors in Node.js environments if not managed carefully.
  Fix: Monitor memory usage during parsing. For very large files, consider increasing Node.js's memory limit (`--max-old-space-size=4096`) or explore streaming/batch processing options if the library supports them (currently, it reads the whole file into memory).
• gotcha The library is designed to parse the specific R1CS binary format defined by Iden3 (e.g., from Circom). Using it with R1CS files generated by other tools or custom formats may lead to parsing errors or incorrect interpretation of data.
  Fix: Ensure that your R1CS files originate from compatible sources, primarily Circom. If generating R1CS files programmatically, strictly adhere to the Iden3 R1CS binary format specification.

Install

• npm install r1csfile npm
• yarn add r1csfile yarn
• pnpm add r1csfile pnpm

Imports

• readR1cs
  wrong:

  const readR1cs = require('r1csfile');

  correct:

  import { readR1cs } from 'r1csfile';

  While the README shows CommonJS `require`, modern Node.js and browser environments typically use named ESM imports. The `readR1cs` function is the primary utility.
• readR1cs

  const { readR1cs } = require('r1csfile');

  This is the CommonJS syntax shown in the official README for Node.js environments. Useful for older projects or specific module setups.
• R1CS
  wrong:

  import { R1CS } from 'r1csfile';

  correct:

  import type { R1CS } from 'r1csfile';

  Import the `R1CS` interface as a type for static analysis in TypeScript projects, as it represents the structure of the parsed R1CS object.

Quickstart

This quickstart demonstrates how to asynchronously read and parse an R1CS binary file using `readR1cs`, including basic error handling for file access and parsing issues. It logs key metadata from the parsed R1CS object, such as variable and constraint counts.

import { readR1cs } from 'r1csfile';
import { promises as fs } from 'fs';

async function parseR1CSFile(filePath: string) {
  try {
    // Ensure the R1CS file exists before attempting to read
    await fs.access(filePath);
    console.log(`Attempting to read R1CS file: ${filePath}`);

    const r1cs = await readR1cs(filePath);

    console.log('Successfully parsed R1CS file.');
    console.log(`Number of wires: ${r1cs.nVars}`);
    console.log(`Number of constraints: ${r1cs.nConstraints}`);
    console.log('R1CS structure (truncated):', {
      header: r1cs.header,
      nVars: r1cs.nVars,
      nConstraints: r1cs.nConstraints,
      // Further properties like `constraints` or `witness` can be very large.
      // For demonstration, we'll just log header info.
    });

    // Example: Accessing specific header fields
    if (r1cs.header.q instanceof Uint8Array) {
      console.log(`Field prime (q): 0x${Buffer.from(r1cs.header.q).toString('hex')}`);
    } else {
      console.log(`Field prime (q): ${r1cs.header.q}`);
    }

  } catch (error) {
    if (error instanceof Error) {
      console.error(`Error parsing R1CS file ${filePath}: ${error.message}`);
      if ((error as any).code === 'ENOENT') {
        console.error('File not found. Please ensure the path is correct.');
      }
    } else {
      console.error(`An unknown error occurred: ${error}`);
    }
    process.exit(1);
  }
}

// To run this, you would need an actual .r1cs file.
// For demonstration, let's assume 'example.r1cs' exists in the current directory.
// Replace 'example.r1cs' with your actual file path.
// If you don't have one, this will output a 'File not found' error.
parseR1CSFile('example.r1cs');