From 9dc2611ac90c3ae4490203cc22a29507278d6442 Mon Sep 17 00:00:00 2001 From: Ben Edgington Date: Fri, 12 Feb 2021 19:49:43 +0000 Subject: [PATCH] Improve docs --- src/c_kzg.h | 2 +- src/fk20_proofs.c | 21 ++++++++++++++------- src/fk20_proofs_test.c | 29 +++++++++++++++++++++++++---- 3 files changed, 40 insertions(+), 12 deletions(-) diff --git a/src/c_kzg.h b/src/c_kzg.h index 8e257b1..a421cad 100644 --- a/src/c_kzg.h +++ b/src/c_kzg.h @@ -34,7 +34,7 @@ typedef enum { C_KZG_OK = 0, /**< Success! */ C_KZG_BADARGS, /**< The supplied data is invalid in some way */ - C_KZG_ERROR, /**< Internal error - this should never occur and indicates a bug in the library */ + C_KZG_ERROR, /**< Internal error - this should never occur and may indicate a bug in the library */ C_KZG_MALLOC, /**< Could not allocate memory */ } C_KZG_RET; diff --git a/src/fk20_proofs.c b/src/fk20_proofs.c index 8ab060a..d4bed20 100644 --- a/src/fk20_proofs.c +++ b/src/fk20_proofs.c @@ -197,7 +197,7 @@ C_KZG_RET toeplitz_part_3(blst_p1 *out, const blst_p1 *h_ext_fft, uint64_t n2, c /** * Reorder and extend polynomial coefficients for the toeplitz method. * - * @warning Allocates space for the return polynomial that needs to be freed by calling #free_poly. + * @remark Allocates space for the return polynomial that needs to be freed by calling #free_poly. * * @param[out] out The reordered polynomial, size `n * 2` * @param[in] in The input polynomial, size `n` @@ -226,6 +226,11 @@ C_KZG_RET toeplitz_coeffs_step(poly *out, const poly *in) { * The upper half of the polynomial coefficients is always 0, so we do not need to extend to twice the size * for Toeplitz matrix multiplication. * + * Simultaneously calculates all the KZG proofs for `x_i = w^i` (`0 <= i < 2n`), where `w` is a `(2 * n)`th root of + * unity. The `2n` comes from the polynomial being extended with zeros to twice the original size. + * + * `out[i]` is the proof for `y[i]`, the evaluation of the polynomial at `fs.expanded_roots_of_unity[i]`. + * * @param[out] out Array size `n * 2` * @param[in] p Polynomial, size `n` * @param[in] fk FK20 single settings previously initialised by #new_fk20_single_settings @@ -233,8 +238,6 @@ C_KZG_RET toeplitz_coeffs_step(poly *out, const poly *in) { * @retval C_CZK_BADARGS Invalid parameters were supplied * @retval C_CZK_ERROR An internal error occurred * @retval C_CZK_MALLOC Memory allocation failed - * - * @todo Better parameter descriptions */ C_KZG_RET fk20_single_da_opt(blst_p1 *out, const poly *p, FK20SingleSettings *fk) { uint64_t n = p->length, n2 = n * 2; @@ -263,16 +266,20 @@ C_KZG_RET fk20_single_da_opt(blst_p1 *out, const poly *p, FK20SingleSettings *fk } /** - * Data availability using FK20 single. + * Data availability using the FK20 single algorithm. * - * @param[out] out Array size `n * 2` + * Simultaneously calculates all the KZG proofs for `x_i = w^i` (`0 <= i < 2n`), where `w` is a `(2 * n)`th root of + * unity. The `2n` comes from the polynomial being extended with zeros to twice the original size. + * + * `out[reverse_bits_limited(2 * n, i)]` is the proof for `y[i]`, the evaluation of the polynomial at + * `fs.expanded_roots_of_unity[i]`. + * + * @param[out] out All the proofs, array length 2 * `n` * @param[in] p Polynomial, size `n` * @param[in] fk FK20 single settings previously initialised by #new_fk20_single_settings * @retval C_CZK_OK All is well * @retval C_CZK_BADARGS Invalid parameters were supplied * @retval C_CZK_ERROR An internal error occurred - * - * @todo Better parameter descriptions */ C_KZG_RET da_using_fk20_single(blst_p1 *out, const poly *p, FK20SingleSettings *fk) { uint64_t n = p->length, n2 = n * 2; diff --git a/src/fk20_proofs_test.c b/src/fk20_proofs_test.c index 17ec162..5a92479 100644 --- a/src/fk20_proofs_test.c +++ b/src/fk20_proofs_test.c @@ -123,11 +123,15 @@ void fk_single(void) { TEST_CHECK(C_KZG_OK == new_kzg_settings(&ks, s1, s2, secrets_len, &fs)); TEST_CHECK(C_KZG_OK == new_fk20_single_settings(&fk, 2 * poly_len, &ks)); - // Generate the proofs + // Commit to the polynomial commit_to_poly(&commitment, &p, &ks); + + // 1. First with `da_using_fk20_single` + + // Generate the proofs TEST_CHECK(da_using_fk20_single(all_proofs, &p, &fk) == C_KZG_OK); - // Verify the proof at each position + // Verify the proof at each root of unity for (uint64_t i = 0; i < 2 * poly_len; i++) { x = fs.expanded_roots_of_unity[i]; eval_poly(&y, &p, &x); @@ -137,6 +141,21 @@ void fk_single(void) { TEST_CHECK(true == result); } + // 2. Exactly the same thing again with `fk20_single_da_opt` + + // Generate the proofs + TEST_CHECK(fk20_single_da_opt(all_proofs, &p, &fk) == C_KZG_OK); + + // Verify the proof at each root of unity + for (uint64_t i = 0; i < 2 * poly_len; i++) { + x = fs.expanded_roots_of_unity[i]; + eval_poly(&y, &p, &x); + proof = all_proofs[i]; + + TEST_CHECK(C_KZG_OK == check_proof_single(&result, &commitment, &proof, &x, &y, &ks)); + TEST_CHECK(true == result); + } + // Clean up free_poly(&p); free_fft_settings(&fs); @@ -178,11 +197,13 @@ void fk_single_strided(void) { TEST_CHECK(C_KZG_OK == new_kzg_settings(&ks, s1, s2, secrets_len, &fs)); TEST_CHECK(C_KZG_OK == new_fk20_single_settings(&fk, 2 * poly_len, &ks)); - // Generate the proofs + // Commit to the polynomial commit_to_poly(&commitment, &p, &ks); + + // Generate the proofs TEST_CHECK(da_using_fk20_single(all_proofs, &p, &fk) == C_KZG_OK); - // Verify the proof at each position + // Verify the proof at each root of unity for (uint64_t i = 0; i < 2 * poly_len; i++) { x = fs.expanded_roots_of_unity[i * stride]; eval_poly(&y, &p, &x);