frontend

Documentation

Index

• func IgnoreUnconstrainedInputs(opt *CompileOption) error
• func RegisterDefaultBuilder(b backend.ID, builder NewBuilder)
• func WithBuilder(builder NewBuilder) func(opt *CompileOption) error
• func WithCapacity(capacity int) func(opt *CompileOption) error
• type API
• type Builder
• type Circuit
• type CompileOption
• type CompiledConstraintSystem
  • func Compile(curveID ecc.ID, zkpID backend.ID, circuit Circuit, ...) (CompiledConstraintSystem, error)
• type Counter
• type NewBuilder
• type Tag
• type Variable

Functions

func IgnoreUnconstrainedInputs

func IgnoreUnconstrainedInputs(opt *CompileOption) error

IgnoreUnconstrainedInputs when set, the Compile function doesn't check for unconstrained inputs

func RegisterDefaultBuilder

func RegisterDefaultBuilder(b backend.ID, builder NewBuilder)

RegisterDefaultBuilder registers a frontend f for a backend b. This registration ensures that a correct frontend system is chosen for a specific backend when compiling a circuit. The method does not check that the compiler for that frontend is already registered and the compiler is looked up during compile time. It is an error to double-assign a frontend to a single backend and the mehod panics.

/!\ This is highly experimental and may change in upcoming releases /!\

func WithBuilder

func WithBuilder(builder NewBuilder) func(opt *CompileOption) error

WithBuilder enables the compiler to build the constraint system with a user-defined builder

/!\ This is highly experimental and may change in upcoming releases /!\

func WithCapacity

func WithCapacity(capacity int) func(opt *CompileOption) error

WithOutput is a Compile option that specifies the estimated capacity needed for internal variables and constraints

Types

type API

type API interface {

	// Add returns res = i1+i2+...in
	Add(i1, i2 Variable, in ...Variable) Variable

	// Sub returns res = i1 - i2 - ...in
	Sub(i1, i2 Variable, in ...Variable) Variable

	// Neg returns -i
	Neg(i1 Variable) Variable

	// Mul returns res = i1 * i2 * ... in
	Mul(i1, i2 Variable, in ...Variable) Variable

	// DivUnchecked returns i1 / i2 . if i1 == i2 == 0, returns 0
	DivUnchecked(i1, i2 Variable) Variable

	// Div returns i1 / i2
	Div(i1, i2 Variable) Variable

	// Inverse returns res = 1 / i1
	Inverse(i1 Variable) Variable

	// ToBinary unpacks a Variable in binary,
	// n is the number of bits to select (starting from lsb)
	// n default value is fr.Bits the number of bits needed to represent a field element
	//
	// The result in in little endian (first bit= lsb)
	ToBinary(i1 Variable, n ...int) []Variable

	// FromBinary packs b, seen as a fr.Element in little endian
	FromBinary(b ...Variable) Variable

	// Xor returns a ^ b
	// a and b must be 0 or 1
	Xor(a, b Variable) Variable

	// Or returns a | b
	// a and b must be 0 or 1
	Or(a, b Variable) Variable

	// Or returns a & b
	// a and b must be 0 or 1
	And(a, b Variable) Variable

	// Select if b is true, yields i1 else yields i2
	Select(b Variable, i1, i2 Variable) Variable

	// Lookup2 performs a 2-bit lookup between i1, i2, i3, i4 based on bits b0
	// and b1. Returns i0 if b0=b1=0, i1 if b0=1 and b1=0, i2 if b0=0 and b1=1
	// and i3 if b0=b1=1.
	Lookup2(b0, b1 Variable, i0, i1, i2, i3 Variable) Variable

	// IsZero returns 1 if a is zero, 0 otherwise
	IsZero(i1 Variable) Variable

	// AssertIsEqual fails if i1 != i2
	AssertIsEqual(i1, i2 Variable)

	// AssertIsDifferent fails if i1 == i2
	AssertIsDifferent(i1, i2 Variable)

	// AssertIsBoolean fails if v != 0 || v != 1
	AssertIsBoolean(i1 Variable)

	// AssertIsLessOrEqual fails if  v > bound
	AssertIsLessOrEqual(v Variable, bound Variable)

	// Println behaves like fmt.Println but accepts cd.Variable as parameter
	// whose value will be resolved at runtime when computed by the solver
	Println(a ...Variable)

	// NewHint initializes internal variables whose value will be evaluated
	// using the provided hint function at run time from the inputs. Inputs must
	// be either variables or convertible to *big.Int. The function returns an
	// error if the number of inputs is not compatible with f.
	//
	// The hint function is provided at the proof creation time and is not
	// embedded into the circuit. From the backend point of view, the variable
	// returned by the hint function is equivalent to the user-supplied witness,
	// but its actual value is assigned by the solver, not the caller.
	//
	// No new constraints are added to the newly created wire and must be added
	// manually in the circuit. Failing to do so leads to solver failure.
	NewHint(f hint.Function, inputs ...Variable) ([]Variable, error)

	// Tag creates a tag at a given place in a circuit. The state of the tag may contain informations needed to
	// measure constraints, variables and coefficients creations through AddCounter
	Tag(name string) Tag

	// AddCounter measures the number of constraints, variables and coefficients created between two tags
	// note that the PlonK statistics are contextual since there is a post-compile phase where linear expressions
	// are factorized. That is, measuring 2 times the "repeating" piece of circuit may give less constraints the second time
	AddCounter(from, to Tag)

	// IsConstant returns true if v is a constant known at compile time
	IsConstant(v Variable) bool

	// ConstantValue returns the big.Int value of v. It
	// panics if v.IsConstant() == false
	ConstantValue(v Variable) *big.Int

	// CurveID returns the ecc.ID injected by the compiler
	Curve() ecc.ID

	// Backend returns the backend.ID injected by the compiler
	Backend() backend.ID
}

