circuits

package
v0.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 4, 2026 License: AGPL-3.0 Imports: 36 Imported by: 0

Documentation

Overview

Package circuits provides functionality for working with zero-knowledge proof circuits and their associated artifacts (circuit definitions, proving keys, and verification keys). It includes utilities for loading, downloading, and verifying the integrity of these artifacts.

Index

Constants

View Source 
const (
	EncryptionKeySerializedLen = 2
)

Variables

View Source 
var (
	ErrArtifactNotFound     = errors.New("artifact not found in cache")
	ErrArtifactHashMismatch = errors.New("artifact hash mismatch")
)
View Source 
var BaseDir string

BaseDir is the path where the artifact cache is expected to be found. If the artifacts are not found there, they will be downloaded and stored. It can be set to a different path if needed from other packages. Defaults to the env var DAVINCI_ARTIFACTS_DIR or the user home directory.

View Source 
var Poseidon377Domain = poseidon377.DomainFromLEBytes([]byte("/davinci/"))

Poseidon377Domain is the domain used for Poseidon377 hashing

View Source 
var Poseidon377DomainVar frontend.Variable

Poseidon377DomainVar is the domain as a frontend.Variable for use in circuits

Functions

func AssertIsEqualIf added in v0.0.2 

func AssertIsEqualIf(api frontend.API, condition, i1, i2 frontend.Variable)

AssertIsEqualIf fails if condition is true and i1 != i2. If condition is false, the check is skipped.

func AssertTrueIf added in v0.0.2 

func AssertTrueIf(api frontend.API, condition, mustBeTrue frontend.Variable)

AssertTrueIf fails if condition is true and mustBeTrue is not (mustBeTrue != 1). If condition is false, the check is skipped.

func BallotHash 

func BallotHash(
	api frontend.API,
	process Process[frontend.Variable],
	vote Vote[frontend.Variable],
) []frontend.Variable

BallotHash returns the inputs hashed for BallotHash in this order: 

Process.ID
Process.BallotMode
Process.EncryptionKey (in Twisted Edwards format)
Vote.Address
Vote.VoteID
Vote.Ballot (in Twisted Edwards format)
Vote.UserWeight

func BigIntArrayToN 

func BigIntArrayToN(arr []*big.Int, n int) []*big.Int

BigIntArrayToN pads the big.Int array to n elements, if needed, with zeros.

func BigIntArrayToNInternal 

func BigIntArrayToNInternal(arr []*big.Int, n int) []*types.BigInt

BigIntArrayToNInternal pads the types.BigInt array to n elements, if needed, with zeros.

func FrontendError 

func FrontendError(api frontend.API, msg string, trace error)

FrontendError function is an in-circuit function to print an error message and an error trace, making the circuit fail.

func NextK 

func NextK(api frontend.API, k frontend.Variable) frontend.Variable

NextK uses the Poseidon hasher to generate a new k starting from the provided k.

Types

type Artifact 

type Artifact struct {
	RemoteURL string
	Hash      []byte
}

Artifact describes a cached/downloadable circuit artifact by hash and source URL.

type Ballot 

type Ballot [params.FieldsPerBallot]elgamal.Ciphertext

func NewBallot 

func NewBallot() *Ballot

func (*Ballot) Add 

func (z *Ballot) Add(api frontend.API, x, y *Ballot) *Ballot

Add sets z to the sum x+y and returns z.

Panics if twistededwards curve init fails.

func (*Ballot) AssertDecrypt 

func (z *Ballot) AssertDecrypt(api frontend.API, privKey frontend.Variable, originals [params.FieldsPerBallot]frontend.Variable)

AssertDecrypt checks that the ballot can be decrypted with the provided private key and the original values. It uses the elgamal.Ciphertext's AssertDecrypt method for each ciphertext in the ballot.

func (*Ballot) AssertIsEqual 

func (z *Ballot) AssertIsEqual(api frontend.API, x *Ballot)

AssertIsEqual fails if any of the fields differ between z and x

func (*Ballot) Encrypt 

func (z *Ballot) Encrypt(
	api frontend.API,
	messages [params.FieldsPerBallot]frontend.Variable,
	encKey EncryptionKey[frontend.Variable],
	k frontend.Variable,
) *Ballot

