proof

Documentation

Overview

* The MIT License (MIT)

Copyright (c) 2018 SmartContract ChainLink, Ltd.

* The MIT License (MIT)

Copyright (c) 2018 SmartContract ChainLink, Ltd.

* The MIT License (MIT)

Copyright (c) 2018 SmartContract ChainLink, Ltd.

* The MIT License (MIT)

Copyright (c) 2018 SmartContract ChainLink, Ltd.

* The MIT License (MIT)

Copyright (c) 2018 SmartContract ChainLink, Ltd.

Index

• 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 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, error)
• func SquareRoot(x *big.Int) *big.Int
• func YSquared(x *big.Int) *big.Int
• type KeyV2
  • func NewV2() (KeyV2, error)
  • func (key KeyV2) GenerateProof(seed *big.Int) (Proof, error)
  • func (key KeyV2) GenerateProofWithNonce(seed, nonce *big.Int) (Proof, error)
  • func (key KeyV2) GoString() string
  • func (key KeyV2) ID() string
  • func (key KeyV2) Raw() Raw
  • func (key KeyV2) String() string
• type PreSeedData
• type Proof
  • func (p *Proof) String() string
  • func (p *Proof) VerifyVRFProof() (bool, error)
  • func (p *Proof) WellFormed() bool
• type Raw
  • func (raw Raw) GoString() string
  • func (raw Raw) Key() (KeyV2, error)
  • func (raw Raw) String() string
• type Seed
  • func BigToSeed(x *big.Int) (Seed, error)
  • func (s *Seed) Big() *big.Int
• type SolidityProof
  • func SolidityPrecalculations(p *Proof) (*SolidityProof, error)
  • func (p *SolidityProof) String() string

Variables

var (
	// FieldSize is number of elements in secp256k1's base field, i.e. GF(FieldSize)
	FieldSize = utils.HexToBig(
		"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F",
	)
	Secp256k1Curve = &secp256k1.Secp256k1{}
	Generator      = Secp256k1Curve.Point().Base()

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

	// RandomOutputHashPrefix is a domain-separation tag for the hash used to
	// compute the final VRF random output
	RandomOutputHashPrefix = common.BigToHash(utils.Three).Bytes()
)

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 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, error)

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 KeyV2

type KeyV2 struct {
	PublicKey secp256k1.PublicKey
	// contains filtered or unexported fields
}

func NewV2

func NewV2() (KeyV2, error)

func (KeyV2) GenerateProof

func (key KeyV2) GenerateProof(seed *big.Int) (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 (KeyV2) GenerateProofWithNonce

func (key KeyV2) GenerateProofWithNonce(seed, nonce *big.Int) (Proof, error)

GenerateProofWithNonce allows external nonce generation for testing purposes

As with signatures, using nonces which are in any way predictable to an adversary will leak your secret key! Most people should use GenerateProof instead.

func (KeyV2) GoString

func (key KeyV2) GoString() string

func (KeyV2) ID

func (key KeyV2) ID() string

func (KeyV2) Raw

func (key KeyV2) Raw() Raw

func (KeyV2) String

func (key KeyV2) String() string

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
	SubId            uint64
	CallbackGasLimit uint32
	NumWords         uint32
	Sender           common.Address
}

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 (*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 Raw

type Raw []byte

func (Raw) GoString

func (raw Raw) GoString() string

func (Raw) Key

func (raw Raw) Key() (KeyV2, error)

func (Raw) String

func (raw Raw) String() string

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 (*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 verify proofs

func SolidityPrecalculations

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

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

func (*SolidityProof) String

func (p *SolidityProof) String() string

String returns the values in p, in hexadecimal format