goethkzg

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

go-eth-kzg

This library provides the necessary cryptographic functions for EIP-4844. If one is not familiar with EIP-4844, you can think of this library as a KZG library where the polynomial degree is set to 4095 and opening proofs are computed on polynomials in lagrange form (4096 evaluations at 4096'th roots of unity).

Installation

go get github.com/crate-crypto/go-eth-kzg

Example

Check out examples_test.go for an example of how to use this library.

Benchmarks

To run the benchmarks, execute the following command:

go test -bench=.

Consensus specs

This version of the code is conformant with the consensus-specs as of the following commit: 017a8495f7671f5fff2075a9bfc9238c1a0982f8

Security

  • For security bugs in this library, email kev@the.dev.
  • This library uses gnark-crypto for elliptic curve operations. An audit of gnark can be seen here. This library uses a more recent version than the audited version, since that version had a serialization bug. We only rely on gnark-crypto's underlying group operations and pairing code for bls12-381. For code that we do need to use, that has not been audited, we have copied it into this library so that it can be a part of this libraries audit. We have noted in the comments which functions we have done this for.

Panics

Panics can be a DoS vector when running code in a node. This library endeavors to only panic on startup; only methods which are called when we create the Context object should panic.

Minimum Supported Golang Version

Because we use generics, the minimum golang version needs to be 1.18 or above. Since Golang only back ports security fixes to the latest version and one version behind latest, this library will at most be one version behind latest.

Tests are ran against the current version and the latest version.

License

This project is licensed under the APACHE-2 license.

Documentation

Index

Constants

View Source 
const BytesPerCell = scalarsPerCell * SerializedScalarSize

BytesPerCell is the number of bytes in a `Cell`.

View Source 
const CellsPerExtBlob = 128

The number of cells in an extended blob.

View Source 
const CompressedG1Size = 48

CompressedG1Size is the number of bytes needed to represent a group element in G1 when compressed.

View Source 
const CompressedG2Size = 96

CompressedG2Size is the number of bytes needed to represent a group element in G2 when compressed.

View Source 
const DomSepProtocol = "FSBLOBVERIFY_V1_"

DomSepProtocol is a Domain Separator to identify the protocol.

It matches FIAT_SHAMIR_PROTOCOL_DOMAIN in the spec.

View Source 
const ScalarsPerBlob = 4096

ScalarsPerBlob is the number of serialized scalars in a blob.

It matches FIELD_ELEMENTS_PER_BLOB in the spec.

Note: These scalars are not guaranteed to be valid (a value less than BLS_MODULUS). If any of the scalars in a blob are invalid (non-canonical), an error will be returned on deserialization.

View Source 
const SerializedScalarSize = 32

SerializedScalarSize is the number of bytes needed to represent a field element corresponding to the order of the G1 group.

It matches BYTES_PER_FIELD_ELEMENT in the spec.

Variables

View Source 
var (
	ErrBatchLengthCheck   = errors.New("all designated elements in the batch should have the same size")
	ErrNonCanonicalScalar = errors.New("scalar is not canonical when interpreted as a big integer in big-endian")
	ErrInvalidCellID      = errors.New("cell ID should be less than CellsPerExtBlob")
	ErrInvalidRowIndex    = errors.New("row index should be less than the number of row commitments")

	ErrNumCellIDsNotEqualNumCells      = errors.New("number of cell IDs should be equal to the number of cells")
	ErrCellIDsNotUnique                = errors.New("cell IDs are not unique")
	ErrFoundInvalidCellID              = errors.New("cell ID should be less than CellsPerExtBlob")
	ErrNotEnoughCellsForReconstruction = errors.New("not enough cells to perform reconstruction")

	// The following errors indicate that the library constants have not been setup properly.
	// These should never happen unless the library has been incorrectly modified.
	ErrNumCosetEvaluationsCheck   = errors.New("expected number of coset evaluations to be `CellsPerExtBlob`")
	ErrCosetEvaluationLengthCheck = errors.New("expected coset evaluations to have `ScalarsPerCell` number of field elements")
	ErrNumProofsCheck             = errors.New("expected number of proofs to be `CellsPerExtBlob`")
)
View Source 
var BlsModulus = [32]byte{
	0x73, 0xed, 0xa7, 0x53, 0x29, 0x9d, 0x7d, 0x48,
	0x33, 0x39, 0xd8, 0x08, 0x09, 0xa1, 0xd8, 0x05,
	0x53, 0xbd, 0xa4, 0x02, 0xff, 0xfe, 0x5b, 0xfe,
	0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x01,
}

BlsModulus is the bytes representation of the bls12-381 scalar field modulus.

It matches BLS_MODULUS in the spec.

View Source 
var PointAtInfinity = [48]byte{0xc0}

PointAtInfinity represents the serialized form of the point at infinity on the G1 group.

It matches G1_POINT_AT_INFINITY in the spec.

Functions

func CheckTrustedSetupIsWellFormed 

func CheckTrustedSetupIsWellFormed(trustedSetup *JSONTrustedSetup) error

CheckTrustedSetupIsWellFormed checks whether the trusted setup is well-formed.

To be specific, this checks that:

  • All elements are in the correct subgroup.

func DeserializeBlob 

func DeserializeBlob(blob *Blob) (kzg.Polynomial, error)

DeserializeBlob implements blob_to_polynomial.

func DeserializeKZGCommitment 

func DeserializeKZGCommitment(commitment KZGCommitment) (bls12381.G1Affine, error)

DeserializeKZGCommitment implements bytes_to_kzg_commitment.

func DeserializeKZGProof 

func DeserializeKZGProof(proof KZGProof) (bls12381.G1Affine, error)

DeserializeKZGProof implements bytes_to_kzg_proof.

func DeserializeScalar 

func DeserializeScalar(serScalar Scalar) (fr.Element, error)

DeserializeScalar implements bytes_to_bls_field.

Note: Returns an error if the scalar is not in the range [0, p-1] (inclusive) where `p` is the prime associated with the scalar field.

Types

type Blob 

type Blob [ScalarsPerBlob * SerializedScalarSize]byte

Blob is a flattened representation of a serialized polynomial.

It matches Blob in the spec.

func SerializePoly 

func SerializePoly(poly kzg.Polynomial) *Blob

SerializePoly converts a kzg.Polynomial to Blob.

Note: This method is never used in the API because we always expect a byte array and will never receive deserialized field elements. We include it so that upstream fuzzers do not need to reimplement it.

type Cell 

type Cell [BytesPerCell]byte

Cell is a serialized version of a set of evaluations to a polynomial

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context holds the necessary configuration needed to create and verify proofs.

Note: We could marshall this object so that clients won't need to process the SRS each time. The time to process is about 2-5 seconds.

func NewContext4096 

func NewContext4096(trustedSetup *JSONTrustedSetup) (*Context, error)

NewContext4096 creates a new context object which will hold the state needed for one to use the EIP-4844 methods. The 4096 represents the fact that without extra changes to the code, this context will only handle polynomials with 4096 evaluations (degree 4095).

Note: The G2 points do not have a fixed size. Technically, we could specify it to be 2, as this is the number of G2 points that are required for KZG. However, the trusted setup in Ethereum has 65 since they want to use it for a future protocol: Full Danksharding. For this reason, we do not apply a fixed size, allowing the user to pass, say, 2 or 65.

To initialize one must pass the parameters generated after the trusted setup, plus the lagrange version of the G1 points. This function assumes that the G1 and G2 points are in order:

  • G1points = {G, alpha * G, alpha^2 * G, ..., alpha^n * G}
  • G2points = {H, alpha * H, alpha^2 * H, ..., alpha^n * H}
  • Lagrange G1Points = {L_0(alpha^0) * G, L_1(alpha) * G, L_2(alpha^2) * G, ..., L_n(alpha^n) * G}

func NewContext4096Secure 

func NewContext4096Secure() (*Context, error)

NewContext4096Secure creates a new context object which will hold the state needed for one to use the KZG methods. "4096" denotes that we will only be able to commit to polynomials with at most 4096 evaluations. "Secure" denotes that this method is using a trusted setup file that was generated in an official ceremony. In particular, the trusted file being used was taken from the ethereum KZG ceremony.

func (*Context) BlobToKZGCommitment 

func (c *Context) BlobToKZGCommitment(blob *Blob, numGoRoutines int) (KZGCommitment, error)

BlobToKZGCommitment implements blob_to_kzg_commitment.

numGoRoutines is used to configure the amount of concurrency needed. Setting this value to a negative number or 0 will make it default to the number of CPUs.

func (*Context) ComputeBlobKZGProof 

func (c *Context) ComputeBlobKZGProof(blob *Blob, blobCommitment KZGCommitment, numGoRoutines int) (KZGProof, error)

ComputeBlobKZGProof implements compute_blob_kzg_proof. It takes a blob and returns the KZG proof that is used to verify it against the given KZG commitment at a random point.

Note: This method does not check that the commitment corresponds to the `blob`. The method does still check that the commitment is a valid commitment. One should check this externally or call Context.BlobToKZGCommitment.

numGoRoutines is used to configure the amount of concurrency needed. Setting this value to a negative number or 0 will make it default to the number of CPUs.

func (*Context) ComputeCellsAndKZGProofs 

func (ctx *Context) ComputeCellsAndKZGProofs(blob *Blob, numGoRoutines int) ([CellsPerExtBlob]*Cell, [CellsPerExtBlob]KZGProof, error)

func (*Context) ComputeKZGProof 

func (c *Context) ComputeKZGProof(blob *Blob, inputPointBytes Scalar, numGoRoutines int) (KZGProof, Scalar, error)

ComputeKZGProof implements compute_kzg_proof.

numGoRoutines is used to configure the amount of concurrency needed. Setting this value to a negative number or 0 will make it default to the number of CPUs.

func (*Context) RecoverCellsAndComputeKZGProofs 

func (ctx *Context) RecoverCellsAndComputeKZGProofs(cellIDs []uint64, cells []*Cell, numGoRoutines int) ([CellsPerExtBlob]*Cell, [CellsPerExtBlob]KZGProof, error)

func (*Context) VerifyBlobKZGProof 

func (c *Context) VerifyBlobKZGProof(blob *Blob, blobCommitment KZGCommitment, kzgProof KZGProof) error

VerifyBlobKZGProof implements verify_blob_kzg_proof.

func (*Context) VerifyBlobKZGProofBatch 

func (c *Context) VerifyBlobKZGProofBatch(blobs []Blob, polynomialCommitments []KZGCommitment, kzgProofs []KZGProof) error

VerifyBlobKZGProofBatch implements verify_blob_kzg_proof_batch.

func (*Context) VerifyBlobKZGProofBatchPar 

func (c *Context) VerifyBlobKZGProofBatchPar(blobs []Blob, commitments []KZGCommitment, proofs []KZGProof) error

VerifyBlobKZGProofBatchPar implements verify_blob_kzg_proof_batch. This is the parallelized version of Context.VerifyBlobKZGProofBatch, which is single-threaded. This function uses go-routines to process each proof in parallel. If you are worried about resource starvation on large batches, it is advised to schedule your own go-routines in a more intricate way than done below for large batches.

func (*Context) VerifyCellKZGProofBatch 

func (ctx *Context) VerifyCellKZGProofBatch(commitments []KZGCommitment, cellIndices []uint64, cells []*Cell, proofs []KZGProof) error

func (*Context) VerifyKZGProof 

func (c *Context) VerifyKZGProof(blobCommitment KZGCommitment, inputPointBytes, claimedValueBytes Scalar, kzgProof KZGProof) error

VerifyKZGProof implements verify_kzg_proof.

type G1CompressedHexStr 

type G1CompressedHexStr = string

G1CompressedHexStr is a hex-string (with the 0x prefix) of a compressed G1 point.

type G1Point 

type G1Point [CompressedG1Size]byte

G1Point matches G1Point in the spec.

func SerializeG1Point 

func SerializeG1Point(affine bls12381.G1Affine) G1Point

SerializeG1Point converts a bls12381.G1Affine to G1Point.

type G2CompressedHexStr 

type G2CompressedHexStr = string

G2CompressedHexStr is a hex-string (with the 0x prefix) of a compressed G2 point.

type G2Point 

type G2Point [CompressedG2Size]byte

G2Point matches G2Point in the spec.

type JSONTrustedSetup 

type JSONTrustedSetup struct {
	SetupG2         []G2CompressedHexStr               `json:"g2_monomial"`
	SetupG1Lagrange [ScalarsPerBlob]G1CompressedHexStr `json:"g1_lagrange"`
	SetupG1Monomial [ScalarsPerBlob]G1CompressedHexStr `json:"g1_monomial"`
}

JSONTrustedSetup is a struct used for serializing the trusted setup from/to JSON format.

The intended use-case is that library users store the trusted setup in a JSON file and we provide such a file as part of the package.

type KZGCommitment 

type KZGCommitment G1Point

KZGCommitment is a serialized commitment to a polynomial.

It matches KZGCommitment in the spec.

type KZGProof 

type KZGProof G1Point

KZGProof is a serialized commitment to the quotient polynomial.

It matches KZGProof in the spec.

type Scalar 

type Scalar [SerializedScalarSize]byte

Scalar matches BLSFieldElement in the spec.

func SerializeScalar 

func SerializeScalar(element fr.Element) Scalar

SerializeScalar converts a fr.Element to Scalar.

Source Files

View all Source files

Directories

Path Synopsis
internal
domain
erasure_code
kzg
kzg_multi
kzg_multi/fk20
multiexp
poly
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.