Encrypt encrypts the ballot using the provided encryption key and messages. It uses the Poseidon hasher to generate a new k for each ciphertext starting from the provided k.

func (*Ballot) EncryptedZero 

func (b *Ballot) EncryptedZero(api frontend.API, encKey EncryptionKey[frontend.Variable], k frontend.Variable) *Ballot

EncryptedZero returns a new ballot with all fields set to the encrypted zero point using the provided encryption key and k.

func (*Ballot) IsEqual 

func (z *Ballot) IsEqual(api frontend.API, x *Ballot) frontend.Variable

func (*Ballot) Neg added in v0.0.7 

func (z *Ballot) Neg(api frontend.API, x *Ballot) *Ballot

Neg sets z to the negation of x and returns z.

func (*Ballot) Reencrypt 

func (z *Ballot) Reencrypt(api frontend.API, encKey EncryptionKey[frontend.Variable], k frontend.Variable) (*Ballot, frontend.Variable, error)

Reencrypt re-encrypts the ballot using the provided encryption key and the provided k. To re-encrypt the ballot, it uses the encrypted zero point with the inputs provided and them adds it to the original ballot. It uses the Poseidon hasher to generate a new k for each ciphertext starting from the provided k.

func (*Ballot) Select 

func (z *Ballot) Select(api frontend.API, b frontend.Variable, i1 *Ballot, i2 *Ballot) *Ballot

Select if b is true, sets z = i1, else z = i2, and returns z

func (*Ballot) Serialize 

func (z *Ballot) Serialize(api frontend.API) []emulated.Element[sw_bn254.ScalarField]

Serialize returns a slice with the C1.X, C1.Y, C2.X, C2.Y in order

func (*Ballot) SerializeVars 

func (z *Ballot) SerializeVars() []frontend.Variable

Serialize returns a slice with the C1.X, C1.Y, C2.X, C2.Y in order

func (*Ballot) ToEmulatedBallot 

func (z *Ballot) ToEmulatedBallot(api frontend.API) EmulatedBallot[sw_bn254.ScalarField]

type CircuitArtifacts 

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

CircuitArtifacts is a struct that holds the artifacts of a zkSNARK circuit (definition, proving and verification key). It provides a method to load the keys from the local cache or download them from the remote URLs provided.

func NewCircuitArtifacts 

func NewCircuitArtifacts(name string, curve ecc.ID, proverOpts []backend.ProverOption, verifierOpts []backend.VerifierOption,
	circuit, provingKey, verifyingKey *Artifact,
) *CircuitArtifacts

NewCircuitArtifacts creates a new CircuitArtifacts struct with the circuit artifacts provided. It returns the struct with the artifacts set.

func (*CircuitArtifacts) CircuitHash added in v0.0.2 

func (ca *CircuitArtifacts) CircuitHash() []byte

CircuitHash returns the circuit-definition hash.

func (CircuitArtifacts) Curve added in v0.0.2 

func (c CircuitArtifacts) Curve() ecc.ID

Curve returns the elliptic curve identifier associated with this circuit.

func (*CircuitArtifacts) Download added in v0.0.4 

func (ca *CircuitArtifacts) Download(ctx context.Context) error

Download ensures all artifacts are available, downloading them if necessary.

func (*CircuitArtifacts) LoadOrDownload added in v0.0.4 

func (ca *CircuitArtifacts) LoadOrDownload(ctx context.Context) (cr *CircuitRuntime, err error)

LoadOrDownload ensures all artifacts are available, downloading them if necessary, and returns a ready-to-use CircuitRuntime.

func (*CircuitArtifacts) LoadOrDownloadCircuitDefinition added in v0.0.4 

func (ca *CircuitArtifacts) LoadOrDownloadCircuitDefinition(ctx context.Context) (constraint.ConstraintSystem, error)

LoadOrDownloadCircuitDefinition downloads any missing circuit definition artifact and decodes it into memory.

func (*CircuitArtifacts) LoadOrDownloadProvingKey added in v0.0.4 

func (ca *CircuitArtifacts) LoadOrDownloadProvingKey(ctx context.Context) (groth16.ProvingKey, error)

LoadOrDownloadProvingKey downloads any missing proving key artifact and decodes it into memory.

func (*CircuitArtifacts) LoadOrDownloadVerifyingKey added in v0.0.4 

