Add some documentation

This commit is contained in:
Ramana Kumar 2022-09-18 09:51:55 +01:00
parent 8cdc4e62e3
commit 25be720f62
No known key found for this signature in database
GPG Key ID: ED471C788B900433
2 changed files with 51 additions and 0 deletions

View File

@ -43,6 +43,15 @@ C_KZG_RET commit_to_poly(g1_t *out, const poly *p, const KZGSettings *ks) {
return C_KZG_OK;
}
/**
* Make a KZG commitment to a polynomial in Lagrange form.
*
* @param[out] out The commitment to the polynomial, in the form of a G1 group point
* @param[in] p_l The polynomial to be committed to
* @param[in] ks The settings containing the secrets, previously initialised with #new_kzg_settings
* @retval C_CZK_OK All is well
* @retval C_CZK_BADARGS Invalid parameters were supplied
*/
C_KZG_RET commit_to_poly_l(g1_t *out, const poly_l *p_l, const KZGSettings *ks) {
CHECK(p_l->length <= ks->length);
g1_linear_combination(out, ks->secret_g1_l, p_l->values, p_l->length);
@ -91,6 +100,18 @@ C_KZG_RET check_proof_single(bool *out, const g1_t *commitment, const g1_t *proo
return C_KZG_OK;
}
/**
* Compute KZG proof for evaluation of a polynomial in Lagrange form.
*
* @param[out] out The proof, in the form of a G1 point
* @param[in] p The polynomial
* @param[in] x0 The x-value the polynomial is to be proved at
* @param[in] y The y-value of the polynomial evaluation, which is assumed to be correct
* @param[in] ks The settings containing the secrets, previously initialised with #new_kzg_settings
* @retval C_CZK_OK All is well
* @retval C_CZK_ERROR An internal error occurred
* @retval C_CZK_MALLOC Memory allocation failed
*/
C_KZG_RET compute_proof_single_l(g1_t *out, const poly_l *p, const fr_t *x0, const fr_t *y, const KZGSettings *ks) {
fr_t tmp, tmp2;
poly_l q;

View File

@ -584,6 +584,16 @@ C_KZG_RET new_poly(poly *out, uint64_t length) {
return new_fr_array(&out->coeffs, length);
}
/**
* Initialise an empty polynomial in Lagrange form of the given size.
*
* @remark This allocates space for the Lagrange values that must be later reclaimed by calling #free_poly_l.
*
* @param[out] out The initialised polynomial structure
* @param[in] length The number of coefficients required, which is one more than the polynomial's degree
* @retval C_CZK_OK All is well
* @retval C_CZK_MALLOC Memory allocation failed
*/
C_KZG_RET new_poly_l(poly_l *out, uint64_t length) {
out->length = length;
return new_fr_array(&out->values, length);
@ -610,6 +620,18 @@ C_KZG_RET new_poly_with_coeffs(poly *out, const fr_t *coeffs, uint64_t length) {
return C_KZG_OK;
}
/**
* Initialise a polynomial in Lagrange form from the given polynomial in coefficient form.
*
* @remark This allocates space for the Lagrange values that must be later reclaimed by calling #free_poly_l.
*
* @param[out] out The initialised Lagrange polynomial structure
* @param[in] in The polynomial of which to compute the Lagrange form
* @param[in] ks The settings containing the roots of unity to use for DFT
* @retval C_CZK_OK All is well
* @retval C_CZK_BADARGS Invalid settings, e.g., fft max_width too low for this polynomial
* @retval C_CZK_MALLOC Memory allocation failed
*/
C_KZG_RET new_poly_l_from_poly(poly_l *out, const poly *in, const KZGSettings *ks) {
TRY(new_poly_l(out, ks->length));
if (out->length <= in->length) {
@ -645,6 +667,14 @@ void free_poly(poly *p) {
}
}
/**
* Reclaim the memory used by a polynomial in Lagrange form.
*
* @remark To avoid memory leaks, this must be called for polynomials initialised with #new_poly_l or
* #new_poly_l_from_poly after use.
*
* @param[in,out] p The polynomial
*/
void free_poly_l(poly_l *p) {
if (p->values != NULL) {
free(p->values);