frontend

Documentation

Overview

Package frontend contains the object and logic to define and compile gnark circuits

Index

• Variables
• func FromInterface(i1 interface{}) big.Int
• func GetAssignedValue(v Variable) interface{}
• type Circuit
• type CompiledConstraintSystem
  • func Compile(curveID ecc.ID, zkpID backend.ID, circuit Circuit, initialCapacity ...int) (ccs CompiledConstraintSystem, err error)
• type ConstraintSystem
  • func (cs *ConstraintSystem) Add(i1, i2 interface{}, in ...interface{}) Variable
  • func (cs *ConstraintSystem) And(a, b Variable) Variable
  • func (cs *ConstraintSystem) AssertIsBoolean(v Variable)
  • func (cs *ConstraintSystem) AssertIsEqual(i1, i2 interface{})
  • func (cs *ConstraintSystem) AssertIsLessOrEqual(v Variable, bound interface{})
  • func (cs *ConstraintSystem) Constant(input interface{}) Variable
  • func (cs *ConstraintSystem) Div(i1, i2 interface{}) Variable
  • func (cs *ConstraintSystem) FromBinary(b ...Variable) Variable
  • func (cs *ConstraintSystem) Inverse(v Variable) Variable
  • func (cs *ConstraintSystem) IsZero(a Variable, id ecc.ID) Variable
  • func (cs *ConstraintSystem) LinearExpression(terms ...compiled.Term) compiled.LinearExpression
  • func (cs *ConstraintSystem) Mul(i1, i2 interface{}, in ...interface{}) Variable
  • func (cs *ConstraintSystem) NbConstraints() int
  • func (cs *ConstraintSystem) Neg(i interface{}) Variable
  • func (cs *ConstraintSystem) Or(a, b Variable) Variable
  • func (cs *ConstraintSystem) Println(a ...interface{})
  • func (cs *ConstraintSystem) Select(b Variable, i1, i2 interface{}) Variable
  • func (cs *ConstraintSystem) Sub(i1, i2 interface{}) Variable
  • func (cs *ConstraintSystem) ToBinary(a Variable, nbBits int) []Variable
  • func (cs *ConstraintSystem) Xor(a, b Variable) Variable
• type Variable
  • func (v *Variable) Assign(value interface{})
• type Wire

Variables

var ErrInputNotSet = errors.New("variable is not allocated")

ErrInputNotSet triggered when trying to access a variable that was not allocated

Functions

func FromInterface

func FromInterface(i1 interface{}) big.Int

FromInterface converts an interface to a big.Int element interface must implement ToBigIntRegular(res *big.Int) *big.Int (which is the case for field generated by goff) or be uint64, int, string, []byte or big.Int it panics if the input is invalid

func GetAssignedValue

func GetAssignedValue(v Variable) interface{}

GetAssignedValue returns the assigned value (or nil) to the variable This is used for witness preparation internally and not exposed on Variable struct to avoid confusion in circuit definition.

Types

type Circuit

type Circuit interface {
	// Define declares the circuit's Constraints
	Define(curveID ecc.ID, cs *ConstraintSystem) error
}

Circuit must be implemented by user-defined circuits

the tag format is as follow:

type MyCircuit struct {
	Y frontend.Variable `gnark:"name,option"`
}

if empty, default resolves to variable name (here "Y") and secret visibility similarly to json or xml struct tags, these are valid:

`gnark:",public"` or `gnark:"-"`

using "-" marks the variable as ignored by the Compile method. This can be useful when you need to declare variables as aliases that are already allocated. For example

type MyCircuit struct {
	Y frontend.Variable `gnark:",public"`
	Z frontend.Variable `gnark:"-"`
}

it is then the developer responsability to do circuit.Z = circuit.Y in the Define() method

type CompiledConstraintSystem

type CompiledConstraintSystem interface {
	io.WriterTo
	io.ReaderFrom

	// GetNbVariables return number of internal, secret and public variables
	GetNbVariables() (internal, secret, public int)
	GetNbConstraints() int
	GetNbCoefficients() int

	// SetLoggerOutput replace existing logger output with provided one
	SetLoggerOutput(w io.Writer)

	CurveID() ecc.ID
	FrSize() int
}

CompiledConstraintSystem ...

func Compile

func Compile(curveID ecc.ID, zkpID backend.ID, circuit Circuit, initialCapacity ...int) (ccs CompiledConstraintSystem, err error)

Compile will generate a CompiledConstraintSystem from the given circuit

1. it will first allocate the user inputs (see type Tag for more info) example:

type MyCircuit struct {
	Y frontend.Variable `gnark:"exponent,public"`
}

in that case, Compile() will allocate one public variable with id "exponent"

2. it then calls circuit.Define(curveID, constraintSystem) to build the internal constraint system from the declarative code

3. finally, it converts that to a CompiledConstraintSystem. if zkpID == backend.GROTH16 --> R1CS if zkpID == backend.PLONK --> SparseR1CS

initialCapacity is an optional parameter that reserves memory in slices it should be set to the estimated number of constraints in the circuit, if known.

