Enum BlackBoxFuncCall

pub enum BlackBoxFuncCall<F> {
    AES128Encrypt {
        inputs: Vec<FunctionInput<F>>,
        iv: Box<[FunctionInput<F>; 16]>,
        key: Box<[FunctionInput<F>; 16]>,
        outputs: Vec<Witness>,
    },
    AND {
        lhs: FunctionInput<F>,
        rhs: FunctionInput<F>,
        output: Witness,
    },
    XOR {
        lhs: FunctionInput<F>,
        rhs: FunctionInput<F>,
        output: Witness,
    },
    RANGE {
        input: FunctionInput<F>,
    },
    Blake2s {
        inputs: Vec<FunctionInput<F>>,
        outputs: Box<[Witness; 32]>,
    },
    Blake3 {
        inputs: Vec<FunctionInput<F>>,
        outputs: Box<[Witness; 32]>,
    },
    EcdsaSecp256k1 {
        public_key_x: Box<[FunctionInput<F>; 32]>,
        public_key_y: Box<[FunctionInput<F>; 32]>,
        signature: Box<[FunctionInput<F>; 64]>,
        hashed_message: Box<[FunctionInput<F>; 32]>,
        output: Witness,
    },
    EcdsaSecp256r1 {
        public_key_x: Box<[FunctionInput<F>; 32]>,
        public_key_y: Box<[FunctionInput<F>; 32]>,
        signature: Box<[FunctionInput<F>; 64]>,
        hashed_message: Box<[FunctionInput<F>; 32]>,
        output: Witness,
    },
    MultiScalarMul {
        points: Vec<FunctionInput<F>>,
        scalars: Vec<FunctionInput<F>>,
        outputs: (Witness, Witness, Witness),
    },
    EmbeddedCurveAdd {
        input1: Box<[FunctionInput<F>; 3]>,
        input2: Box<[FunctionInput<F>; 3]>,
        outputs: (Witness, Witness, Witness),
    },
    Keccakf1600 {
        inputs: Box<[FunctionInput<F>; 25]>,
        outputs: Box<[Witness; 25]>,
    },
    RecursiveAggregation {
        verification_key: Vec<FunctionInput<F>>,
        proof: Vec<FunctionInput<F>>,
        public_inputs: Vec<FunctionInput<F>>,
        key_hash: FunctionInput<F>,
        proof_type: u32,
    },
    BigIntAdd {
        lhs: u32,
        rhs: u32,
        output: u32,
    },
    BigIntSub {
        lhs: u32,
        rhs: u32,
        output: u32,
    },
    BigIntMul {
        lhs: u32,
        rhs: u32,
        output: u32,
    },
    BigIntDiv {
        lhs: u32,
        rhs: u32,
        output: u32,
    },
    BigIntFromLeBytes {
        inputs: Vec<FunctionInput<F>>,
        modulus: Vec<u8>,
        output: u32,
    },
    BigIntToLeBytes {
        input: u32,
        outputs: Vec<Witness>,
    },
    Poseidon2Permutation {
        inputs: Vec<FunctionInput<F>>,
        outputs: Vec<Witness>,
        len: u32,
    },
    Sha256Compression {
        inputs: Box<[FunctionInput<F>; 16]>,
        hash_values: Box<[FunctionInput<F>; 8]>,
        outputs: Box<[Witness; 8]>,
    },
}

These opcodes represent a specialized computation. Even if any computation can be done using only assert-zero opcodes, it is not always efficient. Some proving systems, can implement several computations more efficiently using techniques such as custom gates and lookup tables.

Variants

AES128Encrypt

Ciphers (encrypts) the provided plaintext using AES128 in CBC mode, padding the input using PKCS#7.

• inputs: byte array [u8; N]
• iv: initialization vector [u8; 16]
• key: user key [u8; 16]
• outputs: byte vector [u8] of length input.len() + (16 - input.len() % 16)

Fields

inputs: Vec<FunctionInput<F>>

iv: Box<[FunctionInput<F>; 16]>

