@aztec-labs/blob-lib 6.0.0-nightly.20260829

package/dest/testing.d.ts

@@ -0,0 +1,31 @@
+import { Blob } from './blob.js';
+import { BlobAccumulator } from './circuit_types/blob_accumulator.js';
+import { FinalBlobAccumulator } from './circuit_types/final_blob_accumulator.js';
+import { FinalBlobBatchingChallenges } from './circuit_types/final_blob_batching_challenges.js';
+import { SpongeBlob } from './sponge_blob.js';
+export * from './encoding/fixtures.js';
+/**
+ * Makes arbitrary poseidon sponge for blob inputs.
+ * Note: will not verify inside the circuit.
+ * @param seed - The seed to use for generating the sponge.
+ * @returns A sponge blob instance.
+ */
+export declare function makeSpongeBlob(seed?: number): SpongeBlob;
+/**
+ * Makes arbitrary blob public accumulator.
+ * Note: will not verify inside the circuit.
+ * @param seed - The seed to use for generating the blob accumulator.
+ * @returns A blob accumulator instance.
+ */
+export declare function makeBlobAccumulator(seed?: number): BlobAccumulator;
+export declare function makeFinalBlobAccumulator(seed?: number): FinalBlobAccumulator;
+export declare function makeFinalBlobBatchingChallenges(seed?: number): FinalBlobBatchingChallenges;
+/**
+ * Make a blob with random fields.
+ *
+ * This will fail deserialisation in the archiver
+ * @param length
+ * @returns
+ */
+export declare function makeRandomBlob(length: number): Promise<Blob>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdGluZy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3Rlc3RpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBSUEsT0FBTyxFQUFFLElBQUksRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUNqQyxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0scUNBQXFDLENBQUM7QUFDdEUsT0FBTyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sMkNBQTJDLENBQUM7QUFDakYsT0FBTyxFQUFFLDJCQUEyQixFQUFFLE1BQU0sbURBQW1ELENBQUM7QUFDaEcsT0FBTyxFQUFtQixVQUFVLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUUvRCxjQUFjLHdCQUF3QixDQUFDO0FBRXZDOzs7OztHQUtHO0FBQ0gsd0JBQWdCLGNBQWMsQ0FBQyxJQUFJLFNBQUksR0FBRyxVQUFVLENBVW5EO0FBMEJEOzs7OztHQUtHO0FBQ0gsd0JBQWdCLG1CQUFtQixDQUFDLElBQUksU0FBSSxHQUFHLGVBQWUsQ0FTN0Q7QUFFRCx3QkFBZ0Isd0JBQXdCLENBQUMsSUFBSSxTQUFJLHdCQU9oRDtBQUVELHdCQUFnQiwrQkFBK0IsQ0FBQyxJQUFJLFNBQUksK0JBRXZEO0FBRUQ7Ozs7OztHQU1HO0FBQ0gsd0JBQWdCLGNBQWMsQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFNUQifQ==

package/dest/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,mDAAmD,CAAC;AAChG,OAAO,EAAmB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE/D,cAAc,wBAAwB,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAI,GAAG,UAAU,CAUnD;AA0BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAI,GAAG,eAAe,CAS7D;AAED,wBAAgB,wBAAwB,CAAC,IAAI,SAAI,wBAOhD;AAED,wBAAgB,+BAA+B,CAAC,IAAI,SAAI,+BAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D"}

package/dest/testing.js