func (ca *CircuitArtifacts) LoadOrDownloadVerifyingKey(ctx context.Context) (groth16.VerifyingKey, error)

LoadOrDownloadVerifyingKey downloads any missing verifying key artifact and decodes it into memory.

func (*CircuitArtifacts) LoadOrSetupForCircuit added in v0.0.4 

func (ca *CircuitArtifacts) LoadOrSetupForCircuit(ctx context.Context, circuit frontend.Circuit) (*CircuitRuntime, error)

LoadOrSetupForCircuit compiles the provided circuit and returns a runtime consistent with it. It reuses configured artifacts when the compiled circuit hash matches, and otherwise sets up fresh proving and verifying keys.

func (*CircuitArtifacts) Matches added in v0.0.4 

func (ca *CircuitArtifacts) Matches(ccs constraint.ConstraintSystem) (bool, error)

Matches reports whether the provided compiled circuit definition matches the configured circuit artifact hash.

func (CircuitArtifacts) Name added in v0.0.4 

func (c CircuitArtifacts) Name() string

Name returns the logical name associated with this circuit.

func (CircuitArtifacts) ProverOptions added in v0.0.4 

func (c CircuitArtifacts) ProverOptions() []backend.ProverOption

ProverOptions returns the prover options associated with this circuit.

func (*CircuitArtifacts) ProvingKeyHash added in v0.0.2 

func (ca *CircuitArtifacts) ProvingKeyHash() []byte

ProvingKeyHash returns the proving-key hash.

func (*CircuitArtifacts) RawVerifyingKey 

func (ca *CircuitArtifacts) RawVerifyingKey() ([]byte, error)

RawVerifyingKey returns the content of the verifying key as types.HexBytes. It returns an error if the verifying key is not locally available or cannot be serialized.

func (*CircuitArtifacts) Setup added in v0.0.4 

func (ca *CircuitArtifacts) Setup(ccs constraint.ConstraintSystem) (*CircuitRuntime, error)

Setup generates fresh proving and verifying keys for the provided compiled circuit definition and returns a runtime built from them.

func (CircuitArtifacts) VerifierOptions added in v0.0.4 

func (c CircuitArtifacts) VerifierOptions() []backend.VerifierOption

VerifierOptions returns the verifier options associated with this circuit.

func (*CircuitArtifacts) VerifyingKeyHash added in v0.0.2 

func (ca *CircuitArtifacts) VerifyingKeyHash() []byte

VerifyingKeyHash returns the verifying-key hash.

type CircuitRuntime added in v0.0.4 

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

CircuitRuntime is a fully initialized runtime view of a circuit's decoded artifacts. Once constructed, its getters are infallible.

func NewCircuitRuntime added in v0.0.4 

func NewCircuitRuntime(name string, curve ecc.ID, proverOpts []backend.ProverOption, verifierOpts []backend.VerifierOption,
	ccs constraint.ConstraintSystem, pk groth16.ProvingKey, vk groth16.VerifyingKey,
) *CircuitRuntime

NewCircuitRuntime constructs a runtime from already-decoded artifacts.

func (*CircuitRuntime) ConstraintSystem added in v0.0.4 

func (cr *CircuitRuntime) ConstraintSystem() constraint.ConstraintSystem

ConstraintSystem returns the decoded constraint system.

func (CircuitRuntime) Curve added in v0.0.4 

func (c CircuitRuntime) Curve() ecc.ID

Curve returns the elliptic curve identifier associated with this circuit.

func (CircuitRuntime) Name added in v0.0.4 

func (c CircuitRuntime) Name() string

Name returns the logical name associated with this circuit.

func (*CircuitRuntime) Prove added in v0.0.4 

func (cr *CircuitRuntime) Prove(assignment frontend.Circuit) (proof groth16.Proof, err error)

Prove generates a proof from the assignment.

func (*CircuitRuntime) ProveAndVerify added in v0.0.4 

func (cr *CircuitRuntime) ProveAndVerify(assignment frontend.Circuit) (groth16.Proof, error)

ProveAndVerify generates a proof from the assignment and verifies it immediately.

func (*CircuitRuntime) ProveAndVerifyWithWitness added in v0.0.4 