key: Box<[FunctionInput<F>; 16]>

outputs: Vec<Witness>

AND

Performs the bitwise AND of lhs and rhs. bit_size must be the same for both inputs.

• lhs: (witness, bit_size)
• rhs: (witness, bit_size)
• output: a witness whose value is constrained to be lhs AND rhs, as bit_size bit integers

Fields

lhs: FunctionInput<F>

rhs: FunctionInput<F>

output: Witness

XOR

Performs the bitwise XOR of lhs and rhs. bit_size must be the same for both inputs.

• lhs: (witness, bit_size)
• rhs: (witness, bit_size)
• output: a witness whose value is constrained to be lhs XOR rhs, as bit_size bit integers

Fields

lhs: FunctionInput<F>

rhs: FunctionInput<F>

output: Witness

RANGE

Range constraint to ensure that a witness can be represented in the specified number of bits.

• input: (witness, bit_size)

Fields

input: FunctionInput<F>

Blake2s

Computes the Blake2s hash of the inputs, as specified in https://tools.ietf.org/html/rfc7693

• inputs are a byte array, i.e a vector of (witness, 8)
• output is a byte array of length 32, i.e. an array of 32 (witness, 8), constrained to be the blake2s of the inputs.

Fields

inputs: Vec<FunctionInput<F>>

outputs: Box<[Witness; 32]>

Blake3

Computes the Blake3 hash of the inputs

• inputs are a byte array, i.e a vector of (witness, 8)
• output is a byte array of length 32, i.e an array of 32 (witness, 8), constrained to be the blake3 of the inputs.

Fields

inputs: Vec<FunctionInput<F>>

outputs: Box<[Witness; 32]>

EcdsaSecp256k1

Verifies a ECDSA signature over the secp256k1 curve.

• inputs:
  • x coordinate of public key as 32 bytes
  • y coordinate of public key as 32 bytes
  • the signature, as a 64 bytes array The signature internally will be represented as (r, s), where r and s are fixed-sized big endian scalar values. As the secp256k1 has a 256-bit modulus, we have a 64 byte signature while r and s will both be 32 bytes. We expect s to be normalized. This means given the curve’s order, s should be less than or equal to order / 2. This is done to prevent malleability. For more context regarding malleability you can reference BIP 0062.
  • the hash of the message, as a vector of bytes
• output: 0 for failure and 1 for success

Expected backend behavior:

• The backend MAY fail to prove this opcode if the public key is not on the secp256k1 curve.
  • Otherwise the backend MUST constrain the output to be false.
• The backend MUST constrain the output to be false if s is not normalized.
• The backend MUST constrain the output to match the signature’s validity.

Fields

public_key_x: Box<[FunctionInput<F>; 32]>

public_key_y: Box<[FunctionInput<F>; 32]>

signature: Box<[FunctionInput<F>; 64]>

hashed_message: Box<[FunctionInput<F>; 32]>

output: Witness

EcdsaSecp256r1

Verifies a ECDSA signature over the secp256r1 curve.

Same as EcdsaSecp256k1, but done over another curve.

Fields

public_key_x: Box<[FunctionInput<F>; 32]>

public_key_y: Box<[FunctionInput<F>; 32]>

signature: Box<[FunctionInput<F>; 64]>

hashed_message: Box<[FunctionInput<F>; 32]>

output: Witness

MultiScalarMul

Multiple scalar multiplication (MSM) with a variable base/input point (P) of the embedded curve. An MSM multiplies the points and scalars and sums the results.

• input:
  • points (witness, N) a vector of x and y coordinates of input
  • points [x1, y1, x2, y2,...].
  • scalars (witness, N) a vector of low and high limbs of input
  • scalars [s1_low, s1_high, s2_low, s2_high, ...]. (witness, N) For Barretenberg, they must both be less than 128 bits.
• output:
  • a tuple of x and y coordinates of output points computed as s_low*P+s_high*2^{128}*P