@@ -0,0 +1,66 @@
+import { makeTuple } from '@aztec-labs/foundation/array';
+import { BLS12Fq, BLS12Fr, BLS12Point, BLSPointNotOnCurveError } from '@aztec-labs/foundation/curves/bls12';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { Blob } from './blob.js';
+import { BlobAccumulator } from './circuit_types/blob_accumulator.js';
+import { FinalBlobAccumulator } from './circuit_types/final_blob_accumulator.js';
+import { FinalBlobBatchingChallenges } from './circuit_types/final_blob_batching_challenges.js';
+import { Poseidon2Sponge, SpongeBlob } from './sponge_blob.js';
+export * from './encoding/fixtures.js';
+/**
+ * Makes arbitrary poseidon sponge for blob inputs.
+ * Note: will not verify inside the circuit.
+ * @param seed - The seed to use for generating the sponge.
+ * @returns A sponge blob instance.
+ */ export function makeSpongeBlob(seed = 1) {
+    return new SpongeBlob(new Poseidon2Sponge(makeTuple(3, (i)=>new Fr(i)), makeTuple(4, (i)=>new Fr(i)), 1, false), seed);
+}
+/**
+ * Makes an arbitrary but valid BLS12 point. The value is deterministic for a given seed.
+ * @param seed - The seed to use for generating the point.
+ * @returns A BLS12 point instance.
+ */ function makeBLS12Point(seed = 1) {
+    let accum = 0;
+    while(true){
+        try {
+            const x = new BLS12Fq(seed + accum);
+            const y = BLS12Point.YFromX(x);
+            if (y) {
+                return new BLS12Point(x, y, false);
+            }
+            accum++;
+        } catch (e) {
+            if (!(e instanceof BLSPointNotOnCurveError)) {
+                throw e;
+            }
+        // The point is not on the curve - try again
+        }
+    }
+}
+/**
+ * Makes arbitrary blob public accumulator.
+ * Note: will not verify inside the circuit.
+ * @param seed - The seed to use for generating the blob accumulator.
+ * @returns A blob accumulator instance.
+ */ export function makeBlobAccumulator(seed = 1) {
+    return new BlobAccumulator(new Fr(seed), new Fr(seed + 0x10), new BLS12Fr(seed + 0x20), makeBLS12Point(seed + 0x30), new Fr(seed + 0x50), new BLS12Fr(seed + 0x60));
+}
+export function makeFinalBlobAccumulator(seed = 1) {
+    return new FinalBlobAccumulator(new Fr(seed), new Fr(seed + 0x10), new BLS12Fr(seed + 0x20), makeBLS12Point(seed + 0x30));
+}
+export function makeFinalBlobBatchingChallenges(seed = 1) {
+    return new FinalBlobBatchingChallenges(new Fr(seed), new BLS12Fr(seed + 0x10));
+}
+/**
+ * Make a blob with random fields.
+ *
+ * This will fail deserialisation in the archiver
+ * @param length
+ * @returns
+ */ export function makeRandomBlob(length) {
+    return Blob.fromFields([
+        ...Array.from({
+            length: length
+        }, ()=>Fr.random())
+    ]);
+}

package/dest/types.d.ts

@@ -0,0 +1,17 @@
+export * from './batched_blob.js';
+export * from './circuit_types/index.js';
+export * from './interface.js';
+export * from './sponge_blob.js';
+/**
+ * Type definition for the KZG instance returned by Blob.getViemKzgInstance().
+ * Contains the cryptographic functions needed for blob commitment and proof generation.
+ */
+export interface BlobKzgInstance {
+    /** Function to compute KZG commitment from blob data */
+    blobToKzgCommitment(blob: Uint8Array): Uint8Array;
+    /** Function to compute KZG proof for blob data */
+    computeBlobKzgProof(blob: Uint8Array, commitment: Uint8Array): Uint8Array;
+    /** Function to compute both blob data cells and their corresponding KZG proofs for EIP7594 */
+    computeCellsAndKzgProofs(blob: Uint8Array): [Uint8Array[], Uint8Array[]];
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBRWpDOzs7R0FHRztBQUNILE1BQU0sV0FBVyxlQUFlO0lBQzlCLHdEQUF3RDtJQUN4RCxtQkFBbUIsQ0FBQyxJQUFJLEVBQUUsVUFBVSxHQUFHLFVBQVUsQ0FBQztJQUNsRCxrREFBa0Q7SUFDbEQsbUJBQW1CLENBQUMsSUFBSSxFQUFFLFVBQVUsRUFBRSxVQUFVLEVBQUUsVUFBVSxHQUFHLFVBQVUsQ0FBQztJQUMxRSw4RkFBOEY7SUFDOUYsd0JBQXdCLENBQUMsSUFBSSxFQUFFLFVBQVUsR0FBRyxDQUFDLFVBQVUsRUFBRSxFQUFFLFVBQVUsRUFBRSxDQUFDLENBQUM7Q0FDMUUifQ==

package/dest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAEjC;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAClD,kDAAkD;IAClD,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;IAC1E,8FAA8F;IAC9F,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;CAC1E"}

package/dest/types.js

@@ -0,0 +1,4 @@
+export * from './batched_blob.js';
+export * from './circuit_types/index.js';
+export * from './interface.js';
+export * from './sponge_blob.js';

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@aztec-labs/blob-lib",
+  "version": "6.0.0-nightly.20260829",
+  "type": "module",
+  "exports": {
+    ".": "./dest/index.js",
+    "./encoding": "./dest/encoding/index.js",
+    "./types": "./dest/types.js",
+    "./testing": "./dest/testing.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/index.ts"
+    ],
+    "name": "Blob Lib",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "start:dev": "concurrently -k \"../scripts/tsc.sh --watch\" \"nodemon --watch dest --exec yarn start\"",
+    "start": "node ./dest/index.js",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "dependencies": {
+    "@aztec-labs/constants": "6.0.0-nightly.20260829",
+    "@aztec-labs/foundation": "6.0.0-nightly.20260829",
+    "@crate-crypto/node-eth-kzg": "^0.10.0",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.15.17",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "get-port": "^7.1.0",
+    "jest": "^30.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs",
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
+    ]
+  },
+  "engines": {
+    "node": ">=20.10"
+  }
+}

