⚠️This API and documentation is still under active development.
List Registered Circuits
The Provide Privacy API can be thought of more generally as a circuit registry that enables best practices with regard to interacting with zero-knowledge circuits. The API exposes a way to query circuits in the registry.
The scope of the response is based on the authorized subject of the given bearer authorization request header.
The following query parameters can be used to filter the response:
filter the response by elliptic curve
filter the response by circuit identifier
filter the response by interface provider
filter the response by proving scheme
filter the response by provisioning status
You must provision a circuit before it can be used to generate and verify proofs. The foregoing holds true regardless of which provider, proving_scheme, curve and circuit identifier you specify (or source, if the raw source code of the circuit is provided instead of an identifier).
A powerful aspect of the Provide Privacy API is the asynchronous nature by which computationally-intensive cryptographic operations are executed. The lifecycle of a zero-knowledge circuit depends largely on the chosen proving_scheme. For example, zkSNARK proving schemes (i.e., groth16) require a trusted setup whereas more modern schemes (i.e., plonk) do not.
A persistent store is implicitly initialized upon the creation of a new circuit unless an existing store_id is provided and the referenced store is valid in the context of the circuit and authorized scope.
This API will evolve as additional providers and proving schemes are supported. Creating a circuit entails compiling the circuit from source, performing the appropriate setup or multiparty key ceremony and securely persist resulting artifacts.
The parameters required to provision a Circuit vary slightly across providers and proving schemes. Ensure you are using the source or identifier parameter properly for the selected provider and proving_scheme.
pairing-friendly elliptic curve, i.e., BN256
name of the circuit
proving scheme to be used; i.e., groth16
circuit provider, i.e., gnark
identifier of the persistent store instance for the encrypted notes tree
identifier of the persistent store instance for the nullifiers tree
The following API call illustrates how to compile and setup a new groth16 zkSNARK circuit using gnark.
default status value for all newly-initialized circuits
circuit is currently being compiled
circuit has been successfully compiled
trusted setup will begin asynchronously
trusted setup is running asynchronously
on-chain shield/verifier contract artifacts are being deployed
circuit is ready for use
¹ Trusted setup only applies to certain proving schemes. Setups are managed asynchronously by the Backplane component.
² On-chain artifacts are deployed if supported by the selected provider and proving_scheme.
Once you have provisioned a circuit, this API can be used to generate a proof given valid witness parameters. Calling this API has an implicit side-effect of writing the hash of generated proof to the persistent store associated with the circuit.
circuit-specific public and private inputs
The following API call illustrates how to generate a proof using a provisioned Circuit:
The API returns a 422 status code and human-readable error message(s) if (i) the witness parameters is not provided, (ii) required circuit arguments (i.e., fields) are not included within the given witness parameter or (iii) when Circuit constraints are not satisfied.
Here is example API call that results in an error message related to unsatisfied constraints: