Update node README (#228)

bindings/node.js/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contribution Guidelines
+
+Thanks for your interest in contributing to the Node.js bindings for
+c-kzg-4844.
+
+## Prerequisites
+
+- [NodeJS](https://nodejs.org/) (LTS)
+- [Yarn](https://yarnpkg.com/)
+
+## Setup
+
+Open a terminal and navigate to the root of the `c-kzg-4844` repo and run the
+following commands if you have not already done so:
+
+```sh
+git submodule update --init # Install the blst submodule
+cd src
+make blst # Build blst
+cd ../bindings/node.js
+yarn install --ignore-scripts # Install dependencies
+make # Build bindings and verify build worked
+```
+
+## Project Commands
+
+* `make clean` - cleans artifacts
+* `make build` - prepares assets and builds bindings
+* `make test` - runs unit tests
+* `make format` - lints code
+* `make bundle` - builds `dist` for publishing
+* `make publish` - runs `npm publish`
+
+## `n-api` and `node-addon-api`
+
+There are two different flavors of abi-stable node addons.
+[n-api](https://nodejs.org/api/n-api.html) is the `C` api that is natively
+exported by `node.js`.  There is also a header-only `C++` implementation of the
+`n-api` called [node-addon-api](https://github.com/nodejs/node-addon-api).
+There is mixed usage of the two in this library.
+
+The addon was built to be
+[context-aware](https://nodejs.github.io/node-addon-examples/special-topics/context-awareness/)
+so it will be safe to run on a worker thread.  Be sure not to use any
+static/global variables as those are not thread safe.

bindings/node.js/README.md

@@ -1,93 +1,171 @@
-This package wraps the c-kzg C code in C++ NAPI bindings which allow it to be imported into a NodeJS program.
+# C-KZG-4844
+
+This is a TypeScript library for EIP-4844 that implements the [Polynomial
+Commitments](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/polynomial-commitments.md)
+API. The core functionality was originally a stripped-down copy of
+[C-KZG](https://github.com/benjaminion/c-kzg), but has been heavily modified
+since then. This package wraps that native `c-kzg` C code in C/C++ NAPI
+bindings for use in node.js applications.
 
 Spec: https://github.com/ethereum/consensus-specs/blob/dev/specs/eip4844/polynomial-commitments.md
 
-# Usage
+## Prerequisites
 
-Install this library with
+Installation requires compilation of C code. Target environment must have:
+
+- A compiler like g++ or clang
+- [`make`](https://www.gnu.org/software/make/manual/make.html)
+- [`python3`](https://docs.python.org/3/)
+
+## Installation
 
 ```sh
 yarn add c-kzg
+# or
+npm i -S c-kzg
 ```
 
-Import from it like any other library
+## Usage
 
-```js
+```ts
 import {
-  KZGCommitment,
+  BYTES_PER_BLOB,
+  Blob,
+  Bytes48,
   blobToKzgCommitment,
-  verifyAggregateKzgProof,
+  computeBlobKzgProof,
-  loadTrustedSetup,
+  verifyBlobKzgProofBatch,
-  transformTrustedSetupJSON,
 } from "c-kzg";
+
+const blobs = [] as Blob[];
+const commitments = [] as Bytes48[];
+const proofs = [] as Bytes48[];
+
+for (let i = 0; i < BATCH_SIZE; i++) {
+  blobs.push(Buffer.alloc(BYTES_PER_BLOB, "*"));
+  commitments.push(blobToKzgCommitment(blobs[i]));
+  proofs.push(computeBlobKzgProof(blobs[i], commitments[i]));
+}
+
+const isValid = verifyBlobKzgProofBatch(blobs, commitments, proofs);
 ```
 
-# Requirements
+## API
 
-The C and C++ code is compiled by node-gyp on installation. Your environment will need
+### `loadTrustedSetup`
 
-- A compiler like g++ or clang
+```ts
-- `make`
+/**
-- `python3`
+ * Sets up the c-kzg library. Pass in a properly formatted trusted setup file
-
+ * to configure the library.  File must be in json format, see TrustedSetupJson
-# Contributing
+ * interface for more details, or as a properly formatted utf-8 encoded file.
-
+ *
-This directory contains the code necessary to generate NodeJS bindings for C-KZG.
+ * @remark This function must be run before any other functions in this
-
+ *         library can be run.
-The bindings file has the following interface:
+ *
-
+ * @param {string} filePath - The absolute path of the trusted setup
-```js
+ */
-
+loadTrustedSetup(filePath: string): void;
-  loadTrustedSetup: (filePath: string) => SetupHandle;
-
-  freeTrustedSetup: (setupHandle: SetupHandle) => void;
-
-  blobToKzgCommitment: (blob: Blob, setupHandle: SetupHandle) => KZGCommitment;
-
-  computeAggregateKzgProof: (
-    blobs: Blob[],
-    setupHandle: SetupHandle
-  ) => KZGProof;
-
-  verifyAggregateKzgProof: (
-    blobs: Blob[],
-    expectedKzgCommitments: KZGCommitment[],
-    kzgAggregatedProof: KZGProof,
-    setupHandle: SetupHandle
-  ) => boolean;
 ```
 
-But this library wraps it in module with manages the setupHandle internally.
+### `blobToKzgCommitment`
 
-First,
+```ts
-`npm install -g yarn` if you don't have it.
+/**
-
+ * Convert a blob to a KZG commitment.
-Install the blst submodule
+ *
-
+ * @param {Blob} blob - The blob representing the polynomial to be committed to
-```sh
+ */
-git submodule update --init
+blobToKzgCommitment(blob: Blob): KZGCommitment;
 ```
 
-Build blst and c_kzg_4844.c
+### `computeKzgProof`
 
-```
+```ts
-cd src && make blst lib
+/**
+ * Compute KZG proof for polynomial in Lagrange form at position z.
+ *
+ * @param {Blob}    blob - The blob (polynomial) to generate a proof for
+ * @param {Bytes32} zBytes - The generator z-value for the evaluation points
+ *
+ * @return {ProofResult} - Tuple containing the resulting proof and evaluation
+ *                         of the polynomial at the evaluation point z
+ */
+computeKzgProof(blob: Blob, zBytes: Bytes32): ProofResult;
 ```
 
-Generate NodeJS bindings and run the TypeScript tests against them
+### `computeBlobKzgProof`
 
-```sh
+```ts
-cd ../bindings/node.js && yarn install && make test
+/**
+ * Given a blob, return the KZG proof that is used to verify it against the
+ * commitment.
+ *
+ * @param {Blob}    blob - The blob (polynomial) to generate a proof for
+ * @param {Bytes48} commitmentBytes - Commitment to verify
+ */
+computeBlobKzgProof(
+  blob: Blob,
+  commitmentBytes: Bytes48,
+): KZGProof;
 ```
 
-After doing this once, you can re-build (if necessary) and re-run the tests with
+### `verifyKzgProof`
 
-```sh
+```ts
-make build test
+/**
+ * Verify a KZG poof claiming that `p(z) == y`.
+ *
+ * @param {Bytes48} commitmentBytes - The serialized commitment corresponding to
+ *                                    polynomial p(x)
+ * @param {Bytes32} zBytes - The serialized evaluation point
+ * @param {Bytes32} yBytes - The serialized claimed evaluation result
+ * @param {Bytes48} proofBytes - The serialized KZG proof
+ */
+verifyKzgProof(
+  commitmentBytes: Bytes48,
+  zBytes: Bytes32,
+  yBytes: Bytes32,
+  proofBytes: Bytes48,
+): boolean;
 ```
 
-After making changes, regenerate the distributable JS and type defs
+### `verifyBlobKzgProof`
 
-```sh
+```ts
-make bundle
+/**
+ * Given a blob and its proof, verify that it corresponds to the provided
+ * commitment.
+ *
+ * @param {Blob}    blob - The serialized blob to verify
+ * @param {Bytes48} commitmentBytes - The serialized commitment to verify
+ * @param {Bytes48} proofBytes - The serialized KZG proof for verification
+ */
+verifyBlobKzgProof(
+  blob: Blob,
+  commitmentBytes: Bytes48,
+  proofBytes: Bytes48,
+): boolean;
+```
+
+### `verifyBlobKzgProofBatch`
+
+```ts
+/**
+ * Given an array of blobs and their proofs, verify that they corresponds to
+ * their provided commitment.
+ *
+ * Note: blobs[0] relates to commitmentBytes[0] and proofBytes[0]
+ *
+ * @param {Blob}    blobs - An array of serialized blobs to verify
+ * @param {Bytes48} commitmentBytes - An array of serialized commitments to
+ *                                    verify
+ * @param {Bytes48} proofBytes - An array of serialized KZG proofs for
+ *                               verification
+ */
+verifyBlobKzgProofBatch(
+  blobs: Blob[],
+  commitmentsBytes: Bytes48[],
+  proofsBytes: Bytes48[],
+): boolean;
 ```

bindings/node.js/lib/kzg.ts

@@ -89,7 +89,7 @@ function transformTrustedSetupJson(filePath: string): string {
 
 /**
  * Sets up the c-kzg library. Pass in a properly formatted trusted setup file
- * to configure the library.  File must be in json format, see or {@link TrustedSetupJson}
+ * to configure the library.  File must be in json format, see {@link TrustedSetupJson}
  * interface for more details, or as a properly formatted utf-8 encoded file.
  *
  * @remark This function must be run before any other functions in this