From b3d654a052533271b47bfa6b9952c2934dae8c0c Mon Sep 17 00:00:00 2001 From: kevaundray Date: Fri, 16 Aug 2024 02:51:05 +0100 Subject: [PATCH] Add redundant java docs (#231) --- .../ethereum/cryptography/CellsAndProofs.java | 122 +++++++++++------- .../java/ethereum/cryptography/LibEthKZG.java | 47 ++++++- 2 files changed, 122 insertions(+), 47 deletions(-) diff --git a/bindings/java/java_code/src/main/java/ethereum/cryptography/CellsAndProofs.java b/bindings/java/java_code/src/main/java/ethereum/cryptography/CellsAndProofs.java index 7515a74c..e97ed78d 100644 --- a/bindings/java/java_code/src/main/java/ethereum/cryptography/CellsAndProofs.java +++ b/bindings/java/java_code/src/main/java/ethereum/cryptography/CellsAndProofs.java @@ -1,65 +1,95 @@ package ethereum.cryptography; + import java.nio.ByteBuffer; import java.util.Arrays; +/** + * Represents a pair of cells and their corresponding proofs in KZG + * cryptography. + */ public class CellsAndProofs { + + /** The array of cells. */ public byte[][] cells; + + /** The array of proofs corresponding to the cells. */ public byte[][] proofs; + /** + * Constructs a CellsAndProofs object with the given cells and proofs. + * + * @param cells The array of cells. + * @param proofs The array of proofs corresponding to the cells. + */ public CellsAndProofs(byte[][] cells, byte[][] proofs) { this.cells = cells; this.proofs = proofs; } + /** + * Gets the array of cells. + * + * @return The array of cells. + */ + public byte[][] getCells() { + return cells; + } - public byte[][] getCells() { - return cells; - } - - public byte[][] getProofs() { - return proofs; - } - - public static CellsAndProofs of(final byte[][] cells, final byte[][] proofs) { - return new CellsAndProofs(cells, proofs); - } - - public byte[] toBytes() { - int cellsLength = Arrays.stream(cells).mapToInt(cell -> cell.length).sum(); - int proofsLength = Arrays.stream(proofs).mapToInt(proof -> proof.length).sum(); - int totalLength = cellsLength + proofsLength; - - ByteBuffer buffer = ByteBuffer.allocate(totalLength); - - // Flatten cells - Arrays.stream(cells).forEach(buffer::put); - - // Flatten proofs - Arrays.stream(proofs).forEach(buffer::put); - - return buffer.array(); - } + /** + * Gets the array of proofs. + * + * @return The array of proofs. + */ + public byte[][] getProofs() { + return proofs; + } - @Override - public int hashCode() { - int prime = 31; - int result = 1; + /** + * Creates a new CellsAndProofs object with the given cells and proofs. + * + * @param cells The array of cells. + * @param proofs The array of proofs corresponding to the cells. + * @return A new CellsAndProofs object. + */ + public static CellsAndProofs of(final byte[][] cells, final byte[][] proofs) { + return new CellsAndProofs(cells, proofs); + } - result = prime * result + Arrays.deepHashCode(cells); - result = prime * result + Arrays.deepHashCode(proofs); + /** + * Converts the cells and proofs to a single byte array. + * + * @return A byte array containing all cells followed by all proofs. + */ + public byte[] toBytes() { + int cellsLength = Arrays.stream(cells).mapToInt(cell -> cell.length).sum(); + int proofsLength = Arrays.stream(proofs).mapToInt(proof -> proof.length).sum(); + int totalLength = cellsLength + proofsLength; + ByteBuffer buffer = ByteBuffer.allocate(totalLength); + // Flatten cells + Arrays.stream(cells).forEach(buffer::put); + // Flatten proofs + Arrays.stream(proofs).forEach(buffer::put); + return buffer.array(); + } - return result; - } + @Override + public int hashCode() { + int prime = 31; + int result = 1; + result = prime * result + Arrays.deepHashCode(cells); + result = prime * result + Arrays.deepHashCode(proofs); + return result; + } - @Override - public boolean equals(Object obj) { - if (this == obj) { - return true; - } - if (obj == null || getClass() != obj.getClass()) { - return false; - } - CellsAndProofs other = (CellsAndProofs) obj; - return Arrays.deepEquals(cells, other.cells) && Arrays.deepEquals(proofs, other.proofs); - } + @Override + public boolean equals(Object obj) { + if (this == obj) { + return true; + } + if (obj == null || getClass() != obj.getClass()) { + return false; + } + CellsAndProofs other = (CellsAndProofs) obj; + return Arrays.deepEquals(cells, other.cells) && Arrays.deepEquals(proofs, other.proofs); + } } \ No newline at end of file diff --git a/bindings/java/java_code/src/main/java/ethereum/cryptography/LibEthKZG.java b/bindings/java/java_code/src/main/java/ethereum/cryptography/LibEthKZG.java index 8829a95b..8b431a02 100644 --- a/bindings/java/java_code/src/main/java/ethereum/cryptography/LibEthKZG.java +++ b/bindings/java/java_code/src/main/java/ethereum/cryptography/LibEthKZG.java @@ -6,6 +6,10 @@ import java.nio.file.Path; import java.nio.file.StandardCopyOption; +/** + * This class handles the loading of native libraries and provides methods for + * Ethereum's DAS related cryptography. + */ public class LibEthKZG implements AutoCloseable{ /** The number of bytes in a KZG commitment. */ public static final int BYTES_PER_COMMITMENT = 48; @@ -25,7 +29,10 @@ public class LibEthKZG implements AutoCloseable{ private static volatile boolean libraryLoaded = false; private static final Object libraryLock = new Object(); - + /** + * Constructs a LibEthKZG instance with default parameters. + * Uses pre-computation and a single thread. + */ public LibEthKZG() { ensureLibraryLoaded(); boolean usePrecomp = true; @@ -33,6 +40,12 @@ public LibEthKZG() { this.contextPtr = DASContextNew(usePrecomp, numThreads); } + /** + * Constructs a LibEthKZG instance with specified parameters. + * + * @param usePrecomp Whether to use pre-computation. + * @param numThreads Number of threads to use. + */ public LibEthKZG(boolean usePrecomp, long numThreads) { ensureLibraryLoaded(); this.contextPtr = DASContextNew(usePrecomp, numThreads); @@ -54,6 +67,10 @@ public void close() { destroy(); } + /** + * Destroys the KZG context and frees associated resources. + * This method should be called when the LibEthKZG instance is no longer needed. + */ public void destroy() { if (contextPtr != 0) { DASContextDestroy(contextPtr); @@ -67,23 +84,51 @@ private void checkContextHasNotBeenFreed() { } } + /** + * Computes the KZG commitment for a given blob. + * + * @param blob The input blob. + * @return The KZG commitment as a byte array. + */ public byte[] blobToKZGCommitment(byte[] blob) { checkContextHasNotBeenFreed(); return blobToKZGCommitment(contextPtr, blob); } + /** + * Computes cells and KZG proofs for a given blob. + * + * @param blob The input blob. + * @return CellsAndProofs object containing the computed cells and proofs. + */ public CellsAndProofs computeCellsAndKZGProofs(byte[] blob) { checkContextHasNotBeenFreed(); CellsAndProofs cellsAndProofs = computeCellsAndKZGProofs(contextPtr, blob); return cellsAndProofs; } + /** + * Verifies a batch of cell KZG proofs. + * + * @param commitmentsArr Array of commitments. + * @param cellIndices Array of cell indices. + * @param cellsArr Array of cells. + * @param proofsArr Array of proofs. + * @return true if the batch verification succeeds, false otherwise. + */ public boolean verifyCellKZGProofBatch(byte[][] commitmentsArr, long[] cellIndices, byte[][] cellsArr, byte[][] proofsArr) { checkContextHasNotBeenFreed(); return verifyCellKZGProofBatch(contextPtr, commitmentsArr, cellIndices, cellsArr, proofsArr); } + /** + * Recovers cells and computes KZG proofs from given cell IDs and cells. + * + * @param cellIDs Array of cell IDs. + * @param cellsArr Array of cells. + * @return CellsAndProofs object containing the recovered cells and proofs. + */ public CellsAndProofs recoverCellsAndProofs(long[] cellIDs, byte[][] cellsArr) { checkContextHasNotBeenFreed(); return recoverCellsAndProof(contextPtr, cellIDs, cellsArr);