package/src/batched_blob.ts

@@ -0,0 +1,26 @@
+import { BLS12Fr, BLS12Point } from '@aztec-labs/foundation/curves/bls12';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import { FinalBlobAccumulator } from './circuit_types/index.js';
+
+/**
+ * A class to represent the result from accumulating blobs in an epoch using BatchedBlobAccumulator.
+ */
+export class BatchedBlob {
+  constructor(
+    /** Hash of Cs (to link to L1 blob hashes). */
+    public readonly blobCommitmentsHash: Fr,
+    /** Challenge point z such that p_i(z) = y_i. */
+    public readonly z: Fr,
+    /** Evaluation y, linear combination of all evaluations y_i = p_i(z) with gamma. */
+    public readonly y: BLS12Fr,
+    /** Commitment C, linear combination of all commitments C_i = [p_i] with gamma. */
+    public readonly commitment: BLS12Point,
+    /** KZG opening 'proof' Q (commitment to the quotient poly.), linear combination of all blob kzg 'proofs' Q_i with gamma. */
+    public readonly q: BLS12Point,
+  ) {}
+
+  toFinalBlobAccumulator() {
+    return new FinalBlobAccumulator(this.blobCommitmentsHash, this.z, this.y, this.commitment);
+  }
+}

package/src/blob.ts

