vrf

Documentation

Overview

Numbers are deterministically generated from seeds and a secret key, and are statistically indistinguishable from uniform sampling from {0,...,2**256-1}, to computationally-bounded observers who know the seeds, don't know the key, and only see the generated numbers. But each number also comes with a proof that it was generated according to the procedure mandated by a public key associated with that secret key.

See VRF.sol for design notes.

Usage -----

You should probably not be using this directly. chainlink/store/core/models/vrfkey.PrivateKey provides a simple, more misuse-resistant interface to the same functionality, via the CreateKey and MarshaledProof methods.

Nonetheless, a secret key sk should be securely sampled uniformly from {0,...,Order-1}. Its public key can be calculated from it by

secp256k1.Secp256k1{}.Point().Mul(secretKey, Generator)

To generate random output from a big.Int seed, pass sk and the seed to GenerateProof, and use the Output field of the returned Proof object.

To verify a Proof object p, run p.Verify(); or to verify it on-chain pass p.MarshalForSolidityVerifier() to randomValueFromVRFProof on the VRF solidity contract.

Index

• Constants
• Variables
• func FieldHash(msg []byte) *big.Int
• func FinalSeed(s PreSeedData) (finalSeed *big.Int)
• func HashToCurve(p kyber.Point, input *big.Int, ordinates func(x *big.Int)) (kyber.Point, error)
• func HashUint256s(xs ...*big.Int) (*big.Int, error)
• func IsCurveXOrdinate(x *big.Int) bool
• func IsSquare(x *big.Int) bool
• func ProjectiveECAdd(p, q kyber.Point) (x, y, z fieldElt)
• func ScalarFromCurvePoints(hash, pk, gamma kyber.Point, uWitness [20]byte, v kyber.Point) *big.Int
• func SquareRoot(x *big.Int) *big.Int
• func YSquared(x *big.Int) *big.Int
• type MarshaledOnChainResponse
  • func GenerateProofResponse(secretKey common.Hash, s PreSeedData) (MarshaledOnChainResponse, error)
• type MarshaledProof
  • func (m MarshaledProof) String() string
• type PreSeedData
• type Proof
  • func GenerateProof(secretKey, seed common.Hash) (Proof, error)
  • func UnmarshalSolidityProof(proof []byte) (rv Proof, err error)
  • func (p *Proof) MarshalForSolidityVerifier() (MarshaledProof, error)
  • func (p *Proof) SolidityPrecalculations() (*SolidityProof, error)
  • func (p *Proof) String() string
  • func (p *Proof) VerifyVRFProof() (bool, error)
  • func (p *Proof) WellFormed() bool
• type ProofResponse
  • func UnmarshalProofResponse(m MarshaledOnChainResponse) (*ProofResponse, error)
  • func (p ProofResponse) CryptoProof(s PreSeedData) (Proof, error)
  • func (p *ProofResponse) MarshalForVRFCoordinator() (response MarshaledOnChainResponse, err error)
• type Seed
  • func BigToSeed(x *big.Int) (Seed, error)
  • func BytesToSeed(b []byte) (*Seed, error)
  • func (s *Seed) Big() *big.Int
• type SolidityProof
  • func (p *SolidityProof) MarshalForSolidityVerifier() (proof MarshaledProof)
  • func (p *SolidityProof) String() string

Constants

const OnChainResponseLength = ProofLength + 32

