Struct PermutationRelation 

pub struct PermutationRelation<T, const WIDTH: usize> { /* private fields */ }

A relation over evaluations of a permutation acting on WIDTH wires.

Handles are reference counted: cloning one, as DuplexSponge::from does, shares the relation rather than forking it, so the queries a sponge makes are visible on every handle.

use spongefish::{DuplexSponge, DuplexSpongeInterface};
use spongefish_circuit::PermutationRelation;

let relation = PermutationRelation::<u32, 4>::new();
let public = relation.allocate_vars_with(&[1, 2]);
let secret = relation.allocate_vars::<2>();

let mut sponge = DuplexSponge::<_, 4, 2>::from(relation.clone());
let [digest] = sponge.absorb(&public).absorb(&secret).squeeze_array();
relation.set_var(digest, 42);

let instance = relation.compile().unwrap();
assert_eq!(instance.queries().len(), 2);

Implementations

impl<T: Unit, const WIDTH: usize> PermutationRelation<T, WIDTH>

pub fn new() -> Self

An unlabeled relation over a fresh VarAllocator.

pub fn labeled(label: impl Into<String>) -> Self

A relation naming its permutation, such as keccak-f[1600].

The label travels with the compiled instance and its byte encoding, so a proof system can check it is being handed the permutation it implements. It is free text; the relation does not interpret it.

pub fn with_allocator(allocator: VarAllocator<T>) -> Self

A relation sharing allocator with other relations.

pub fn label(&self) -> &str

The permutation’s label, empty unless set by Self::labeled.

pub const fn allocator(&self) -> &VarAllocator<T>

The allocator, for sharing wires with another relation.

pub fn allocate_var(&self) -> FieldVar

See VarAllocator::allocate_var.

pub fn allocate_vars<const N: usize>(&self) -> [FieldVar; N]

See VarAllocator::allocate_vars.

pub fn allocate_vars_vec(&self, count: usize) -> Vec<FieldVar>

See VarAllocator::allocate_vars_vec.

pub fn allocate_var_with(&self, value: T) -> FieldVar

where T: PartialEq,

See VarAllocator::allocate_var_with.

pub fn allocate_vars_with<const N: usize>( &self, values: &[T; N], ) -> [FieldVar; N]

where T: PartialEq,

See VarAllocator::allocate_vars_with.

pub fn allocate_vars_vec_with(&self, values: &[T]) -> Vec<FieldVar>

where T: PartialEq,

See VarAllocator::allocate_vars_vec_with.

pub fn set_var(&self, var: FieldVar, value: T)

where T: PartialEq,

See VarAllocator::set_var.

pub fn set_vars<Var, Val>( &self, vars: impl IntoIterator<Item = Var>, values: impl IntoIterator<Item = Val>, )

where Var: Borrow<FieldVar>, Val: Borrow<T>, T: PartialEq,

See VarAllocator::set_vars.

pub fn allocate_permutation( &self, input: &[FieldVar; WIDTH], ) -> [FieldVar; WIDTH]

Records a query of the permutation on input, returning fresh output wires.

pub fn add_permutation( &self, input: [FieldVar; WIDTH], output: [FieldVar; WIDTH], )

Records that the permutation maps input to output.

pub fn add_equation(&self, terms: impl Into<Sum<T>>, image: T)

Adds the equation terms = image.

Terms are built with the operators on FieldVar: x * a + y * b + z weights x by a, y by b, and z by one. Every wire with a nonzero weight must be an input or output of some query, or be assigned; Self::compile rejects the equation otherwise, as nothing else would fix the wire’s value.

pub fn queries(&self) -> Vec<QueryAnswerPair<FieldVar, WIDTH>>

The queries recorded so far.

pub fn equations(&self) -> Vec<LinearEquation<T>>

The equations recorded so far.

pub fn public_vars(&self) -> Vec<(FieldVar, T)>

See VarAllocator::public_vars.

pub fn compile(&self) -> Result<PermutationInstance<T, WIDTH>, InvalidRelation>

where T: PartialEq,

Compiles the relation into a validated PermutationInstance.

Every wire a query or an equation mentions must have been allocated, and every wire with a nonzero weight in an equation must be bound: an input or output of some query, or assigned a value. Wires that are allocated but neither bound nor mentioned are left in place, so wire indices are the same on both sides of this call.

Trait Implementations

impl<T, const WIDTH: usize> Clone for PermutationRelation<T, WIDTH>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Unit, const WIDTH: usize> Default for PermutationRelation<T, WIDTH>

fn default() -> Self

Returns the “default value” for a type.

impl<T: Unit, const WIDTH: usize> Permutation<WIDTH> for PermutationRelation<T, WIDTH>

fn permute_mut(&self, state: &mut [Self::U; WIDTH])

A query mints fresh output wires rather than mixing the state in place, so both maps go through Self::allocate_permutation.

type U = FieldVar

The Unit defining the alphabet for the permutation function.

fn permute(&self, state: &[Self::U; WIDTH]) -> [Self::U; WIDTH]

The permutation function.