func (cr *CircuitRuntime) ProveAndVerifyWithWitness(fullWitness witness.Witness) (groth16.Proof, error)

ProveAndVerifyWithWitness generates a proof from a full witness and verifies it immediately.

func (*CircuitRuntime) ProveWithWitness added in v0.0.4 

func (cr *CircuitRuntime) ProveWithWitness(fullWitness witness.Witness) (proof groth16.Proof, err error)

ProveWithWitness generates a proof from a full witness.

func (CircuitRuntime) ProverOptions added in v0.0.4 

func (c CircuitRuntime) ProverOptions() []backend.ProverOption

ProverOptions returns the prover options associated with this circuit.

func (*CircuitRuntime) ProvingKey added in v0.0.4 

func (cr *CircuitRuntime) ProvingKey() groth16.ProvingKey

ProvingKey returns the decoded proving key.

func (CircuitRuntime) VerifierOptions added in v0.0.4 

func (c CircuitRuntime) VerifierOptions() []backend.VerifierOption

VerifierOptions returns the verifier options associated with this circuit.

func (*CircuitRuntime) Verify added in v0.0.4 

func (cr *CircuitRuntime) Verify(proof groth16.Proof, publicAssignment frontend.Circuit) (err error)

Verify builds a public witness from the public assignment and verifies the proof.

func (*CircuitRuntime) VerifyWithWitness added in v0.0.4 

func (cr *CircuitRuntime) VerifyWithWitness(proof groth16.Proof, publicWitness witness.Witness) (err error)

VerifyWithWitness verifies the proof using the public witness.

func (*CircuitRuntime) VerifyingKey added in v0.0.4 

func (cr *CircuitRuntime) VerifyingKey() groth16.VerifyingKey

VerifyingKey returns the decoded verifying key.

type EmulatedBallot 

type EmulatedBallot[F emulated.FieldParams] [params.FieldsPerBallot]EmulatedCiphertext[F]

EmulatedBallot is a copy of the Ballot struct, but using the EmulatedCiphertext type

func NewEmulatedBallot 

func NewEmulatedBallot[F emulated.FieldParams]() *EmulatedBallot[F]

NewEmulatedBallot returns a new EmulatedBallot with all fields with both points to zero point (0, 1).

func (*EmulatedBallot[F]) Serialize 

func (z *EmulatedBallot[F]) Serialize() []emulated.Element[F]

Serialize returns a slice with the C1.X, C1.Y, C2.X, C2.Y in order

func (*EmulatedBallot[F]) SerializeAsTE 

func (zt *EmulatedBallot[F]) SerializeAsTE(api frontend.API) []emulated.Element[sw_bn254.ScalarField]

SerializeAsTE returns a slice with the C1.X, C1.Y, C2.X, C2.Y in order, in Twisted Edwards format (rather than Reduced Twisted Edwards)

type EmulatedCiphertext 

type EmulatedCiphertext[F emulated.FieldParams] struct {
	C1, C2 EmulatedPoint[F]
}

EmulatedCiphertext struct is a copy of the elgamal.Ciphertext struct, but using the EmulatedPoint type

type EmulatedPoint 

type EmulatedPoint[F emulated.FieldParams] struct {
	X, Y emulated.Element[F]
}

EmulatedPoint struct is a copy of the elgamal.Point struct, but using the emulated.Element type

type EmulatedVote 

type EmulatedVote[F emulated.FieldParams] struct {
	Address    emulated.Element[F]
	VoteID     emulated.Element[F]
	Ballot     EmulatedBallot[F]
	VoteWeight emulated.Element[F]
}

EmulatedVote is a copy of the Vote struct, but using the emulated.Element type as generic type for the Address, VoteID fields and the EmulatedBallot type for the Ballot field.

func (*EmulatedVote[F]) Serialize 

func (z *EmulatedVote[F]) Serialize() []emulated.Element[F]

Serialize returns a slice with the vote parameters in order 

EmulatedVote.Address
EmulatedVote.VoteID
EmulatedVote.UserWeight
EmulatedVote.Ballot

func (*EmulatedVote[F]) SerializeForBallotProof 

func (zt *EmulatedVote[F]) SerializeForBallotProof(api frontend.API) []emulated.Element[sw_bn254.ScalarField]