OnChainResponseLength is the length of the MarshaledOnChainResponse. The extra 32 bytes are for blocknumber (as a uint256), which goes at the end. The seed is rewritten with the preSeed. (See MarshalForVRFCoordinator and ProofResponse#ActualProof.)

const ProofLength = 64 +
	64 +
	32 +
	32 +
	32 +
	32 +
	64 +
	64 +

	32 // zInv  (Leave Output out, because that can be efficiently calculated)

Length of marshaled proof, in bytes

Variables

var ErrCGammaEqualsSHash = fmt.Errorf(
	"pick a different nonce; c*gamma = s*hash, with this one")

var FieldSize = bigFromHex(
	"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F")

FieldSize is number of elements in secp256k1's base field, i.e. GF(FieldSize)

var Generator = secp256k1Curve.Point().Base()

Generator is the generator point of secp256k1

Functions

func FieldHash

func FieldHash(msg []byte) *big.Int

FieldHash hashes xs uniformly into {0, ..., fieldSize-1}. msg is assumed to already be a 256-bit hash

func FinalSeed

func FinalSeed(s PreSeedData) (finalSeed *big.Int)

FinalSeed is the seed which is actually passed to the VRF proof generator, given the pre-seed and the hash of the block in which the VRFCoordinator emitted the log for the request this is responding to.

func HashToCurve

func HashToCurve(p kyber.Point, input *big.Int, ordinates func(x *big.Int),
) (kyber.Point, error)

HashToCurve is a cryptographic hash function which outputs a secp256k1 point, or an error. It passes each candidate x ordinate to ordinates function.

func HashUint256s

func HashUint256s(xs ...*big.Int) (*big.Int, error)

HashUint256s returns a uint256 representing the hash of the concatenated byte representations of the inputs

func IsCurveXOrdinate

func IsCurveXOrdinate(x *big.Int) bool

IsCurveXOrdinate returns true iff there is y s.t. y^2=x^3+7

func IsSquare

func IsSquare(x *big.Int) bool

IsSquare returns true iff x = y^2 for some y in GF(p)

func ProjectiveECAdd

func ProjectiveECAdd(p, q kyber.Point) (x, y, z fieldElt)

ProjectiveECAdd(px, py, qx, qy) duplicates the calculation in projective coordinates of VRF.sol#projectiveECAdd, so we can reliably get the denominator (i.e, z)

func ScalarFromCurvePoints

func ScalarFromCurvePoints(
	hash, pk, gamma kyber.Point, uWitness [20]byte, v kyber.Point) *big.Int

ScalarFromCurve returns a hash for the curve points. Corresponds to the hash computed in VRF.sol#ScalarFromCurvePoints

func SquareRoot

func SquareRoot(x *big.Int) *big.Int

SquareRoot returns a s.t. a^2=x, as long as x is a square

func YSquared

func YSquared(x *big.Int) *big.Int

YSquared returns x^3+7 mod fieldSize, the right-hand side of the secp256k1 curve equation.

Types

type MarshaledOnChainResponse

type MarshaledOnChainResponse [OnChainResponseLength]byte

MarshaledOnChainResponse is the flat bytes which are sent back to the VRFCoordinator.

func GenerateProofResponse

func GenerateProofResponse(secretKey common.Hash, s PreSeedData) (
	MarshaledOnChainResponse, error)

GenerateProofResponse returns the marshaled proof of the VRF output given the secretKey and the seed computed from the s.PreSeed and the s.BlockHash

type MarshaledProof

type MarshaledProof [ProofLength]byte

MarshaledProof contains a VRF proof for randomValueFromVRFProof.

NB: when passing one of these to randomValueFromVRFProof via the geth blockchain simulator, it must be passed as a slice ("proof[:]"). Passing it as-is sends hundreds of single bytes, each padded to their own 32-byte word.

func (MarshaledProof) String

func (m MarshaledProof) String() string

String returns m as 0x-hex bytes

type PreSeedData

type PreSeedData struct {
	PreSeed   Seed        // Seed to be mixed with hash of containing block
	BlockHash common.Hash // Hash of block containing VRF request
	BlockNum  uint64      // Cardinal number of block containing VRF request
}

PreSeedData contains the data the VRF provider needs to compute the final VRF output and marshal the proof for transmission to the VRFCoordinator contract.

type Proof

type Proof struct {
	PublicKey kyber.Point // secp256k1 public key of private key used in proof
	Gamma     kyber.Point
	C         *big.Int
	S         *big.Int
	Seed      *big.Int // Seed input to verifiable random function
	Output    *big.Int // verifiable random function output;, uniform uint256 sample
}

Proof represents a proof that Gamma was constructed from the Seed according to the process mandated by the PublicKey.

N.B.: The kyber.Point fields must contain secp256k1.secp256k1Point values, C, S and Seed must be secp256k1Point, and Output must be at most 256 bits. See Proof.WellFormed.

func GenerateProof

func GenerateProof(secretKey, seed common.Hash) (Proof, error)

GenerateProof returns gamma, plus proof that gamma was constructed from seed as mandated from the given secretKey, with public key secretKey*Generator

secretKey and seed must be less than secp256k1 group order. (Without this constraint on the seed, the samples and the possible public keys would deviate very slightly from uniform distribution.)

func UnmarshalSolidityProof

func UnmarshalSolidityProof(proof []byte) (rv Proof, err error)

func (*Proof) MarshalForSolidityVerifier

func (p *Proof) MarshalForSolidityVerifier() (MarshaledProof, error)

MarshalForSolidityVerifier renders p as required by randomValueFromVRFProof

func (*Proof) SolidityPrecalculations

func (p *Proof) SolidityPrecalculations() (*SolidityProof, error)

SolidityPrecalculations returns the precomputed values needed by the solidity verifier, or an error on failure.

func (*Proof) String

func (p *Proof) String() string

func (*Proof) VerifyVRFProof

func (p *Proof) VerifyVRFProof() (bool, error)

VerifyProof is true iff gamma was generated in the mandated way from the given publicKey and seed, and no error was encountered

func (*Proof) WellFormed

func (p *Proof) WellFormed() bool

WellFormed is true iff p's attributes satisfy basic domain checks

type ProofResponse

type ProofResponse struct {
	// Approximately the proof which will be checked on-chain. Note that this
	// contains the pre-seed in place of the final seed. That should be computed
	// as in FinalSeed.
	P        Proof
	PreSeed  Seed   // Seed received during VRF request
	BlockNum uint64 // Height of the block in which tihs request was made
}

ProofResponse is the data which is sent back to the VRFCoordinator, so that it can verify that the seed the oracle finally used is correct.

func UnmarshalProofResponse

func UnmarshalProofResponse(m MarshaledOnChainResponse) (*ProofResponse, error)

UnmarshalProofResponse returns the ProofResponse represented by the bytes in m

func (ProofResponse) CryptoProof

func (p ProofResponse) CryptoProof(s PreSeedData) (Proof, error)

CryptoProof returns the proof implied by p, with the correct seed

func (*ProofResponse) MarshalForVRFCoordinator

func (p *ProofResponse) MarshalForVRFCoordinator() (
	response MarshaledOnChainResponse, err error)

MarshalForVRFCoordinator constructs the flat bytes which are sent to the VRFCoordinator.

type Seed

type Seed [32]byte

Seed represents a VRF seed as a serialized uint256

func BigToSeed

func BigToSeed(x *big.Int) (Seed, error)

BigToSeed returns seed x represented as a Seed, or an error if x is too big

func BytesToSeed

func BytesToSeed(b []byte) (*Seed, error)

BytesToSeed returns the Seed corresponding to b, or an error if b is too long

func (*Seed) Big

func (s *Seed) Big() *big.Int

Big returns the uint256 seed represented by s

type SolidityProof

type SolidityProof struct {
	P                           *Proof         // The core proof
	UWitness                    common.Address // Address of P.C*P.PK+P.S*G
	CGammaWitness, SHashWitness kyber.Point    // P.C*P.Gamma, P.S*HashToCurve(P.Seed)
	ZInv                        *big.Int       // Inverse of Z coord from ProjectiveECAdd(CGammaWitness, SHashWitness)
}

SolidityProof contains precalculations which VRF.sol needs to verifiy proofs

func (*SolidityProof) MarshalForSolidityVerifier

func (p *SolidityProof) MarshalForSolidityVerifier() (proof MarshaledProof)

MarshalForSolidityVerifier renders p as required by randomValueFromVRFProof

func (*SolidityProof) String

func (p *SolidityProof) String() string

String returns the values in p, in hexadecimal format