Because the Grumpkin scalar field is bigger than the ACIR field, we provide 2 ACIR fields representing the low and high parts of the Grumpkin scalar $a$: a=low+high*2^{128}, with low, high < 2^{128}

Fields

points: Vec<FunctionInput<F>>

scalars: Vec<FunctionInput<F>>

outputs: (Witness, Witness, Witness)

EmbeddedCurveAdd

Addition over the embedded curve on which the witness is defined The opcode makes the following assumptions but does not enforce them because it is more efficient to do it only when required. For instance, adding two points that are on the curve it guarantee to give a point on the curve.

It assumes that the points are on the curve. If the inputs are the same witnesses index, it will perform a doubling, If not, it assumes that the points’ x-coordinates are not equal. It also assumes neither point is the infinity point.

Fields

input1: Box<[FunctionInput<F>; 3]>

input2: Box<[FunctionInput<F>; 3]>

outputs: (Witness, Witness, Witness)

Keccakf1600

Keccak Permutation function of width 1600

• inputs: An array of 25 64-bit Keccak lanes that represent a keccak sponge of 1600 bits
• outputs: The result of a keccak f1600 permutation on the input state. Also an array of 25 Keccak lanes.

Fields

inputs: Box<[FunctionInput<F>; 25]>

outputs: Box<[Witness; 25]>

RecursiveAggregation

Computes a recursive aggregation object when verifying a proof inside another circuit. The outputted aggregation object will then be either checked in a top-level verifier or aggregated upon again. The aggregation object should be maintained by the backend implementer.

This opcode prepares the verification of the final proof. In order to fully verify a recursive proof, some operations may still be required to be done by the final verifier (e.g. a pairing check). This is why this black box function does not say if verification is passing or not. It delays the expensive part of verification out of the SNARK and leaves it to the final verifier outside of the SNARK circuit.

This opcode also verifies that the key_hash is indeed a hash of verification_key, allowing the user to use the verification key as private inputs and only have the key_hash as public input, which is more performant.

Warning: the key hash logic does not need to be part of the black box and subject to be removed.

If one of the recursive proofs you verify with the black box function fails to verify, then the verification of the final proof of the main ACIR program will ultimately fail.

Fields

verification_key: Vec<FunctionInput<F>>

Verification key of the circuit being verified

proof: Vec<FunctionInput<F>>

public_inputs: Vec<FunctionInput<F>>

These represent the public inputs of the proof we are verifying They should be checked against in the circuit after construction of a new aggregation state

key_hash: FunctionInput<F>

A key hash is used to check the validity of the verification key. The circuit implementing this opcode can use this hash to ensure that the key provided to the circuit matches the key produced by the circuit creator

proof_type: u32

Backend-specific proof type constant. The proof field is agnostic and can come from witness inputs. However, a backend may have many different verifiers which affect the circuit construction. In order for a backend to construct the correct recursive verifier it expects the user to specify a proof type.

BigIntAdd

BigInt addition

Fields

lhs: u32

rhs: u32

output: u32

BigIntSub

BigInt subtraction

Fields

lhs: u32

rhs: u32

output: u32

BigIntMul

BigInt multiplication

Fields

lhs: u32

rhs: u32

output: u32

BigIntDiv

BigInt division

Fields

lhs: u32

rhs: u32

output: u32

BigIntFromLeBytes

BigInt from le bytes

Fields

inputs: Vec<FunctionInput<F>>

modulus: Vec<u8>

output: u32

BigIntToLeBytes

BigInt to le bytes

Fields

input: u32

outputs: Vec<Witness>

Poseidon2Permutation

Applies the Poseidon2 permutation function to the given state, outputting the permuted state.

Fields

inputs: Vec<FunctionInput<F>>

Input state for the permutation of Poseidon2

outputs: Vec<Witness>

Permuted state

len: u32

State length (in number of field elements) It is the length of inputs and outputs vectors

Sha256Compression

Applies the SHA-256 compression function to the input message

Arguments

• inputs - input message block
• hash_values - state from the previous compression
• outputs - result of the input compressed into 256 bits

Fields

inputs: Box<[FunctionInput<F>; 16]>

