frontend

Documentation

Overview

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

Index

• func Compile(curveID gurvy.ID, circuit Circuit) (r1cs.R1CS, error)
• func ParseWitness(input interface{}) (map[string]interface{}, error)
• type Circuit
• type ConstraintSystem
  • func (cs *ConstraintSystem) Add(i1, i2 interface{}, in ...interface{}) 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) LinearExpression(terms ...r1c.Term) r1c.LinearExpression
  • func (cs *ConstraintSystem) Mul(i1, i2 interface{}, in ...interface{}) 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) Term(v Variable, coeff *big.Int) r1c.Term
  • func (cs *ConstraintSystem) ToBinary(a Variable, nbBits int) []Variable
  • func (cs *ConstraintSystem) Xor(a, b Variable) Variable
• type Tag
• type Variable
  • func (v *Variable) Assign(value interface{})

Functions

func Compile

func Compile(curveID gurvy.ID, circuit Circuit) (r1cs.R1CS, error)

Compile will generate a R1CS 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 R1CS

func ParseWitness

func ParseWitness(input interface{}) (map[string]interface{}, error)

ParseWitness will returns a map[string]interface{} to be used as input in in R1CS.Solve(), groth16.Prove() or groth16.Verify()

if input is not already a map[string]interface{}, it must implement frontend.Circuit

Types

type Circuit

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

Circuit must be implemented by user-defined circuits

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) 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 backend.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)

func (*ConstraintSystem) LinearExpression

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

LinearExpression packs a list of r1c.Term in a r1c.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) 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) Term

func (cs *ConstraintSystem) Term(v Variable, coeff *big.Int) r1c.Term

Term packs a variable and a coeff in a r1c.Term and returns it.

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 Tag

type Tag string

Tag is a (optional) struct tag one can add to Variable to specify frontend.Compile() behavior

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 Variable

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

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

func (*Variable) Assign

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

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