SerializeForBallotProof returns a slice with the vote parameters in order 

	EmulatedVote.Address
	EmulatedVote.VoteID
	EmulatedVote.Ballot (in Twisted Edwards format)
 EmulatedVote.UserWeight

type EncryptionKey 

type EncryptionKey[T any] struct {
	PubKey [2]T
}

func EncryptionKeyFromECCPoint 

func EncryptionKeyFromECCPoint(p ecc.Point) EncryptionKey[*big.Int]

func (EncryptionKey[T]) AsVar 

func (k EncryptionKey[T]) AsVar() EncryptionKey[frontend.Variable]

AsVar returns the EncryptionKey as a different type. Returns an empty EncryptionKey if T is not *big.Int.

func (EncryptionKey[T]) BigIntsToEmulatedElementBN254 

func (k EncryptionKey[T]) BigIntsToEmulatedElementBN254() EncryptionKey[emulated.Element[sw_bn254.ScalarField]]

BigIntsToEmulatedElementBN254 returns the EncryptionKey as a different type. Returns an empty EncryptionKey if T is not *big.Int.

func (EncryptionKey[T]) Bytes 

func (k EncryptionKey[T]) Bytes() []byte

Bytes returns 2*32 bytes representing PubKey components. Returns an empty slice if T is not *big.Int.

func (EncryptionKey[T]) Deserialize 

func (k EncryptionKey[T]) Deserialize(values []T) (EncryptionKey[T], error)

func (EncryptionKey[T]) Serialize 

func (k EncryptionKey[T]) Serialize() []T

func (EncryptionKey[T]) SerializeAsTE 

func (kt EncryptionKey[T]) SerializeAsTE(api frontend.API) []emulated.Element[sw_bn254.ScalarField]

SerializeAsTE returns the EncryptionKey in Twisted Edwards format

func (EncryptionKey[T]) VarsToEmulatedElementBN254 

func (k EncryptionKey[T]) VarsToEmulatedElementBN254(api frontend.API) EncryptionKey[emulated.Element[sw_bn254.ScalarField]]

VarsToEmulatedElementBN254 returns the EncryptionKey as a different type. Returns an empty EncryptionKey if T is not frontend.Variable

type Process 

type Process[T any] struct {
	ID            T
	CensusOrigin  T
	BallotMode    T
	EncryptionKey EncryptionKey[T]
}

Process is a struct that contains the common inputs for a process. Is a generic struct that can be used with any type of circuit input.

func (Process[T]) Serialize 

func (p Process[T]) Serialize() []T

Serialize returns a slice with the process parameters in order 

Process.ID
Process.CensusOrigin
Process.BallotMode
Process.EncryptionKey

func (Process[T]) SerializeForBallotProof 

func (pt Process[T]) SerializeForBallotProof(api frontend.API) []emulated.Element[sw_bn254.ScalarField]

SerializeForBallotProof returns a slice with the process parameters in order 

Process.ID
Process.BallotMode
Process.EncryptionKey (in Twisted Edwards format)

func (Process[T]) VarsToEmulatedElementBN254 

func (p Process[T]) VarsToEmulatedElementBN254(api frontend.API) Process[emulated.Element[sw_bn254.ScalarField]]

type Vote 

type Vote[T any] struct {
	Ballot     Ballot
	VoteID     T
	Address    T
	VoteWeight T
}

Vote is a struct that contains all data related to a vote. Is a generic struct that can be used with any type of circuit input.

func (Vote[T]) SerializeAsVars 

func (v Vote[T]) SerializeAsVars(api frontend.API) []frontend.Variable

func (Vote[T]) ToEmulated 

func (v Vote[T]) ToEmulated(api frontend.API) EmulatedVote[sw_bn254.ScalarField]

Source Files

View all Source files

Directories

Path Synopsis
aggregator package contains the Gnark circuit defiinition that aggregates some votes and proves the validity of the aggregation.
 aggregator package contains the Gnark circuit defiinition that aggregates some votes and proves the validity of the aggregation.
aggregator
ballotproof
statetransition
voteverifier
voteverifier package contains the Gnark circuit definition that verifies a vote package to be aggregated by the vote aggregator and included in a new state transition.
 voteverifier package contains the Gnark circuit definition that verifies a vote package to be aggregated by the vote aggregator and included in a new state transition.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.