type ConstraintSystem

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

ConstraintSystem represents a Groth16 like circuit

All the APIs to define a circuit (see Circuit.Define) like Add, Sub, Mul, ... may take as input interface{}

these interfaces are either Variables (/LinearExpressions) or constants (big.Int, strings, uint, fr.Element)

func (*ConstraintSystem) Add

func (cs *ConstraintSystem) Add(i1, i2 interface{}, in ...interface{}) Variable

Add returns res = i1+i2+...in

func (*ConstraintSystem) And

func (cs *ConstraintSystem) And(a, b Variable) Variable

And compute the AND between two variables

func (*ConstraintSystem) AssertIsBoolean

func (cs *ConstraintSystem) AssertIsBoolean(v Variable)

AssertIsBoolean adds an assertion in the constraint system (v == 0 || v == 1)

func (*ConstraintSystem) AssertIsEqual

func (cs *ConstraintSystem) AssertIsEqual(i1, i2 interface{})

AssertIsEqual adds an assertion in the constraint system (i1 == i2)

func (*ConstraintSystem) AssertIsLessOrEqual

func (cs *ConstraintSystem) AssertIsLessOrEqual(v Variable, bound interface{})

AssertIsLessOrEqual adds assertion in constraint system (v <= bound)

bound can be a constant or a Variable

derived from: https://github.com/zcash/zips/blOoutputb/master/protocol/protocol.pdf

func (*ConstraintSystem) Constant

func (cs *ConstraintSystem) Constant(input interface{}) Variable

Constant will return (and allocate if neccesary) a constant Variable

input can be a Variable or must be convertible to big.Int (see FromInterface)

func (*ConstraintSystem) Div

func (cs *ConstraintSystem) Div(i1, i2 interface{}) Variable

Div returns res = i1 / i2

func (*ConstraintSystem) FromBinary

func (cs *ConstraintSystem) FromBinary(b ...Variable) Variable

FromBinary packs b, seen as a fr.Element in little endian

func (*ConstraintSystem) Inverse

func (cs *ConstraintSystem) Inverse(v Variable) Variable

Inverse returns res = inverse(v) TODO the function should take an interface

func (*ConstraintSystem) IsZero

func (cs *ConstraintSystem) IsZero(a Variable, id ecc.ID) Variable

IsZero returns 1 if a is zero, 0 otherwise

func (*ConstraintSystem) LinearExpression

func (cs *ConstraintSystem) LinearExpression(terms ...compiled.Term) compiled.LinearExpression

LinearExpression packs a list of compiled.Term in a compiled.LinearExpression and returns it.

func (*ConstraintSystem) Mul

func (cs *ConstraintSystem) Mul(i1, i2 interface{}, in ...interface{}) Variable

Mul returns res = i1 * i2 * ... in

func (*ConstraintSystem) NbConstraints

func (cs *ConstraintSystem) NbConstraints() int

NbConstraints enables circuit profiling and helps debugging It returns the number of constraints created at the current stage of the circuit construction.

The number returns included both the assertions and the non-assertion constraints (eg: the constraints which creates a new variable)

func (*ConstraintSystem) Neg

func (cs *ConstraintSystem) Neg(i interface{}) Variable

Neg returns -i

func (*ConstraintSystem) Or

func (cs *ConstraintSystem) Or(a, b Variable) Variable

Or compute the OR between two variables

func (*ConstraintSystem) Println

func (cs *ConstraintSystem) Println(a ...interface{})

Println enables circuit debugging and behaves almost like fmt.Println()

the print will be done once the R1CS.Solve() method is executed

if one of the input is a Variable, its value will be resolved avec R1CS.Solve() method is called

func (*ConstraintSystem) Select

func (cs *ConstraintSystem) Select(b Variable, i1, i2 interface{}) Variable

Select if b is true, yields i1 else yields i2

func (*ConstraintSystem) Sub

func (cs *ConstraintSystem) Sub(i1, i2 interface{}) Variable

Sub returns res = i1 - i2

func (*ConstraintSystem) ToBinary

func (cs *ConstraintSystem) ToBinary(a Variable, nbBits int) []Variable

ToBinary unpacks a variable in binary, n is the number of bits of the variable

The result in in little endian (first bit= lsb)

func (*ConstraintSystem) Xor

func (cs *ConstraintSystem) Xor(a, b Variable) Variable

Xor compute the XOR between two variables

type Variable

type Variable struct {
	Wire
	// contains filtered or unexported fields
}

Variable of a circuit represents a Variable to a circuit, plus the linear combination leading to it. the linExp is always non empty, the PartialVariabl can be unset. It is set and allocated in the circuit when there is no other choice (to avoid wasting wires doing only linear expressions)

func (*Variable) Assign

func (v *Variable) Assign(value interface{})

Assign v = value . This must called when using a Circuit as a witness data structure

type Wire

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

Wire of a circuit They represent secret or public inputs in a circuit struct{} / definition (see circuit.Define(), type Tag)