@@ -0,0 +1,191 @@
+import { FIELDS_PER_BLOB } from '@aztec-labs/constants';
+import { BLS12Fr } from '@aztec-labs/foundation/curves/bls12';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+
+import { computeBlobCommitment, computeChallengeZ, computeEthVersionedBlobHash } from './hash.js';
+import type { BlobJson } from './interface.js';
+import { getBytesPerBlob, getBytesPerCommitment, getKzg } from './kzg_context.js';
+
+export { FIELDS_PER_BLOB };
+
+/**
+ * A class to create, manage, and prove EVM blobs.
+ *
+ * @dev Note: All methods in this class do not check the encoding of the given data. It's the responsibility of other
+ * components to ensure that the blob data (which might spread across multiple blobs) was created following the protocol
+ * and is correctly encoded.
+ */
+export class Blob {
+  constructor(
+    /**
+     * The data to be broadcast on L1 in bytes form.
+     */
+    public readonly data: Uint8Array,
+    /**
+     * Commitment to the blob data. Used in compressed BLS12 point format (48 bytes).
+     */
+    public readonly commitment: Buffer,
+  ) {
+    if (data.length !== getBytesPerBlob()) {
+      throw new Error(`Blob data must be ${getBytesPerBlob()} bytes. Got ${data.length}.`);
+    }
+    if (commitment.length !== getBytesPerCommitment()) {
+      throw new Error(`Blob commitment must be ${getBytesPerCommitment()} bytes. Got ${commitment.length}.`);
+    }
+  }
+
+  /**
+   * Create a Blob from a buffer.
+   * @param data - The buffer of the Blob.
+   * @returns A Blob created from the buffer.
+   *
+   * @throws If data does not match the expected length (getBytesPerBlob()).
+   */
+  static async fromBlobBuffer(data: Uint8Array): Promise<Blob> {
+    const commitment = await computeBlobCommitment(data);
+    return new Blob(data, commitment);
+  }
+
+  /**
+   * Create a Blob from an array of fields.
+   *
+   * @dev This method pads 0s to the data, extending it to the size of a full blob.
+   *
+   * @param fields - The array of fields to create the Blob from.
+   * @returns A Blob created from the array of fields.
+   */
+  static async fromFields(fields: Fr[]): Promise<Blob> {
+    if (fields.length > FIELDS_PER_BLOB) {
+      throw new Error(`Attempted to overfill blob with ${fields.length} fields. The maximum is ${FIELDS_PER_BLOB}.`);
+    }
+
+    const data = Buffer.concat([serializeToBuffer(fields)], getBytesPerBlob());
+    const commitment = await computeBlobCommitment(data);
+    return new Blob(data, commitment);
+  }
+
+  /**
+   * Get the fields from the blob data.
+   *
+   * @dev WARNING: this method returns all fields
+   *
+   * @returns The fields from the blob.
+   */
+  toFields(): Fr[] {
+    const reader = BufferReader.asReader(this.data);
+    const numTotalFields = this.data.length / Fr.SIZE_IN_BYTES;
+    return reader.readArray(numTotalFields, Fr);
+  }
+
+  /**
+   * Create a Blob from a JSON object.
+   *
+   * Blobs will be in this form when requested from the blob client, or from
+   * the beacon chain via `getBlobSidecars`
+   * https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getBlobSidecars
+   *
+   * @param json - The JSON object to create the Blob from.
+   * @returns A Blob created from the JSON object.
+   */
+  static async fromJson(json: BlobJson): Promise<Blob> {
+    const blobBuffer = Buffer.from(json.blob.slice(2), 'hex');
+    const blob = await Blob.fromBlobBuffer(blobBuffer);
+
+    if (blob.commitment.toString('hex') !== json.kzg_commitment.slice(2)) {
+      throw new Error('KZG commitment does not match');
+    }
+
+    return blob;
+  }
+
+  /**
+   * Get the JSON representation of the blob.
+   *
+   * @returns The JSON representation of the blob.
+   */
+  toJSON(): BlobJson {
+    return {
+      blob: `0x${Buffer.from(this.data).toString('hex')}`,
+      // eslint-disable-next-line camelcase
+      kzg_commitment: `0x${this.commitment.toString('hex')}`,
+    };
+  }
+
+  getEthVersionedBlobHash(): Buffer {
+    return computeEthVersionedBlobHash(this.commitment);
+  }
+
+  /**
+   * Challenge point z (= H(H(tx_effects), kzgCommitment)).
+   * Used such that p(z) = y for a single blob, used as z_i in batching (see ./blob_batching.ts).
+   */
+  async computeChallengeZ(blobFieldsHash: Fr): Promise<Fr> {
+    return await computeChallengeZ(blobFieldsHash, this.commitment);
+  }
+
+  /**
+   * Evaluate the blob at a given challenge and return the evaluation and KZG proof.
+   *
+   * @param challengeZ - The challenge z at which to evaluate the blob.
+   * @param verifyProof - Whether to verify the KZG proof.
+   *
+   * @returns
+   *  y: BLS12Fr -  Evaluation y = p(z), where p() is the blob polynomial. BLS12 field element, rep. as BigNum in nr, bigint in ts.
+   *  proof: Buffer - KZG opening proof for y = p(z). The commitment to quotient polynomial Q, used in compressed BLS12 point format (48 bytes).
+   */
+  async evaluate(challengeZ: Fr, verifyProof = false) {
+    const kzg = getKzg();
+    const res = await kzg.asyncComputeKzgProof(this.data, challengeZ.toBuffer());
+    if (verifyProof && !kzg.verifyKzgProof(this.commitment, challengeZ.toBuffer(), res[1], res[0])) {
+      throw new Error(`KZG proof did not verify.`);
+    }
+
+    const proof = Buffer.from(res[0]);
+    const y = BLS12Fr.fromBuffer(Buffer.from(res[1]));
+    return { y, proof };
+  }
+
+  /**
+   * Get the buffer representation of the ENTIRE blob.
+   *
+   * @dev WARNING: this buffer contains all metadata as well as the data itself.
+   *
+   * @returns The buffer representation of the blob.
+   */
+  toBuffer(): Buffer {
+    return Buffer.from(serializeToBuffer(this.data.length, this.data, this.commitment.length, this.commitment));
+  }
+
+  /**
+   * Create a Blob from a buffer.
+   *
+   * @dev WARNING: this method contains all metadata as well as the data itself.
+   *
+   * @param buf - The buffer to create the Blob from.
+   * @returns A Blob created from the buffer.
+   */
+  static fromBuffer(buf: Buffer | BufferReader): Blob {
+    const reader = BufferReader.asReader(buf);
+    return new Blob(reader.readUint8Array(), reader.readBuffer());
+  }
+
+  /**
+   * Get the size of the blob in bytes
+   */
+  getSize() {
+    return this.data.length;
+  }
+
+  static getViemKzgInstance() {
+    const kzg = getKzg();
+    return {
+      blobToKzgCommitment: kzg.blobToKzgCommitment.bind(kzg),
+      computeBlobKzgProof: kzg.computeBlobKzgProof.bind(kzg),
+      computeCellsAndKzgProofs: (b: Uint8Array): [Uint8Array[], Uint8Array[]] => {
+        const result = kzg.computeCellsAndKzgProofs(b);
+        return [result.cells, result.proofs];
+      },
+    };
+  }
+}