schema

Documentation

Index

• type Field
• type FieldType
• type InitHook
• type LeafCount
  • func Walk(circuit interface{}, tLeaf reflect.Type, handler LeafHandler) (count LeafCount, err error)
• type LeafHandler
• type LeafInfo
• type Schema
  • func New(circuit interface{}, tLeaf reflect.Type) (*Schema, error)
  • func (s Schema) Instantiate(leafType reflect.Type, omitEmptyTag ...bool) interface{}
  • func (s Schema) WriteSequence(w io.Writer) error
• type TagOpt
• type Visibility
  • func (v Visibility) String() string

Types

type Field

type Field struct {
	Name       string
	NameTag    string
	FullName   string
	Visibility Visibility
	Type       FieldType
	SubFields  []Field // will be set only if it's a struct, or an array of struct
	ArraySize  int
}

Field represent a schema Field and is analogous to reflect.StructField (but simplified)

type FieldType

type FieldType uint8

FieldType represents the type a field is allowed to have in a gnark Schema

const (
	Leaf FieldType = iota
	Array
	Struct
)

type InitHook

type InitHook interface {
	GnarkInitHook() // TODO @gbotrel find a better home for this
}

An object implementing an init hook knows how to "init" itself when parsed at compile time

type LeafCount

type LeafCount struct {
	Secret int
	Public int
}

LeafCount stores the number of secret and public interface of type target(reflect.Type) found by the walker.

func Walk

func Walk(circuit interface{}, tLeaf reflect.Type, handler LeafHandler) (count LeafCount, err error)

Walk walks through the provided object and stops when it encounters objects of type tLeaf

It returns the number of secret and public leafs encountered during the walk.

type LeafHandler

type LeafHandler func(field LeafInfo, tValue reflect.Value) error

LeafHandler is the handler function that will be called when Walk reaches leafs of the struct

type LeafInfo

type LeafInfo struct {
	Visibility Visibility
	FullName   func() string // in most instances, we don't need to actually evaluate the name.
	// contains filtered or unexported fields
}

LeafInfo stores the leaf visibility (always set to Secret or Public) and the fully qualified name of the path to reach the leaf in the circuit struct.

type Schema

type Schema struct {
	Fields   []Field
	NbPublic int
	NbSecret int
}

Schema represents the structure of a gnark circuit (/ witness)

func New

func New(circuit interface{}, tLeaf reflect.Type) (*Schema, error)

New builds a schema.Schema walking through the provided interface (a circuit structure).

schema.Walk performs better and should be used when possible.

func (Schema) Instantiate

func (s Schema) Instantiate(leafType reflect.Type, omitEmptyTag ...bool) interface{}

Instantiate builds a concrete type using reflect matching the provided schema

It replaces leafs by provided type, such that one can do:

struct { A []frontend.Variable} -> Schema -> struct {A [12]fr.Element}

Default behavior is to add "json:,omitempty" to the generated struct

func (Schema) WriteSequence

func (s Schema) WriteSequence(w io.Writer) error

WriteSequence writes the expected sequence order of the witness on provided writer witness elements are identified by their tag name, or if unset, struct & field name

The expected sequence matches the binary encoding protocol [public | secret]

type TagOpt

type TagOpt string

TagOpt is a (optional) struct tag one can add to a Variable field in the circuit definition to specify compiler behaviour and witness parsing. The order of the tag matters, the first element in the tag list is always the assumed name of the witness element and the rest of the tags define the properties of the witness element. Valid tag options are given by constants

• TagOptPublic ("public"): element belongs to the public part of the witness;
• TagOptSecret ("secret"): element belongs to the secret part of the witness;
• TagOptInherit ("inherit"): element's visibility is inherited from its parent visibility. Is useful for defining custom types to allow consistent visibility;
• TagOptOmit ("-"): do not insert the element into a witness.

Examples

In the code, it would look like this:

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

If no tags are defined, then the parser by default deduces the name from the field name in the struct. If the witness element is defined on the circuit type level, then applies "secret" visibility and otherwise inherits the visibility of its parent. For example, for a circuit defined as:

type DefaultCircuit struct {
    X frontend.Variable
 }

the assumed name of the field "X" would be "X" and its visibility would be "secret".

To define only a name tag, the options part of tag can be left empty i.e.:

type NameOnlyCircuit struct {
    X frontend.Variable `gnark:"Result"`   // assumed visibility "secret"
}

To define only options tag (and have the parser assume the name for the witness element), keep the name part empty i.e.:

type OptionOnlyCircuit struct {
    X frontend.Variable `gnark:",public"` // assumed name "X"
 }

The tag "-" instructs the compiler to ignore the variable in parsing and compiling. In that case, it is the responsibility of the developer to assign a value to the ignored variable in circuit. Such circuit would look like:

type NoWitnessCircuit struct {
    X frontend.Variable `gnark:"-"`
}

When defining a custom type we use the "inherit" tag. For example, if there is a custom type

type List struct {
    Vals []frontend.Variable `gnark:",inherit"`
}

then we can use this type in the in the circuit definition:

type ListCircuit struct {
    X List `gnark:",secret"`
}

const (
	TagOptPublic  TagOpt = "public"  // public witness element
	TagOptSecret  TagOpt = "secret"  // secret witness element
	TagOptInherit TagOpt = "inherit" // inherit the visibility of the witness element from its parent.
	TagOptOmit    TagOpt = "-"       // do not parse the field as witness element
)

type Visibility

type Visibility uint8

Visibility encodes a Variable (or wire) visibility Possible values are Unset, Internal, Secret or Public

const (
	Unset Visibility = iota
	Internal
	Secret
	Public
	Virtual
)

func (Visibility) String

func (v Visibility) String() string