API represents the available functions to circuit developers

type Builder

type Builder interface {
	API
	CheckVariables() error
	NewPublicVariable(name string) Variable
	NewSecretVariable(name string) Variable
	Compile() (CompiledConstraintSystem, error)
}

Builder represents a constraint system builder

type Circuit

type Circuit interface {
	// Define declares the circuit's Constraints
	Define(api API) 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 CompileOption

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

CompileOption enables to set optional argument to call of frontend.Compile()

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

	CurveID() ecc.ID
	FrSize() int

	// ToHTML generates a human readable representation of the constraint system
	ToHTML(w io.Writer) error

	// GetCounters return the collected constraint counters, if any
	GetCounters() []compiled.Counter
}

CompiledConstraintSystem interface that a compiled (=typed, and correctly routed) should implement.

func Compile

func Compile(curveID ecc.ID, zkpID backend.ID, circuit Circuit, opts ...func(opt *CompileOption) error) (CompiledConstraintSystem, error)

Compile will generate a ConstraintSystem 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, R1CS) to build the internal constraint system from the declarative code

3. finally, it converts that to a ConstraintSystem. 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 Counter

type Counter struct {
	From, To      Tag
	NbVariables   int
	NbConstraints int
}

Counter contains measurements of useful statistics between two Tag

type NewBuilder

type NewBuilder func(ecc.ID) (Builder, error)

type Tag

type Tag struct {
	Name     string
	VID, CID int
}

Tag contains informations needed to measure and display statistics of a delimited piece of circuit

type Variable

type Variable interface{}

Variable represents a variable in the circuit. Any integer type (e.g. int, *big.Int, fr.Element) can be assigned to it. It is also allowed to set a base-10 encoded string representing an integer value. The only purpose of putting this defintion here is to avoid the import cycles (cs/plonk <-> frontend) and (cs/r1cs <-> frontend)