chainlink: Index | Files

package vrf

import ""

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.


Package Files

go_generate.go solidity_ports.go solidity_proof.go vrf.go vrf_coordinator_abi_values.go vrf_coordinator_interface.go


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


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

Generator is the generator point of secp256k1

func CoordinatorABI Uses

func CoordinatorABI() abi.ABI

CoordinatorABI returns the ABI for the VRFCoordinator contract

func FulfillMethod Uses

func FulfillMethod() abi.Method

FulfillMethod returns the golang abstraction of the fulfillRandomnessRequest method

func FulfillSelector Uses

func FulfillSelector() string

FulfillSelector returns the signature of the fulfillRandomnessRequest method on the VRFCoordinator contract

func HashToCurve Uses

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 Uses

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 Uses

func IsCurveXOrdinate(x *big.Int) bool

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

func IsSquare Uses

func IsSquare(x *big.Int) bool

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

func ProjectiveECAdd Uses

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 RandomnessRequestLogTopic Uses

func RandomnessRequestLogTopic() common.Hash

RandomnessRequestLogTopic returns the signature of the RandomnessRequest log emitted by the VRFCoordinator contract

func ScalarFromCurvePoints Uses

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 Uses

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

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

func YSquared Uses

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

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

type MarshaledProof Uses

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 Uses

func (m MarshaledProof) String() string

String returns m as 0x-hex bytes

type Proof Uses

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 Uses

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 Uses

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

func (*Proof) MarshalForSolidityVerifier Uses

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

MarshalForSolidityVerifier renders p as required by randomValueFromVRFProof

func (*Proof) SolidityPrecalculations Uses

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

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

func (*Proof) String Uses

func (p *Proof) String() string

func (*Proof) VerifyVRFProof Uses

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 Uses

func (p *Proof) WellFormed() bool

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

type RandomnessRequestLog Uses

type RandomnessRequestLog struct {
    KeyHash common.Hash
    Seed    *big.Int // uint256
    JobID   common.Hash
    Sender  common.Address
    Fee     *assets.Link // uint256
    Raw     RawRandomnessRequestLog

RandomnessRequestLog contains the data for a RandomnessRequest log, represented as compatible golang types.

func ParseRandomnessRequestLog Uses

func ParseRandomnessRequestLog(log eth.Log) (*RandomnessRequestLog, error)

ParseRandomnessRequestLog returns the RandomnessRequestLog corresponding to the raw logData

func RawRandomnessRequestLogToRandomnessRequestLog Uses

func RawRandomnessRequestLogToRandomnessRequestLog(
    l *RawRandomnessRequestLog) *RandomnessRequestLog

func (*RandomnessRequestLog) Equal Uses

func (l *RandomnessRequestLog) Equal(ol RandomnessRequestLog) bool

Equal(ol) is true iff l is the same log as ol, and both represent valid RandomnessRequest logs.

func (*RandomnessRequestLog) RawData Uses

func (l *RandomnessRequestLog) RawData() ([]byte, error)

RawData returns the raw bytes corresponding to l in a solidity log

This serialization does not include the JobID, because that's an indexed field.

func (*RandomnessRequestLog) RequestID Uses

func (l *RandomnessRequestLog) RequestID() common.Hash

type RawRandomnessRequestLog Uses

type RawRandomnessRequestLog solidity_vrf_coordinator_interface.VRFCoordinatorRandomnessRequest

RawRandomnessRequestLog is used to parse a RandomnessRequest log into types go-ethereum knows about.

type SolidityProof Uses

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 Uses

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

MarshalForSolidityVerifier renders p as required by randomValueFromVRFProof

func (*SolidityProof) String Uses

func (p *SolidityProof) String() string

String returns the values in p, in hexadecimal format

Package vrf imports 16 packages (graph). Updated 2020-04-09. Refresh now. Tools for package owners.

The go get command cannot install this package because of the following issues: