gokzg4844

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2024 License: Apache-2.0 Imports: 13 Imported by: 80

README

Go-KZG-4844

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-kzg-4844

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 1.18, the current version and the latest version. If support for 1.18 is broken, we will update the CI to reflect this with a given reason.

License

This project is licensed under the APACHE-2 license.

Documentation

Index

Constants

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("the number of blobs, commitments, and proofs must be the same")
	ErrNonCanonicalScalar = errors.New("scalar is not canonical when interpreted as a big integer in big-endian")
)
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 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 added in v0.7.0 

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) 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) 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) 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"`
}

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
kzg
multiexp
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.