frontend

Documentation

Index

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

Functions

func NewWitness

func NewWitness(assignment Circuit, curveID ecc.ID, opts ...WitnessOption) (*witness.Witness, error)

NewWitness build an orderded vector of field elements from the given assignment (Circuit) if PublicOnly is specified, returns the public part of the witness only else returns [public | secret]. The result can then be serialized to / from json & binary

Returns an error if the assignment has missing entries

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 /!\

Types

type API

type API interface {

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

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

	// Sub returns res = i1 - i2 - ...in
	Sub(i1, i2 Variable, in ...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

	// Cmp returns 1 if i1>i2, 0 if i1=i2, -1 if i1<i2
	Cmp(i1, i2 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)
	SetSchema(*schema.Schema)
}

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 func(opt *compileConfig) error

CompileOption defines option for altering the behaviour of the Compile method. See the descriptions of the functions returning instances of this type for available options.

func IgnoreUnconstrainedInputs

func IgnoreUnconstrainedInputs() CompileOption

IgnoreUnconstrainedInputs is a compile option which allow compiling input circuits where not all inputs are not constrained. If not set, then the compiler returns an error if there exists an unconstrained input.

This option is useful for debugging circuits, but should not be used in production settings as it means that there is a potential error in the circuit definition or that it is possible to optimize witness size.

func WithBuilder

func WithBuilder(builder NewBuilder) CompileOption

WithBuilder is a compile option which 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) CompileOption

WithCapacity is a compile option that specifies the estimated capacity needed for internal variables and constraints. If not set, then the initial capacity is 0 and is dynamically allocated as needed.

type CompiledConstraintSystem

type CompiledConstraintSystem interface {
	io.WriterTo
	io.ReaderFrom

	// IsSolved returns nil if given witness solves the constraint system and error otherwise
	IsSolved(witness *witness.Witness, opts ...backend.ProverOption) error

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

	CurveID() ecc.ID
	FrSize() int

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

	GetSchema() *schema.Schema

	// GetConstraints return a human readable representation of the constraints
	GetConstraints() [][]string
}

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

func Compile

func Compile(curveID ecc.ID, zkpID backend.ID, circuit Circuit, opts ...CompileOption) (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)

type WitnessOption

type WitnessOption func(*witnessConfig) error

WitnessOption sets optional parameter to witness instantiation from an assigment

func PublicOnly

func PublicOnly() WitnessOption

PublicOnly enables to instantiate a witness with the public part only of the assignment