KZG for Ruby

A library for KZG commitment over BLS12-381 in Ruby.

Note: This library has not been security audited and tested widely, so should not be used in production.

Installation

Add this line to your application's Gemfile:

gem 'kzg'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install kzg

Usage

Setup

The first step is to generate public parameters via Trusted Setup. The following method specifies the secret value for development purposes, but essentially you need to create these parameters in a way that nobody knows the secret.

KZG.setup_params takes the secret value and the maximum degree + 1 of the polynomial to be generated as input and outputs the public parameters. The public parameters consist of an array of point in BLS::PointG1 and BLS::PointG2.

require 'kzg'

secret = xxx # secret number
n = 10
setting = KZG.setup_params(secret, n)

The above public parameters can support up to a polynomial of degree 9.

Commitment

With a public parameter, a commitment to a polynomial can be made.

KZG::Commitment#from_coeffs creates the corresponding polynomial commitment from the public parameters and the coefficients of the polynomial.

coefficients = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
commitment = KZG::Commitment.from_coeffs(setting, coefficients)
commitment.value

KZG::Commitment#value returns the committed value, i.e. the point in the BLS::PointG1.

The committer can compute proof that the value of the polynomial (f(x)) for any value (x) is correct.

proof = commitment.compute_proof(35)

This proof is a point in the BLS::PointG1.

Multi proof

A multi-proof for disclosing multiple x values is created as follows:

x = [1, 2, 3]

multi_proof = commitment.compute_multi_proof(x)

This proof is a point in the BLS::PointG1.

Verify

Verifiers can use committed value and proof to verify that the value of f(x) for the value of x is correct.

x = 35
y = 808951170278371
setting.valid_proof?(commitment.value, proof, x, y)

Multi proof

The validity of multiple proofs disclosing more than one value can be verified as follows:

x = [1, 2, 3]
y = [55, 9217, 280483]
setting.valid_multi_proof?(commitment.value, multi_proof, x, y)

Untrusted input

valid_proof? and valid_multi_proof? answer false for anything they will not accept, so a commitment or a proof that arrives over the wire cannot turn into an exception. Both check that the points they are given are in the prime-order subgroup, which being on the curve does not imply and which proofs are forgeable without.

What they cannot check is how x and y were spelled, because they never see it. BLS::Fr reduces modulo the group order, which is what makes -6 and r - 6 one element, and also what leaves 1 and 1 + BLS::Curve::R as two encodings of a single claim: a proof for either verifies against the other. Decode field elements that arrive as bytes with KZG.decode_field_element, which refuses everything but the canonical 32 byte big endian form, in the same way BLS::PointG1.from_hex refuses a non-canonical point:

x = KZG.decode_field_element(x_hex) # 32 bytes, big endian, no 0x prefix
y = KZG.decode_field_element(y_hex) # raises KZG::Error if x_hex is not canonical
commitment = BLS::PointG1.from_hex(commitment_hex)
proof = BLS::PointG1.from_hex(proof_hex)

setting.valid_proof?(commitment, proof, x, y)

The EIP-4844 reference vectors for verify_kzg_proof are run against valid_proof? in the specs; that function verifies with the same pairing equation and reads nothing from the trusted setup but [s]_2.

Use as vector commitment

When used as a Vector commitment, the value to be committed is encoded in a polynomial expression as the evaluated value of the polynomial. For example, if commit to the vector [3, 2, 9], compute the polynomial pass the points (1, 3), (2, 2), (3, 9). This can be computed by polynomial interpolation.

KZG::Polynomial#lagrange_interpolate method recovers a polynomial from several points using Lagrangian interpolation. Then commitment is created using the restored polynomial.

x = [1, 2, 3]
y = [3, 2, 9]

polynomial = KZG::Polynomial.lagrange_interpolate(x, y)

commitment = KZG::Commitment.from_coeffs(setting, polynomial.coeffs)

# compute proof
proof = commitment.compute_proof(3)
# verify
setting.valid_proof?(commitment.value, proof, 3, 9)

Side channels

Committing is not safe against an attacker who can measure it. A commitment multiplies a setup point by each coefficient of the polynomial, and those coefficients are the very thing the commitment hides — the vector above among them. The multiplication underneath is not constant time: the scalar decides which precomputed point each window adds and so which memory is touched, point addition returns early on the identity, and Ruby's bignum arithmetic takes time that depends on its operands.

A pure Ruby implementation cannot fix this, and neither can the library underneath. Treat committing as suitable where it cannot be observed. Verifying is fine either way, since it touches nothing secret.

Threads

Verifying from several threads gives the right answers. valid_proof? pairs against BLS::PointG2::BASE, which memoises its pairing coefficients on first use without a lock, so racing callers can each compute them; what is assigned is always a finished array, so the cost is the repeated work rather than a wrong result.