512 bits of the input message, represented by 16 u32s

hash_values: Box<[FunctionInput<F>; 8]>

Vector of 8 u32s used to compress the input

outputs: Box<[Witness; 8]>

Output of the compression, represented by 8 u32s

Implementations

impl<F> BlackBoxFuncCall<F>

pub fn get_black_box_func(&self) -> BlackBoxFunc

pub fn name(&self) -> &str

pub fn get_outputs_vec(&self) -> Vec<Witness>

impl<F: Copy> BlackBoxFuncCall<F>

pub fn get_inputs_vec(&self) -> Vec<FunctionInput<F>>

pub fn get_input_witnesses(&self) -> BTreeSet<Witness>

Trait Implementations

impl<F: Clone> Clone for BlackBoxFuncCall<F>

fn clone(&self) -> BlackBoxFuncCall<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Display + Copy> Debug for BlackBoxFuncCall<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, F> Deserialize<'de> for BlackBoxFuncCall<F>

where F: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<F: Display + Copy> Display for BlackBoxFuncCall<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Hash> Hash for BlackBoxFuncCall<F>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<F: PartialEq> PartialEq for BlackBoxFuncCall<F>

fn eq(&self, other: &BlackBoxFuncCall<F>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<F> ProtoCodec<BlackBoxFuncCall<F>, BlackBoxFuncCall> for ProtoSchema<F>

where F: AcirField,

fn encode(value: &BlackBoxFuncCall<F>) -> BlackBoxFuncCall

Convert domain type T to protobuf representation R.

fn decode(value: &BlackBoxFuncCall) -> Result<BlackBoxFuncCall<F>>

Try to convert protobuf representation R to domain type T.

fn encode_some(value: &T) -> Option<R>

Encode a field as Some.

fn encode_vec<'a, I>(values: I) -> Vec<R>

where I: IntoIterator<Item = &'a T>, T: 'a,

Encode multiple values as a vector.

fn decode_wrap(value: &R, msg: &'static str) -> Result<T, Report>

Decode a field and attach the name of the field if it fails.

fn decode_vec(values: &[R]) -> Result<Vec<T>, Report>

Decode multiple values into a vector.

fn decode_vec_wrap(values: &[R], msg: &'static str) -> Result<Vec<T>, Report>

Decode multiple values into a vector, attaching a field name to any errors.

fn decode_arr<const N: usize>(values: &[R]) -> Result<[T; N], Report>

Decode a fixed size array.

fn decode_arr_wrap<const N: usize>( values: &[R], msg: &'static str, ) -> Result<[T; N], Report>

Decode a fixed size array, attaching a field name to any errors

fn decode_box_arr<const N: usize>(values: &[R]) -> Result<Box<[T; N]>, Report>

Decode a boxed fixed size array.

fn decode_box_arr_wrap<const N: usize>( values: &[R], msg: &'static str, ) -> Result<Box<[T; N]>, Report>

Decode a boxed fixed size array, attaching a field name to any errors

fn decode_some(value: &Option<R>) -> Result<T, Report>

Decode an optional field as a required one; fails if it’s None.

fn decode_some_wrap(value: &Option<R>, msg: &'static str) -> Result<T, Report>

Decode an optional field as a required one, attaching a field name to any errors. Returns error if the field is missing.

fn decode_opt_wrap( value: &Option<R>, msg: &'static str, ) -> Result<Option<T>, Report>

Decode an optional field, attaching a field name to any errors. Return None if the field is missing.

fn serialize_to_vec(value: &T) -> Vec<u8>

where R: Message,

Encode a domain type to protobuf and serialize it to bytes.

fn deserialize_from_slice(buf: &[u8]) -> Result<T, Report>

where R: Message + Default,

Deserialize a buffer into protobuf and then decode into the domain type.

impl<F> Serialize for BlackBoxFuncCall<F>

where F: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<F: Eq> Eq for BlackBoxFuncCall<F>

impl<F> StructuralPartialEq for BlackBoxFuncCall<F>